A Job Scheduler sitting on top of IHostedService
in dotnet.
Often times one finds themself between the simplicity of the BackgroundService
/IHostedService
and the complexity of
a full-blown Hangfire
or Quartz
scheduler.
This library aims to fill that gap by providing a simple and easy to use job scheduler that can be used in any dotnet
application and feels "native".
So no need for setting up a database, just schedule your stuff right away! The library gives you two ways of scheduling jobs:
- Instant jobs - just run a job right away
- Cron jobs - schedule a job using a cron expression
- NCronJob
- The ability to schedule jobs using a cron expression
- The ability to instantly run a job
- Parameterized jobs - instant as well as cron jobs!
- Integrated in ASP.NET - Access your DI container like you would in any other service
- Get notified when a job is done (either successfully or with an error).
- Retries - If a job fails, it will be retried.
As this is a simple scheduler, some features are not included by design. If you need these features, you might want to
look into a more advanced scheduler like Hangfire
or Quartz
.
- Job persistence - Jobs are not persisted between restarts of the application.
- Job history - There is no history of jobs that have been run.
- Progress state - There is no way to track the progress of a job. The library will support notifying when a job is done, but not the progress of the job itself.
- The job scheduler always uses UTC time. We might change that in the future.
- Import the namespace (or let your IDE do the dirty work)
using LinkDotNet.NCronJob;
- Create a job
public class PrintHelloWorld : IJob
{
private readonly ILogger<PrintHelloWorld> logger;
public PrintHelloWorld(ILogger<PrintHelloWorld> logger)
{
this.logger = logger;
}
public Task RunAsync(JobExecutionContext context, CancellationToken token)
{
logger.LogInformation("Hello World");
logger.LogInformation("Parameter: {Parameter}", context.Parameter);
return Task.CompletedTask;
}
}
- Register the NCronJob and the job in your
Program.cs
builder.Services.AddNCronJob(options =>
options.AddJob<PrintHelloWorld>(j =>
{
// Every minute and optional parameter
j.WithCronExpression("* * * * *")
.WithParameter("Hello World");
}));
- Run your application and see the magic happen
If the need arises and you want to trigger a job instantly, you can do so:
public class MyService
{
private readonly IInstantJobRegistry jobRegistry;
public MyService(IInstantJobRegistry jobRegistry) => this.jobRegistry = jobRegistry;
public void MyMethod() => jobRegistry.RunInstantJob<MyJob>("I am an optional parameter");
}
NCronJob provides a way to get notified when a job is done. For this, implement a IJobNotificationHandler<TJob>
and register it in your DI container.
builder.Services.AddNCronJob(options =>
options.AddCronJob<PrintHelloWorld>(j =>
{
// Every minute and optional parameter
j.WithCronExpression("* * * * *")
.WithParameter("Hello World");
})
.AddNotificationHandler<MyJobNotificationHandler, PrintHelloWorld>());
This allows to run logic after a job is done. The JobExecutionContext
and the Exception
(if there was one) are
passed to the Handle
method.
public class MyJobNotificationHandler : IJobNotificationHandler<MyJob>
{
private readonly ILogger<MyJobNotificationHandler> logger;
public MyJobNotificationHandler(ILogger<MyJobNotificationHandler> logger)
{
this.logger = logger;
}
public Task HandleAsync(JobExecutionContext context, Exception? exception, CancellationToken token)
{
if (exception is not null)
{
logger.LogError(exception, "Job failed");
}
else
{
logger.LogInformation("Job was successful");
logger.LogInformation("Output: {Output}", context.Output);
}
return Task.CompletedTask;
}
}
The new Retry support provides a robust mechanism for handling transient failures by retrying failed operations. This feature is implemented using the RetryPolicy
attribute that can be applied to any class implementing the IJob
interface.
The RetryPolicy
attribute allows you to specify the number of retry attempts and the strategy for handling retries. There are two built-in retry strategies:
- ExponentialBackoff: Increases the delay between retry attempts exponentially.
- FixedInterval: Keeps the delay between retry attempts consistent.
Here are examples of how to use the built-in retry policies:
[RetryPolicy(retryCount: 4)]
public class RetryJob(ILogger<RetryJob> logger) : IJob
{
public async Task RunAsync(JobExecutionContext context, CancellationToken token)
{
var attemptCount = context.Attempts;
if (attemptCount <= 3)
{
logger.LogWarning("RetryJob simulating failure.");
throw new InvalidOperationException("Simulated operation failure in RetryJob.");
}
logger.LogInformation($"RetryJob with Id {context.Id} was attempted {attemptCount} times.");
await Task.CompletedTask;
}
}
[RetryPolicy(4, PolicyType.FixedInterval)]
public class FixedIntervalRetryJob(ILogger<FixedIntervalRetryJob> logger) : IJob
{
public async Task RunAsync(JobExecutionContext context, CancellationToken token)
{
var attemptCount = context.Attempts;
if (attemptCount <= 3)
{
logger.LogWarning("FixedIntervalRetryJob simulating failure.");
throw new InvalidOperationException("Simulated operation failure in FixedIntervalRetryJob.");
}
logger.LogInformation($"FixedIntervalRetryJob with Id {context.Id} was attempted {attemptCount} times.");
await Task.CompletedTask;
}
}
You can also create custom retry policies by implementing the IPolicyCreator
interface. This allows you to define complex retry logic tailored to your specific needs.
[RetryPolicy<MyCustomPolicyCreator>(retryCount:4, delayFactor:1)]
public class CustomPolicyJob(ILogger<CustomPolicyJob> logger) : IJob
{
public async Task RunAsync(JobExecutionContext context, CancellationToken token)
{
var attemptCount = context.Attempts;
if (attemptCount <= 3)
{
logger.LogWarning("FixedIntervalRetryJob simulating failure.");
throw new InvalidOperationException("Simulated operation failure in FixedIntervalRetryJob.");
}
logger.LogInformation($"CustomPolicyJob with Id {context.Id} was attempted {attemptCount} times.");
await Task.CompletedTask;
}
}
public class MyCustomPolicyCreator : IPolicyCreator
{
public IAsyncPolicy CreatePolicy(int maxRetryAttempts = 3, double delayFactor = 2)
{
return Policy.Handle<Exception>()
.WaitAndRetryAsync(maxRetryAttempts,
retryAttempt => TimeSpan.FromSeconds(Math.Pow(delayFactor, retryAttempt)));
}
}
Concurrency support allows multiple instances of the same job type to run simultaneously, controlled by the SupportsConcurrency
attribute. This feature is crucial for efficiently managing jobs that are capable of running in parallel without interference.
By default jobs are not executed concurrently if the SupportsConcurrency
attribute is not set.
The SupportsConcurrency
attribute specifies the maximum degree of parallelism for job instances. This means you can define how many instances of a particular job can run concurrently, optimizing performance and resource utilization based on the nature of the job and the system capabilities.
Here is an example of how to apply this attribute to a job:
[SupportsConcurrency(10)]
public class ConcurrentJob : IJob
{
private readonly ILogger<ConcurrentJob> logger;
public ConcurrentJob(ILogger<ConcurrentJob> logger)
{
this.logger = logger;
}
public async Task RunAsync(JobExecutionContext context, CancellationToken token)
{
logger.LogInformation($"ConcurrentJob with Id {context.Id} is running.");
// Simulate some work by delaying
await Task.Delay(5000, token);
logger.LogInformation($"ConcurrentJob with Id {context.Id} has completed.");
}
}
When using concurrency, it's essential to ensure that each job instance is idempotent. This means that even if the job is executed multiple times concurrently or sequentially, the outcome and side effects should remain consistent, without unintended duplication or conflict.
Jobs that are marked to support concurrency should be designed carefully to avoid contention over shared resources. This includes, but is not limited to, database connections, file handles, or any external systems. In scenarios where shared resources are unavoidable, proper synchronization mechanisms or concurrency control techniques, such as semaphores, mutexes, or transactional control, should be implemented to prevent race conditions and ensure data integrity.
If you want to schedule a job multiple times, you can do so by calling utilizing the builder:
Services.AddNCronJob(options =>
options.AddJob<PrintHelloWorld>(j =>
{
j.WithCronExpression("* * * * *")
.WithParameter("Hello World")
.And
.WithCronExpression("0 * * * *")
.WithParameter("Hello World Again");
}));
The NCronJob scheduler can be configured to log at a specific log level.
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"LinkDotNet.NCronJob": "Debug"
Version 2 of NCronJob brings some breaking changes to mae a better API.
- In
v1
one would define as such:
services.AddNCronJob();
services.AddCronJob<PrintHelloWorld>(options =>
{
options.CronExpression = "* * * * *";
options.Parameter = "Hello World";
});
With v2
the CronExpression
is moved towards the builder pattern and AddCronJob
is merged into AddNCronJob
:
Services.AddNCronJob(options =>
{
options.AddJob<PrintHelloWorld>(j =>
{
j.WithCronExpression("* * * * *")
.WithParameter("Hello World");
});
});
This allows to easily define multiple jobs without adding much boilerplate code.
Services.AddNCronJob(options =>
{
options.AddJob<PrintHelloWorld>(p => p
.WithCronExpression("0 * * * *").WithParameter("Foo")
.And
.WithCronExpression("0 0 * * *").WithParameter("Bar"));
});
Thanks to all contributors and people that are creating bug-reports and valuable input: