关于Quartz .NET(V3.0.7)的简要说明

---

0. 任务调度

比如说，财务系统需要在每个月初生成上一个月的财务报表。

比如说，每天或每周固定时间对数据库更新。

比如说，每天定时发送邮件。

这些需要在某个预定的时间点周期性的执行某个特定的任务的功能（也就是任务调度），可以使用任务调度框架——Quartz .NET

Quartz.NET是一个开源的任务调度框架（作业调度框架），是从Java移植过来的，使用较为广泛！

---

1. Quartz .NET

1.1 基本概念

调度器(Scheduler)：存放触发器和定时任务，根据触发器执行定时任务

触发器(Trigger)：决定执行时间，执行间隔，运行次数，故触发器用来告诉调度程序作业什么时候触发

任务(Job):需要定时或是周期性执行的任务

使用流程：

创建调度器-->创建任务-->创建触发器-->Job和Trigger注册到调度器-->启动调度器;

1.2 主要接口和对象

接口/类	作用
IScheduler	调度器接口
IJob	任务接口，将需要定时执行的方法实现在该接口的Excute方法中
IJobDetail	用于定义Job的实例
ITrigger	触发器接口
JobBuilder	任务构造者：用于创建任务实例
TriggerBuilder	触发器构造者：用于创建触发器实例
JobDetailImpl	实现了IJobDetail类
JobKey	任务名
TriggerKey	触发器名

其中触发器的类型

关于分组：https://www.cnblogs.com/sunliyuan/p/5921016.html

触发器最常用的主要有两种：

SimpleTrigger：用于指定任务重复执行的时间间隔

IMutableTrigger：用于指定任务重复执行的具体时间

2. 使用示例

2.0 准备工作

①安装Quartz程序包

当前时间：2020年3月18日 23:20:59，最新版本的Quartz.NET为3.0.7

每次的版本的变化，API变化都好大，所以在这里注明当前的使用版本！

建议使用最新版本，新版本都是异步方法实现的。

NuGet：Install-Package Quartz -Version 3.0.7

②新建TestJob.cs
实现IJob接口

public class TestJob : IJob
{
    public async Task Execute(IJobExecutionContext context)
    {
        await Task.Run(() => Console.WriteLine($"{DateTime.Now}：执行任务了……"));
    }
}

2.1 每间隔一定时间间隔执行一次任务

//间隔5s重复一次执行指定的任务
public static async void WithInterval()
{
    //-------1.准备调度者
    ISchedulerFactory factory = new StdSchedulerFactory(); //创建调度器工厂
    IScheduler scheduler = await factory.GetScheduler(); //创建调度者

    //-------2.准备任务
    JobBuilder jobBuilder = JobBuilder.Create<TestJob>();//创建任务构造者：JobBuilder
    IJobDetail job1 = jobBuilder.Build();//创建任务

    //-------3.准备触发器
    TriggerBuilder triggerBuilder = TriggerBuilder.Create()
    .StartNow()//立即生效
    .WithSimpleSchedule(x=>x.WithIntervalInSeconds(5)
    .RepeatForever());  //创建触发器构造者：TriggerBuilder
    ISimpleTrigger trigger = triggerBuilder.WithIdentity("trigger1","group2").Build() as ISimpleTrigger;//创建触发器

    //-------4.将任务与触发器添加到调度器中
    await scheduler.ScheduleJob(job1, trigger);
    await scheduler.Start();//开始执行
}
        

【代码说明】：

• 示例中使用的而是ISimpleTrigger类型的触发器,可以精准的设置任务重复的时间间隔。

• 其中的触发器构造者中的

  triggerBuilder.StartNow()表示触发器立即生效

  triggerBuilder.StartAt(DateTimeOffset startTimeUtc)设置触发器生效的时间

  triggerBuilder.EndAt(DateTimeOffset startTimeUtc)设置触发器失效的时间

• 其中使用WithIntervalInSeconds(5)表示每五秒触发一次任务

  其他的一些按照小时和天的做间隔，以及明确触发次数的方法都简单明确，根据VS的智能提示即可了解，不一一列举于此！

