Background workers are commonly used in ASP.NET Core applications to process queued messages, send notifications, generate reports, synchronize data, and execute scheduled operations.
These workers often run continuously while the application is active.
The problem appears when the application needs to stop.
A deployment replaces an application instance. A container platform terminates a Pod. An administrator restarts a service. In each situation, the application may receive a shutdown signal while a background worker is processing an important operation.
If the worker does not handle shutdown correctly, it may leave work incomplete, lose messages, hold database connections, or create duplicate processing when another instance picks up the same job.
Consider a background worker that processes payment notifications.
It reads a message from a queue, calls an external payment provider, updates the database, and acknowledges the message.
If the application stops between the database update and message acknowledgement, the message may be delivered again.
If the application acknowledges the message before completing the database update, the operation may be lost.
The solution is not simply to stop the worker as quickly as possible. The worker needs a controlled shutdown process that stops accepting new work, allows safe operations to finish when possible, releases resources, and preserves unfinished work for recovery.
ASP.NET Core provides IHostedService and BackgroundService for implementing background workloads. Understanding their lifecycle and cancellation behavior is essential for building reliable workers.
Understand the ASP.NET Core Hosted Service Lifecycle
ASP.NET Core uses the hosting infrastructure to manage application startup and shutdown.
A background service can be implemented using IHostedService or by inheriting from BackgroundService.
IHostedService defines two important methods:
StartAsync starts the hosted service.
StopAsync requests the hosted service to stop.
BackgroundService provides an implementation of the hosted service lifecycle and allows developers to place long-running work inside ExecuteAsync.
A basic background service looks like this:
public class NotificationWorker : BackgroundService
{
private readonly ILogger<NotificationWorker> _logger;
public NotificationWorker(
ILogger<NotificationWorker> logger)
{
_logger = logger;
}
protected override async Task ExecuteAsync(
CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
_logger.LogInformation(
"Notification worker is running.");
await Task.Delay(
TimeSpan.FromSeconds(5),
stoppingToken);
}
}
}Register the worker:
builder.Services.AddHostedService<NotificationWorker>();The host starts the worker when the application starts and signals it to stop when the application shuts down gracefully.
The cancellation token passed to ExecuteAsync is important.
It is cancelled when the host requests the background service to stop.
The worker should observe this token and finish its ongoing work within the available shutdown time.
Ignoring the token can cause the application to exceed its graceful shutdown period.
Understand What Happens During Application Shutdown
Application shutdown is not always immediate.
When the host begins a graceful shutdown, it signals hosted services to stop.
The host waits for their background operations to finish, subject to the configured shutdown timeout.
For the Generic Host, the default shutdown timeout is 30 seconds.
This does not mean every background operation automatically receives 30 seconds to finish. The time is shared across the shutdown process and can be affected by other hosted services and shutdown configuration.
If the application does not finish shutting down within the available period, the hosting environment may eventually terminate the process.
There is another important detail: graceful shutdown cannot be guaranteed in every situation.
If the process crashes, the machine loses power, or the container is terminated forcefully, StopAsync may never complete or may not be called at all.
Therefore, a background worker should never depend on StopAsync as its only mechanism for preserving important work.
Important operations must be recoverable even when the application stops unexpectedly.
Stop Accepting New Work Before Finishing Existing Work
A reliable shutdown process should separate two responsibilities:
Stop accepting new work.
Complete or safely abandon work that is already in progress.
Suppose a worker continuously reads messages from a queue.
When shutdown begins, it should stop requesting additional messages. However, if it is already processing a message, it may be able to complete that operation before exiting.
A simplified worker can follow this structure:
protected override async Task ExecuteAsync(
CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
try
{
var message = await ReadNextMessageAsync(
stoppingToken);
if (message is null)
{
continue;
}
await ProcessMessageAsync(
message,
stoppingToken);
}
catch (OperationCanceledException)
when (stoppingToken.IsCancellationRequested)
{
break;
}
}
_logger.LogInformation(
"Background worker is stopping.");
}The example assumes that ReadNextMessageAsync and ProcessMessageAsync correctly support cancellation.
However, cancellation behavior must be designed carefully.
If ProcessMessageAsync is cancelled after performing an external side effect but before recording completion, the same message may be processed again.
That is why stopping safely also requires idempotent processing and durable message acknowledgement.
Use Cancellation Tokens Throughout the Operation
A common mistake is observing cancellation only in the main worker loop.
For example:
while (!stoppingToken.IsCancellationRequested)
{
await ProcessBatchAsync();
}If ProcessBatchAsync takes several minutes and does not accept a cancellation token, the worker cannot respond promptly to shutdown.
Pass the token through the complete operation:
private async Task ProcessBatchAsync(
CancellationToken cancellationToken)
{
await LoadPendingItemsAsync(cancellationToken);
await CallExternalServiceAsync(cancellationToken);
await SaveResultsAsync(cancellationToken);
}The same principle applies to database queries, HTTP requests, delays, and queue operations.
For example:
await httpClient.GetAsync(
"https://api.example.com/status",
cancellationToken);For Entity Framework Core:
var items = await dbContext.Orders
.Where(x => x.Status == "Pending")
.ToListAsync(cancellationToken);Passing the cancellation token allows supported operations to stop when shutdown begins.
However, cancellation is cooperative. A method that ignores the token may continue running.
Also, cancellation does not automatically undo an operation that has already been committed by a database or external service.
The application must define what happens when shutdown occurs between individual processing steps.
Use a Scoped Dependency Injection Scope for Each Batch
Hosted services are registered as long-lived services.
They are not automatically created with a new dependency injection scope for every processing operation.
This becomes important when a background worker depends on scoped services such as DbContext or other request-scoped components.
Injecting a scoped service directly into a singleton hosted service can create lifetime problems.
A common solution is to inject IServiceScopeFactory and create a scope for each batch.
public class OrderWorker : BackgroundService
{
private readonly IServiceScopeFactory _scopeFactory;
private readonly ILogger<OrderWorker> _logger;
public OrderWorker(
IServiceScopeFactory scopeFactory,
ILogger<OrderWorker> logger)
{
_scopeFactory = scopeFactory;
_logger = logger;
}
protected override async Task ExecuteAsync(
CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
try
{
await using var scope =
_scopeFactory.CreateAsyncScope();
var processor = scope.ServiceProvider
.GetRequiredService<OrderProcessor>();
await processor.ProcessPendingOrdersAsync(
stoppingToken);
}
catch (OperationCanceledException)
when (stoppingToken.IsCancellationRequested)
{
break;
}
catch (Exception ex)
{
_logger.LogError(
ex,
"Error processing pending orders.");
}
await Task.Delay(
TimeSpan.FromSeconds(10),
stoppingToken);
}
}
}
Join the conversation! Your thoughts help the community grow.