Scheduling Helpers

Helper classes for defining when and how scheduled jobs run: the Every and Cron factory classes for creating Schedule objects, the Schedule record itself, and ManifestOptions for per-job configuration.

Every

Static factory class for creating interval-based schedules.

public static class Every

The shortest interval is one second. A zero or negative count throws ArgumentOutOfRangeException at the call, since the manifest stores whole seconds and would otherwise store zero. A new interval schedule runs on the first poll after it is scheduled, then once per interval after each success.

Examples

Every.Seconds(30)   // Every 30 seconds
Every.Minutes(5)    // Every 5 minutes
Every.Hours(2)      // Every 2 hours
Every.Days(1)       // Every day

Cron

Static factory class for creating cron-based schedules with readable methods. Supports both standard 5-field (minute granularity) and 6-field (second granularity) cron formats. For complex expressions, use Cron.Expression().

Every cron time is UTC. Cron.Daily(hour: 3) runs at 03:00 UTC, whatever the host's time zone.

Each method builds its schedule through Schedule.FromCron, which parses the expression, so a value out of range throws FormatException at the call that states it: Cron.Daily(hour: 25), Cron.Hourly(minute: 60), or a malformed Cron.Expression(...). So does a valid expression with no occurrence in the next ten years, such as 0 0 30 2 * (February 30th), with a message saying it never fires; a cron that fires only in leap years is accepted. A cron stored some other way that has no occurrence at all is never due.

A new cron schedule first runs at its first occurrence after it is scheduled, not on the next poll: Cron.Daily(hour: 3) scheduled at 14:00 first runs at 03:00 the next day. Scheduling records that occurrence on the manifest's NextScheduledRun, and re-stating the same cron at a restart keeps it. A cron manifest written by an earlier Trax version that has never succeeded and has no stored NextScheduledRun is due on the next poll instead; scheduling it again, which the builder does for its own manifests at every start, records its first occurrence.

public static class Cron

When a second parameter is 0 (the default), the method produces a standard 5-field expression. When second is non-zero, it produces a 6-field expression with seconds.

Examples

// 5-field (minute granularity)
Cron.Minutely()                              // Every minute
Cron.Hourly(minute: 30)                      // Every hour at :30
Cron.Daily(hour: 3)                          // Daily at 03:00 UTC
Cron.Daily(hour: 14, minute: 30)             // Daily at 14:30 UTC
Cron.Weekly(DayOfWeek.Monday, hour: 9)       // Every Monday at 09:00 UTC
Cron.Monthly(day: 15, hour: 0)               // 15th of each month at midnight UTC
Cron.Expression("0 */6 * * *")              // Every 6 hours (custom cron)
 
// 6-field (second granularity)
Cron.Secondly()                              // Every second
Cron.Minutely(second: 30)                   // Every minute at :30 seconds
Cron.Hourly(minute: 15, second: 45)         // Every hour at 15:45
Cron.Daily(hour: 3, minute: 0, second: 30)  // Daily at 03:00:30 UTC
Cron.Expression("*/15 * * * * *")           // Every 15 seconds (custom 6-field)

Cron Expression Format

Trax supports both standard 5-field and 6-field (with seconds) cron formats. The format is auto-detected by counting fields. Expressions are evaluated in UTC.

5-field (minute granularity): minute hour day-of-month month day-of-week

6-field (second granularity): second minute hour day-of-month month day-of-week

Note: 7-field cron (with year) is not supported. The effective resolution of seconds-granularity cron is limited by the ManifestManagerPollingInterval (default: 5 seconds).

Schedule (Record)

An immutable record that represents a schedule definition. Created by Every, Cron, or the static factory methods.

public record Schedule

Properties

Factory Methods

ToCronExpression

public string ToCronExpression()

Converts the schedule to a cron expression (5-field or 6-field). For cron-type schedules, returns the expression as-is. For interval-type schedules, converts to the closest valid cron expression. Sub-minute intervals produce 6-field (seconds) cron; minute-or-above intervals produce 5-field cron.

Approximation: Cron cannot express all intervals. Intervals that don't divide evenly into 60 minutes or 60 seconds are approximated to the nearest valid cron divisor of 60 (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30).

ScheduleType Enum

MisfirePolicy Enum

Determines behavior when a scheduled run is missed.

See Misfire Policies for detailed behavior and examples.

ExclusionType Enum

Defines the kind of exclusion window for a manifest schedule. Used inside the JSONB exclusions column.

See Exclusion Windows for usage patterns and examples.

ManifestOptions

Per-item configuration passed to the configureEach callback of the batch scheduling methods (ScheduleMany, IncludeMany, ThenIncludeMany, ScheduleManyAsync, ScheduleManyDependentAsync), which receives each source item and its ManifestOptions. A single manifest, and settings shared by a whole batch, are configured through the ScheduleOptions builder instead.

public class ManifestOptions

Example

// Per item, through configureEach on a batch...
await scheduler.ScheduleManyAsync<ISyncTableTrain, SyncTableInput, Unit, string>(
    tables,
    table => ($"sync-{table}", new SyncTableInput { TableName = table }),
    Every.Minutes(5),
    configureEach: (table, opts) =>
    {
        opts.MaxRetries = table == "orders" ? 5 : 3;
        opts.Timeout = TimeSpan.FromMinutes(30);
        opts.Priority = 20;
    });
 
// ...or for a single manifest, through the ScheduleOptions builder
await scheduler.ScheduleAsync<IMyTrain, MyInput, Unit>(
    "my-job",
    new MyInput(),
    Every.Minutes(5),
    options => options.MaxRetries(5).Timeout(TimeSpan.FromMinutes(30)).Priority(20));