Cronos .NET Library

Cronos supports "schedule jitter" to distribute cron jobs randomly, spreading out system load. You can enable this by using the special character H in your cron expression and providing a seed (an integer) to the parsing method.

Important:

• If you use H in an expression but fail to provide a seed, Cronos will throw an exception.
• When H is used for the day of the month, the range is automatically limited to the first 28 days to prevent impossible dates.
• For job-scheduling scenarios, it is recommended to use a unique identifier (like a jobId.GetHashCode()) as the seed to ensure consistent jitter for that specific job.

// Example of using a seed to enable jitter
var seed = jobId.GetHashCode();

// Using H in a string expression
var hourlyExpressionWithJitter = CronExpression.Parse("H H * * * *", CronFormat.IncludeSeconds, seed);

// Using a macro with a seed
var hourlyMacroWithJitter = CronExpression.Parse("@hourly", seed);

// Using a named property with a seed
var hourlyNamedWithJitter = CronExpression.HourlyWithJitter(seed);

Cronos handles DST transitions intuitively, following Vixie Cron behavior.

Spring Transition (Clock moves forward)

If a scheduled time becomes invalid (e.g., 02:30 AM during a jump from 01:59 to 03:00), Cronos adjusts the occurrence to the next valid time.

Autumn Transition (Clock moves backward)

When the clock repeats an hour, behavior depends on the expression type:

1. Interval-based expressions: If the second, minute, or hour field contains *, ranges, or steps (e.g., */30 * * * *), the expression is treated as periodic. It will run both before and after the clock shift to maintain the interval.
2. Non-interval expressions: If the second, minute, or hour fields contain specific values without *, ranges, or steps (e.g., 0 30 1 * * *), the expression is treated as a fixed daily occurrence. It will run once, typically just before the clock shift, to avoid duplicate runs during the repeated hour.

Cronos handles time zone conversions and Daylight Saving Time (DST) transitions intuitively. You can specify a TimeZoneInfo when calculating occurrences.

Using DateTime (UTC Result)

If you pass a DateTime with DateTimeKind.Utc, the resulting occurrence will be returned in UTC.

CronExpression expression = CronExpression.Parse("* * * * *");
TimeZoneInfo easternTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");

DateTime? next = expression.GetNextOccurrence(DateTime.UtcNow, easternTimeZone);

Using DateTimeOffset (Offset-Aware Result)

If you use DateTimeOffset, the resulting object will contain the correct offset, which is critical during DST transitions.

CronExpression expression = CronExpression.Parse("* * * * *");
TimeZoneInfo easternTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");

DateTimeOffset? next = expression.GetNextOccurrence(DateTimeOffset.UtcNow, easternTimeZone);

CronExpression expression = CronExpression.Parse("* * * * *");
TimeZoneInfo easternTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");

DateTime?       next = expression.GetNextOccurrence(DateTime.UtcNow, easternTimeZone);
DateTimeOffset? next = expression.GetNextOccurrence(DateTimeOffset.UtcNow, easternTimeZone);
DateTime?       previous = expression.GetPreviousOccurrence(DateTime.UtcNow, easternTimeZone);
DateTimeOffset? previous = expression.GetPreviousOccurrence(DateTimeOffset.UtcNow, easternTimeZone);

Cronos is a .NET library for parsing Cron expressions and calculating next or previous occurrences. It is not a task scheduler; it only handles the logic of Cron expressions.

Core Usage Pattern

1. Parse a Cron expression using CronExpression.Parse().
2. Calculate the next or previous occurrence using GetNextOccurrence() or GetPreviousOccurrence().

Important: DateTime Constraints

To avoid ambiguity during Daylight Saving Time (DST) transitions, you cannot use local DateTime objects (like DateTime.Now). You must use:

• DateTime with DateTimeKind.Utc (e.g., DateTime.UtcNow)
• DateTimeOffset classes

If you attempt to use a local DateTime, an exception will be thrown.

Basic Example

using Cronos;

CronExpression expression = CronExpression.Parse("* * * * *");

// Returns the next occurrence in UTC after the given time, or null if unreachable
DateTime? nextUtc = expression.GetNextOccurrence(DateTime.UtcNow);

// Returns the most recent occurrence in UTC before the given time, or null if none exist
DateTime? previousUtc = expression.GetPreviousOccurrence(DateTime.UtcNow);

If an invalid Cron expression is provided, a CronFormatException is thrown.

You can retrieve multiple occurrences within a specific date/time range using GetOccurrences or GetOccurrencesDescending.

GetOccurrences (Forward)

Returns occurrences between from and to.

• By default, from is inclusive and to is exclusive.
• You can configure this via fromInclusive and toInclusive parameters.

CronExpression expression = CronExpression.Parse("* * * * *");
IEnumerable<DateTime> occurrences = expression.GetOccurrences(
    DateTime.UtcNow,
    DateTime.UtcNow.AddYears(1),
    fromInclusive: true,
    toInclusive: false);

GetOccurrencesDescending (Reverse)

Returns occurrences in reverse order. The from argument acts as the upper bound and the to argument acts as the lower bound.

IEnumerable<DateTime> previousOccurrences = expression.GetOccurrencesDescending(
    DateTime.UtcNow,
    DateTime.UtcNow.AddDays(-7),
    fromInclusive: true,
    toInclusive: false);