Calabonga.Microservices.BackgroundWorkers
3.2.0
See the version list below for details.
dotnet add package Calabonga.Microservices.BackgroundWorkers --version 3.2.0
NuGet\Install-Package Calabonga.Microservices.BackgroundWorkers -Version 3.2.0
<PackageReference Include="Calabonga.Microservices.BackgroundWorkers" Version="3.2.0" />
<PackageVersion Include="Calabonga.Microservices.BackgroundWorkers" Version="3.2.0" />
<PackageReference Include="Calabonga.Microservices.BackgroundWorkers" />
paket add Calabonga.Microservices.BackgroundWorkers --version 3.2.0
#r "nuget: Calabonga.Microservices.BackgroundWorkers, 3.2.0"
#:package Calabonga.Microservices.BackgroundWorkers@3.2.0
#addin nuget:?package=Calabonga.Microservices.BackgroundWorkers&version=3.2.0
#tool nuget:?package=Calabonga.Microservices.BackgroundWorkers&version=3.2.0
BackgroundWorkers
Background Workers for Microservices on ASP.NET Core. Contains Scoped, Scheduled and Periodic workers
Installation and sample
You can install from nuget-package Calabonga.Microservices.BackgroundWorkers. Also you can see the using sample on the github
dotnet add package Calabonga.Microservices.BackgroundWorkers
How it works
Scoped worker. ScopedHostedServiceBase is an IHostedService that runs your code in an endless loop with a 5-second pause between iterations until the application stops. Every iteration gets its own DI scope, so you can safely resolve scoped services such as DbContext from the serviceProvider argument. An exception thrown inside an iteration is logged with the ILogger you passed to the constructor, and the worker keeps running; only cancellation on application shutdown stops the loop.
public sealed class CleanupWorker : ScopedHostedServiceBase
{
public CleanupWorker(IServiceScopeFactory serviceScopeFactory, ILogger<CleanupWorker> logger)
: base(serviceScopeFactory, logger) { }
protected override async Task ProcessInScopeAsync(IServiceProvider serviceProvider, CancellationToken token)
{
var repository = serviceProvider.GetRequiredService<IOrderRepository>();
await repository.DeleteExpiredAsync(token);
}
}
Scheduled worker. ScheduledHostedServiceBase adds a CronTab schedule on top of the scoped worker: it checks the schedule every 5 seconds and calls ProcessInScopeAsync when the next occurrence has come. Provide the cron expression in Schedule and a name in DisplayName. Set IncludingSeconds to true to use the 6-field format with seconds, and IsExecuteOnServerRestart to true to run once 5 seconds after the application starts. Since version 3.0.0 the schedule and the public NextRun property are in UTC, not in the server's local time. Missed occurrences are not replayed, and the schedule accuracy is about 5 seconds. The schedule is parsed in the base constructor, so overridden properties must return constant values and must not depend on fields of your class.
public sealed class DailyReportWorker : ScheduledHostedServiceBase
{
public DailyReportWorker(IServiceScopeFactory serviceScopeFactory, ILogger<DailyReportWorker> logger)
: base(serviceScopeFactory, logger) { }
// every day at 03:00 UTC
protected override string Schedule => "0 3 * * *";
protected override string DisplayName => "Daily report";
protected override bool IsExecuteOnServerRestart => true;
protected override async Task ProcessInScopeAsync(IServiceProvider serviceProvider, CancellationToken token)
{
var reports = serviceProvider.GetRequiredService<IReportService>();
await reports.BuildDailyReportAsync(token);
}
}
Periodic worker. PeriodicHostedServiceBase (since version 3.2.0) runs your code repeatedly with a random interval instead of a fixed schedule. Set the unit in PeriodType (Minutes or Hours) and the bounds in MinValue and MaxValue: after each run the next interval is chosen randomly between them, inclusive, with whole-minute precision, and is counted from the start of the run. For example, 3–4 hours gives intervals like 3:00, 3:07, 3:59 or 4:00, and 10–15 minutes gives 10, 11, …, 15 minutes. Unlike the scheduled worker, the settings are read when the worker starts, not in the constructor, so they can come from options injected into your class; invalid values (MinValue less than 1, MaxValue less than MinValue) throw WorkerArgumentOutOfRangeException and stop the host from starting. IsExecuteOnServerRestart, IsDelayBeforeStart and NextRun work the same way as in the scheduled worker.
// appsettings.json
{
"DatabaseReview": {
"MinHours": 3,
"MaxHours": 4
}
}
public sealed class ReviewOptions
{
public int MinHours { get; set; } = 3;
public int MaxHours { get; set; } = 4;
}
public sealed class DatabaseReviewWorker : PeriodicHostedServiceBase
{
private readonly ReviewOptions _options;
public DatabaseReviewWorker(IServiceScopeFactory serviceScopeFactory, ILogger<DatabaseReviewWorker> logger, IOptions<ReviewOptions> options)
: base(serviceScopeFactory, logger)
{
_options = options.Value;
}
// every 3-4 hours, values from the "DatabaseReview" section of appsettings.json
protected override PeriodType PeriodType => PeriodType.Hours;
protected override int MinValue => _options.MinHours;
protected override int MaxValue => _options.MaxHours;
protected override string DisplayName => "Database review";
protected override bool IsExecuteOnServerRestart => true;
protected override async Task ProcessInScopeAsync(IServiceProvider serviceProvider, CancellationToken token)
{
var viewer = serviceProvider.GetRequiredService<IDatabaseViewer>();
await viewer.CheckDatabaseAsync(token);
}
}
Registration. Workers are ordinary hosted services, so register them with AddHostedService<T>(): the host starts them together with the application and cancels them on shutdown. The library targets netstandard2.1 and depends only on Microsoft.Extensions.*.Abstractions, Microsoft.Bcl.TimeProvider and ncrontab, so it works with any .NET host, not only ASP.NET Core. For a custom loop you can inherit HostedServiceBase directly and override ProcessAsync (and ExecuteAsync to change the timing).
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHostedService<CleanupWorker>();
builder.Services.AddHostedService<DailyReportWorker>();
builder.Services.Configure<ReviewOptions>(builder.Configuration.GetSection("DatabaseReview"));
builder.Services.AddHostedService<DatabaseReviewWorker>();
var app = builder.Build();
app.Run();
Testing. Since version 3.1.0 every base class has a constructor overload that accepts TimeProvider: the workers read the current time and wait between checks only through it (the old constructors use TimeProvider.System). Pass a FakeTimeProvider from Microsoft.Extensions.TimeProvider.Testing in tests to check your schedule instantly, without real 5-second waits. Each Advance that passes a 5-second check triggers one iteration of the loop. PeriodicHostedServiceBase also has an overload with Random: pass a seeded or custom Random to make the chosen intervals predictable.
public sealed class DailyReportWorker : ScheduledHostedServiceBase
{
public DailyReportWorker(IServiceScopeFactory serviceScopeFactory, ILogger<DailyReportWorker> logger, TimeProvider timeProvider)
: base(serviceScopeFactory, logger, timeProvider) { }
// ...
}
// registration: TimeProvider must be available in DI
builder.Services.TryAddSingleton(TimeProvider.System);
// test
var time = new FakeTimeProvider(new DateTimeOffset(2026, 1, 15, 10, 0, 0, TimeSpan.Zero));
var worker = new DailyReportWorker(scopeFactory, logger, time);
Assert.Equal(new DateTime(2026, 1, 16, 3, 0, 0), worker.NextRun);
| Product | Versions 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. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.1 is compatible. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.1
- Microsoft.Bcl.TimeProvider (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
- ncrontab (>= 3.3.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 3.2.1 | 228 | 10/4/2026 |
| 3.2.0 | 132 | 9/27/2026 |
| 3.1.0 | 100 | 9/27/2026 |
| 3.0.0 | 110 | 9/27/2026 |
| 2.0.3 | 1,948 | 6/28/2023 |
| 2.0.2 | 1,663 | 2/9/2023 |
| 2.0.1 | 916 | 2/9/2023 |
| 2.0.0 | 917 | 2/9/2023 |
| 1.0.5 | 1,890 | 12/3/2021 |
| 1.0.4 | 2,248 | 10/8/2020 |
| 1.0.3 | 1,250 | 10/6/2020 |
| 1.0.2 | 1,198 | 9/24/2020 |
| 1.0.1 | 1,488 | 9/3/2020 |
| 1.0.0 | 1,535 | 8/3/2020 |
| 1.0.0-beta2 | 1,054 | 4/20/2020 |
| 1.0.0-beta1 | 1,108 | 4/20/2020 |
New PeriodicHostedServiceBase: runs periodically with a random interval between MinValue and MaxValue (PeriodType.Minutes or PeriodType.Hours, inclusive, whole minutes).