Quartz.NET 作业调度（三）：Trigger
在 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分钟
下面对部分符号进行说明：
| 符号 | 说明 |
|---|---|
| ? | 只在日期和星期字段中使用，天和星期必须有一个是? |
| * | 每（秒、分、小时、天、月) |
| / | 递增：0/5。如果在分位，则代表在 0分，5分，10分，15分 的时候执行 |
| - | 范围 8-22 。如果在小时位，则代表在8点到22点之间执行 |
| , | 或 1,3,5,6。如果在天位，则代表每月1号，3号，5号，6号执行 |
| L | 只在日期和星期字段中使用，代表 "Last" 的意思。 "0 0 0 L * ?" 表示每月最后一天； "0 0 0 ? * L" 表示每月最一个星期六（相当于7L）； |
| # | 只能在星期字段中。使用 "0 0 0 ? * 6#3" 表示每月的第三个星期五 （6表示星期五，#3表示当前的第三个） |
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 机制：
-
WithMisfireHandlingInstructionFireNow
之前丢失的立即补执行一次，时间会从当前执行开始计算，时间周期不变
剩余次数=预定的总次数-(丢失次数-1）
(如：原设置是15时开始，循环周期是1h，循环10次。系统在14点挂了，当 16:30 恢复时，首先马上会执行一次，下一次执行时间变成 17:30，剩余10-(2【丢失2次】-1【补1次】)=9 ) -
WithMisfireHandlingInstructionIgnoreMisfires
之前丢失的次数会马上全部补上，之后执行时间点和周期不会发生变化
剩余次数=预定的总次数-丢失次数
(如：原来设置16时开始，循环周期是1h。当恢复时间是 16:30，首先马上会执行丢失的所有次数，下一次执行时间依然是 17:00) -
WithMisfireHandlingInstructionNextWithRemainingCount
之前丢失的不管了，之后执行时间点和周期不会发生变化
剩余次数=预定的总次数-丢失的次数 -
WithMisfireHandlingInstructionNextWithExistingCount
之前丢失的不管了，之后执行时间点和周期不会发生变化
剩余次数=预定的总次数 -
WithMisfireHandlingInstructionNowWithRemainingCount
之前丢失的立即补执行一次，时间会从当前执行开始计算，时间周期不变
剩余次数=预定的总次数-(丢失次数-1） -
WithMisfireHandlingInstructionNowWithExistingCount
之前丢失的立即补执行一次，时间会从当前执行开始计算，时间周期不变
剩余次数=预定的总次数-1
WithCalendarIntervalSchedule、WithDailyTimeIntervalSchedule、WithCronSchedule 有 3 种 Misfire 机制：
-
WithMisfireHandlingInstructionDoNothing
之前丢失的不管了，之后执行时间点和周期不会发生变化
剩余次数=预定的总次数 -
WithMisfireHandlingInstructionFireAndProceed
之前丢失的立即补执行一次，之后执行时间点和周期不会发生变化
剩余次数=预定的总次数-1 -
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：
-
DailyCalendar 排除一天中的某些时间段不执行
// 排除每天的21~22点 DailyCalendar dailyCalendar = new DailyCalendar( DateBuilder.DateOf(21, 0, 0).DateTime, DateBuilder.DateOf(22, 0, 0).DateTime ); -
WeeklyCalendar 排除星期中的一天或多天
// 排除每周五 WeeklyCalendar weeklyCalendar = new WeeklyCalendar(); weeklyCalendar.SetDayExcluded(DayOfWeek.Friday, true); -
HolidayCalendar 排除特定的日期，精确到天
// 排除2018年11月11日 HolidayCalendar holidayCalendar = new HolidayCalendar(); var holidayDateTime = new DateTime(2018, 3, 24); holidayCalendar.AddExcludedDate(holidayDateTime); -
MonthlyCalendar 排除月份中的某天，可选值为1-31，精确到天
// 排除每月1号 MonthlyCalendar monthlyCalendar = new MonthlyCalendar(); monthlyCalendar.SetDayExcluded(1, true); -
AnnualCalendar 排除每年中的某天，精确到天
// 排除每年的11月11日 AnnualCalendar annualCalendar = new AnnualCalendar(); var annualDateTime = new DateTime(2018, 11, 11); annualCalendar.SetDayExcluded(annualDateTime, true); -
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();
