DioRed.Common.Jobs 3.0.1

DioRed.Common.Jobs

Lightweight in-process scheduling primitives for one-time and recurring jobs (.NET 10+).

Key types

• ISchedule - stateless schedule definition.
• Built-in schedules:
  • OneTimeSchedule
  • IntervalSchedule
  • DailySchedule (specific TimeZoneInfo, including DST)
  • LocalTimeDailySchedule (uses TimeZoneInfo.Local)
  • CronSchedule (5- or 6-field CRON)
• Job - runs an async/sync delegate according to a schedule.

Schedule contract

ISchedule.GetNextOccurrence(DateTimeOffset after) returns the next occurrence that is strictly greater than after. Return null when the schedule is exhausted.

Breaking note

DailySchedule now accepts TimeZoneInfo instead of a fixed UTC offset.

Old shape:

new DailySchedule(new TimeOnly(7, 40), TimeSpan.FromHours(2))

New shape:

new DailySchedule(
    new TimeOnly(7, 40),
    TimeZoneInfo.FindSystemTimeZoneById("Europe/Riga")
)

This change was made so daily schedules can follow real time zone rules and handle DST correctly.

Ambiguous local times during DST fall-back are resolved to the first matching occurrence.

Example (interval)

using DioRed.Common.Jobs;

var job = new Job(
    action: async ct =>
    {
        // Your work here
        await Task.Delay(250, ct);
    },
    schedule: new IntervalSchedule(TimeSpan.FromMinutes(5)),
    options: new JobOptions
    {
        MaxOccurrences = null, // run until cancelled
        TimeProvider = TimeProvider.System
    }
);

job.Scheduled += (_, e) => Console.WriteLine($"Next: {e.NextOccurrence:o}");
job.OccurrenceStarted += (_, e) => Console.WriteLine($"Start #{e.OccurrenceNumber} at {e.StartedAt:o}");
job.OccurrenceFinished += (_, e) => Console.WriteLine($"Finish #{e.OccurrenceNumber} ({e.Duration})");
job.Faulted += (_, e) => Console.WriteLine($"Faulted: {e.Exception}");

var task = job.StartAsync();

// Later:
// job.Cancel();

await task;

Example (cron)

Every day at 03:30 local time:

var job = new Job(
    action: ct => DoSomethingAsync(ct),
    schedule: new CronSchedule("30 3 * * *"),
    options: new JobOptions { MaxOccurrences = null }
);

await job.StartAsync();

Every 10 seconds in UTC:

var job = new Job(
    action: ct => TickAsync(ct),
    schedule: new CronSchedule("*/10 * * * * *", TimeZoneInfo.Utc)
);

await job.StartAsync();

CRON notes

• Supported fields: *, lists (1,2,3), ranges (1-5), steps (*/5, 1-10/2).
• Month names: JAN..DEC, day names: SUN..SAT.
• Day-of-month and day-of-week follow traditional cron semantics:
  • if one of them is a wildcard, the other must match
  • if both are restricted, match if either matches (OR)
  • you can use ? to mark the field as "no specific value".

Misfire handling

If the job wakes up after a scheduled time (for example, machine sleep / long GC pause), it detects a misfire when:

now - scheduledFor > MisfireThreshold (defaults to 1 second).

Choose behavior with JobOptions.MisfirePolicy:

• Skip (default) — skip missed occurrences.
• FireOnce — run once immediately, then continue from "now".
• CatchUp — run missed occurrences sequentially (up to MaxCatchUpExecutions), then continue.

var job = new Job(
    action: ct => WorkAsync(ct),
    schedule: new CronSchedule("0 */5 * * *"),
    options: new JobOptions
    {
        MisfirePolicy = MisfirePolicy.CatchUp,
        MaxCatchUpExecutions = 5,
        MisfireThreshold = TimeSpan.FromSeconds(2)
    }
);

job.Misfired += (_, e) => Console.WriteLine($"Late by {e.Lateness} (policy: {e.Policy})");
await job.StartAsync();