klod68/gen-worker-service

---

name: gen-worker-service description: "Use when creating a new .NET Worker Service project for background processing, scheduled tasks, or long-running daemons. Generates a full project scaffold: BackgroundService, options class, health check, and DI registration. Also invoke when the user mentions: worker service, new worker project, dotnet worker, background processor project. Domain: Code Generation, Infrastructure. Level: Intermediate."

Generate a Worker Service for ${1:ServicePurpose}.

Context

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

---

Required output — generate ALL of the following:

1. Worker class

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

/// <summary>
/// Background worker that ${4:description}.
/// </summary>
internal sealed class ${1}Worker : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly IOptions<${1}Options> _options;
    private readonly ILogger<${1}Worker> _logger;
    private readonly ${1}HealthCheck _healthCheck;

    public ${1}Worker(
        IServiceScopeFactory scopeFactory,
        IOptions<${1}Options> options,
        ILogger<${1}Worker> logger,
        ${1}HealthCheck healthCheck)
    {
        ArgumentNullException.ThrowIfNull(scopeFactory);
        ArgumentNullException.ThrowIfNull(options);
        ArgumentNullException.ThrowIfNull(logger);
        ArgumentNullException.ThrowIfNull(healthCheck);
        _scopeFactory = scopeFactory;
        _options = options;
        _logger = logger;
        _healthCheck = healthCheck;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var config = _options.Value;
        config.EnsureValid();

        if (!config.Enabled)
        {
            _logger.LogInformation("{Worker} is disabled — exiting", nameof(${1}Worker));
            return;
        }

        _logger.LogInformation("{Worker} started with interval {Interval}",
            nameof(${1}Worker), config.Interval);

        using var timer = new PeriodicTimer(config.Interval);

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                await using var scope = _scopeFactory.CreateAsyncScope();
                // Resolve scoped services from scope.ServiceProvider

                // ... process one iteration

                _healthCheck.RecordSuccess();
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                break;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "{Worker} failed during iteration", nameof(${1}Worker));
                _healthCheck.RecordFailure();
            }
        }

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

2. Options class

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

/// <summary>
/// Configuration for <see cref="${1}Worker"/>.
/// </summary>
public sealed class ${1}Options
{
    /// <summary>Whether the worker is enabled.</summary>
    public bool Enabled { get; set; } = true;

    /// <summary>Interval between processing cycles.</summary>
    public TimeSpan Interval { get; set; } = TimeSpan.FromMinutes(5);

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

    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. Health check

${2}.HealthChecks.${1}HealthCheck.cs

/// <summary>
/// Reports whether <see cref="${1}Worker"/> is alive and making progress.
/// </summary>
internal sealed class ${1}HealthCheck : IHealthCheck
{
    private DateTime _lastSuccess = DateTime.UtcNow;
    private readonly TimeSpan _threshold = TimeSpan.FromMinutes(15);

    public void RecordSuccess() => _lastSuccess = DateTime.UtcNow;
    public void RecordFailure() { /* optional: track consecutive failures */ }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var elapsed = DateTime.UtcNow - _lastSuccess;
        var result = elapsed < _threshold
            ? HealthCheckResult.Healthy($"Last success {elapsed.TotalSeconds:F0}s ago")
            : HealthCheckResult.Unhealthy($"No success for {elapsed.TotalMinutes:F0} minutes");

        return Task.FromResult(result);
    }
}

4. DI registration

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

/// <summary>
/// Registers the <see cref="${1}Worker"/> background service.
/// </summary>
public static class ${1}WorkerExtensions
{
    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.AddSingleton<${1}HealthCheck>();
        services.AddHealthChecks().AddCheck<${1}HealthCheck>("${1:kebab}");
        services.AddHostedService<${1}Worker>();

        return services;
    }
}

5. appsettings section

{
  "${1}": {
    "Enabled": true,
    "Interval": "00:05:00",
    "BatchSize": 100
  }
}

---

Rules

• Worker class is internal sealed and extends BackgroundService
• Constructor injects IServiceScopeFactory, IOptions<T>, ILogger<T>, health check — never scoped services
• Use PeriodicTimer for interval-based work — never Task.Delay in a loop
• Create async scope per iteration — never reuse scopes
• Respect stoppingToken in all loops and async calls
• Health check tracks last-success timestamp for liveness monitoring
• Options follow the Options Pattern with EnsureValid()
• Guard with Enabled flag — disabled workers exit immediately

---

Constraints

• Follow all rules in the workspace root instruction file and the worker-service rule file
• No fire-and-forget Task.Run — all work is tracked by the host
• Never use Thread.Sleep or .Result