Aspnet Background Services

Representative direction:

public class OrderProcessingWorker : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ILogger<OrderProcessingWorker> _logger;

    public OrderProcessingWorker(
        IServiceScopeFactory scopeFactory,
        ILogger<OrderProcessingWorker> 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<IOrderProcessor>();
                await processor.ProcessPendingOrdersAsync(stoppingToken);
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                break;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error processing orders");
            }

            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}

Channel-Based Queue Processing

• Use Channel<T> for in-process producer-consumer patterns.
• Register the channel as a singleton and inject it into both producers (API endpoints) and consumers (background service).
• Use bounded channels with back-pressure to prevent unbounded memory growth.
• Complete the channel writer during shutdown.

Representative direction:

// Registration
builder.Services.AddSingleton(Channel.CreateBounded<WorkItem>(new BoundedChannelOptions(100)
{
    FullMode = BoundedChannelFullMode.Wait
}));

// Consumer (BackgroundService)
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    await foreach (var item in _channel.Reader.ReadAllAsync(stoppingToken))
    {
        await ProcessItemAsync(item, stoppingToken);
    }
}

Periodic Timer Services

• Use PeriodicTimer (.NET 6+) for scheduled work instead of Task.Delay in a loop.
• The timer respects the interval between ticks and does not drift.

Representative direction:

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    using var timer = new PeriodicTimer(TimeSpan.FromMinutes(5));

    while (await timer.WaitForNextTickAsync(stoppingToken))
    {
        await DoScheduledWorkAsync(stoppingToken);
    }
}

Scoped Services in Background Work

• Background services are registered as singletons; they cannot inject scoped services directly.
• Use IServiceScopeFactory to create a scope per unit of work.
• Dispose the scope after the work completes.

Hosted Lifecycle Services (.NET 8+)

• Use IHostedLifecycleService for services that need hooks at Starting, Started, Stopping, and Stopped phases.
• Use this when initialization or cleanup work must happen at specific lifecycle points.

Graceful Shutdown

• Respect the CancellationToken passed to ExecuteAsync or StopAsync.
• Complete in-progress work or abandon it cleanly when cancellation is requested.
• Configure HostOptions.ShutdownTimeout if background work needs more than the default 30 seconds to finish.
• Log shutdown events for operational visibility.

Error Handling

• Catch and log exceptions within the execution loop; do not allow them to terminate the service silently.
• For transient failures, use a delay or exponential backoff before retrying.
• For fatal errors that cannot be recovered, log and allow the host to shut down.
• In .NET 8+, configure BackgroundServiceExceptionBehavior.Ignore only if the service handles its own errors.

Hangfire (Preferred for Scheduled and Persistent Jobs)

Prefer Hangfire over BackgroundService with PeriodicTimer when the workload needs:

• Persistent job storage (survives restarts).
• Built-in dashboard for monitoring and manual retry.
• Recurring schedules with cron expressions.
• Automatic retries with configurable attempt counts.
• Continuations and job chaining.

Setup

• Add Hangfire.Core, Hangfire.AspNetCore, and a storage package (e.g., Hangfire.SqlServer, Hangfire.PostgreSql, Hangfire.InMemory for dev).
• Register Hangfire in DI and map the dashboard endpoint.
• Protect the dashboard with authorization in non-development environments.

Representative direction:

builder.Services.AddHangfire(config => config
    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
    .UseSimpleAssemblyNameTypeSerializer()
    .UseRecommendedSerializerSettings()
    .UseSqlServerStorage(builder.Configuration.GetConnectionString("Hangfire")));

builder.Services.AddHangfireServer();

app.MapHangfireDashboard("/hangfire", new DashboardOptions
{
    Authorization = [new HangfireDashboardAuthFilter()]
});

Fire-and-Forget Jobs

• Use BackgroundJob.Enqueue or IBackgroundJobClient.Enqueue for one-off async work triggered by an API request.
• Keep job methods small, idempotent, and safe to retry.

BackgroundJob.Enqueue<IEmailService>(svc => svc.SendWelcomeEmailAsync(userId, CancellationToken.None));

Recurring Jobs

• Use RecurringJob.AddOrUpdate with a cron expression for periodic work.
• Give every recurring job a stable, descriptive ID.
• Use AddOrUpdate at startup so the schedule is always current.

RecurringJob.AddOrUpdate<IReportService>(
    "daily-sales-report",
    svc => svc.GenerateDailySalesReportAsync(CancellationToken.None),
    Cron.Daily(hour: 6, minute: 0));

Preventing Overlapping Recurring Executions

When a recurring job iteration must not start while the previous one is still running, apply [DisableConcurrentExecution] combined with [AutomaticRetry(Attempts = 0)] so a skipped execution does not queue a retry.

public class ReportService : IReportService
{
    [DisableConcurrentExecution(timeoutInSeconds: 0)]
    [AutomaticRetry(Attempts = 0)]
    public async Task GenerateDailySalesReportAsync(CancellationToken cancellationToken)
    {
        // Long-running work — safe from overlapping invocations.
        await BuildReportAsync(cancellationToken);
    }
}

• timeoutInSeconds: 0 means the new invocation does not wait for the lock — if the previous run holds it, the new one is skipped immediately.
• Set AutomaticRetry(Attempts = 0) so a skipped execution is not retried later, which would defeat the purpose.
• For distributed deployments, the lock is storage-backed — it works across multiple server instances.

Delayed Jobs

• Use BackgroundJob.Schedule for work that should run after a delay.

BackgroundJob.Schedule<IOrderService>(
    svc => svc.CancelUnpaidOrderAsync(orderId, CancellationToken.None),
    TimeSpan.FromHours(1));

Continuations

• Use BackgroundJob.ContinueJobWith to chain jobs.

var parentId = BackgroundJob.Enqueue<IImportService>(svc => svc.ImportDataAsync(CancellationToken.None));
BackgroundJob.ContinueJobWith<INotificationService>(parentId,
    svc => svc.NotifyImportCompleteAsync(CancellationToken.None));

Hangfire Best Practices

• Keep job methods idempotent — jobs may be retried on failure.
• Accept CancellationToken in job methods for cooperative cancellation during shutdown.
• Do not capture large objects or HttpContext in job arguments; pass IDs and resolve data inside the job.
• Use job filters (IServerFilter, IElectStateFilter) for cross-cutting concerns like logging or tenant context.
• Store the Hangfire connection string separately from the application database when possible.
• Monitor the dashboard for stuck or failed jobs in production.

Review Priorities

1. CancellationToken is respected for graceful shutdown.
2. Scoped services are resolved through IServiceScopeFactory (for BackgroundService) or through Hangfire's built-in DI activation (for Hangfire jobs).
3. Exceptions are caught, logged, and do not crash the host unexpectedly.
4. Queue-based processing uses bounded channels with back-pressure.
5. Recurring jobs use Hangfire with [DisableConcurrentExecution] when overlap is not safe.
6. Hangfire dashboard is protected with authorization in production.
7. Job methods are idempotent and safe to retry.

Completion Criteria

• Background services start and stop cleanly with the host.
• Work loops handle cancellation and errors correctly.
• Scoped dependencies are resolved per unit of work.
• Queue-based patterns use bounded channels.
• Scheduled and recurring jobs use Hangfire with persistent storage.
• Recurring jobs that must not overlap use [DisableConcurrentExecution] with [AutomaticRetry(Attempts = 0)].
• Hangfire dashboard is accessible and secured.
• Graceful shutdown completes within the configured timeout.