klod68/gen-hosted-service

---

name: gen-hosted-service description: "Use when adding a new background service or worker to a .NET application. Generates a BackgroundService subclass, options class, DI registration, and health check — for periodic timers or Channel<T> queue-based work. Also invoke when the user mentions: background service, hosted service, IHostedService, background worker, timer-based service. Domain: Code Generation, Infrastructure. Level: Intermediate."

Generate a BackgroundService for ${1:ServicePurpose}.

Context

• Namespace root: ${2:MyApp}
• Service type: ${3:periodic | queue-processor | event-listener}
• Processing description: ${4:Brief description of what the service does}

---

Required output — generate ALL of the following:

1. Background service class

${2}.Workers.${1}Service.cs

/// <summary>
/// Background service that ${4:description}.
/// </summary>
public sealed class ${1}Service : BackgroundService
{
    private readonly IServiceProvider _serviceProvider;
    private readonly ILogger<${1}Service> _logger;

    public ${1}Service(IServiceProvider serviceProvider, ILogger<${1}Service> logger)
    {
        ArgumentNullException.ThrowIfNull(serviceProvider);
        ArgumentNullException.ThrowIfNull(logger);
        _serviceProvider = serviceProvider;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("{Service} started", nameof(${1}Service));

        // For periodic: use PeriodicTimer
        // For queue: use Channel<T>.Reader.ReadAllAsync
        // For event: use message bus subscription

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await using var scope = _serviceProvider.CreateAsyncScope();
                // Resolve scoped services here — NEVER in constructor

                // ... process one iteration
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                break; // Graceful shutdown
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "{Service} encountered an error — retrying",
                    nameof(${1}Service));
                await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
            }
        }

        _logger.LogInformation("{Service} stopped", nameof(${1}Service));
    }
}

2. Options class

${2}.Configuration.${1}Options.cs

/// <summary>
/// Configuration for <see cref="${1}Service"/>.
/// </summary>
public sealed class ${1}Options
{
    /// <summary>Interval between processing cycles (for periodic services).</summary>
    public TimeSpan Interval { get; set; } = TimeSpan.FromMinutes(5);

    /// <summary>Maximum number of items to process per batch.</summary>
    public int BatchSize { get; set; } = 100;

    /// <summary>Whether the service is enabled.</summary>
    public bool Enabled { get; set; } = true;

    public void EnsureValid()
    {
        if (Interval <= TimeSpan.Zero)
            throw new ArgumentException("Interval must be positive.", nameof(Interval));
        if (BatchSize <= 0)
            throw new ArgumentException("BatchSize must be positive.", nameof(BatchSize));
    }
}

3. DI Registration

${2}.Extensions.${1}ServiceExtensions.cs

/// <summary>
/// Registers the <see cref="${1}Service"/> background worker.
/// </summary>
public static class ${1}ServiceExtensions
{
    public static IServiceCollection Add${1}Worker(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        ArgumentNullException.ThrowIfNull(services);
        ArgumentNullException.ThrowIfNull(configuration);

        services.Configure<${1}Options>(configuration.GetSection("${1}"));
        services.AddHostedService<${1}Service>();

        return services;
    }
}

4. Channel queue class (only for queue-processor type)

${2}.Workers.${1}Queue.cs

• Channel.CreateBounded<T> with configurable capacity
• SingleReader = true, SingleWriter = false
• Public Writer and Reader properties

---

Rules

• Service class is public sealed and extends BackgroundService
• Constructor injects IServiceProvider and ILogger<T> — never scoped services
• ExecuteAsync loop catches Exception (excluding OperationCanceledException on shutdown)
• Scoped services resolved via _serviceProvider.CreateAsyncScope() per iteration
• Options follow the Options Pattern with EnsureValid()
• Guard with options.Enabled check — don't start processing if disabled
• Log start, stop, errors, and periodic summaries
• Never use Thread.Sleep or .Result — always await

---

Constraints

• Follow all rules in the workspace root instruction file
• No fire-and-forget Task.Run — all work is tracked by the host
• Respect stoppingToken in all loops and async calls
• Create one DI scope per work item or per iteration — never reuse scopes