Quick.Quartz.Furion 1.0.1

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+）组件进行封装使用的，目的在于结合.Net Core（.Net6+）更快、更简单和更灵活的使用Quartz！！！

功能说明：

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

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

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

• 支持灵活的Cron表达式；

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

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

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

• 更多功能尽情期待。

3、🍖安装

安装命令如下所示：

Install-Package 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 * * * * ?"
                    }
                ]
            }
        ]
    }
}

简化的配置

{
    "QuickQuartzSchedule": {
        "Groups": [
            {
                "Name": "测试分组任务", //分组名称
                "Tasks": [
                    //任务集合
                    {
                        "IsEnable": true, //是否启用，默认为 false
                        "DllName": "Quick.Quartz.TestFurion", //具体业务程序集dll名称
                        "ClassName": "Quick.Quartz.TestFurion.AppCode.Business.TestTask.TestData", //具体业务类名称（包括命名空间）
                        "Method": "ExecMethod", //执行方法
                        "CronExp": "0/2 * * * * ?" //Cron表达式
                    },
                    {
                        "IsEnable": true,
                        "DllName": "Quick.Quartz.TestFurion",
                        "ClassName": "Quick.Quartz.TestFurion.AppCode.Business.TestTask.ITestData2",
                        "Method": "ExecMethod",
                        "CronExp": "0/3 * * * * ?"
                    }
                ]
            }
        ]
    }
}

配置说明：

4.2、🍞配置Program.cs

由于我们使用的是Furion，因此，我们可在程序启动文件中配置如下代码（具体可参考Furion入门指南），目的是注册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
    }
}

实现接口的业务类Demo代码如下：

namespace Quick.Quartz.TestFurion.AppCode.Business.TestTask
{
    public interface ITestData2
    {
        Task ExecMethod();
    }

    public class TestData2 : ITestData2
    {
        #region 属性

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

        #endregion

        #region 构造方法

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

        #endregion

        #region 业务方法

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

        #endregion
    }
}

需要注意的是：

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

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

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

  QuickQuartzJobModel实体属性说明：

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