A CronTrigger fires on a schedule written as a cron expression, such as "at 8:00 every Monday through Friday" or "at 1:30 on the last Friday of the month".

Format

A cron expression is 6 or 7 fields separated by white space:

Simple: * * * * ? *. Complex: 0/5 14,18,3-39,52 * ? JAN,MAR,SEP MON-FRI 2002-2010.

Special characters

• * — all values. * in the minute field is every minute.
• ? — no specific value. Day-of-month and day-of-week only, where it is a synonym for *: the field names no days. Use it to set one day field and not the other: 10 in day-of-month and ? in day-of-week fires on the 10th, whatever the weekday.
• - — a range. 10-12 in the hour field is 10, 11 and 12. A range whose end is below its start wraps: 22-2 in the hour field is 22, 23, 0, 1 and 2, and FRI-MON is Friday to Monday.
• , — a list. MON,WED,FRI in the day-of-week field is Monday, Wednesday and Friday.
• / — an increment. 0/15 in the seconds field is 0, 15, 30 and 45; 5/15 is 5, 20, 35 and 50. */n is 0/n. 1/3 in day-of-month is every 3 days starting on the 1st. A day-of-week step may start from a name: MON/2 is 2/2, Monday, Wednesday and Friday — see MON/2 is a step through the week if the expression came from 3.x.
• L — last. Its meaning depends on the field:
  • Day-of-month: the last day of the month — 31 for January, 28 for February in a non-leap year. L-3 is three days before the last day: the 28th of a 31-day month. L can be used in a list: 1,15,L is the 1st, the 15th and the last day, and L,L-1 is the last two days.
  • Day-of-week, alone: 7, Saturday. After a value: the last such day of the month — 6L is the last Friday.
• W — the weekday (Monday to Friday) nearest the given day, in day-of-month only, and only after a single day, not a range or list. 15W: a Saturday 15th fires on Friday the 14th, a Sunday 15th on Monday the 16th, a Tuesday 15th on the 15th. It never crosses into another month: 1W on a Saturday 1st fires on Monday the 3rd.
• # — the nth weekday of the month, in day-of-week. 6#3 is the third Friday, 2#1 the first Monday, 4#5 the fifth Wednesday. A month without a fifth one does not fire.
• @ — a macro naming a whole schedule: @daily is the expression. See Macros.

Forms the parser refuses

These six shapes parsed on 3.x but meant something other than what they said: a special character was dropped, or a step degenerated. 4.x throws a FormatException whose message gives the expression the author meant.

If a database may hold one of these, audit it before upgrading: Before you upgrade has the query.

MON/2 is a step through the week

Since 4.1 a textual day-of-week may take a step, and it means what its numeric twin means: MON/2 is 2/2, Monday, Wednesday and Friday. MON-FRI/2 is 2-6/2, the same three days. The step runs to Saturday and does not wrap, as after a number.

The step must be a whole number from 1 to 7, as in the numeric spelling. MON/X and SUN/9 are rejected; the message says what a step must be and where the fortnight lives now.

Macros

The @ macros are Vixie cron's, with the same meanings:

A macro needs no dialect and no opt-in. It works wherever an expression string is read: in code, in an XML scheduling file's <cron-expression>@daily</cron-expression>, in the dashboard's expression box and over the HTTP API.

ITrigger trigger = TriggerBuilder.Create()
    .WithIdentity("nightly")
    .WithCronSchedule("@daily") // stored, and shown, as "0 0 0 * * ?"
    .Build();

The expansion is what is stored: a trigger written with @daily reports 0 0 0 * * ?.

• @reboot is rejected by name: a scheduler has no reboot to fire on, so schedule the work at startup.
• Any other @name is rejected with the list above.
• There is no @every_minute or @every_second: 0 * * * * ? is already short, and H spreads load deterministically.

The Unix five-field form

An expression from a crontab, a Kubernetes CronJob or most online generators has five fields: no seconds, and days of the week numbered 0-7 from Sunday instead of 1-7. Quartz reads that form when asked, with CronFormat.Unix:

// "at 04:30 on Mondays", written the way crontab writes it
CronExpression expression = CronExpression.Parse("30 4 * * 1", CronFormat.Unix);

// ...and held the way Quartz writes it: "0 30 4 ? * MON"
string canonical = expression.CronExpressionString;

The format only changes how the string is read. Three methods take it — CronExpression.Parse, CronExpression.TryParse and CronScheduleBuilder.Create — and the result is an ordinary CronExpression:

ITrigger trigger = TriggerBuilder.Create()
    .WithIdentity("weekday-report")
    .WithSchedule(CronScheduleBuilder.Create("15 10 * * 1-5", CronFormat.Unix))
    .Build();

