klod68/background-hosted-service

---

name: background-hosted-service description: "Use when implementing background work, queued processing, or recurring tasks, or when replacing fire-and-forget Task.Run calls that lose exceptions silently. Covers BackgroundService with PeriodicTimer, Channel<T> for high-performance producer-consumer pipelines, IServiceScopeFactory for per-iteration DI scopes, and graceful shutdown with CancellationToken propagation. Domain: Infrastructure, Concurrency, Worker Patterns. Level: Intermediate. Tags: background-service, hosted-service, channels, worker, periodic-timer."

Background & Hosted Services

Problem

Without a structured approach to background work:

• Long-running tasks block request threads, causing timeouts
• Fire-and-forget Task.Run calls lose exceptions silently
• Background workers don't shut down gracefully, causing data loss
• Producer-consumer patterns are hand-rolled with ConcurrentQueue + polling loops
• DI scopes leak or are absent in background threads

Solution: BackgroundService + System.Threading.Channels

Use the IHostedService / BackgroundService infrastructure for managed background work, and Channel<T> for high-performance producer-consumer patterns.

Implementation

Tier 1: Periodic Timer Service

public sealed class CleanupService : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly ILogger<CleanupService> _logger;
    private readonly TimeSpan _interval = TimeSpan.FromMinutes(30);

    public CleanupService(IServiceProvider serviceProvider, ILogger<CleanupService> logger)
    {
        _serviceProvider = serviceProvider;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(_interval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                await using var scope = _serviceProvider.CreateAsyncScope();
                var repository = scope.ServiceProvider.GetRequiredService<IOrderRepository>();

                var cleaned = await repository.CleanupExpiredOrdersAsync(stoppingToken);
                _logger.LogInformation("Cleaned {Count} expired orders", cleaned);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                _logger.LogError(ex, "Cleanup failed — will retry at next interval");
            }
        }
    }
}

Tier 2: Channel-Based Queue Processor

// 1. Define the channel as a singleton service
public sealed class EmailQueue
{
    private readonly Channel<EmailMessage> _channel =
        Channel.CreateBounded<EmailMessage>(new BoundedChannelOptions(1000)
        {
            FullMode = BoundedChannelFullMode.Wait,
            SingleReader = true,
            SingleWriter = false
        });

    public ChannelWriter<EmailMessage> Writer => _channel.Writer;
    public ChannelReader<EmailMessage> Reader => _channel.Reader;
}

// 2. Producer (in request handler)
public class OrderService
{
    private readonly EmailQueue _emailQueue;

    public async Task PlaceOrderAsync(Order order, CancellationToken ct)
    {
        // ... save order
        await _emailQueue.Writer.WriteAsync(
            new EmailMessage(order.CustomerEmail, "Order Confirmed", $"Order #{order.Id}"),
            ct);
    }
}

// 3. Consumer (background service)
public sealed class EmailSenderService : BackgroundService
{
    private readonly EmailQueue _queue;
    private readonly IServiceProvider _serviceProvider;
    private readonly ILogger<EmailSenderService> _logger;

    public EmailSenderService(EmailQueue queue, IServiceProvider serviceProvider,
        ILogger<EmailSenderService> logger)
    {
        _queue = queue;
        _serviceProvider = serviceProvider;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var message in _queue.Reader.ReadAllAsync(stoppingToken))
        {
            try
            {
                await using var scope = _serviceProvider.CreateAsyncScope();
                var sender = scope.ServiceProvider.GetRequiredService<IEmailSender>();
                await sender.SendAsync(message, stoppingToken);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                _logger.LogError(ex, "Failed to send email to {Recipient}", message.To);
                // Optionally: re-enqueue with retry count
            }
        }
    }
}

Tier 3: Event-Driven Listener

public sealed class OrderEventListener : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly ILogger<OrderEventListener> _logger;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await using var scope = _serviceProvider.CreateAsyncScope();
        var bus = scope.ServiceProvider.GetRequiredService<IMessageBus>();

        await bus.SubscribeAsync<OrderPlaced>(async (message, ct) =>
        {
            await using var innerScope = _serviceProvider.CreateAsyncScope();
            var handler = innerScope.ServiceProvider.GetRequiredService<IOrderPlacedHandler>();
            await handler.HandleAsync(message, ct);
        }, stoppingToken);
    }
}

DI Registration

// Periodic timer
builder.Services.AddHostedService<CleanupService>();

// Channel-based queue
builder.Services.AddSingleton<EmailQueue>();
builder.Services.AddHostedService<EmailSenderService>();

// Options-driven interval
builder.Services.Configure<CleanupOptions>(builder.Configuration.GetSection("Cleanup"));

When to Use

• Periodic tasks: cleanup, sync, health polling, report generation.
• Queue processing: email sending, notification dispatch, event publishing.
• Event listeners: message bus consumers, webhook processors.
• Any fire-and-forget work that currently uses Task.Run without error handling.

When NOT to Use

• CPU-intensive work that should run on a separate worker process, not in the web host.
• Short-lived operations that can complete within the request lifecycle — just use await.
• Distributed job scheduling — use Hangfire, Quartz.NET, or Azure Functions instead.

Gotchas

1. Unobserved exceptions kill the host: An unhandled exception in ExecuteAsync terminates the entire application in .NET 6+. ALWAYS wrap the loop body in try/catch and log errors. Never let exceptions escape.
2. Blocking in ExecuteAsync: Synchronous blocking (Thread.Sleep, .Result) starves the thread pool. Always use await with PeriodicTimer, Channel.ReadAllAsync, or Task.Delay.
3. DI scope issues: BackgroundService is a singleton. Never inject scoped services (DbContext, repositories) via constructor. Create a scope per iteration: _serviceProvider.CreateAsyncScope().
4. Graceful shutdown: The stoppingToken is cancelled when the host shuts down. Respect it in loops. PeriodicTimer.WaitForNextTickAsync and Channel.ReadAllAsync handle this automatically.
5. Channel backpressure: Use BoundedChannelOptions with a reasonable capacity. Unbounded channels can eat all memory if the consumer is slower than the producer.
6. Multiple consumers: Set SingleReader = false if you need parallel consumers, but then ensure your processing logic is thread-safe.

Related Skills

• Retry with Exponential Backoff (retry failed background operations)
• Distributed Logging & Correlation (trace background work with Activity)
• Health Check Endpoint (report background service health status)