Class CronExpressionBuilder

Namespace

Quartz

Assembly

Quartz.dll

CronExpressionBuilder provides a fluent API for composing cron expression strings programmatically, one field at a time - useful when a schedule is assembled from user input (e.g. a scheduling UI) rather than hand-written.

public sealed class CronExpressionBuilder

Inheritance

object

CronExpressionBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Remarks

An unconfigured second is '0', so a builder that names only a minute or an hour fires once in each minute it matches. Every other unconfigured field is every value ('*'), and an unconfigured year is left out; Build() lists them. Before 4.7 an unconfigured second was '*'. For every second, say so: WithSecondRange(0, 59).

One expression carries one day field here: configuring day-of-month and day-of-week both is refused, and the unused one renders as '?'. That is this builder's constraint rather than cron's — an expression naming both days fires on the union of the two, which Parse(string) accepts and reads that way. Each field can be configured only once. Day-of-week values are emitted using their textual names (SUN-SAT) so that the produced expressions stay unambiguous across cron dialects that use different day-of-week numbering.

Client code can use the builder to write code such as this:

ITrigger trigger = TriggerBuilder.Create()
    .WithIdentity("myTrigger")
    .WithCronSchedule(CronExpressionBuilder.Create()
        .WithMinuteIncrements(0, 15)
        .WithHourRange(8, 17)
        .OnWeekdays()) // "0 0/15 8-17 ? * MON-FRI"
    .Build();

Methods

AtTime(TimeOnly)

Set the second, minute and hour fields to one time of day, so the expression fires once a day — or once on each day the day-of-week or day-of-month field selects.

public CronExpressionBuilder AtTime(TimeOnly time)

Parameters

time TimeOnly

the time of day to fire at.

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

Remarks

This is the whole of a "daily at 09:30" schedule: AtTime(new TimeOnly(9, 30)) is "0 30 9 ? * *". Add WithDaysOfWeek(params ReadOnlySpan<DayOfWeek>), OnWeekdays() or a day-of-month method for the days it applies to.

Cron resolves to a whole second, so any sub-second part of time is ignored.

Build()

Build a validated CronExpression from the configured fields.

public CronExpression Build()

Returns

CronExpression

the new CronExpression

Remarks

A field that was never configured renders as:

Field	Unconfigured
Second	'0'. Before 4.7 it was '*'; WithSecondRange(0, 59) is every second
Minute, hour, month	'*'
Day-of-month	'?'
Day-of-week	'*', or '?' when day-of-month is configured
Year	left out, which is every year

Exceptions

FormatException

if the composed expression fails final validation

Create()

Create a new CronExpressionBuilder with all fields unconfigured ("0 * * ? * *": once a minute).

public static CronExpressionBuilder Create()

Returns

CronExpressionBuilder

the new CronExpressionBuilder

Every(TimeSpan)

Set the expression to fire every interval, counted on the clock: every ten minutes is :00, :10, :20 and so on past each hour, whenever the trigger started.

public CronExpressionBuilder Every(TimeSpan interval)

Parameters

interval TimeSpan

how often to fire.

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

Remarks

The interval has to divide the next unit up evenly, so that every minute, hour or day starts on the same offsets: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20 or 30 seconds or minutes, or 1, 2, 3, 4, 6, 8 or 12 hours. Any other interval has no cron form that fires evenly; use WithSimpleSchedule(interval), which counts it from the trigger's start time instead.

It writes the interval's own field and every smaller one: Every(TimeSpan.FromMinutes(10)) is "0 0/10 * ? * *" and Every(TimeSpan.FromHours(6)) is "0 0 0/6 ? * *". The fields it leaves alone still say when the interval runs — add WithHourRange(int, int) for working hours or OnWeekdays() for weekdays. It cannot be combined with AtTime(TimeOnly), or with a value of your own for a field it writes.

Exceptions

ArgumentOutOfRangeException

interval is not a whole number of seconds or minutes that divides 60, or of hours that divides 24.

InvalidOperationException

a field the interval writes is already configured.

OnLastDayOfMonth()

