Philiprehberger.Scheduler 0.2.1

Philiprehberger.Scheduler

Lightweight in-process job scheduler with cron expressions, timezone support, execution history, and lifecycle callbacks.

Installation

dotnet add package Philiprehberger.Scheduler

Usage

Define a Job

using Philiprehberger.Scheduler;

public class CleanupJob : IScheduledJob
{
    public async Task ExecuteAsync(CancellationToken ct)
    {
        // Clean up old records
        await Task.CompletedTask;
    }
}

Register with DI

using Philiprehberger.Scheduler;

builder.Services.AddScheduler(options =>
{
    options.AddJob<CleanupJob>("*/5 * * * *"); // every 5 minutes
});

Using Attributes

using Philiprehberger.Scheduler;

[ScheduledJob("cleanup", "*/5 * * * *", TimeZone = "America/New_York")]
public class CleanupJob : IScheduledJob
{
    public async Task ExecuteAsync(CancellationToken ct)
    {
        // Runs every 5 minutes in Eastern time
        await Task.CompletedTask;
    }
}

Timezone-Aware Scheduling

using Philiprehberger.Scheduler;

builder.Services.AddScheduler(options =>
{
    // Evaluate cron in a specific timezone instead of UTC
    options.AddJob<ReportJob>("0 9 * * 1-5", timeZone: "Europe/London");
});

One-Time Scheduled Jobs

using Philiprehberger.Scheduler;

builder.Services.AddScheduler(options =>
{
    options.ScheduleOnce("send-welcome", async ct =>
    {
        // Runs once at the specified time, then auto-removes
        await SendWelcomeEmailAsync(ct);
    }, DateTimeOffset.UtcNow.AddHours(1));
});

Job Execution History

using Philiprehberger.Scheduler;

// Inject IJobHistory to query past executions
app.MapGet("/jobs/history", (IJobHistory history) =>
{
    var all = history.GetAll();
    var cleanup = history.GetHistory("cleanup");
    return Results.Ok(new { all, cleanup });
});

Job Event Callbacks

using Philiprehberger.Scheduler;

builder.Services.AddScheduler(options =>
{
    options.AddJob<CleanupJob>("*/5 * * * *");

    options.OnJobStarted = name =>
        Console.WriteLine($"Job started: {name}");

    options.OnJobCompleted = (name, duration) =>
        Console.WriteLine($"Job completed: {name} in {duration.TotalMilliseconds}ms");

    options.OnJobFailed = (name, ex) =>
        Console.WriteLine($"Job failed: {name} - {ex.Message}");
});

Cron Expressions

using Philiprehberger.Scheduler;

var cron = CronExpression.Parse("*/5 * * * *");
var next = cron.GetNextOccurrence(DateTimeOffset.UtcNow);
var matches = cron.Matches(DateTimeOffset.UtcNow);

API

IScheduledJob

CronExpression

ScheduledJobAttribute

SchedulerOptions

IJobHistory

JobExecutionRecord

CronScheduler

Development

dotnet build src/Philiprehberger.Scheduler.csproj --configuration Release

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT