在 Quartz 中,Trigger 即 Job 執(zhí)行的觸發(fā)器。和 JobBuilder 類(lèi)似,我們可以通過(guò) TriggerBuilder 來(lái)創(chuàng)建各種情況需要的觸發(fā)器。Trigger 結(jié)合 Job,才能實(shí)現(xiàn)完美的作業(yè)調(diào)度。
await scheduler.ScheduleJob(job, trigger);
TriggerBuilder
Identity
Trigger 和 Job 類(lèi)似,都需要設(shè)置 name 和 group 來(lái)標(biāo)識(shí)。如果不設(shè)置依然由其自動(dòng)生成 name。
ITrigger trigger = TriggerBuilder.Create()
.WithIdentity("trigger1", "triggerGroup1")
.Build();
簡(jiǎn)單粗暴點(diǎn),這樣的 Trigger 其實(shí)就可以配合 Job 工作了,運(yùn)行測(cè)試會(huì)發(fā)現(xiàn) Job 會(huì)被馬上執(zhí)行一次,通過(guò)源碼可以發(fā)現(xiàn),默認(rèn)開(kāi)始時(shí)間是當(dāng)前時(shí)間,循環(huán)一次,但這樣的 Trigger 基本什么卵用。如:開(kāi)始時(shí)間、結(jié)束時(shí)間、執(zhí)行頻率等都沒(méi)有體現(xiàn),基本是屬于失控的觸發(fā)器,所以接下來(lái)我們需要繼續(xù)完善它。
StartAt & EndAt
通過(guò) StartAt 和 EndAt 我們可以設(shè)置一個(gè) Trigger 開(kāi)始執(zhí)行和結(jié)束時(shí)間,TriggerBuilder 同時(shí)預(yù)置了一個(gè) StartNow() 方法。
ITrigger trigger = TriggerBuilder.Create()
.WithIdentity("trigger1", "triggerGroup1")
//.StartNow()
.StartAt(DateTimeOffset.Now)
.EndAt(DateTimeOffset.Now.AddHours(1))
.Build();
UsingJobData
通過(guò) TriggerBuilder 的 UsingJobData 可以為 Trigger 設(shè)置一些附屬信息,在 Job 的 Execute 方法中,通過(guò) 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
通過(guò) WithSimpleSchedule 可以設(shè)置 Job 執(zhí)行的周期及執(zhí)行的次數(shù),不過(guò)循環(huán)周期基本是局限于 時(shí)、分、秒。
ITrigger trigger = TriggerBuilder.Create()
.WithIdentity("trigger1", "triggerGroup1")
.StartNow()
.EndAt(DateTimeOffset.Now.AddHours(1))
.UsingJobData(triggerDataMap)
.WithSimpleSchedule(w => w
.WithIntervalInSeconds(1) // 每秒執(zhí)行一次
.WithRepeatCount(10) // 循環(huán)10次
//.RepeatForever() // 一直循環(huán)下去
)
.Build();
WithCalendarIntervalSchedule
針對(duì) WithSimpleSchedule 做了一定的擴(kuò)展,可以支持 年、月、周、日、時(shí)、分、秒及夏令時(shí)是設(shè)置。
ITrigger trigger = TriggerBuilder.Create()
.WithIdentity("trigger1", "triggerGroup1")
.StartNow()
.UsingJobData(triggerDataMap)
.WithCalendarIntervalSchedule(w => w
.WithIntervalInWeeks(1) // 一周執(zhí)行一次
//.WithIntervalInDays(1) // 一天執(zhí)行一次
//.WithIntervalInMonths(1) // 一個(gè)月執(zhí)行一次
//.WithIntervalInYears(1) // 一年執(zhí)行一次
)
.Build();
WithDailyTimeIntervalSchedule
支持更精確的時(shí)間配置,可選每天、周末、工作日、周幾,并指定的時(shí)間范圍及執(zhí)行時(shí)間周期,相比前面兩種方式更加靈活。
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 開(kāi)始
.EndingDailyAt(TimeOfDay.HourMinuteAndSecondOfDay(22, 10, 12)) // 每天 22:10:12 結(jié)束
.EndingDailyAfterCount(10) // 每天最多10次
//.OnMondayThroughFriday() // 每周一到周五
//.OnSaturdayAndSunday() // 每周六到周日
//.OnEveryDay() // 每天
//.OnDaysOfTheWeek(DayOfWeek.Friday, DayOfWeek.Monday) // 每周特定某些天
)
.Build();
WithCronSchedule
通過(guò) Cron 表達(dá)式來(lái)設(shè)置執(zhí)行時(shí)間與周期,語(yǔ)法簡(jiǎn)單,但卻能實(shí)現(xiàn)非常豐富和靈活的時(shí)間配置。Cron 表達(dá)式一共7位,最后一位代表年,通??梢灾苯邮褂?位。
* * * * * *
代表秒 代表分 表小時(shí) 代表天 代表月 代表星期
先瞄一眼下面表達(dá)式及含義:
* * * * * ? // 每秒
0/5 * * * * ? // 每5秒
0 * * * * ? // 每分鐘
0 0/30 8-22 * * ? // 每天8~22點(diǎn)每30分鐘
下面對(duì)部分符號(hào)進(jìn)行說(shuō)明:
| 符號(hào) | 說(shuō)明 |
|---|---|
| ? | 只在日期和星期字段中使用,天和星期必須有一個(gè)是? |
| * | 每(秒、分、小時(shí)、天、月) |
| / | 遞增:0/5。如果在分位,則代表在 0分,5分,10分,15分 的時(shí)候執(zhí)行 |
| - | 范圍 8-22 。如果在小時(shí)位,則代表在8點(diǎn)到22點(diǎn)之間執(zhí)行 |
| , | 或 1,3,5,6。如果在天位,則代表每月1號(hào),3號(hào),5號(hào),6號(hào)執(zhí)行 |
| L | 只在日期和星期字段中使用,代表 "Last" 的意思。 "0 0 0 L * ?" 表示每月最后一天; "0 0 0 ? * L" 表示每月最一個(gè)星期六(相當(dāng)于7L); |
| # | 只能在星期字段中。使用 "0 0 0 ? * 6#3" 表示每月的第三個(gè)星期五 (6表示星期五,#3表示當(dāng)前的第三個(gè)) |
ITrigger trigger = TriggerBuilder.Create()
.WithIdentity("trigger1", "triggerGroup1")
.StartNow()
.UsingJobData(triggerDataMap)
.WithCronSchedule("0/20 0/30 2,4 2-5 8 ?") // 每年的8月2-5號(hào)2點(diǎn)和4點(diǎn)的0分、30分的時(shí)候每20秒執(zhí)行一次
.Build();

