.NET Background Jobs: Hosted Services and Hangfire
On this page
Learning Objective
Run work outside the request path with hosted services, bounded in-process queues and durable job schedulers, make jobs idempotent and retry-safe, handle shutdown gracefully, and secure job identity, payloads and dashboards.
Concept Explanation
Not everything belongs in a request. Sending an email, generating a report, resizing an image, syncing with a partner system, and expiring old invitations are work that takes too long to make a user wait for, can fail and need retries, or must run on a schedule. In ASP.NET Core the basic building block is the hosted service: a class that the host starts with the application and stops when it shuts down. Deriving from BackgroundService gives you an ExecuteAsync method that runs for the lifetime of the app, in which you can loop over a queue, or wait on a PeriodicTimer to do work at intervals. Hosted services are singletons, so they must create their own scope to use scoped services such as the DbContext, as Day 15 showed.
For handing work from a request to a background worker inside the same process, System.Threading.Channels provides a fast, thread-safe queue. A bounded channel, with a maximum capacity, matters for resilience: when producers outpace the worker, a bounded queue applies backpressure, either making the producer wait or rejecting new work, instead of consuming memory without limit until the process dies. This suits best-effort tasks. The limitation is durability: everything in memory is lost when the process restarts or crashes, so anything that must not be lost, such as sending a payment confirmation, needs a durable store.
Durable job systems store jobs in a database so they survive restarts, retry with backoff, run on schedules, and can be spread across servers. Hangfire, using SQL Server as its storage, and Quartz.NET, a port of the Java Quartz scheduler, are the widely used options in .NET, and cloud services such as Azure Service Bus and Azure Functions play the same role at larger scale, as Day 66 covers. Whatever the mechanism, design jobs for the reality that they can run more than once: a worker may crash after doing the work but before recording completion, so the job is retried. Make them idempotent, by recording a unique key for each logical operation and skipping it if already done, and pass identifiers, not large objects, so the job loads current state.
Background code has its own security considerations. A job runs without a signed-in user, so it must have an explicit identity and, in a multi-tenant system, an explicit tenant, otherwise queries may run unscoped and expose or modify data across tenants. Job payloads are stored in the database and often logged, so never put secrets or sensitive personal data in them. Job dashboards, such as Hangfire's, can view and trigger jobs and must be protected by authorization, since by default many are reachable only locally, and exposing one is a way to run arbitrary registered code. Cap concurrency and enqueue rates so an attacker who triggers job creation, for example by requesting many reports, cannot flood the queue. And shut down gracefully: honor the stopping token so in-flight work finishes or is safely requeued when the host stops for a deployment.
| Tool | Durable | Best for |
|---|---|---|
| BackgroundService with PeriodicTimer | No | Simple recurring in-process work |
| Bounded Channel with a worker | No | Best-effort offloading with backpressure |
| Hangfire with SQL Server storage | Yes | Retries, schedules, dashboard, one database |
| Quartz.NET | Yes | Complex schedules and calendars |
| Service Bus or a message broker | Yes | Cross-service work and larger scale |
| Idempotency key per operation | Not applicable | Makes retries safe for any of the above |
Worked Example: A Bounded Queue, a Hangfire Job and a Protected Dashboard
The first block is an in-process worker with backpressure. The second defines an idempotent Hangfire job and locks down the dashboard. The last enqueues with a limit.
// In-process, best-effort work with a bounded queue.
public sealed class EmailQueue
{
private readonly Channel<EmailJob> _channel = Channel.CreateBounded<EmailJob>(
new BoundedChannelOptions(500) { FullMode = BoundedChannelFullMode.Wait, SingleReader = true });
public bool TryEnqueue(EmailJob job) => _channel.Writer.TryWrite(job); // false when full: tell the caller
public IAsyncEnumerable<EmailJob> ReadAllAsync(CancellationToken ct) => _channel.Reader.ReadAllAsync(ct);
}
public sealed class EmailWorker(EmailQueue queue, IServiceScopeFactory scopes, ILogger<EmailWorker> log) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
await foreach (var job in queue.ReadAllAsync(stoppingToken))
{
try
{
using var scope = scopes.CreateScope(); // scoped services need their own scope
await scope.ServiceProvider.GetRequiredService<IEmailSender>().SendAsync(job, stoppingToken);
}
catch (OperationCanceledException) { break; } // host is stopping
catch (Exception ex) { log.LogError(ex, "Email job {JobId} failed", job.Id); } // never let one job kill the loop
}
}
}// Durable jobs: Hangfire with SQL Server storage.
builder.Services.AddHangfire(c => c
.SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
.UseSimpleAssemblyNameTypeSerializer().UseRecommendedSerializerSettings()
.UseSqlServerStorage(builder.Configuration.GetConnectionString("Jobs")));
builder.Services.AddHangfireServer(o => o.WorkerCount = 4); // cap concurrency
public sealed class InvitationExpiryJob(AppDb db, TimeProvider clock)
{
[AutomaticRetry(Attempts = 5, DelaysInSeconds = new[] { 30, 120, 600, 1800, 3600 })]
public async Task RunAsync(CancellationToken ct)
{
var now = clock.GetUtcNow();
// Set-based and naturally idempotent: running twice expires nothing extra.
await db.Invitations.Where(i => i.ExpiresAt < now && i.Status == InvitationStatus.Pending)
.ExecuteUpdateAsync(s => s.SetProperty(i => i.Status, InvitationStatus.Expired), ct);
}
}
// A per-operation idempotency key for jobs that call outside systems.
public sealed class SendReceiptJob(AppDb db, IReceiptSender sender)
{
public async Task RunAsync(Guid orderId, CancellationToken ct) // pass ids, not objects, and never secrets
{
var key = $"receipt:{orderId}";
if (await db.CompletedOperations.AnyAsync(o => o.Key == key, ct)) return; // already done, a retry is harmless
await sender.SendAsync(orderId, ct);
db.CompletedOperations.Add(new CompletedOperation(key)); // unique index on Key
await db.SaveChangesAsync(ct);
}
}
var app = builder.Build();
app.MapHangfireDashboard("/admin/jobs", new DashboardOptions
{
Authorization = [new HangfireAdminOnlyFilter()], // require the SiteAdmin policy, never open
IsReadOnlyFunc = _ => true, // view only unless you truly need controls
}).RequireAuthorization("SiteAdmin");
RecurringJob.AddOrUpdate<InvitationExpiryJob>("expire-invitations", j => j.RunAsync(CancellationToken.None), Cron.Hourly);// Enqueue safely: bound how much one user can create, and identify the actor explicitly.
app.MapPost("/api/reports", (ReportRequest req, IBackgroundJobClient jobs, ICurrentUser user, IReportQuota quota) =>
{
if (!quota.TryReserve(user.Id!.Value, perHour: 5)) return Results.Problem("Report limit reached.", statusCode: 429);
var id = jobs.Enqueue<ReportJob>(j => j.RunAsync(user.Id!.Value, user.TenantId, req.Kind, CancellationToken.None));
return Results.Accepted($"/api/reports/{id}"); // 202: the work happens later
}).RequireAuthorization();Notice that the report job receives the user and tenant identifiers explicitly, since a job has no ambient HTTP context, and that the endpoint returns 202 Accepted with a location the client can poll, which is the correct status for work that has been accepted but not completed.
Real-World Examples
- BackgroundService and hosted services were introduced in ASP.NET Core 2.0 and became the standard way to run long-lived work inside a .NET host, replacing custom threads and separate Windows services for many cases. The same abstraction runs in worker service templates, containers, and Azure hosting, so the code moves between environments unchanged.
- Quartz.NET is a port of the Java Quartz Scheduler, one of the longest-established job scheduling libraries in the industry, bringing its calendar and cron scheduling model to .NET. Hangfire, chosen here for its simplicity, and Quartz cover most in-application scheduling needs before a team reaches for a broker-based system.
Review Questions & Answers
An unbounded queue lets producers add work faster than the worker can process it, so memory grows without limit until the process fails. A bounded channel applies backpressure by making producers wait or fail when full, so the system degrades in a controlled way and the caller can respond, for instance with a 429 or 503.
A job can be executed more than once, for example when a worker crashes after finishing the work but before recording completion, so the scheduler retries it. Without idempotency a retry could send a second email or charge a card twice. Recording a unique key per logical operation, or using naturally repeatable set-based updates, makes repeats harmless.
There is no authenticated request, so the job has no user or tenant unless you pass them explicitly. Running with an implicit or missing tenant can cause queries to be unscoped and to read or modify other tenants' data, and actions may be attributed to no one. Pass the actor and tenant as identifiers and set the context before running any data access.
It lists jobs and their arguments, and in many configurations lets a user trigger, retry, or delete jobs, which can run privileged code paths or reveal sensitive payloads. It must sit behind strong authorization, ideally read-only, and never be reachable by anonymous users or on an unprotected network.