Quartz.NET 作业调度(三):Trigger

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

1
await scheduler.ScheduleJob(job, trigger);

TriggerBuilder

Identity

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

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

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

StartAt & EndAt

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

1
2
3
4
5
6
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 使用方式一致。

1
2
3
4
5
6
7
8
9
var triggerDataMap = new JobDataMap();
triggerDataMap.Add("name", "beck");

ITrigger trigger = TriggerBuilder.Create()
.WithIdentity("trigger1", "triggerGroup1")
.StartNow()
.EndAt(DateTimeOffset.Now.AddHours(1))
.UsingJobData(triggerDataMap)
.Build();
1
2
3
4
5
public async Task Execute(IJobExecutionContext context)
{
var name = context.Trigger.JobDataMap["name"].ToString();
await Console.Out.WriteLineAsync($"Execute me, {name}");
}

WithSchedule

WithSimpleSchedule

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

1
2
3
4
5
6
7
8
9
10
11
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 做了一定的扩展,可以支持 年、月、周、日、时、分、秒及夏令时是设置。

1
2
3
4
5
6
7
8
9
10
11
ITrigger trigger = TriggerBuilder.Create()
.WithIdentity("trigger1", "triggerGroup1")
.StartNow()
.UsingJobData(triggerDataMap)
.WithCalendarIntervalSchedule(w => w
.WithIntervalInWeeks(1) // 一周执行一次
//.WithIntervalInDays(1) // 一天执行一次
//.WithIntervalInMonths(1) // 一个月执行一次
//.WithIntervalInYears(1) // 一年执行一次
)
.Build();

WithDailyTimeIntervalSchedule

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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位。

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

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

1
2
3
4
* * * * * ?  		// 每秒
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表示当前的第三个)
1
2
3
4
5
6
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 已经存在于调度器内。

1
2
3
4
5
6
7
8
9
10
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。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// 设置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 排除一天中的某些时间段不执行

    1
    2
    3
    4
    5
    // 排除每天的21~22点
    DailyCalendar dailyCalendar = new DailyCalendar(
    DateBuilder.DateOf(21, 0, 0).DateTime,
    DateBuilder.DateOf(22, 0, 0).DateTime
    );
  2. WeeklyCalendar 排除星期中的一天或多天

    1
    2
    3
    // 排除每周五
    WeeklyCalendar weeklyCalendar = new WeeklyCalendar();
    weeklyCalendar.SetDayExcluded(DayOfWeek.Friday, true);
  3. HolidayCalendar 排除特定的日期,精确到天

    1
    2
    3
    4
    // 排除2018年11月11日
    HolidayCalendar holidayCalendar = new HolidayCalendar();
    var holidayDateTime = new DateTime(2018, 3, 24);
    holidayCalendar.AddExcludedDate(holidayDateTime);
  4. MonthlyCalendar 排除月份中的某天,可选值为1-31,精确到天

    1
    2
    3
    // 排除每月1号
    MonthlyCalendar monthlyCalendar = new MonthlyCalendar();
    monthlyCalendar.SetDayExcluded(1, true);
  5. AnnualCalendar 排除每年中的某天,精确到天

    1
    2
    3
    4
    // 排除每年的11月11日
    AnnualCalendar annualCalendar = new AnnualCalendar();
    var annualDateTime = new DateTime(2018, 11, 11);
    annualCalendar.SetDayExcluded(annualDateTime, true);
  6. CronCalendar 使用表达式排除某些时间段不执行

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

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

1
2
3
4
5
6
7
8
9
10
11
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();

参考链接:

如果对你有帮助就好