Calendars in Quartz.Net–Part 1

In this series of posts we will cover the use of calendars in Quartz.Net. In this first post we’ll start off by explaining what calendars are and what they’re used for. We’ll also describe all of the calendars that are included with the Quartz.Net distribution. In following posts we’ll look at examples of how to use the different calendars and eventually we’ll build our own custom calendar.

What Are Calendars?

Calendars are used to exclude periods of time during which a trigger would normally fire. Let’s say for example that we have a job that should run every workday, but not during holidays. To schedule this job we could use a CronTrigger to tell it to run Monday through Friday. To exclude holidays, we would then add a calendar to the trigger, specifying the holidays to exclude. This combination of a trigger and a calendar would produce the schedule we want.

Built-in Calendars

Quartz.Net provides several built-in calendars, such as the AnnualCalendar, the CronCalendar, the DailyCalendar, the HolidayCalendar, the MonthlyCalendar and the WeeklyCalendar. We’ll describe these calendars in detail next.

Annual Calendar

The AnnualCalendar is one of the built-in calendars in Quartz.Net. With the annual calendar you can exclude a given set of days every year. This calendar is useful for excluding holidays that always fall on the same date every year. Let’s say you have defined a cron trigger that should fire every day. However, you do not want it to fire on Jan 1. In order to achieve this schedule, you would create a cron trigger that fires every day, and then you would add an annual calendar that excludes Jan 1 to the trigger.

Cron Calendar

The CronCalendar is another of the Quartz.Net built-in calendars. This calendar uses a cron expression to define the times to be excluded. Keep in mind that whereas in the CronTrigger the cron expression supplied is used to determine the times to fire, in the the CronCalendar the expression is used to exclude certain times from firing. As an example, let’s say that you have configured a cron trigger that fires every hour. However, you don’t want it to fire during siesta time. One way to achieve this schedule is to add a CronCalendar that excludes every day at noon.

Daily Calendar

The DailyCalendar lets you exclude or include a time range each day. To configure this calendar, you specify the time range that you want to exclude. For example, let’s take the siesta example from the CronCalendar and say that we do not want our trigger to fire between noon and 2 PM. In this case we would set our time range to be 12:00 PM to 2:00 PM.

It’s also possible to invert the time range, so if we used the time range above and set the InvertTimeRange property to true, our trigger would only fire between 12:00 PM and 2:00 PM.

Holiday Calendar

The HolidayCalendar contains a list of all the days that should be excluded from triggering a job. If you use this calendar, you must provide a full list of all of the days that must be excluded. Only full days can be excluded by using this calendar.

Monthly Calendar

The MonthlyCalendar can be used to exclude a given set of days each month. This calendar lets you create exclusion schedules such as don’t run on the 1st and the 15th of every month.

Weekly Calendar

The WeeklyCalendar can be used to exclude a given set of days each week. This calendar lets you create exclusion schedules such as don’t run on the weekends, or don’t run on Mondays, for example.You set which days are excluded by adding System.DayOfWeek values to the calendar.

This concludes our introduction to Quartz.Net calendars. In the following post of the series I will provide hands on examples of how to create and add calendars to your jobs.