NCrontab.Scheduler 2.0.13-pre

This is a prerelease version of NCrontab.Scheduler.
dotnet add package NCrontab.Scheduler --version 2.0.13-pre
NuGet\Install-Package NCrontab.Scheduler -Version 2.0.13-pre
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="NCrontab.Scheduler" Version="2.0.13-pre" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add NCrontab.Scheduler --version 2.0.13-pre
#r "nuget: NCrontab.Scheduler, 2.0.13-pre"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install NCrontab.Scheduler as a Cake Addin
#addin nuget:?package=NCrontab.Scheduler&version=2.0.13-pre&prerelease

// Install NCrontab.Scheduler as a Cake Tool
#tool nuget:?package=NCrontab.Scheduler&version=2.0.13-pre&prerelease

NCrontab.Scheduler

Version Downloads

NCrontab.Scheduler is a simple, open source task scheduling system that can be used in any .NET application. The main component of this project is a thread-safe scheduler which facilitates very basic scheduling operations like adding, remove or changing task schedules. NCrontab.Scheduler is built on top of NCrontab.

Download and Install NCrontab.Scheduler

This library is available on NuGet: https://www.nuget.org/packages/NCrontab.Scheduler Use the following command to install NCrontab.Scheduler using NuGet package manager console:

PM> Install-Package NCrontab.Scheduler

You can use this library in any .NET Standard or .NET Core project.

ASP.NET Core Integration

In ASP.NET Core projects, use following NuGet package: https://www.nuget.org/packages/NCrontab.Scheduler.AspNetCore Use the following command to install NCrontab.Scheduler.AspNetCore using NuGet package manager console:

PM> Install-Package NCrontab.Scheduler.AspNetCore

You can use this library in any ASP.NET Core project which is compatible to .NET Core 3.1 and higher.

API Usage

Creating a Scheduler

Scheduler implements the main scheduler operations.

Create new Scheduler instance

You can either create a new instance of Scheduler manually:

IScheduler scheduler = new Scheduler();
Access static Scheduler instance

Alternatively, you can access the provided singleton instance Scheduler.Current.

Inject Scheduler using dependency injection

Alternatively, you can register/resolve IScheduler in Microsoft's DI framework Microsoft.Extensions.DependencyInjection.

serviceCollection.AddScheduler();

This AddScheduler call regist ers IScheduler and ISchedulerFactory as singleton services which can now be injected in your code. If you prefer to have multiple instances of IScheduler across your code, inject ISchedulerFactory instead and use the Create method to create new instances of IScheduler.

Scheduler Options

The Scheduler class has an extra parameter ISchedulerOptions which allows to override the default configuration of the scheduler. If you use dependency injection, you can also configure the scheduler using the AddScheduler method:

serviceCollection.AddScheduler(o =>
{
    o.DateTimeKind = DateTimeKind.Utc;
});

Scheduler options can also be read from appSettings.json. Create a new section in your appSettings.json.

"NCrontab.Scheduler": {
    "DateTimeKind": "Utc"
},

Refer to the new configuration section when you call AddScheduler:

var configurationSection = builder.Configuration.GetSection("NCrontab.Scheduler");
builder.Services.AddScheduler(configurationSection);

Following options are available:

  • DateTimeKind: Interprets the given cron expressions as UTC or local time. Default is UTC.

Add Scheduled Tasks

Use method AddTask with all the provided convenience overloads to add tasks to the scheduler. A task is composed of a cron pattern which specifies the recurrance interval and an action (for synchronous callbacks) or a task (for asynchronous callbacks).

scheduler.AddTask(
    cronExpression: CrontabSchedule.Parse("* * * * *"),
    action: ct => { Console.WriteLine($"{DateTime.Now:O} -> Task runs every minutes"); });

scheduler.AddTask(
    cronExpression: CrontabSchedule.Parse("*/2 * * * *"),
    action: ct => { Console.WriteLine($"{DateTime.Now:O} -> Task runs every second minute"); });

scheduler.AddTask(
    cronExpression: CrontabSchedule.Parse("0 * * * *"),
    action: ct => { Console.WriteLine($"{DateTime.Now:O} -> Task runs every hour"); });
            
scheduler.AddTask(
    cronExpression: CrontabSchedule.Parse("0 0 * * *"),
    action: ct => { Console.WriteLine($"{DateTime.Now:O} -> Task runs every day at midnight"); });
            
scheduler.AddTask(
    cronExpression: CrontabSchedule.Parse("0 0 1 1 *"),
    action: ct => { Console.WriteLine($"{DateTime.Now:O} -> Task runs on Januar 1 every year"); });    

A task is identified by its Id or its Name. The Id is a Guid which can be user-defined. If it's not set, a rand Guid is used. The Name property is optional and will remain unset if it's not set. The Name property is used in log messages, if the appropriate option is enabled.

Tasks can be added to the scheduler either before or after the scheduler has been started.