• 示例中使用RepeatForever()表示重复无穷次，还是可以使用WithRepeatCount()设置重复的次数的。

  这里有一个细节问题，比如说，设置执行三次，WithRepeatCount(3),但是注意实际会执行4次

2.3 某天的固定时间点执行任务

Quartz.NET的接口比较繁多，第一个示例中是使用的最基础的方法，下面代码示例将换一种简写的方式。

//每天按照指定的时间点执行任务
public static async void AtHourAndMinute()
{
    //创建调度器
    IScheduler scheduler = await new StdSchedulerFactory().GetScheduler();
    //创建任务
    //JobDetailImpl job1 = new JobDetailImpl("TestJob1", "group1", typeo(TestJob))//JobDetailImpl是IJobDetail的实现类
    //等价于：
    IJobDetail job1 = JobBuilder.Create<TestJob>().WithIdentity("Testjob1""group1").Build();
    //创建触发器
    IMutableTrigger trigger2job1 = CronScheduleBuilder.DailyAtHourAndMinut(03, 50).Build();//每天更具某时间点重复触发任务
    //将任务和触发器添加到调度器中
    trigger2job1.Key = new TriggerKey("trigger1");//注意一定要给触发器命名
    await scheduler.ScheduleJob(job1, trigger2job1);
    //开始执行调度者
    await scheduler.Start();
}

【代码说明】：

• 示例中使用的是IMutableTrigger类型的触发器

• 通过CronScheduleBuilder类的静态方法可以设置触发的具体的某一日

  设置触发时间为每天的某时某分：DailyAtHourAndMinut(03, 50)

  设置触发时间是一周中的哪几天中的几时几分 ：AtHourAndMinuteOnGivenDaysOfWeek(int hour , int min, params DayOfWeek[] daysOfWeek)

  设置触发时间是每月中某天某时某分 ：CronScheduleBuilder.MonthlyOnDayAndHourAndMinute(int dayOfMonth, int hour, int min).Build()

• 封装好的一些方法还是有一定局限的（但是我自己够用的了），关于其他的一些复杂的周期任务，都是可以使用cron expression,使用cron expression可以定义你能想到的所有触发时间和周期

  cron expression什么样？怎么用？例如设置触发的时间是：每年每月的2点18分40秒CronScheduleBuilder.CronSchedule("40 18 2 ? * * *").WithIdentity("trigger1").Build();

  关于cron expression写起来还是有点麻烦的，可以使用一些在线生成器为我们自动的生成期望的表达式。

  推荐：Cron Expression Generator

2.4 封装整个定时任务，并给任务传递参数

前面的示例为了简洁的表示Quartz.NET的一些API的使用，

项目中都是把为定时任务，整个的操作流程封装在一个静态方法中，存放在我们自定义的Job类中

做一个简单的示例：定时发送短信。

自定义Job，实现IJob接口，同时把创建调度器对象，创建触发器和任务封装于其中，作为一个静态方法

class TestJob2 : IJob
{
    public async Task Execute(IJobExecutionContext context)
    {
        try
            {
                JobDataMap dataMap = context.MergedJobDataMap;
                string tag = dataMap.GetString("tag");
                string title = dataMap.GetString("title");
                string content = dataMap.GetString("content");
                string description = dataMap.GetString("description");
                string tels = dataMap.GetString("tels");

                //执行定时任务:模拟发送短信
                await Task.Run(() => Console.WriteLine($"发短信：【{tag}】,{title}：{content },{description},电话：{tels}。"));

                //await context.Scheduler.Shutdown();//表示完成当前的定时任务，关闭调度器

                //记入日志
                Console.WriteLine("执行了一次定时任务，记入日志");
            }
            catch (Exception ex)
            {
                //记入日志Log.Error()
                Console.WriteLine(ex.Message);
            }
    }

