sss

Quick.Quartz.Furion介绍

Quber...大约 10 分钟研发后端C#CSharpQuartz

Quick.Quartz.Furion 说明

本章，我们主要对封装的组件Quick.Quartz.Furion进行介绍。

该组件是基于Quartz（3.5.0+）和Furion（4.7.2+）组件进行封装使用的，目的在于结合.Netopen in new window Core（.Net6+）更快、更简单和更灵活的使用 Quartz！！！

1、🍹 更新日志

  • 1.0.1

    • 移除了方法 AddQuartz 传泛型 T 的重载；

    • 移除了方法GetInstance以及其重载方法；

    • 配置文件支持热更新操作（比如我们在 Windows 服务程序中运用该组件，然后不想在停止服务的情况下暂停或启动某个定时任务，我们只需要手动修改 JSON 文件的配置即可）；

    • 增加了方法GetAllTasks，用于获取所有任务的集合；

    • JSON 配置文件中增加了任务的描述属性Description。

  • 1.0.0

    • 全新组件重磅发布；

    • 支持通过 JSON 配置来管理任务的注册与执行;

    • 支持任务的启用与禁用；

    • 支持单个任务的并发控制（即可以控制单个任务如果上一次还没执行完成，那么下次一来的时候直接跳过）；

    • 支持灵活的Cron表达式；

    • 支持动态注入业务类（可以是一般类，也可以是接口类）；

    • 支持所有任务的暂停与恢复；

    • 支持单个任务的暂停、恢复与删除；

    • 更多功能尽情期待。

2、🍟Quick.Quartz.Furion 使用说明

该组件是基于Quartz（3.5.0+）和Furion（4.7.2+）组件进行封装使用的，目的在于结合.Netopen in new window Core（.Net6+）更快、更简单和更灵活的使用 Quartz！！！

功能说明：

  • 支持通过 JSON 配置来管理任务的注册与执行;

  • 支持任务的启用与禁用；

  • 支持单个任务的并发控制（即可以控制单个任务如果上一次还没执行完成，那么下次一来的时候直接跳过）；

  • 支持灵活的Cron表达式；

  • 支持动态注入业务类（可以是一般类，也可以是接口类）；

  • 支持所有任务的暂停与恢复；

  • 支持单个任务的暂停、恢复与删除；

  • 更多功能尽情期待。

3、🍖 安装

安装命令如下所示：

Install-Package Quick.Quartz.Furion

该组件的命名空间为：Quick.Quartz.Furion。

Quick.Quartz.Furion
Quick.Quartz.Furion
Quick.Quartz.Furion
Quick.Quartz.Furion

4、🧀 具体使用

4.1、🥞 配置appsettings.json

在appsettings.json配置文件中创建节点QuickQuartzSchedule，具体配置如下所示：

注意，如果不想把该配置放到appsettings.json中，你也可以自己新建一个 json 文件，没做限制一定要放到appsettings.json中。比如我们可以在 Windows 服务项目库中新建一个名称为quartzsettings.json的文件，专门用来存放 Quartz 的配置。

完整的配置
{
    "QuickQuartzSchedule": {
        "Groups": [
            {
                "Name": "测试分组任务", //分组名称
                //"GroupId": "TestGroup1",//可以不指定该属性，不指定后台会随机生成，建议指定值，便于可控
                "Tasks": [
                    //任务集合
                    {
                        "IsEnable": true, //是否启用，默认为 false
                        "Description": "任务1",
                        //"IsConcurrentExec": false, //是否允许并发执行（也就是上次任务还没执行完成，下次任务是否允许立即执行，默认为 false）
                        //"JobId": "Job0",//任务Id（请确保该Id的唯一性），可以不指定该属性，不指定后台会随机生成，建议指定值，便于可控
                        //"TriggerId": "TriggerId0",//触发器Id，可以不指定该属性，不指定后台会随机生成，建议指定值，便于可控
                        "DllName": "Quick.Quartz.TestFurion", //具体业务程序集dll名称
                        "ClassName": "Quick.Quartz.TestFurion.AppCode.Business.TestTask.TestData", //具体业务类名称（包括命名空间）
                        "Method": "ExecMethod", //执行方法
                        "CronExp": "0/2 * * * * ?" //Cron表达式
                    },
                    {
                        "IsEnable": true,
                        "Description": "任务2",
                        //"IsConcurrentExec": false,
                        //"JobId": "Job1",//可以不指定该属性，不指定后台会随机生成，建议指定值，便于可控
                        //"TriggerId": "TriggerId1",//可以不指定该属性，不指定后台会随机生成，建议指定值，便于可控
                        "DllName": "Quick.Quartz.TestFurion",
                        "ClassName": "Quick.Quartz.TestFurion.AppCode.Business.TestTask.ITestData2",
                        "Method": "ExecMethod",
                        "CronExp": "0/3 * * * * ?"
                    }
                ]
            }
        ]
    }
}

