The Quartz API

The tutorial uses IScheduler and Scheduler, IJob and Job, IJobDetail and JobDetail, and ITrigger and Trigger interchangeably.

A scheduler exists from the moment the container builds it until Shutdown(). Meanwhile IScheduler adds, removes and lists jobs and triggers and performs other operations such as pausing a trigger. Triggers do not fire until Start() is called; the hosted service calls it, as shown in Lesson 1.

Jobs and triggers are defined with fluent builders. The example from the previous lesson:

// define the job and tie it to our HelloJob class
IJobDetail job = JobBuilder.Create<HelloJob>()
    .WithIdentity("myJob", "group1") // name "myJob", group "group1"
    .Build();

// Trigger the job to run now, and then every 40 seconds
ITrigger trigger = TriggerBuilder.Create()
    .WithIdentity("myTrigger", "group1")
    .StartNow()
    .WithSimpleSchedule(x => x
        .WithInterval(TimeSpan.FromSeconds(40))
        .RepeatForever())
    .Build();

// Tell Quartz to schedule the job using our trigger
await scheduler.ScheduleJob(job, trigger);

JobBuilder builds the IJobDetail. TriggerBuilder builds the trigger, with one schedule method per trigger type:

A daily time interval schedule looks like StartingDailyAt(new TimeOnly(9, 0)), EndingDailyAt(new TimeOnly(17, 0)), OnMondayThroughFriday(). Times of day are TimeOnly in 4.0; 3.x had its own TimeOfDay type.

DateBuilder builds a DateTimeOffset that is awkward to write out: DateBuilder.Create().AtHourMinuteAndSecond(22, 0, 0).Build() is today at 22:00:00, and DateBuilder.CreateInTimeZone(timeZone) does the same in a given zone. When you pass the scheduler's TimeProvider, both read the clock through it, so a test that fakes time sees the faked time.

Jobs and Triggers

A job is a class that implements the IJob interface, which has only one simple method:

IJob Interface

namespace Quartz
{
    public interface IJob
    {
        ValueTask Execute(IJobExecutionContext context, CancellationToken cancellationToken = default);
    }
}

When the job's trigger fires, one of the scheduler's worker threads calls Execute. The IJobExecutionContext carries the run-time environment: the scheduler that ran the job, the trigger that fired it, the job's JobDetail, and a few other items.

cancellationToken is the same token as context.CancellationToken. It is a separate parameter so that analysis (CA2016) catches a job that does not forward it.

Your program creates the JobDetail when it adds the job to the scheduler. It holds the job's settings and a JobDataMap for state; the next lesson covers it.

A trigger fires a job. It can also carry a JobDataMap, for parameters specific to its firings. The common trigger types:

Jobs and triggers are separate so that:

• a job can be stored without a trigger, and many triggers can fire the same job;
• a job can stay in the scheduler after its triggers expire and be rescheduled later without being re-defined;
• a trigger can be changed or replaced without re-defining its job.

Identities

Jobs and triggers are identified by keys (JobKey and TriggerKey), each a name plus a group. Groups organize jobs and triggers into categories such as "reporting jobs" and "maintenance jobs". A name must be unique within its group. A key given only a name is in the group Key<T>.DefaultGroup, "DEFAULT".

Next: Lesson 3: More About Jobs & JobDetails and Lesson 5: More About Triggers.