    //将创建定时任务的所有操作封装在此
    public static async void SendMessage(string starttime, string cronStr,string tag, string title, string content,string description, string tels)
    {
        try
        {
            //创建调度器
            IScheduler scheduler = await new StdSchedulerFactory().GetScheduler();
            //为任务准备参数
            DateTime time = DateTime.Parse(starttime);
            JobDataMap jobData = new JobDataMap()
            {
                new KeyValuePair<string, object>("tag", tag),
                new KeyValuePair<string, object>("title", title),
                new KeyValuePair<string, object>("content", content),
                new KeyValuePair<string, object>("description", description),
                new KeyValuePair<string, object>("tels", tels),
            };
            //创建任务：
            //注意可以用时间做组名：DateTime.Now.ToLongDateString()
            IJobDetail job = JobBuilder.Create<TestJob2>()
                                       .WithIdentity("Testjob1", "group1")
                                       .SetJobData(jobData)
                                       .Build();
            //创建触发器
            ITrigger trigger = TriggerBuilder.Create()
                                             .WithIdentity("triger1", "group1")
                                             .StartAt(time)//触发器开始时间//.StartNow()现在开始
                                             .WithCronSchedule(cronstr)
                                             .Build();
            //将任务和触发器添加到调度器中
            await scheduler.ScheduleJob(job, trigger);
            await scheduler.Start();
        }
        catch (Exception ex)
        {
            //记入日志
            Console.WriteLine(ex.Message);
        }
    }
}

调用：

public static async void PackageJob()
{
    //从系统当前时间，每隔5s，发送一条短信：【新闻】，新冠病毒，治愈者越来越多，普天同庆，10086。
    await Task.Run(() => TestJob2.SendMessage(DateTime.Now .ToString(),"/5 * * ? * *","新闻", "新冠病毒", "治愈者越来越多", "普天同庆", "10086"));
}

【代码说明】：

• 使用JobDataMap类型存放需要传递到IJob接口的Excute(IJobExecutionContext context)方法中

  在JobDataMap中以键值对的方式存放数据,jobDataMao.Add("key",value)

• 在定义Job的时候，使用触发器对象中的方法jobBuilder.SetJobData(jobData)将JobDataMap类型的数据传递到任务中

• 使用JobDataMap dataMap = context.MergedJobDataMap;获取传递到Excute()中的JobDataMap类型的数据

  使用string value = dataMap.GetString("key");获取数据

• 因为定时任务的是延时的执行的，所以切记一定要把每个周期中执行的定时任务记入到日志中，便于维护管理！

• 注意，因为实现了IJob接口的任务类，其Excute()方法是在一个单独的线程中运行的，所以其异常的处理也在Excute()中使用try……catch……进行处理

• BTW：在MVC项目中使用Quartz .NET,直接在Global.asax.cs中的Application_Start()运行封装好的定时任务即可

2.5 关于调度器的一些说明

• 一个调度器中可以调度多个方法

  使用 scheduler.ScheduleJob(job,trigger)将指定的任务和触发器添加到指定的调度器中，可以多次添加，从而实现一个调度器中调度多个任务

  但是有一点要注意：一个任务可以有多个触发器，但是一个触发器只能对应一个任务

• 调度器可以添加任务，那么就一定是可以移除任务的

  //停止触发器
  await scheduler.PauseTrigger(triggerKey);
  //移除触发器
  await scheduler.UnscheduleJob(triggerKey);
  //删除任务
  await scheduler.DeleteJob(jobkey);

• 调度器可以开始运行，那么就一定停止运行：

  context.Scheduler.Shutdown();表示完成当前的定时任务，关闭调度器

2.6 关于监视器

Undone……

可参考监听器：JobListeners/TriggerListeners/SchedulerListeners

---

参考及示例代码下载

• 示例中的源代码下载

• 官方文档：官方教程:Quartz.NET 3.x Tutorial

• 监听器：Quartz.NET使用教程

• Quartz(Java)源码：Quartz 源码解析

• 远程管理及可视化操作： ASP.NET MVC5 实现基于Quartz.NET任务调度

• 配置方式1：Quartz.NET文档 入门教程

• 配置方式2：Quartz.Net定时任务简单实用（实例）

• Cron Expression：Cron Expression Generator

• 封装任务和传参：NET作业调度(定时任务)-Quartz.Net

• 取消任务：Net作业调度-----Quartz.Net