Catalog My learning Blog
Full-Stack Developer Course: React, .NET and SQL Server · Phase 7 · Lesson 65 · 7 min read

.NET Background Jobs: Hosted Services and Hangfire

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: A Bounded Queue, a Hangfire Job and a Protected Dashboard
  4. Real-World Examples
  5. Review Questions & Answers

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.

ToolDurableBest for
BackgroundService with PeriodicTimerNoSimple recurring in-process work
Bounded Channel with a workerNoBest-effort offloading with backpressure
Hangfire with SQL Server storageYesRetries, schedules, dashboard, one database
Quartz.NETYesComplex schedules and calendars
Service Bus or a message brokerYesCross-service work and larger scale
Idempotency key per operationNot applicableMakes 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.

C#
// 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
        }
    }
}
C#
// 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);
C#
// 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.

Best-effort work goes through a bounded channel to a hosted service that creates a scope per job. Durable work uses Hangfire with SQL Server storage. Jobs are idempotent, carry the user and tenant explicitly, and the dashboard is protected.
Best-effort work goes through a bounded channel to a hosted service that creates a scope per job. Durable work uses Hangfire with SQL Server storage. Jobs are idempotent, carry the user and tenant explicitly, and the dashboard is protected.

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.
Key TakeawaysUse hosted services for in-process background work and bounded channels for best-effort offloading with backpressure. Use a durable scheduler such as Hangfire when work must survive restarts and retry. Make every job idempotent, pass identifiers and explicit identities, keep secrets out of payloads, protect dashboards, cap concurrency and enqueue rates, and honor the stopping token on shutdown.

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.