在 Quartz 中，Trigger 即 Job 执行的触发器。和 JobBuilder 类似，我们可以通过 TriggerBuilder 来创建各种情况需要的触发器。Trigger 结合 Job，才能实现完美的作业调度。

 await scheduler.ScheduleJob(job, trigger);

TriggerBuilder

Identity

Trigger 和 Job 类似，都需要设置 name 和 group 来标识。如果不设置依然由其自动生成 name。

ITrigger trigger = TriggerBuilder.Create()
        .WithIdentity("trigger1", "triggerGroup1")
        .Build();

简单粗暴点，这样的 Trigger 其实就可以配合 Job 工作了，运行测试会发现 Job 会被马上执行一次，通过源码可以发现，默认开始时间是当前时间，循环一次，但这样的 Trigger 基本什么卵用。如：开始时间、结束时间、执行频率等都没有体现，基本是属于失控的触发器，所以接下来我们需要继续完善它。

StartAt & EndAt

通过 StartAt 和 EndAt 我们可以设置一个 Trigger 开始执行和结束时间，TriggerBuilder 同时预置了一个 StartNow() 方法。

ITrigger trigger = TriggerBuilder.Create()
        .WithIdentity("trigger1", "triggerGroup1")
        //.StartNow()
        .StartAt(DateTimeOffset.Now)
        .EndAt(DateTimeOffset.Now.AddHours(1))
        .Build();

UsingJobData

通过 TriggerBuilder 的 UsingJobData 可以为 Trigger 设置一些附属信息，在 Job 的 Execute 方法中，通过 context.Trigger.JobDataMap["xxx"] 获取属性值，和 context.JobDetail.JobDataMap 使用方式一致。

var triggerDataMap = new JobDataMap();
triggerDataMap.Add("name", "beck");

ITrigger trigger = TriggerBuilder.Create()
        .WithIdentity("trigger1", "triggerGroup1")
        .StartNow()
        .EndAt(DateTimeOffset.Now.AddHours(1))
        .UsingJobData(triggerDataMap)
        .Build();

public async Task Execute(IJobExecutionContext context)
{
  var name = context.Trigger.JobDataMap["name"].ToString();
  await Console.Out.WriteLineAsync($"Execute me, {name}");
}

WithSchedule

WithSimpleSchedule

通过 WithSimpleSchedule 可以设置 Job 执行的周期及执行的次数，不过循环周期基本是局限于 时、分、秒。

ITrigger trigger = TriggerBuilder.Create()
        .WithIdentity("trigger1", "triggerGroup1")
        .StartNow()
        .EndAt(DateTimeOffset.Now.AddHours(1))
        .UsingJobData(triggerDataMap)
        .WithSimpleSchedule(w => w
            .WithIntervalInSeconds(1)   // 每秒执行一次
            .WithRepeatCount(10)        // 循环10次
            //.RepeatForever()          // 一直循环下去
        )
        .Build();

WithCalendarIntervalSchedule

针对 WithSimpleSchedule 做了一定的扩展，可以支持 年、月、周、日、时、分、秒及夏令时是设置。

ITrigger trigger = TriggerBuilder.Create()
        .WithIdentity("trigger1", "triggerGroup1")
        .StartNow()
        .UsingJobData(triggerDataMap)
        .WithCalendarIntervalSchedule(w => w
            .WithIntervalInWeeks(1)       // 一周执行一次
            //.WithIntervalInDays(1)      // 一天执行一次
            //.WithIntervalInMonths(1)    // 一个月执行一次
            //.WithIntervalInYears(1)     // 一年执行一次
        )
        .Build();

WithDailyTimeIntervalSchedule

支持更精确的时间配置，可选每天、周末、工作日、周几，并指定的时间范围及执行时间周期，相比前面两种方式更加灵活。

ITrigger trigger = TriggerBuilder.Create()
        .WithIdentity("trigger1", "triggerGroup1")
        .StartNow()
        .UsingJobData(triggerDataMap)
        .WithDailyTimeIntervalSchedule(w => w
            .WithIntervalInSeconds(1)
            .WithRepeatCount(20)
            .StartingDailyAt(TimeOfDay.HourAndMinuteOfDay(0, 1))            // 每天 00:01:00 开始
            .EndingDailyAt(TimeOfDay.HourMinuteAndSecondOfDay(22, 10, 12))  // 每天 22:10:12 结束
            .EndingDailyAfterCount(10)                                      // 每天最多10次
            //.OnMondayThroughFriday()                                      // 每周一到周五
            //.OnSaturdayAndSunday()                                        // 每周六到周日
            //.OnEveryDay()                                                 // 每天
            //.OnDaysOfTheWeek(DayOfWeek.Friday, DayOfWeek.Monday)          // 每周特定某些天
        )
        .Build();

