Ducode.Jobs 0.0.3

Ducode Jobs

Ducode Jobs (or Jobs for short) is a simple .NET library for working with asynchronous jobs. You can define a job that is long-running and/or needs to be retried on failure and Jobs takes care of the rest. The jobs will be persisted in a given store and will be executed asynchronously.

The purpose of this library is to keep things simple. By default, all jobs are executed sequentially.

Getting started

First, install the Nuget package.

Jobs works together with the .NET dependency injection. The following code is a very simple console app to add the correct services, start listening for jobs and add a simple job to the queue. This can be done in either an ASP.NET web application or a console app. Anyway, the services variable should be an implementation of the IServiceCollection interface.

using Ducode.Jobs;
using Ducode.Jobs.DI;
using Ducode.Jobs.TestUtilities;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

var services = new ServiceCollection();
services.AddLogging(cfg => cfg.AddConsole());
services.AddDucodeJobs(cfg =>
{
    // Search for the job handlers in the following assemblies.
    cfg.AddAssembly(typeof(TestJob).Assembly);
    
    // The max. number of retries a job should be retried in case of an exception.
    cfg.MaxNumberOfRetries = 10;
    
    // Whether the amount of seconds between retries should be calculated exponentially.
    cfg.ExponentialRetries = true;
    
    // The default number of seconds between retries.
    cfg.SecondsBetweenTries = 30;
});
var serviceProvider = services.BuildServiceProvider();
var scheduler = serviceProvider.GetRequiredService<IJobScheduler>();
var executor = serviceProvider.GetRequiredService<IJobExecutor>();

// Schedule a job for running.
await scheduler.EnqueueJobAsync(TestJobInput.Create("Test!!", 10));
while (true)
{
    await executor.ExecuteJobsAsync();
    await Task.Delay(5000);
}

You can use the following code as a minimal template to implement your own job. The job handling class should at least implement the IJobHandler<T> interface where T is the type of your data model.

using Ducode.Jobs.Models;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;

namespace Ducode.Jobs.TestUtilities;

public class TestJob(ILogger<TestJob>? logger = null) : IJobHandler<TestJobInput>
{
    private readonly ILogger<TestJob> _logger = logger ?? NullLogger<TestJob>.Instance;
    
    public Task<JobExecutionResult> ExecuteAsync(TestJobInput input, CancellationToken cancellationToken = default)
    {
        _logger.LogInformation($"Message received: {input.Message}");
        if (input.ShouldThrowException)
        {
            throw new InvalidOperationException("ERROR!");
        }

        return Task.FromResult(input.ShouldFail
            ? JobExecutionResult.Invalid(input.Message)
            : JobExecutionResult.Success(input.Message));
    }
}

public class TestJobInput
{
    public string Message { get; set; }

    public bool ShouldFail { get; set; }

    public bool ShouldThrowException { get; set; }

    public static JobInput Create(string message, long? executeInSeconds = null) =>
        JobInput.Create(new TestJobInput { Message = message }).ExecuteInSeconds(executeInSeconds ?? 0);
}

By default, the JobRepository is used to store the jobs. NOTE! The jobs are by default stored in memory, so read on if you want to persist the jobs in a database, file store or add your own repository to store the jobs.

Advanced

Adding a status change handler

You can add a service to your application that implements IJobStatusChangeHandler<TJobInput>. This interface contains a method called OnJobExecutedAsync. Whenever your job is executed (either because it succeeded or it failed), this method is called. You can add as many instances of IJobStatusChangeHandler as you like; each handler will be called in order. To add a handler called, for example, TestStatusChangeHandler, you create the class, implement the type and the dependency registration will find and register it for you.

You can also add a class implementing IGeneralJobStatusChangeHandler. This implementation will then be called for all jobs.

Adding a custom repository

To add a custom repository to your application for storing jobs, you can add a new service that implements IJobRepository and implement the methods. You can register a repository called, for example TestRepository, by calling the following code:

services.AddDucodeJobRepository<TestRepository>();