Introduction

cron is a UNIX tool that has been around for a long time, so its scheduling capabilities are powerful and proven. The CronTrigger class is based on the scheduling capabilities of cron.

CronTrigger uses "cron expressions", which are able to create firing schedules such as: "At 8:00am every Monday through Friday" or "At 1:30am every last Friday of the month".

Cron expressions are powerful, but can be pretty confusing. This tutorial aims to take some of the mystery out of creating a cron expression, giving users a resource which they can visit before having to ask in a forum or mailing list.

Format

A cron expression is a string comprised of 6 or 7 fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. The fields are as follows:

So cron expressions can be as simple as this: * * * * ? *

or more complex, like this: 0/5 14,18,3-39,52 * ? JAN,MAR,SEP MON-FRI 2002-2010

Special characters

• * ("all values") - used to select all values within a field. For example, * in the minute field means "every minute".

• ? ("no specific value") - allowed in the day-of-month and day-of-week fields, where it is a synonym for *: both say that the field names no days. Use it when you need to specify something in one of the two fields but not the other. For example, if I want my trigger to fire on a particular day of the month (say, the 10th), but don't care what day of the week that happens to be, I would put 10 in the day-of-month field, and ? in the day-of-week field. See the examples below for clarification.

• - - used to specify ranges. For example, 10-12 in the hour field means "the hours 10, 11 and 12".

• , - used to specify additional values. For example, MON,WED,FRI in the day-of-week field means "the days Monday, Wednesday, and Friday".

• / - used to specify increments. For example, 0/15 in the seconds field means "the seconds 0, 15, 30, and 45". And 5/15 in the seconds field means "the seconds 5, 20, 35, and 50". You can also specify / after the * character - in this case * is equivalent to having 0 before the /. 1/3 in the day-of-month field means "fire every 3 days starting on the first day of the month". A day-of-week step may start from a name: MON/2 is 2/2, Monday, Wednesday and Friday — but see MON/2 is a step through the week if the expression came from 3.x.

• L ("last") - has different meaning in each of the two fields in which it is allowed. For example, the value L in the day-of-month field means "the last day of the month" - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means "7" or "SAT". But if used in the day-of-week field after another value, it means "the last xxx day of the month" - for example 6L means "the last Friday of the month". You can also specify an offset from the last day of the month, such as L-3 which would mean the third-to-last day of the calendar month. The L option can be used in a list, but there can only be one occurrence of the L. For example 1,15,L would mean trigger on the 1st, 15th and Last Day of the month.

• W ("weekday") - used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify 15W as the value for the day-of-month field, the meaning is: "the nearest weekday to the 15th of the month". So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify 1W as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not 'jump' over the boundary of a month's days. The W character can only be specified when the day-of-month is a single day, not a range or list of days.

• # - used to specify "the nth" XXX day of the month. For example, the value of 6#3 in the day-of-week field means "the third Friday of the month" (day 6 = Friday and "#3" = the 3rd one in the month). Other examples: 2#1 = the first Monday of the month and 4#5 = the fifth Wednesday of the month. Note that if you specify #5 and there is not 5 of the given day-of-week in the month, then no firing will occur that month.

• @ - names a whole schedule instead of one field. @daily is the expression; there is nothing else in it. See Macros below for the set.

Forms the parser refuses

Six shapes parsed on 3.x and then meant something other than what they said — a special character was dropped on the floor, or a step degenerated. Each is a FormatException in 4.x, and the message names the expression that says what the author meant.

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

MON/2 is a step through the week

A textual day-of-week may be followed by a step since 4.1, and it means exactly what its numeric twin means: MON/2 is 2/2, which is 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 it does after a number.

The value after the / has to be a whole number from 1 to 7, the same one the numeric spelling takes. MON/X and SUN/9 are rejected, and the message says both what a step has to be and where the fortnight lives now.

Macros

The @ macros are the ones Unix cron has had since Vixie's, and they mean the same thing here:

A macro needs no dialect and no opt-in, so 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 gets stored: a trigger written with @daily reports its expression as 0 0 0 * * ?.

@reboot is rejected by name - a scheduler has no reboot to fire on, so schedule the work at startup instead - and any other @name is rejected with the list above. There is deliberately no @every_minute or @every_second: 0 * * * * ? is already short, and where the point is to spread load, H does it deterministically.

The Unix five-field form

A cron expression copied from a crontab, a Kubernetes CronJob or almost any online generator has five fields rather than six: it has no seconds field, and it numbers the days of the week 0-7 from Sunday rather than 1-7. Quartz reads that form when you ask it to, 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 is a way of reading the string, and that is all it is. There are three doors - CronExpression.Parse, CronExpression.TryParse and CronScheduleBuilder.Create - and past them the expression 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).

This is the one dialect an online tool describes reliably: crontab.guru explains a five-field expression field by field. Read what it tells you about the string, then hand the string to CronFormat.Unix rather than translating it by hand.

Two things differ between the dialects and nothing else does. The layout: five fields, minutes first, with no seconds and no year. The day-of-week numbering: 0-7 with both 0 and 7 meaning Sunday, so 1-5 is Monday to Friday as it is in crontab, and 5 is Friday rather than the Thursday the same digit means in a Quartz expression. Everything above is one grammar - L, W and # all work inside the five-field layout, and L alone in day-of-week still means Saturday, because it is not a number and so has nothing to renumber.

There is no auto-detection, and the field count alone does not choose the dialect. Letting it would make a dropped field silent: 0 0 12 * * ? without its month field is 0 0 12 * ?, a well-formed crontab line meaning midnight on the 12th rather than noon every day. The same digit also names a different day in each dialect. So Quartz asks, and the error a five-field expression gets when nobody asked names the method that does read it.

An expression copied from Spring