WithCronSchedule

通过 Cron 表达式来设置执行时间与周期，语法简单，但却能实现非常丰富和灵活的时间配置。Cron 表达式一共7位，最后一位代表年，通常可以直接使用6位。

  *      *      *      *      *      *
代表秒  代表分  表小时  代表天  代表月  代表星期

先瞄一眼下面表达式及含义：

* * * * * ?         // 每秒
0/5 * * * * ?       // 每5秒
0 * * * * ?         // 每分钟
0 0/30 8-22 * * ?   // 每天8~22点每30分钟

下面对部分符号进行说明：

ITrigger trigger = TriggerBuilder.Create()
        .WithIdentity("trigger1", "triggerGroup1")
        .StartNow()
        .UsingJobData(triggerDataMap)
        .WithCronSchedule("0/20 0/30 2,4 2-5 8 ?") // 每年的8月2-5号2点和4点的0分、30分的时候每20秒执行一次
        .Build();

前5次

Misfire 机制

系统可能由于出现某些异常导致在预定时刻并没有触发 Job 执行，当系统恢复正常时，Quartz 会先检查当前时刻与预定时刻的差值，如果小于等于 misfireThreshold 值（默认60秒，可以自定义），则不认为发生 Misfire，并立刻启动该任务，而且之前错过的 Job 执行会全部补上。

WithSimpleSchedule 有 6 种 Misfire 机制：

