NOBS.JobSystem.Hosting 1.0.0

NOBS.JobSystem

A lightweight, database-backed, dependency-injection friendly job scheduling system for .NET applications. It provides CRON-based scheduling, job chaining, and a persistent execution history with an optional Blazor-based monitoring UI.

Key Features

• CRON Scheduling: Define recurring jobs using standard CRON expressions.
• Job Chaining: Create workflows by specifying continuation jobs on success or failure.
• Persistent History: Automatically tracks the last successful run time for each job in a database, ensuring schedules resume correctly after an application restart.
• DI-First Design: Jobs are resolved from the service container, giving them access to all registered application services.
• Error Handling: Configure specific jobs to run when a preceding job fails or throws an exception.
• Optional Monitoring UI: A clean, lightweight Blazor UI to monitor job statuses, last run times, and next scheduled runs.
• EF Core Migrations: The database schema for storing job history is managed automatically via Entity Framework Core migrations.

Packages

The system is distributed across three NuGet packages:

Installation

Install the hosting package for the quickest setup in an ASP.NET Core application.

dotnet add package NOBS.JobSystem.Hosting

Or, install the packages individually if you do not require the UI.

dotnet add package NOBS.JobSystem

Quick Start

1. Define Jobs

Create classes that implement the IJob interface.

// src/MyWebApp/Jobs/HelloWorldJob.cs
using NOBS.JobSystem.Abstractions;

public class HelloWorldJob(ILogger<HelloWorldJob> logger) : IJob
{
    public Task<JobExecutionResult> ExecuteAsync(CancellationToken cancellationToken)
    {
        logger.LogInformation("Hello from a scheduled job at {UtcNow}!", DateTime.UtcNow);
        return Task.FromResult(JobExecutionResult.Succeeded);
    }
}

2. Configure the Job System

In your Program.cs, add the job system, configure the database connection, and register your jobs. All jobs, including those used only for chaining, must be registered.

// src/MyWebApp/Program.cs
using NOBS.JobSystem.Hosting;

var builder = WebApplication.CreateBuilder(args);
var connectionString = builder.Configuration.GetConnectionString("JobDbConnection");

// Add services to the container.
builder.Services.AddHostedJobSystem(
    options =>
    {
        options.ConnectionString = connectionString;
        options.PollingFrequency = TimeSpan.FromSeconds(30); // Optional: Default is 1 minute
    },
    registry =>
    {
        // Register a scheduled job
        registry.AddJob<HelloWorldJob>("* * * * *");
        
        // Register jobs that are only used for chaining or error handling
        registry.AddJob<ErrorLoggingJob>();
        registry.AddJob<InitialJob>();

        // Configure a scheduled job with an error handler
        registry.AddJob<InitialJob>("0 * * * *") // Run hourly
            .OnError<ErrorLoggingJob>();         // Run ErrorLoggingJob if InitialJob fails
    }
);

var app = builder.Build();

// Map the UI endpoint
app.MapHostedJobSystemUI();

app.Run();

3. Provide a Connection String

Ensure the connection string is present in your appsettings.json.

{
  "ConnectionStrings": {
    "JobDbConnection": "Server=(localdb)\\mssqllocaldb;Database=MyJobSystemDb;Trusted_Connection=True;"
  }
}

The system will automatically create and migrate the database on startup to add its ExecutionHistory table.

Advanced Usage

Job Chaining

Jobs can trigger other jobs upon completion.

• JobExecutionResult.Success(Type nextJob): Queues a new job immediately if the current job succeeds.
• JobExecutionResult.Failure(Type nextJob): Queues a new job immediately if the current job returns a failure result.
• .OnError<TErrorJob>(): A declarative way to specify an error-handling job if the configured job throws an unhandled exception.

Important: All jobs in a chain must be registered with the JobRegistry in Program.cs to be available for dependency injection.

// Job definitions
public class DataProcessingJob : IJob
{
    public async Task<JobExecutionResult> ExecuteAsync(CancellationToken cancellationToken)
    {
        bool success = await DoSomeWorkAsync();

        if (success)
        {
            return JobExecutionResult.Success(typeof(NotificationJob));
        }

        return JobExecutionResult.Failure(typeof(CleanupJob));
    }
}
public class NotificationJob : IJob { /* ... */ }
public class CleanupJob : IJob { /* ... */ }
public class CriticalFailureAlertJob : IJob { /* ... */ }


// In Program.cs
registry.AddJob<NotificationJob>();
registry.AddJob<CleanupJob>();
registry.AddJob<CriticalFailureAlertJob>();

registry.AddJob<DataProcessingJob>("0 2 * * *") // Run daily at 2 AM
    .OnError<CriticalFailureAlertJob>();       // Run this if DataProcessingJob throws

Building From Source

1. Clone the repository:

   git clone https://github.com/scippo97sensibleproductions/NOBS.JobSystem.git
   

2. Navigate to the solution directory:

   cd NOBS.JobSystem
   

3. Build the solution:

   dotnet build
   

License

This project is licensed under the MIT License. See the LICENSE file for details.