Misfire 機(jī)制
系統(tǒng)可能由于出現(xiàn)某些異常導(dǎo)致在預(yù)定時(shí)刻并沒(méi)有觸發(fā) Job 執(zhí)行,當(dāng)系統(tǒng)恢復(fù)正常時(shí),Quartz 會(huì)先檢查當(dāng)前時(shí)刻與預(yù)定時(shí)刻的差值,如果小于等于 misfireThreshold 值(默認(rèn)60秒,可以自定義),則不認(rèn)為發(fā)生 Misfire,并立刻啟動(dòng)該任務(wù),而且之前錯(cuò)過(guò)的 Job 執(zhí)行會(huì)全部補(bǔ)上。
WithSimpleSchedule 有 6 種 Misfire 機(jī)制:
WithMisfireHandlingInstructionFireNow
之前丟失的立即補(bǔ)執(zhí)行一次,時(shí)間會(huì)從當(dāng)前執(zhí)行開(kāi)始計(jì)算,時(shí)間周期不變
剩余次數(shù)=預(yù)定的總次數(shù)-(丟失次數(shù)-1)
(如:原設(shè)置是15時(shí)開(kāi)始,循環(huán)周期是1h,循環(huán)10次。系統(tǒng)在14點(diǎn)掛了,當(dāng) 16:30 恢復(fù)時(shí),首先馬上會(huì)執(zhí)行一次,下一次執(zhí)行時(shí)間變成 17:30,剩余10-(2【丟失2次】-1【補(bǔ)1次】)=9 )WithMisfireHandlingInstructionIgnoreMisfires
之前丟失的次數(shù)會(huì)馬上全部補(bǔ)上,之后執(zhí)行時(shí)間點(diǎn)和周期不會(huì)發(fā)生變化
剩余次數(shù)=預(yù)定的總次數(shù)-丟失次數(shù)
(如:原來(lái)設(shè)置16時(shí)開(kāi)始,循環(huán)周期是1h。當(dāng)恢復(fù)時(shí)間是 16:30,首先馬上會(huì)執(zhí)行丟失的所有次數(shù),下一次執(zhí)行時(shí)間依然是 17:00)WithMisfireHandlingInstructionNextWithRemainingCount
之前丟失的不管了,之后執(zhí)行時(shí)間點(diǎn)和周期不會(huì)發(fā)生變化
剩余次數(shù)=預(yù)定的總次數(shù)-丟失的次數(shù)WithMisfireHandlingInstructionNextWithExistingCount
之前丟失的不管了,之后執(zhí)行時(shí)間點(diǎn)和周期不會(huì)發(fā)生變化
剩余次數(shù)=預(yù)定的總次數(shù)WithMisfireHandlingInstructionNowWithRemainingCount
之前丟失的立即補(bǔ)執(zhí)行一次,時(shí)間會(huì)從當(dāng)前執(zhí)行開(kāi)始計(jì)算,時(shí)間周期不變
剩余次數(shù)=預(yù)定的總次數(shù)-(丟失次數(shù)-1)WithMisfireHandlingInstructionNowWithExistingCount
之前丟失的立即補(bǔ)執(zhí)行一次,時(shí)間會(huì)從當(dāng)前執(zhí)行開(kāi)始計(jì)算,時(shí)間周期不變
剩余次數(shù)=預(yù)定的總次數(shù)-1
WithCalendarIntervalSchedule、WithDailyTimeIntervalSchedule、WithCronSchedule 有 3 種 Misfire 機(jī)制:
WithMisfireHandlingInstructionDoNothing
之前丟失的不管了,之后執(zhí)行時(shí)間點(diǎn)和周期不會(huì)發(fā)生變化
剩余次數(shù)=預(yù)定的總次數(shù)WithMisfireHandlingInstructionFireAndProceed
之前丟失的立即補(bǔ)執(zhí)行一次,之后執(zhí)行時(shí)間點(diǎn)和周期不會(huì)發(fā)生變化
剩余次數(shù)=預(yù)定的總次數(shù)-1WithMisfireHandlingInstructionIgnoreMisfires
之前丟失的次數(shù)會(huì)馬上全部補(bǔ)上,之后執(zhí)行時(shí)間點(diǎn)和周期不會(huì)發(fā)生變化
剩余次數(shù)=預(yù)定的總次數(shù)-丟失次數(shù)
注意:在測(cè)試過(guò)程中,一定要關(guān)注到默認(rèn)超出60秒才會(huì)觸發(fā) Misfire,否則設(shè)置任何機(jī)制都無(wú)效。
ForJob
指定 Trigger 對(duì)應(yīng)的 Job,對(duì)應(yīng)的參數(shù)值可以是 jobName、 jobKey、jobDetail。但要注意,通過(guò) ForJob 的方式設(shè)置的 Trigger ,當(dāng) Trigger 被加入調(diào)度器時(shí),要確保對(duì)應(yīng)的 Job 已經(jīng)存在于調(diào)度器內(nèi)。
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
當(dāng)多個(gè) Trigger 在同一個(gè)時(shí)間點(diǎn)觸發(fā)一個(gè) Job 的時(shí)候,可以通過(guò)設(shè)置 Trigger 優(yōu)先級(jí)來(lái)控制執(zhí)行順序,Trigger 默認(rèn)的優(yōu)先級(jí)是 5,值越大優(yōu)先級(jí)越高,最高10。
// 設(shè)置trigger開(kāi)始時(shí)間
var startAt = DateTimeOffset.Now;
// trigger的附屬信息
var triggerDataMap = new JobDataMap();
triggerDataMap.Add("name", "beck");
// 創(chuàng)建觸發(fā)器
ITrigger trigger1 = TriggerBuilder.Create()
.WithIdentity("trigger1", "triggerGroup1")
.StartAt(startAt)
.WithCronSchedule("0/2 * * * * ?")
.UsingJobData(triggerDataMap)
.WithPriority(3)
.Build();
// 創(chuàng)建觸發(fā)器
ITrigger trigger2 = TriggerBuilder.Create()
.WithIdentity("trigger2", "triggerGroup1")
.StartAt(startAt)
.EndAt(DateTimeOffset.Now.AddHours(1))
.WithCronSchedule("0/2 * * * * ?")
.ForJob(job)
.UsingJobData(triggerDataMap)
.WithPriority(7)
.Build();
// 加入作業(yè)調(diào)度器中
await scheduler.ScheduleJob(job, trigger1);
await scheduler.ScheduleJob(trigger2);

ModifiedByCalendar
如果希望在指定的周期內(nèi)排除某些時(shí)間段不要執(zhí)行 Job,我們需要在 Trigger 內(nèi)增加 ModifiedByCalendar 配置,所有的 Calendar 既設(shè)置是排除,也可以是包含。Quartz 提供了以下幾種 Calendar:
-
DailyCalendar 排除一天中的某些時(shí)間段不執(zhí)行
// 排除每天的21~22點(diǎn) 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號(hào) 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 使用表達(dá)式排除某些時(shí)間段不執(zhí)行
// 排除每年的11月11日 CronCalendar cronCalendar = new CronCalendar("* * * 11 11 ?");
先通過(guò) AddCalendar 添加到調(diào)度器中,然后通過(guò) ModifiedByCalendar 修改 Trigger,所以下面 Trigger 的配置在 11月11日是不會(huì)觸發(fā) 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();