1. WithMisfireHandlingInstructionFireNow
   之前丢失的立即补执行一次，时间会从当前执行开始计算，时间周期不变
   剩余次数=预定的总次数-(丢失次数-1）
   (如：原设置是15时开始，循环周期是1h，循环10次。系统在14点挂了，当 16:30 恢复时，首先马上会执行一次，下一次执行时间变成 17:30，剩余10-(2【丢失2次】-1【补1次】)=9 )

2. WithMisfireHandlingInstructionIgnoreMisfires
   之前丢失的次数会马上全部补上，之后执行时间点和周期不会发生变化
   剩余次数=预定的总次数-丢失次数
   (如：原来设置16时开始，循环周期是1h。当恢复时间是 16:30，首先马上会执行丢失的所有次数，下一次执行时间依然是 17:00)

3. WithMisfireHandlingInstructionNextWithRemainingCount
   之前丢失的不管了，之后执行时间点和周期不会发生变化
   剩余次数=预定的总次数-丢失的次数

4. WithMisfireHandlingInstructionNextWithExistingCount
   之前丢失的不管了，之后执行时间点和周期不会发生变化
   剩余次数=预定的总次数

5. WithMisfireHandlingInstructionNowWithRemainingCount
   之前丢失的立即补执行一次，时间会从当前执行开始计算，时间周期不变
   剩余次数=预定的总次数-(丢失次数-1）

6. WithMisfireHandlingInstructionNowWithExistingCount
   之前丢失的立即补执行一次，时间会从当前执行开始计算，时间周期不变
   剩余次数=预定的总次数-1

WithCalendarIntervalSchedule、WithDailyTimeIntervalSchedule、WithCronSchedule 有 3 种 Misfire 机制：

1. WithMisfireHandlingInstructionDoNothing
   之前丢失的不管了，之后执行时间点和周期不会发生变化
   剩余次数=预定的总次数

2. WithMisfireHandlingInstructionFireAndProceed
   之前丢失的立即补执行一次，之后执行时间点和周期不会发生变化
   剩余次数=预定的总次数-1

3. WithMisfireHandlingInstructionIgnoreMisfires
   之前丢失的次数会马上全部补上，之后执行时间点和周期不会发生变化
   剩余次数=预定的总次数-丢失次数

注意：在测试过程中，一定要关注到默认超出60秒才会触发 Misfire，否则设置任何机制都无效。

ForJob

指定 Trigger 对应的 Job，对应的参数值可以是 jobName、 jobKey、jobDetail。但要注意，通过 ForJob 的方式设置的 Trigger ，当 Trigger 被加入调度器时，要确保对应的 Job 已经存在于调度器内。

ITrigger trigger = TriggerBuilder.Create()
        .WithIdentity("trigger2", "triggerGroup1")
        .StartNow()
        .UsingJobData(triggerDataMap)
        .WithCronSchedule("0/2 * * * * ?")
        .ForJob(job)
        .Build();

 await scheduler.AddJob(job, true);
 await scheduler.ScheduleJob(trigger);

Priority

当多个 Trigger 在同一个时间点触发一个 Job 的时候，可以通过设置 Trigger 优先级来控制执行顺序，Trigger 默认的优先级是 5，值越大优先级越高，最高10。

// 设置trigger开始时间
var startAt = DateTimeOffset.Now;

// trigger的附属信息
var triggerDataMap = new JobDataMap();
triggerDataMap.Add("name", "beck");

// 创建触发器
ITrigger trigger1 = TriggerBuilder.Create()
    .WithIdentity("trigger1", "triggerGroup1")
    .StartAt(startAt)
    .WithCronSchedule("0/2 * * * * ?")
    .UsingJobData(triggerDataMap)
    .WithPriority(3)
    .Build();

// 创建触发器
ITrigger trigger2 = TriggerBuilder.Create()
    .WithIdentity("trigger2", "triggerGroup1")
    .StartAt(startAt)
    .EndAt(DateTimeOffset.Now.AddHours(1))
    .WithCronSchedule("0/2 * * * * ?")
    .ForJob(job)
    .UsingJobData(triggerDataMap)
    .WithPriority(7)
    .Build();

// 加入作业调度器中
await scheduler.ScheduleJob(job, trigger1);
await scheduler.ScheduleJob(trigger2);

WithPriority

ModifiedByCalendar

如果希望在指定的周期内排除某些时间段不要执行 Job，我们需要在 Trigger 内增加 ModifiedByCalendar 配置，所有的 Calendar 既设置是排除，也可以是包含。Quartz 提供了以下几种 Calendar：

1. DailyCalendar 排除一天中的某些时间段不执行

   // 排除每天的21~22点
   DailyCalendar dailyCalendar = new DailyCalendar(
             DateBuilder.DateOf(21, 0, 0).DateTime, 
             DateBuilder.DateOf(22, 0, 0).DateTime
   );
   

2. WeeklyCalendar 排除星期中的一天或多天

   // 排除每周五
   WeeklyCalendar weeklyCalendar = new WeeklyCalendar();
   weeklyCalendar.SetDayExcluded(DayOfWeek.Friday, true);
   

3. HolidayCalendar 排除特定的日期，精确到天

   // 排除2018年11月11日
   HolidayCalendar holidayCalendar = new HolidayCalendar();
   var holidayDateTime = new DateTime(2018, 3, 24);
   holidayCalendar.AddExcludedDate(holidayDateTime);
   

4. MonthlyCalendar 排除月份中的某天，可选值为1-31，精确到天

   // 排除每月1号
   MonthlyCalendar monthlyCalendar = new MonthlyCalendar();
   monthlyCalendar.SetDayExcluded(1, true);
   

5. AnnualCalendar 排除每年中的某天，精确到天

   // 排除每年的11月11日
   AnnualCalendar annualCalendar = new AnnualCalendar();
   var annualDateTime = new DateTime(2018, 11, 11);
   annualCalendar.SetDayExcluded(annualDateTime, true);
   

6. CronCalendar 使用表达式排除某些时间段不执行

   // 排除每年的11月11日
   CronCalendar cronCalendar = new CronCalendar("* * * 11 11 ?");  
   

先通过 AddCalendar 添加到调度器中，然后通过 ModifiedByCalendar 修改 Trigger，所以下面 Trigger 的配置在 11月11日是不会触发 Job 的。

await scheduler.AddCalendar("calendar", cronCalendar, true, true);

ITrigger trigger2 = TriggerBuilder.Create()
       .WithIdentity("trigger2", "triggerGroup1")
       .StartNow()
       .WithCronSchedule("* * * 11-12 11 ?")
       .ForJob(job)
       .UsingJobData(triggerDataMap)
       .ModifiedByCalendar("calendar")
       .WithPriority(7)
       .Build();

参考链接：

• Quartz.NET Documentation
• 案例 Demo-QuartzNetTrigger