If your expressions came from another .NET cron library

Cronos and NCrontab are crontab-derived, and an expression written for either parses here — six fields have the same shape. Almost all of them also fire at the same instants. Two things differ, and both are silent, because the expression is perfectly valid Quartz cron; it simply means something else.

The day-of-week numbering. Quartz numbers 1-7 with Sunday 1; those libraries number 0-6 with Sunday 0, and crontab itself 0-7 with both ends Sunday. So 0 0 2 * * 1 is 02:00 on Sunday here and 02:00 on Monday there — the same divergence a Spring expression has, and the same answer: write the day as a name. SUN through SAT mean the same day in every one of these dialects.

Both day fields restricted. Quartz fires on the union of day-of-month and day-of-week, which is crontab's rule; Cronos takes their intersection. 0 0 2 5 * MON is "the 5th, and every Monday" here and "the 5th, if it is a Monday" there. Putting ? in one of the two fields says which one is in charge and settles it.

Everything else carries across. Searching from 2026-08-21T00:00:00Z, against Cronos 0.11.0:

A five-field expression from one of those libraries is a different matter: CronFormat.Unix reads it and renumbers the days for you, so CronExpression.Parse("0 2 * * 1", CronFormat.Unix) is Monday, as its author meant. See The Unix five-field form.

H (hash) for load distribution

The H symbol (for "hash") can be used in place of a specific value to spread scheduled tasks evenly across time. When many triggers share an identical cron expression such as 0 0 0 * * ? (midnight daily), they all fire simultaneously, causing resource spikes.

H resolves to a deterministic value derived from the trigger's identity (name and group). The value stays stable as long as the trigger identity doesn't change, but different triggers get different values, spreading load across the allowed range.

Syntax

H can appear in comma-separated lists alongside fixed values (e.g., H,30,45).

H is not supported in the Year field, and cannot be combined with L, W, or #.

Hash examples

Usage with TriggerBuilder

When using H through the builder API, the trigger identity is used as the hash seed. You must call WithIdentity() so the hash is derived from a stable, meaningful name rather than a random GUID:

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

You can also provide an explicit hash key, which does not require a 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();

Or resolve the expression on its own with CronExpression.ParseWithHash, which is the parse the builder overload does for you. CronExpression.TryParseWithHash is the non-throwing form, for a key and an expression that both came from somewhere you do not control. Both take a CronFormat as their second argument when the expression is not written the Quartz way:

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

Building cron expressions programmatically

When a schedule is assembled from user input - for example a scheduling UI that offers dropdowns instead of a free-form cron field - you can compose the expression with 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 closes without naming CronScheduleBuilder; call Build() yourself when you want the CronExpression as a value.

Each field offers a single value, list, range and increment form (e.g. WithHour, WithHours, WithHourRange, WithHourIncrements). A schedule that fires once a day sets three of those fields to say one thing, so AtTime sets them together from a TimeOnly — add the days it applies to 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 any sub-second part of the TimeOnly is ignored.

The special characters are available through 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"

A few rules to be aware of:

• Unconfigured fields default to * (every value).
• Each field can be configured only once; configuring it again throws InvalidOperationException.
• One expression carries one day field: the builder renders the unused one as ? and throws if you configure both. That is the builder's own rule rather than cron's, because an expression naming both day fields fires on the union of the two (0 15 10 1,2,3 * MON,FRI), which CronExpression.Parse accepts - so write that one as text.
• Values are validated eagerly against each field's allowed range, and Build() returns a fully validated CronExpression; use ToString() if you only need the expression string.
• Days of the week are emitted using their textual names (MON, FRI, ...), so the produced expressions stay unambiguous across cron dialects that number weekdays differently.

Checking an expression

An expression you were given - by a colleague, by an online generator, or by a configuration file written years ago - is worth putting through the parser before it reaches a scheduler. CronExpression.TryParse answers whether Quartz.NET can read it at all, and GetNextValidTimeAfter answers the more useful question of what it actually 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;
}

Printing the fire times is what catches a misread field, because a schedule that is off by a day or an hour looks perfectly plausible as a string and obvious as a list of dates. It is also the only check that covers this dialect in full: H, a range that wraps (22-2, FRI-MON), MON/2 and the way the two day fields combine are each a point where Quartz.NET parts company with Java Quartz, with Unix cron, or with both - and an external tool implements none of them.

A few things to know about the loop above:

• GetNextValidTimeAfter returns null when the expression has no further fire time - an expression naming a year that has passed, for instance - so the loop stops rather than repeating.
• The times come back as DateTimeOffset, and TimeZone is the zone the expression is read in (the local zone unless you passed one). Converting before printing is what makes daylight saving time visible.
• CronExpression.Parse is the same thing for code that would rather throw than branch, and both take a CronFormat.

Examples

Here are some full examples:

Daylight saving time

A cron expression names a wall-clock time, and a daylight saving transition is exactly the event that makes a wall clock ambiguous or missing. Nothing is skipped and nothing is fired twice, but it is worth knowing which instant is chosen, and the answer depends on whether the expression names a fixed time of day or an interval.

A fixed-time expression is one whose second, minute and hour fields are plain values or comma lists of plain values - 0 30 2 * * ?, 0 0,30 2 * * ?:

• A wall-clock 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 the gap swallowed names that one instant, so an expression matching several of them still fires once. This is the instant the expression itself matches: IsSatisfiedBy agrees with the fire time, which is what makes it the right answer.
• A wall-clock time that occurs twice on a fall-back day fires once, at the first of the two occurrences.

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

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

Whatever the schedule, name the time zone: an expression with none uses TimeZoneInfo.Local, which is the developer's machine in development and very often UTC in a container. Daylight saving, clock changes and cluster skew covers the choice of trigger family, and the FAQ has the longer treatment.