// WithCronSchedule has no format overload; compose one when you need its other options
ITrigger composed = TriggerBuilder.Create()
    .WithIdentity("weekday-report-2")
    .WithCronSchedule(CronExpression.Parse("15 10 * * 1-5", CronFormat.Unix))
    .Build();

A time zone composes the same way: CronExpression.Parse(s, CronFormat.Unix).WithTimeZone(tz).

crontab.guru explains a five-field expression field by field. Use it to read the string, then pass the string to CronFormat.Unix rather than translating it by hand.

Only two things differ between the dialects:

• Layout: five fields, minutes first, no seconds and no year.
• Day-of-week numbering: 0-7, with both 0 and 7 meaning Sunday. 1-5 is Monday to Friday, as in crontab, and 5 is Friday, not the Thursday it means in a Quartz expression.

The grammar is otherwise the same: L, W and # work in the five-field layout, and L alone in day-of-week is still Saturday, since it is not a number.

The format is stated, never detected. Detecting it from the field count would make a dropped field silent: 0 0 12 * * ? without its month field is 0 0 12 * ?, a valid crontab line meaning midnight on the 12th, not noon every day. The same digit also names a different day in each dialect. A five-field expression given without a format fails with an error naming the method that reads it.

An expression copied from Spring

If your expressions came from another .NET cron library

Cronos and NCrontab expressions parse here, and almost all fire at the same instants. Two differences are silent, because the expression is valid Quartz cron that means something else:

• Day-of-week numbering. Quartz numbers 1-7 with Sunday 1; those libraries number 0-6 with Sunday 0, and crontab 0-7 with both ends Sunday. 0 0 2 * * 1 is 02:00 on Sunday here and on Monday there — the same issue as a Spring expression, with the same fix: write the day as a name.
• Both day fields restricted. Quartz fires on the union of day-of-month and day-of-week, as crontab does; Cronos takes the intersection. 0 0 2 5 * MON is "the 5th, and every Monday" here and "the 5th, if it is a Monday" there. Put ? in one of the two fields to say which one applies.

Searching from 2026-08-21T00:00:00Z, against Cronos 0.11.0:

A five-field expression from those libraries is read by CronFormat.Unix, which renumbers the days: CronExpression.Parse("0 2 * * 1", CronFormat.Unix) is Monday, as its author meant. See The Unix five-field form.

H (hash) for load distribution

H ("hash") spreads triggers that share an expression. Many triggers on 0 0 0 * * ? (midnight daily) all fire at once and cause a resource spike; H in place of a value gives each trigger a different one.

H resolves to a deterministic value derived from the trigger's identity (name and group). It stays the same while the identity does, and differs between triggers.

Syntax

• H can appear in a comma-separated list with fixed values, e.g. H,30,45.
• H is not allowed in the Year field, and cannot be combined with L, W or #.

Hash examples

Usage with TriggerBuilder

Through the builder, the trigger identity is the hash seed. You must call WithIdentity(), so the hash comes from a stable name rather than a random GUID:

ITrigger trigger = TriggerBuilder.Create()
    .WithIdentity("nightly-cleanup")
    .WithCronSchedule("0 H H(0-7) * * ?")
    .Build();

Or give an explicit hash key, which needs no trigger identity. The key rides on the CronExpression, and WithCronSchedule takes one directly:

ITrigger trigger = TriggerBuilder.Create()
    .WithCronSchedule(CronExpression.ParseWithHash("0 H H(0-7) * * ?", "nightly-cleanup"))
    .Build();

CronExpression.ParseWithHash resolves the expression on its own; CronExpression.TryParseWithHash is the non-throwing form, for a key and expression from outside your control. Both take a CronFormat as their second argument for an expression not written the Quartz way:

CronExpression expr = CronExpression.ParseWithHash("0 H H(0-7) * * ?", "nightly-cleanup");

Building cron expressions programmatically

To build a schedule from user input, such as a scheduling UI with dropdowns, use the fluent CronExpressionBuilder instead of concatenating strings:

ITrigger trigger = TriggerBuilder.Create()
    .WithIdentity("myTrigger")
    .WithCronSchedule(CronExpressionBuilder.Create()
        .WithSecond(0)
        .WithMinuteIncrements(0, 15) // every 15 minutes
        .WithHourRange(8, 17)        // between 8:00 and 17:59
        .OnWeekdays())               // "0 0/15 8-17 ? * MON-FRI"
    .Build();

WithCronSchedule accepts the builder (or a built CronExpression) directly, so the chain needs no CronScheduleBuilder. Call Build() yourself when you want the CronExpression as a value.

Each field has a single-value, list, range and increment form (e.g. WithHour, WithHours, WithHourRange, WithHourIncrements). AtTime sets the second, minute and hour together from a TimeOnly; add the days beside it:

CronExpressionBuilder.Create().AtTime(new TimeOnly(9, 30));            // "0 30 9 ? * *"

CronExpressionBuilder.Create()
    .AtTime(new TimeOnly(9, 30))
    .WithDaysOfWeek(DayOfWeek.Monday, DayOfWeek.Thursday);            // "0 30 9 ? * MON,THU"

CronExpressionBuilder.Create()
    .AtTime(new TimeOnly(9, 30))
    .WithDayOfMonth(15);                                              // "0 30 9 15 * ?"

Cron resolves to a whole second, so the sub-second part of the TimeOnly is ignored.

The special characters have dedicated methods:

CronExpressionBuilder.Create().OnLastDayOfMonth();                         // "* * * L * ?"
CronExpressionBuilder.Create().OnNearestWeekdayOfMonth(15);                // "* * * 15W * ?"
CronExpressionBuilder.Create().OnNthDayOfWeekOfMonth(DayOfWeek.Friday, 3); // "* * * ? * FRI#3"
CronExpressionBuilder.Create().OnLastDayOfWeekOfMonth(DayOfWeek.Friday);   // "* * * ? * FRIL"

Rules:

• Unconfigured fields default to * (every value).
• Each field can be configured once; configuring it again throws InvalidOperationException.
• The builder uses one day field: it renders the other as ? and throws if you configure both. That is the builder's rule, not cron's. An expression naming both day fields fires on their union (0 15 10 1,2,3 * MON,FRI) and CronExpression.Parse accepts it, so write that one as text.
• Values are validated against each field's range as they are set, and Build() returns a validated CronExpression. Use ToString() if you only need the string.
• Days of the week are emitted as names (MON, FRI, ...), so the expression means the same day in cron dialects that number weekdays differently.

Checking an expression

Put an expression you were given — by a colleague, an online generator or an old configuration file — through the parser before it reaches a scheduler. CronExpression.TryParse says whether Quartz.NET can read it; GetNextValidTimeAfter says what it means:

// does Quartz.NET accept it?
if (!CronExpression.TryParse("0 0/15 8-17 ? * MON-FRI", out CronExpression? expression))
{
    throw new ArgumentException("Quartz.NET cannot read that expression");
}

// what does it mean? - the next five times it fires, in the expression's own time zone
DateTimeOffset after = DateTimeOffset.UtcNow;
for (int i = 0; i < 5; i++)
{
    DateTimeOffset? fireTime = expression.GetNextValidTimeAfter(after);
    if (fireTime is null)
    {
        break;
    }

    Console.WriteLine(TimeZoneInfo.ConvertTime(fireTime.Value, expression.TimeZone));
    after = fireTime.Value;
}

A schedule off by a day or an hour looks plausible as a string and obvious as a list of dates. This is also the only check that covers the whole dialect: H, a wrapping range (22-2, FRI-MON), MON/2 and how the two day fields combine each differ from Java Quartz, Unix cron or both, and no external tool implements them.

• GetNextValidTimeAfter returns null when there is no further fire time (for example, an expression naming a past year), so the loop stops.
• The times are DateTimeOffset. TimeZone is the zone the expression is read in (the local zone unless you passed one); converting before printing makes daylight saving time visible.
• CronExpression.Parse throws instead of returning false. Both take a CronFormat.

Examples

Daylight saving time

A cron expression names a wall-clock time, and a daylight saving transition makes a wall-clock time missing or ambiguous. Nothing is skipped and nothing fires twice. Which instant fires depends on whether the expression names a fixed time or an interval.

A fixed-time expression has plain values, or comma lists of plain values, in its second, minute and hour fields — 0 30 2 * * ?, 0 0,30 2 * * ?:

• A time the clocks skip fires once, at the end of the gap, the instant the clocks moved. A daily 0 30 2 * * ? over a 02:00-03:00 spring-forward gap fires at 03:00. Every wall-clock time in the gap names that instant, so an expression matching several of them still fires once. IsSatisfiedBy agrees with that fire time.
• A time that occurs twice on a fall-back day fires once, at the first occurrence.

An interval expression has a wildcard, a step or a range in the second, minute or hour field, such as 0 * * * * ? or 0 0/30 * * * ?. It keeps firing through the repeated hour, so both passes run. Over a spring-forward gap, the gap-end rule shows as an extra fire: 0 30 * * * ? fires at 03:00 for the occurrence the gap swallowed and at 03:30 for the next hour's.

A CronCalendar written over the skipped hour excludes the gap's end for the same reason.

Name the time zone. An expression with none uses TimeZoneInfo.Local: the developer's machine in development, and often UTC in a container. Daylight saving, clock changes and cluster skew covers the choice of trigger family, and the FAQ has more.