Set the day-of-month field to the last day of the month ("L"). Cannot be combined with configuring the day-of-week field.

public CronExpressionBuilder OnLastDayOfMonth()

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

OnLastDayOfWeek()

Set the day-of-week field to the last day of the cron week ("L"), which is Saturday. Cannot be combined with configuring the day-of-month field.

public CronExpressionBuilder OnLastDayOfWeek()

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

OnLastDayOfWeekOfMonth(DayOfWeek)

Set the day-of-week field to the last occurrence of the given day in the month, e.g. "FRIL" for the last Friday. Cannot be combined with configuring the day-of-month field.

public CronExpressionBuilder OnLastDayOfWeekOfMonth(DayOfWeek dayOfWeek)

Parameters

dayOfWeek DayOfWeek

the day of the week

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

OnNearestWeekdayOfMonth(int)

Set the day-of-month field to the weekday (Monday-Friday) nearest to the given day, e.g. "15W". Cannot be combined with configuring the day-of-week field.

public CronExpressionBuilder OnNearestWeekdayOfMonth(int day)

Parameters

day int

the day of month to fire nearest to (1-31)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

OnNthDayOfWeekOfMonth(DayOfWeek, int)

Set the day-of-week field to the nth occurrence of the given day in the month, e.g. "FRI#3" for the third Friday. Cannot be combined with configuring the day-of-month field.

public CronExpressionBuilder OnNthDayOfWeekOfMonth(DayOfWeek dayOfWeek, int nth)

Parameters

dayOfWeek DayOfWeek

the day of the week

nth int

the occurrence of the day within the month (1-5)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

OnWeekdays()

Set the day-of-week field to weekdays ("MON-FRI"). Cannot be combined with configuring the day-of-month field.

public CronExpressionBuilder OnWeekdays()

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

ToString()

Returns the cron expression string composed from the configured fields, with the unconfigured ones rendered as Build() lists.

public override string ToString()

Returns

string

WithDayOfMonth(int)

Set the day-of-month field to a single value. Cannot be combined with configuring the day-of-week field.

public CronExpressionBuilder WithDayOfMonth(int day)

Parameters

day int

the day of month to fire on (1-31)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithDayOfMonthIncrements(int, int)

Set the day-of-month field to an incremental list of values, e.g. "1/5" (every 5 days starting on the 1st). Cannot be combined with configuring the day-of-week field.

public CronExpressionBuilder WithDayOfMonthIncrements(int start, int increment)

Parameters

start int

the day of month to start at (1-31)

increment int

the number of days between values (1-31)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithDayOfMonthRange(int, int)

Set the day-of-month field to a range of values, e.g. "20-25". The range may wrap around, e.g. "28-3". Cannot be combined with configuring the day-of-week field.

public CronExpressionBuilder WithDayOfMonthRange(int start, int end)

Parameters

start int

the first day of the range (1-31)

end int

the last day of the range (1-31)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithDayOfWeekIncrements(DayOfWeek, int)

Set the day-of-week field to every incrementth day starting from the given day, emitted as an explicit list of day names, e.g. Monday with increment 2 produces "MON,WED,FRI". Cannot be combined with configuring the day-of-month field.

public CronExpressionBuilder WithDayOfWeekIncrements(DayOfWeek start, int increment)

Parameters

start DayOfWeek

the day of the week to start at

increment int

the number of days between values (1-7)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

Remarks

The list stops at Saturday and does not wrap around, matching the semantics of a numeric cron day-of-week increment.

WithDayOfWeekRange(DayOfWeek, DayOfWeek)

Set the day-of-week field to a range of days, e.g. "MON-FRI". The range may wrap around, e.g. "FRI-MON". Cannot be combined with configuring the day-of-month field.

public CronExpressionBuilder WithDayOfWeekRange(DayOfWeek start, DayOfWeek end)

Parameters

start DayOfWeek

the first day of the range

end DayOfWeek

the last day of the range

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithDaysOfMonth(params int[])

