jaytwo.BackgroundCron 0.1.0-beta-20251115221000

jaytwo.BackgroundCron

Lightweight, resilient, and distributed-friendly cron job scheduling for .NET.

jaytwo.BackgroundCron provides a framework for scheduling recurring tasks in ASP.NET Core applications using cron expressions and time zones. It integrates with IHostedService, supports distributed locking, and allows flexible configuration.

This library is designed to simplify reliable scheduling of background jobs in .NET Core apps without needing external schedulers. It emphasizes idempotent, resilient execution across potentially distributed environments.

View source on GitHub

Features

• Uses standard Unix cron expressions (e.g. "0 6 * * *" = daily at 6am)
• Time zone–aware scheduling using TZDB time zones, including daylight saving time support (e.g. America/Los_Angeles, Europe/London)
• Distributed locking support for multi-instance deployments
• Runtime task toggling via ProcessorEnabledCallback (e.g. for feature flags)
• Supports using IDistributedCache as a timestamp store
• Configurable behavior for missed executions (e.g. skip or catch up)
• Health check interface for schedule metadata and task-specific status

Background

Occasionally, I need to schedule a recurring task in my application—something simple, like running a job every day at 6am.

I don’t want to maintain a separate scheduler app (e.g. Hangfire). I need it to work across multiple instances. I don’t want to worry about the details of scheduling, locking, or time zones. The goal is to make it work simply and reliably.

Cron is the de facto standard for scheduling, and the Time Zone Database is the de facto standard for time zone handling—so I built this library on top of both.

Rolling your own BackgroundService starts out easy enough—that’s exactly how this project began! But soon, you’re dealing with things like:

• Time zones and daylight saving time transitions
• Ensuring the task only runs once, even when deployed across multiple instances

After copying and pasting the same boilerplate into a few different projects, I decided to extract the logic into a reusable library.

Don’t get me wrong—Hangfire is great, but it’s a bit heavy-handed for a simple recurring task. Quartz.NET is also a powerful scheduler, but getting it to work reliably across multiple instances takes a bit more effort. Both are far more mature and widely adopted than this little tool will ever be—but for my use case, I just wanted something lightweight that worked.

Installation

Add the NuGet package:

PM> Install-Package jaytwo.BackgroundCron

Usage

1. Create your task processor

Implement the ICronTaskProcessor interface:

public class SampleCronTaskProcessor : ICronTaskProcessor
{
    private readonly ILogger _logger;

    public SampleCronTaskProcessor(ILogger<SampleCronTaskProcessor> logger)
    {
        _logger = logger;
    }

    public Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation($"{nameof(SampleCronTaskProcessor)} Executed.");
        return Task.CompletedTask;
    }

    public Task<object> HealthCheckAsync(CancellationToken stoppingToken = default)
    {
        object result = new { hello = "world" };
        return Task.FromResult(result);
    }
}

2. Configure in appsettings.json

To run at 6am daily in the America/Denver time zone:

// in appsettings.json:

{
  "SampleCronTask": {
    "TaskName": "MyTask",
    "CronExpression": "0 6 * * *",
    "TimeZoneId": "America/Denver"
  }
}

3. Register services in Program.cs or Startup.cs

Be sure to register the required dependencies, including:

• An IDistributedLockProvider
• Either an ITimestampStore or IDistributedCache

builder.Services.AddSingleton<IDistributedCache, MemoryDistributedCache>(); // For demo/single-instance deployments only
builder.Services.AddSingleton<IDistributedLockProvider, InProcessLockProvider>(); // For demo/single-instance deployments only
builder.Services.AddBackgroundCronService<SampleCronTaskProcessor>("SampleCronTask"); // Matches the config section name in appsettings.json

For production use, implement IDistributedLockProvider and IDistributedCache (or a custom ITimestampStore) with persistent, shared infrastructure like Redis or a distributed database.

Health Check Example

This is useful for exposing runtime status to observability tools or dashboards.

Optionally expose task status through an API:

public class HomeController : Controller
{
    private readonly SampleCronTaskProcessor _processor;
    private readonly BackgroundCronService<SampleCronTaskProcessor> _cronService;

    public HomeController(SampleCronTaskProcessor processor, BackgroundCronService<SampleCronTaskProcessor> cronService)
    {
        _processor = processor;
        _cronService = cronService;
    }

    [Route("/health")]
    public async Task<object> Index(CancellationToken token) => new
    {
        SampleCronTaskProcessor = await _processor.HealthCheckAsync(token),
        BackgroundCronService = await _cronService.HealthCheckAsync(token),
    };
}

Notes

• Tasks are run in-process. For long-running or unreliable operations, ensure idempotency and use retry logic as needed.
• Multiple tasks can be registered with separate configuration sections.
• RunOnMissedExecution allows running the most recent missed execution if the app was offline (earlier missed runs are skipped).
• Task execution is automatically skipped if already executed by another instance.
• Timestamp and lock keys are uniquely scoped per task name and processor type.

Made with ♥ by Jake — Licensed under the MIT License