配置说明：

属性名称属性说明是否必填备注
QuickQuartzScheduleQuartz 根节点配置对象√
GroupsQuartz 分组节点配置对象集合√
Name分组名称
GroupId分组 Id（请确保该 Id 的唯一性）如果不配置或改参数为空，则会随机生成，建议指定值，便于可控
Tasks任务集合√
IsEnable是否启用，默认为 false√
Description任务描述
IsConcurrentExec是否允许并发执行（也就是上次任务还没执行完成，下次任务是否允许立即执行，默认为 false）√
JobId任务 Id（请确保该 Id 的唯一性）如果不配置或改参数为空，则会随机生成，建议指定值，便于可控
TriggerId触发器 Id如果不配置或改参数为空，则会随机生成，建议指定值，便于可控
DllName具体业务程序集 dll 名称√
ClassName具体业务类名称（包括命名空间）√
Method执行方法√
CronExpCron 表达式√

4.2、🍞 配置 Program.cs

由于我们使用的是Furion，因此，我们可在程序启动文件中配置如下代码（具体可参考Furion 入门指南open in new window），目的是注册IQuickQuartz 服务、配置选项 QuickQuartzScheduleOptions以及具体业务处理类等。

Furion 提供的 AppStartup 启动配置文件：

public void ConfigureServices(IServiceCollection services)
{
    //通过AddQuartz注册IQuickQuartz、QuickQuartzScheduleOptions以及具体业务类
    services.AddQuartz();
}


 
 

其他库的使用方式也基本类似，就不一一介绍了。

4.3、🧀Worker 中初始化

接下来我们可以在Window 服务项目库中新建一个 Worker，使用构造函数获取IQuickQuartz的实例，然后一句await _quickQuartz.InitTasks()代码即可完成定时任务的初始化，具体的 Worker 代码如下所示：

using Quick.Quartz.Furion;

namespace Quick.Quartz.TestFurion
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;

        /// <summary>
        /// IQuickQuartz的实例对象
        /// </summary>
        private readonly IQuickQuartz _quickQuartz;

        public Worker(ILogger<Worker> logger, IQuickQuartz quickQuartz)
        {
            _logger = logger;

            //获取IQuickQuartz的实例
            _quickQuartz = quickQuartz;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //初始化任务
                var ret = await _quickQuartz.InitTasks();

                if (ret.IsSucc)
                {
                    //初始化成功
                }
                else
                {
                    //初始化失败，ret.ErrMsg是反馈回来的失败原因
                    var failMsg = ret.ErrMsg;
                }

                await Task.Delay(10000, stoppingToken);
            }
        }
    }
}








 
 
 
 





 
 






 
 
















4.4、🥐 具体业务类

在上述 JSON 配置文件中，我们定义了 2 个测试任务，第一个是一般业务类，第二个是实现接口的业务类。

一般业务类 Demo 代码
namespace Quick.Quartz.TestFurion.AppCode.Business.TestTask
{
    public class TestData
    {
        #region 属性

        /// <summary>
        /// 日志对象
        /// </summary>
        private readonly ILogger<TestData> _logger;

        #endregion

        #region 构造方法

        /// <summary>
        /// 构造方法
        /// </summary>
        /// <param name="logger"></param>
        public TestData(ILogger<TestData> logger)
        {
            _logger = logger;
        }

        #endregion

        #region 业务方法

        public async Task ExecMethod()
        {
            _logger.LogInformation($"一般类任务：{DateTime.Now:yyyy-MM-dd HH:mm:ss}");
        }