A very helpful resource for creating cron expression is https://crontab.guru.

Starting and Stopping

Use method IScheduler.StartAsync to start the scheduler operations. This method can be awaited which blocks all further calls until all scheduled tasks have been canceled or removed. Use IScheduler.Start if you prefer to start the scheduler without blocking the current execution path of your program. If the scheduler is started without having added any tasks, it just waits (and blocks) until tasks are added.

Scheduled tasks can be added at runtime. If the scheduler is started without having added tasks beforehand, it logs this info: Scheduler is waiting for tasks. Use AddTask methods to add tasks.

IScheduler.Stop attempts to cancel all scheduled tasks immediately.

About Scheduling

Real-time systems are systems that are required to respond to an external event in some timely manner. "Timely manner" is often misinterpreted as "very fast". However, for many applications this just means the system needs to react in a specific time. It can be seconds, minutes, hours or even years. Schedulers such as NCrontab.Scheduler can help to satisfy such timing constraints.

Scheduler Algorithm

NCrontab.Scheduler is a classic implementation of the Earliest Deadline First (EDF) algorithm. The EDF algorithm will always schedule the task(s) whose deadline is soonest.

The scheduler provides a dynamic prioritization of tasks by evaluating the cron expressions of the tasks. Each scheduling iteration attempts to find the task with the earliest possible execution date/time.

If tasks are added or removed while waiting for the next execution, the earliest possible execution date/time is re-evaluated.

Task Overrun Condition

Task overrun conditions can happen if a scheduled task's execution time exceeds the limit of one minute. Task overrun can lead to situations where other tasks miss their projected next execution time. Consequently, each of other tasks start missing their deadlines one after the other in sequence (domino effect). This is a classic EDF scheduling problem and can lead to dangerous situations!

Thread-Safety

All scheduler operations are kept thread-safe. Adding and removing tasks as well as starting and stopping the scheduler can be done concurrently.

Task Isolation

Each task run is isolated from all other scheduled tasks. The success or failure of execution does not have any negative side effect on other scheduled tasks.

License

This project is Copyright © 2023 Thomas Galliker. Free for non-commercial use. For commercial use please contact the author.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on NCrontab.Scheduler:

Package Downloads
NCrontab.Scheduler.AspNetCore

NCrontab.Scheduler.AspNetCore is a simple, open source task scheduling system for ASP.NET applications.

SagaFlow

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.0.13-pre 251 9/20/2023
2.0.11-pre 214 9/6/2023
2.0.6-pre 167 8/31/2023
2.0.3-pre 254 8/11/2023
2.0.0-pre 182 8/10/2023
1.2.21-pre 101 12/2/2023
1.2.12-pre 178 7/26/2023
1.2.11-pre 180 7/25/2023
1.2.10 12,640 6/20/2023
1.2.8-pre 201 6/6/2023
1.2.7-pre 205 5/24/2023
1.2.5-pre 175 5/23/2023
1.2.3-pre 204 5/19/2023
1.2.1-pre 208 5/16/2023
1.1.24 1,793 4/21/2023
1.1.21-pre 201 4/20/2023
1.1.17 12,632 1/31/2023
1.1.14-pre 238 1/29/2023
1.1.10-pre 246 1/28/2023
1.1.6-pre 208 1/28/2023
1.1.4-pre 205 1/27/2023
1.1.3-pre 238 1/25/2023
1.0.47-pre 213 1/17/2023
1.0.45-pre 216 12/31/2022
1.0.44-pre 206 12/27/2022
1.0.43 4,099 8/19/2022
1.0.41-pre 284 7/23/2022
1.0.39 26,243 5/17/2022
1.0.37-pre 230 5/17/2022
1.0.35 735 5/11/2022
1.0.34-pre 261 5/6/2022
1.0.31-pre 255 5/1/2022
1.0.30-pre 241 5/1/2022
1.0.26-pre 254 4/26/2022
1.0.25-pre 229 4/26/2022
1.0.24 1,210 4/20/2022
1.0.23-pre 238 4/20/2022
1.0.22-pre 223 4/20/2022
1.0.21-pre 258 4/20/2022
1.0.20 740 4/18/2022
1.0.17-pre 233 4/18/2022
1.0.15-pre 236 4/18/2022
1.0.14-pre 270 4/17/2022
1.0.13-pre 184 4/17/2022
1.0.12-pre 164 4/17/2022
1.0.11-pre 165 4/17/2022
1.0.10-pre 166 4/17/2022
1.0.9 437 4/16/2022
1.0.7-pre 164 4/16/2022
1.0.6-pre 178 4/16/2022
1.0.5 430 4/16/2022
1.0.3-pre 166 4/16/2022
1.0.2-pre 182 4/16/2022

1.2.x
     - Add SchedulerOptions to define if cron time should be parsed in UTC or local time

     1.0.0
     - Initial release