EngUtil.Hosting.CronJob 1.0.0-beta.1

EngUtil.Hosting.CronJob

A lightweight cron job hosting library for .NET applications with configuration support, error handling and scheduling integration.

Packages

Installation

dotnet add package EngUtil.Hosting.CronJob

For the optional ASP.NET Core management endpoints:

dotnet add reference .\EngUtil.Hosting.CronJob.Extension\EngUtil.Hosting.CronJob.AspNetCore.csproj

Note: the ASP.NET Core extension project currently exists in this repository as a project/package named EngUtil.Hosting.CronJob.AspNetCore. If you publish it to NuGet later, replace the command above with dotnet add package EngUtil.Hosting.CronJob.AspNetCore.

Getting Started

1. Implement a Cron Job

Derive from CronJobBase and decorate the class with [CronJob]:

[CronJob("0 * * * *", disabled: false, runOnStartUp: true, errorThreshold: 5)]
public class MyHourlyCronJob : CronJobBase
{
    public MyHourlyCronJob(IServiceProvider services, ILogger<MyHourlyCronJob> logger)
        : base(services, logger)
    {
        DoWorkAction = async cancellationToken =>
        {
            Logger.LogInformation("Job executed at {Time}", DateTimeOffset.Now);
            await Task.CompletedTask;
        };
    }
}

If you use TaskCompletionSource, ensure it is completed or linked to the provided CancellationToken so the job can shut down cleanly:

DoWorkAction = async cancellationToken =>
{
    var tcs = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
    using var registration = cancellationToken.Register(() => tcs.TrySetCanceled(cancellationToken));

    // trigger completion from your async callback/event handler
    // tcs.TrySetResult();

    await tcs.Task;
};

2. Register & Start

// Program.cs
var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddCronJobs();

var app = builder.Build();
app.StartCronJobs();
await app.RunAsync();

AddCronJobs() registers all discovered cron job types as singletons and StartCronJobs() initializes and schedules them.

Cron Expression Format

Standard 5-field cron format is supported:

┌───────────── minute  (0–59)
│ ┌─────────── hour    (0–23)
│ │ ┌───────── day     (1–31)
│ │ │ ┌─────── month   (1–12)
│ │ │ │ ┌───── day of week (0–7, 0 and 7 = Sunday)
│ │ │ │ │
* * * * *

An optional 6-field format (with leading seconds field) and a 7-field format (with trailing year) are also accepted.

Special Characters

The parser also treats both 0 and 7 as Sunday.

Examples

Configuration

Inline (Attribute)

All parameters are defined directly on [CronJob]:

[CronJob(
    cronExpression: "0 8 * * 1-5",
    disabled: false,
    runOnStartUp: false,
    visible: true,
    errorThreshold: 5,
    errorThresholdResetTime: 60)]
public class MyJob : CronJobBase { … }

External (appsettings.json)

Supply a custom config type to load settings from IConfiguration:

[CronJob(typeof(MyJobConfig))]
public class MyExternalCronJob : CronJobBase { … }

// appsettings.json
{
  "CronJobs": {
    "MyExternalCronJob": {
      "CronExpression": "0 6 * * *",
      "Disabled": false,
      "RunOnStartup": true,
      "ErrorThreshold": 3,
      "ErrorThresholdResetTime": 30
    }
  }
}

Configuration lookup is performed under:

• CronJobs:{FullTypeName}
• fallback: CronJobs:{TypeName}

Error Handling

Subscribe to the ErrorOccurred event on any job instance or on ICronJobProvider:

var provider = app.Services.GetRequiredService<ICronJobProvider>();
provider.ErrorOccurred += (sender, args) =>
{
    Console.Error.WriteLine($"[{args.JobType}] Error: {args.Exception.Message}");
};

When the number of consecutive errors reaches ErrorThreshold, the job stops scheduling itself automatically. If ErrorThresholdResetTime is set to a value greater than 0, the error counter resets after the specified number of minutes and the job can be restarted automatically.

Cancellation via the provided CancellationToken is treated as a normal shutdown path and not as an execution error.

ASP.NET Core Management Endpoints

The optional EngUtil.Hosting.CronJob.AspNetCore package adds a REST API for runtime management.

Setup

Reference the ASP.NET Core extension project/package and then register the endpoints in your WebApplication:

// Program.cs
app.AddCronJobEnpoints();

With authorization:

app.AddCronJobEnpoints(o =>
{
    o.RequireAuthorization = true;
    o.Policy = "CronJobAdmin"; // optional named policy
});

Endpoints

All endpoints are registered under /api/CronJob:

The GET /api/CronJob endpoint returns only jobs where Visible == true.

Target Frameworks

License

This project is licensed under the MIT License.
© 2019–2026 Oliver Engels