Set the day-of-month field to a list of values, e.g. "1,15". The values are emitted in the given order. Cannot be combined with configuring the day-of-week field.

public CronExpressionBuilder WithDaysOfMonth(params int[] days)

Parameters

days int[]

the days of month to fire on (each 1-31)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithDaysOfMonth(params ReadOnlySpan<int>)

Set the day-of-month field to a list of values, e.g. "1,15". The values are emitted in the given order. Cannot be combined with configuring the day-of-week field.

public CronExpressionBuilder WithDaysOfMonth(params ReadOnlySpan<int> days)

Parameters

days ReadOnlySpan<int>

the days of month to fire on (each 1-31)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithDaysOfWeek(params DayOfWeek[])

Set the day-of-week field to the given days, e.g. "MON,THU,FRI". The values are emitted in the given order. Cannot be combined with configuring the day-of-month field.

public CronExpressionBuilder WithDaysOfWeek(params DayOfWeek[] daysOfWeek)

Parameters

daysOfWeek DayOfWeek[]

the days of the week to fire on

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithDaysOfWeek(params ReadOnlySpan<DayOfWeek>)

Set the day-of-week field to the given days, e.g. "MON,THU,FRI". The values are emitted in the given order. Cannot be combined with configuring the day-of-month field.

public CronExpressionBuilder WithDaysOfWeek(params ReadOnlySpan<DayOfWeek> daysOfWeek)

Parameters

daysOfWeek ReadOnlySpan<DayOfWeek>

the days of the week to fire on

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithHour(int)

Set the hour field to a single value.

public CronExpressionBuilder WithHour(int hour)

Parameters

hour int

the hour to fire on (0-23)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithHourIncrements(int, int)

Set the hour field to an incremental list of values, e.g. "0/6" (every 6 hours starting at hour 0).

public CronExpressionBuilder WithHourIncrements(int start, int increment)

Parameters

start int

the hour to start at (0-23)

increment int

the number of hours between values (1-23)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithHourRange(int, int)

Set the hour field to a range of values, e.g. "8-17". The range may wrap around, e.g. "22-2".

public CronExpressionBuilder WithHourRange(int start, int end)

Parameters

start int

the first hour of the range (0-23)

end int

the last hour of the range (0-23)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithHours(params int[])

Set the hour field to a list of values, e.g. "8,12,16". The values are emitted in the given order.

public CronExpressionBuilder WithHours(params int[] hours)

Parameters

hours int[]

the hours to fire on (each 0-23)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithHours(params ReadOnlySpan<int>)

Set the hour field to a list of values, e.g. "8,12,16". The values are emitted in the given order.

public CronExpressionBuilder WithHours(params ReadOnlySpan<int> hours)

Parameters

hours ReadOnlySpan<int>

the hours to fire on (each 0-23)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMinute(int)

Set the minute field to a single value.

public CronExpressionBuilder WithMinute(int minute)

Parameters

minute int

the minute to fire on (0-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMinuteIncrements(int, int)

Set the minute field to an incremental list of values, e.g. "0/15" (every 15 minutes starting at minute 0).

public CronExpressionBuilder WithMinuteIncrements(int start, int increment)

Parameters

start int

the minute to start at (0-59)

increment int

the number of minutes between values (1-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMinuteRange(int, int)

Set the minute field to a range of values, e.g. "20-30". The range may wrap around, e.g. "55-5".

public CronExpressionBuilder WithMinuteRange(int start, int end)

Parameters

start int

the first minute of the range (0-59)

end int

the last minute of the range (0-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMinutes(params int[])

Set the minute field to a list of values, e.g. "0,30". The values are emitted in the given order.

public CronExpressionBuilder WithMinutes(params int[] minutes)

Parameters

minutes int[]

the minutes to fire on (each 0-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMinutes(params ReadOnlySpan<int>)

Set the minute field to a list of values, e.g. "0,30". The values are emitted in the given order.

public CronExpressionBuilder WithMinutes(params ReadOnlySpan<int> minutes)

Parameters

minutes ReadOnlySpan<int>

the minutes to fire on (each 0-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMonth(int)

Set the month field to a single value.

public CronExpressionBuilder WithMonth(int month)

Parameters

month int

the month to fire on (1-12)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMonthIncrements(int, int)

Set the month field to an incremental list of values, e.g. "3/4" (every 4 months starting in March).

public CronExpressionBuilder WithMonthIncrements(int start, int increment)

Parameters

start int

the month to start at (1-12)

increment int

the number of months between values (1-12)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMonthRange(int, int)

Set the month field to a range of values, e.g. "2-8". The range may wrap around, e.g. "11-2".

public CronExpressionBuilder WithMonthRange(int start, int end)

Parameters

start int

the first month of the range (1-12)

end int

the last month of the range (1-12)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMonths(params int[])

Set the month field to a list of values, e.g. "3,6,9,12". The values are emitted in the given order.

public CronExpressionBuilder WithMonths(params int[] months)

Parameters

months int[]

the months to fire on (each 1-12)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithMonths(params ReadOnlySpan<int>)

Set the month field to a list of values, e.g. "3,6,9,12". The values are emitted in the given order.

public CronExpressionBuilder WithMonths(params ReadOnlySpan<int> months)

Parameters

months ReadOnlySpan<int>

the months to fire on (each 1-12)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithSecond(int)

Set the second field to a single value.

public CronExpressionBuilder WithSecond(int second)

Parameters

second int

the second to fire on (0-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithSecondIncrements(int, int)

Set the second field to an incremental list of values, e.g. "0/15" (every 15 seconds starting at second 0).

public CronExpressionBuilder WithSecondIncrements(int start, int increment)

Parameters

start int

the second to start at (0-59)

increment int

the number of seconds between values (1-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithSecondRange(int, int)

Set the second field to a range of values, e.g. "20-30". The range may wrap around, e.g. "55-5". WithSecondRange(0, 59) is every second, which an unconfigured second is not.

public CronExpressionBuilder WithSecondRange(int start, int end)

Parameters

start int

the first second of the range (0-59)

end int

the last second of the range (0-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithSeconds(params int[])

Set the second field to a list of values, e.g. "0,30". The values are emitted in the given order.

public CronExpressionBuilder WithSeconds(params int[] seconds)

Parameters

seconds int[]

the seconds to fire on (each 0-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithSeconds(params ReadOnlySpan<int>)

Set the second field to a list of values, e.g. "0,30". The values are emitted in the given order.

public CronExpressionBuilder WithSeconds(params ReadOnlySpan<int> seconds)

Parameters

seconds ReadOnlySpan<int>

the seconds to fire on (each 0-59)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithYear(int)

Set the year field to a single value.

public CronExpressionBuilder WithYear(int year)

Parameters

year int

the year to fire on (1970 to circa 100 years from now)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithYearIncrements(int, int)

Set the year field to an incremental list of values, e.g. "2030/2" (every second year starting in 2030).

public CronExpressionBuilder WithYearIncrements(int start, int increment)

Parameters

start int

the year to start at

increment int

the number of years between values (>= 1)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithYearRange(int, int)

Set the year field to a range of values, e.g. "2030-2035". Unlike the other fields, the year range cannot wrap around.

public CronExpressionBuilder WithYearRange(int start, int end)

Parameters

start int

the first year of the range

end int

the last year of the range

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithYears(params int[])

Set the year field to a list of values, e.g. "2030,2032". The values are emitted in the given order.

public CronExpressionBuilder WithYears(params int[] years)

Parameters

years int[]

the years to fire on (each 1970 to circa 100 years from now)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

WithYears(params ReadOnlySpan<int>)

Set the year field to a list of values, e.g. "2030,2032". The values are emitted in the given order.

public CronExpressionBuilder WithYears(params ReadOnlySpan<int> years)

Parameters

years ReadOnlySpan<int>

the years to fire on (each 1970 to circa 100 years from now)

Returns

CronExpressionBuilder

the updated CronExpressionBuilder

See Also

CronExpression

CronScheduleBuilder