Frank.CronJobs 2.0.9-preview

Frank.CronJobs

A simple library for running jobs on a schedule using cron expressions. Also the cron part is reusable and can be used standalone.

This library is designed to be used with the Microsoft.Extensions.DependencyInjection library, and it is designed to be as easy and simple to use as possible. It is also designed to be as flexible as possible.

It is built on the CronQuery library, but with a different API and approach.

Usage

This library is designed to be used with the Microsoft.Extensions.DependencyInjection library. It is designed to be used list this in your Program.cs file:

using Frank.CronJobs;

var services = new ServiceCollection();
services.AddCronJob<MyJob>("0 15 10 * * ?");

var serviceProvider = services.BuildServiceProvider();

await serviceProvider.StartAsync();

class MyJob : ICronJob
{
    public Task ExecuteAsync(CancellationToken cancellationToken)
    {
        Console.WriteLine("Hello, world!");
        return Task.CompletedTask;
    }
}

This will start the job at 10:15 AM every day. The MyJob class should implement the ICronJob interface, and the ExecuteAsync method should be implemented. This method will be called every time the cron expression is satisfied.

Advanced Usage

If you want to stop or modify the job, you can use the IScheuleMaintainer interface to stop, start, or modify any job at runtime like this:

var maintainer = serviceProvider.GetRequiredService<IScheduleMaintainer>();
maintainer.Stop<MyJob>();

This will stop the job from running. You can also start it again by calling Start<MyJob>(). You can also modify the schedule and timezones of the job by calling SetSchedule<MyJob>("0 15 10 * * ?") and SetTimeZone<MyJob> ("America/New_York") respectively.

The job runner is added as a hosted service, so it will run as long as the application is running.

The scenario for editing the schedule at runtime is meant to make it flexible for the user to change the schedule of the job without having to restart the application, or specify the schedule in a configuration file, and so anything that can have the opportunity to change the schedule at runtime. A service that react to IOptions changes, for example, can look like this:

public class MyService
{
    private readonly IOptionsMonitor<MyOptions> _optionsMonitor;
    private readonly IScheduleMaintainer _scheduleMaintainer;

    public MyService(IOptionsMonitor<MyOptions> optionsMonitor, IScheduleMaintainer scheduleMaintainer)
    {
        _optionsMonitor = optionsMonitor;
        _scheduleMaintainer = scheduleMaintainer;
        _optionsMonitor.OnChange(OnOptionsChange);
    }

    private void OnOptionsChange(MyOptions options)
    {
        _scheduleMaintainer.SetSchedule<MyJob>(options.CronExpression);
        // etc.
    }
}

Installation

Install the NuGet package directly from the package manager console:

PM> Install-Package Frank.CronJobs

License

Frank.CronJobs is licensed under the MIT license.

Contributing

Contributions are welcome, please submit a pull request after you create an issue if you have any ideas or find any bugs. Major changes should be discussed in an issue before submitting a pull request. Also, no new dependencies unless discussed and agreed upon in an issue first.

Credits

This library is based on CronQuery, which I am a contributor to. This is built on that code for the basic cron functionality, and some patterns and ideas are borrowed from that project. This is however a separate implementation, and the code is not shared between the two projects. CronQuery has a lot longer history and is better tested, so I recommend using that library if you need a more stable and tested library; I made this library because I wanted to register the jobs in the DI container and its schedule at the same time, which is not possible with CronQuery nor would I presume it would be a good idea to do so in that library.