        #endregion
    }
}






 
 
 
 





 
 
 
 
 
 
 
 





 
 
 
 




需要注意的是：

  • 配置文件中的DllName属性，一定是业务处理类 dll 程序集的名称；

  • 配置文件中的ClassName属性，一定是业务处理类的全称（命名空间+类名）。

4.5、🥪 演示效果

如下所示的演示效果就是上述配置同时执行的 2 个任务。

一个是执行的一般业务类的任务（JobId 为 Job0 的任务每隔 2 秒执行一次），另一个是执行的实现接口的业务类（JobId 为 Job1 的任务每隔 3 秒执行一次）：

Quick.Quartz.Furion
Quick.Quartz.Furion

5、🥙Quick.Quartz.Furion 方法

  • 首先声明 Quick.Quartz.Furion 的实例化对象（IQuickQuartz），通过依赖注入在构造函数中获取即可，具体可参照上述文档中的相关示例。

  • 依赖注入方法：

    方法名称方法说明方法参数备注
    AddQuartz添加依赖注入服务()该方法为IServiceCollection的扩展方法，目的是实现IQuickQuartz接口的注册、配置QuickQuartzScheduleOptions的注册以及具体业务类的动态注册。

  • 其次就可以使用使用该实例化对象中的各个方法了，具体说明如下所示：

    方法名称方法说明方法参数备注
    InitTasks初始化任务()返回元组对象，包含 2 个值，第一个为是否成功，第二个为失败的提示信息
    StartTasks启动所有任务()返回元组对象，包含 2 个值，第一个为是否成功，第二个为失败的提示信息
    StopTasks停止所有任务()返回元组对象，包含 2 个值，第一个为是否成功，第二个为失败的提示信息
    PauseTask暂停单个任务(string jobId, string? groupId = null)方法第一个参数为 Job 的 Id；
    方法第二个参数为 Group 的 Id；
    返回元组对象，包含 2 个值，第一个为是否成功，第二个为失败的提示信息。
    ResumeTask恢复单个任务(string jobId, string? groupId = null)方法第一个参数为 Job 的 Id；
    方法第二个参数为 Group 的 Id；
    返回元组对象，包含 2 个值，第一个为是否成功，第二个为失败的提示信息。
    ExistTask检查某个任务是否存在(string jobId, string? groupId = null)方法第一个参数为 Job 的 Id；
    方法第二个参数为 Group 的 Id；
    返回元组对象，包含 3 个值，第一个为是否成功，第二个为任务是否存在，第三个为失败的提示信息。
    DeleteTask删除单个任务(string jobId, string? groupId = null)方法第一个参数为 Job 的 Id；
    方法第二个参数为 Group 的 Id；
    返回元组对象，包含 2 个值，第一个为是否成功，第二个为失败的提示信息。
    PauseAllTasks暂停所有任务()返回元组对象，包含 2 个值，第一个为是否成功，第二个为失败的提示信息
    ResumeAllTasks恢复所有任务()返回元组对象，包含 2 个值，第一个为是否成功，第二个为失败的提示信息
    GetNextExecTimes获取任务在未来周期内哪些时间会运行(string cronExp, int execTimes = 3)方法第一个参数为 Cron 表达式；
    方法第二个参数为运行次数；
    返回元组对象，包含 3 个值，第一个为是否成功，第二个为执行的 DateTime 集合，第三个为失败的提示信息。
    GetAllTasks获取所有任务()返回元组对象，包含 3 个值，第一个为是否成功，第二个为QuickQuartzJobModel集合，第三个为失败的提示信息，其中的QuickQuartzJobModel实体说明请参见下表。

    QuickQuartzJobModel 实体属性说明：

    属性名称属性说明属性类型备注
    Description任务描述string?该属性值来自配置文件中的 Description
    GroupId分组 Idstring
    JobId任务 Idstring
    TriggerId触发器 Idstring
    TriggerState任务状态TriggerStateQuartz.TriggerState 的枚举类型，包含的值有：Normal、Paused、Complete、Error、Blocked 和 None。
    DllName具体业务程序集 dll 名称string
    ClassName具体业务类名称（包括命名空间）string
    Method执行方法string
    CronExpCron 表达式string