Quartz.NET笔记（四） 关于Triggers更多内容

Like jobs, triggers are relatively easy to work with, but do contain a variety of customizable options that you need to be aware of and understand before you can make full use of Quartz.NET. Also, as noted earlier, there are different types of triggers, that you can select to meet different scheduling needs.　

同Job一样，trigger非常容易使用，但它有一些可选项需要注意和理解，同时，trigger有不同的类型，要按照需求进行选择。　

Common Trigger Attributes

Aside from the fact that all trigger types have TriggerKey properties for tracking their identities, there are a number of other properties that are common to all trigger types. These common properties are set using the TriggerBuilder when you are building the trigger definition (examples of that will follow).

Here is a listing of properties common to all trigger types:

• The JobKey property indicates the identity of the job that should be executed when the trigger fires.
• The StartTimeUtc property indicates when the trigger's schedule first comes into affect. The value is a DateTimeOffset object that defines a moment in time on a given calendar date. For some trigger types, the trigger will actually fire at the start time, for others it simply marks the time that the schedule should start being followed. This means you can store a trigger with a schedule such as "every 5th day of the month" during January, and if the StartTimeUtc property is set to April 1st, it will be a few months before the first firing.
• The EndTimeUtc property indicates when the trigger's schedule should no longer be in effect. In other words, a trigger with a schedule of "every 5th day of the month" and with an end time of July 1st will fire for it's last time on June 5th.

Other properties, which take a bit more explanation are discussed in the following sub-sections.

Priority 优先级

Sometimes, when you have many Triggers (or few worker threads in your Quartz.NET thread pool), Quartz.NET may not have enough resources to immediately fire all of the Triggers that are scheduled to fire at the same time. In this case, you may want to control which of your Triggers get first crack at the available Quartz.NET worker threads. For this purpose, you can set the priority property on a Trigger. If N Triggers are to fire at the same time, but there are only Z worker threads currently available, then the first Z Triggers with the highest priority will be executed first. If you do not set a priority on a Trigger, then it will use the default priority of 5. Any integer value is allowed for priority, positive or negative.

Note: Priorities are only compared when triggers have the same fire time. A trigger scheduled to fire at 10:59 will always fire before one scheduled to fire at 11:00.

Note: When a trigger's job is detected to require recovery, its recovery is scheduled with the same priority as the original trigger.

Misfire Instructions

未触发指令

Another important property of a Trigger is its "misfire instruction". A misfire occurs if a persistent trigger "misses" its firing time because of the scheduler being shutdown, or because there are no available threads in Quartz.NET's thread pool for executing the job. The different trigger types have different misfire instructions available to them. By default they use a 'smart policy' instruction - which has dynamic behavior based on trigger type and configuration. When the scheduler starts, it searches for any persistent triggers that have misfired, and it then updates each of them based on their individually configured misfire instructions. When you start using Quartz.NET in your own projects, you should make yourself familiar with the misfire instructions that are defined on the given trigger types, and explained in their API documentation. More specific information about misfire instructions will be given within the tutorial lessons specific to each trigger type.

Trigger的另一个重要属性就是它的“misfire instruction(未触发指令)”。如果因为scheduler被关闭而导致持久的触发器“错过”了触发时间，这时，未触发就发生了。不同类型的触发器有不同的未触发指令。缺省情况下，他们会使用一个“智能策略”指令——根据触发器类型和配置的不同产生不同动作。当scheduler开始时，它查找所有未触发的持久triggers，然后按照每个触发器所配置的未触发指令来更新它们。开始工程中使用Quartz的时，应熟悉定义在各个类型触发器上的未触发指令。关于未触发指令信息的详细说明将在每种特定的类型触发器的指南课程中给出。可以通过MisfireInstruction属性来为给定的触发器实例配置未触发指令。

Calendars

Quartz.NET Calendar objects implementing ICalendar interface can be associated with triggers at the time the trigger is stored in the scheduler. Calendars are useful for excluding blocks of time from the the trigger's firing schedule. For instance, you could create a trigger that fires a job every weekday at 9:30 am, but then add a Calendar that excludes all of the business's holidays.

Calendar's can be any serializable objects that implement the ICalendar interface, which looks like this:

Quartz Calendar对象在trigger被存储到scheduler时与trigger相关联。Calendar对于在trigger触发日程中的采用批量世间非常有用。例如：你想要创建一个在每个工作日上午9：30触发一个触发器，那么就添加一个排除所有节假日的日历。

Calendar可以是任何实现Calendar接口的序列化对象。看起来如下：

namespace Quartz
{
    public interface ICalendar
    {
        string Description { get; set; }

        ICalendar CalendarBase { set; get; }

        bool IsTimeIncluded(DateTimeOffset timeUtc);

        DateTime GetNextIncludedTimeUtc(DateTimeOffset timeUtc);
    }
} 

Even though calendars can 'block out' sections of time as narrow as a millisecond, most likely, you'll be interested in 'blocking-out' entire days. As a convenience, Quartz.NET includes the class HolidayCalendar, which does just that.

Calendars must be instantiated and registered with the scheduler via the AddCalendar(..) method. If you use HolidayCalendar, after instantiating it, you should use its AddExcludedDate(DateTime date) method in order to populate it with the days you wish to have excluded from scheduling. The same calendar instance can be used with multiple triggers such as this:

Calendar Example

HolidayCalendar cal = new HolidayCalendar();
    cal.AddExcludedDate(someDate);

    sched.AddCalendar("myHolidays", cal, false);

    ITrigger t = TriggerBuilder.Create()
        .WithIdentity("myTrigger")
        .ForJob("myJob")
        .WithSchedule(CronScheduleBuilder.DailyAtHourAndMinute(9, 30)) // execute job daily at 9:30
        .ModifiedByCalendar("myHolidays") // but not on holidays
        .Build();

    // .. schedule job with trigger

    ITrigger t2 = TriggerBuilder.Create()
        .WithIdentity("myTrigger2")
        .ForJob("myJob2")
        .WithSchedule(CronScheduleBuilder.DailyAtHourAndMinute(11, 30)) // execute job daily at 11:30
        .ModifiedByCalendar("myHolidays") // but not on holidays
        .Build();

    // .. schedule job with trigger2 

The details of the construction/building of triggers will be given in the next couple lessons. For now, just believe that the code above creates two triggers, each scheduled to fire daily. However, any of the firings that would have occurred during the period excluded by the calendar will be skipped.

See the Quartz.Impl.Calendar namespace for a number of ICalendar implementations that may suit your needs.

附录：

TriggerUtils - Triggers Made Easy（TriggerUtils——使Triggers变得容易）

TriggerUtils类包含了创建触发器以及日期的便捷方法。使用这个类可以轻松地使触发器在每分钟，小时，日，星期，月等触发。使用这个类也可以产生距离触发最近的妙、分或者小时，这对设定触发开始时间非常有用。

TriggerListeners

最后，如同job一样，triggers可以注册监听器，实现TriggerListener接口的对象将可以收到触发器被触发的通知。