Skip to main content
skill CX Codex

worker-services — Claude Code skill: what it does, how to install

worker-services guides the agent in building long-running .NET background services with BackgroundService, PeriodicTimer, and proper dependency scoping.

MIT ★ 521 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add managedcode/dotnet-skills --skill worker-services -a claude-code
Open on GitHub

What worker-services does

The skill instructs your coding agent on writing .NET worker processes and hosted services using Generic Host. It directs attention to ExecuteAsync in BackgroundService and emphasizes passing cancellation tokens down call stacks to avoid hung processes on shutdown.

Included workflows cover scheduled execution via PeriodicTimer, message queue workers, and health checks. Because hosted services omit ambient service scopes, the skill enforces explicit scopes through IServiceScopeFactory before resolving dependencies like database contexts.

When targeting .NET runtime v10.0.11, it advises testing cgroup-v2 memory limit behavior and cancellation paths before refactoring worker architecture unnecessarily.

What it helps with

  • build scheduled background jobs using PeriodicTimer
  • resolve scoped dependencies and database contexts via IServiceScopeFactory
  • implement graceful shutdown using CancellationToken handling
  • extract queue processing into an independent hosted worker process

Example prompts for the agent

  • Create a .NET background worker to process message queues with graceful shutdown
  • Show how to use IServiceScopeFactory inside a BackgroundService to query a database
  • Refactor this long-running worker loop to use PeriodicTimer

How to install worker-services

1Skills CLI (Vercel)

npx skills add managedcode/dotnet-skills --skill worker-services -a claude-code

2Manually: put the files in place

~/.claude/skills/worker-services/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/worker-services/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about worker-services

How to install worker-services in Claude Code?

Run npx skills add managedcode/dotnet-skills --skill worker-services -a claude-code. The file will be placed in ~/.claude/skills/worker-services/SKILL.md.

What does worker-services do?

It provides structured patterns and rules for developing .NET hosted services, background daemons, and scheduled workers with BackgroundService.

How does this skill handle scoped dependencies?

Hosted services lack an ambient scope by default, so the skill instructs the agent to inject IServiceScopeFactory and create explicit async scopes per work unit.

Source text

SKILL.md · MIT
---
name: worker-services
description: "Build long-running .NET background services with `BackgroundService`, Generic Host, graceful shutdown, configuration, logging, and deployment patterns suited to workers and daemons. USE FOR: background services; scheduled workers; hosted services; worker extraction; graceful shutdown, health checks, and service hosting review. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Requires a worker, hosted service, or background-processing scenario."
---

# .NET Worker Services

## Trigger On

- building long-running background services or scheduled workers
- adding hosted services to an app or extracting them into a worker process
- reviewing graceful shutdown, cancellation, queue processing, or health behavior

## Documentation

- [Worker Services in .NET](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers)
- [Background tasks with hosted services in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services?view=aspnetcore-10.0)
- [Create Windows Service using BackgroundService](https://learn.microsoft.com/en-us/dotnet/core/extensions/windows-service)
- [App health checks in .NET](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/diagnostic-health-checks)
- [Health checks in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-10.0)

### References

- [patterns.md](references/patterns.md) - BackgroundService patterns, graceful shutdown, and health check implementations
- [anti-patterns.md](references/anti-patterns.md) - Common worker service mistakes and how to avoid them

## Workflow

1. **Use BackgroundService as your base class:**
   - Provides standard `StartAsync`/`StopAsync` handling
   - Focus on implementing `ExecuteAsync` only
   - Proper cancellation token management built-in

2. **Handle scoped dependencies correctly:**
   - Create service scopes for scoped services
   - No scope is created by default in hosted services

3. **Implement graceful shutdown:**
   - Propagate cancellation tokens throughout
   - Complete work promptly when token fires
   - Avoid ungraceful shutdown at timeout

4. **Keep execution loop thin:**
   - Move business logic to testable services
   - Handle exceptions to prevent service crashes
   - Use `PeriodicTimer` for scheduled work

5. **Add observability:**
   - Use health checks for readiness/liveness
   - Expose metrics and structured logging
   - Consider distributed locks for multi-instance

## Current Upstream Notes

- `.NET runtime` `v10.0.11` is servicing. For workers, rerun cgroup-v2 memory-limit detection, cancellation, graceful shutdown, long-running thread-static and GC paths, NativeAOT/WASM startup where relevant, and Windows directory enumeration after upgrading rather than changing architecture by default.
- Use the refreshed Worker Services and hosted-service Learn pages for exact current hosting and health-check APIs when adding new worker entry points.

## Basic BackgroundService Pattern

### Simple Worker
```csharp
public class Worker : BackgroundService
{
    private readonly ILogger<Worker> _logger;

    public Worker(ILogger<Worker> logger)
    {
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Worker starting");

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                _logger.LogInformation("Worker running at: {Time}", DateTimeOffset.Now);
                await DoWorkAsync(stoppingToken);
                await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                // Graceful shutdown, not an error
                break;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error in worker iteration");
                // Continue or break based on error severity
            }
        }

        _logger.LogInformation("Worker stopping");
    }

    private async Task DoWorkAsync(CancellationToken cancellationToken)
    {
        // Business logic here
    }
}
```

### Using PeriodicTimer (Recommended)
```csharp
public class TimedWorker : BackgroundService
{
    private readonly ILogger<TimedWorker> _logger;
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly TimeSpan _period = TimeSpan.FromMinutes(1);

    public TimedWorker(ILogger<TimedWorker> logger, IServiceScopeFactory scopeFactory)
    {
        _logger = logger;
        _scopeFactory = scopeFactory;
    }

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

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                await using var scope = _scopeFactory.CreateAsyncScope();
                var processor = scope.ServiceProvider.GetRequiredService<IDataProcessor>();
                await processor.ProcessAsync(stoppingToken);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error processing scheduled task");
            }
        }
    }
}
```

## Handling Scoped Dependencies

### Correct Pattern with Scope Factory
```csharp
public class ScopedWorker : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ILogger<ScopedWorker> _logger;

    public ScopedWorker(IServiceScopeFactory scopeFactory, ILogger<ScopedWorker> logger)
    {
        _scopeFactory = scopeFactory;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Create scope for each unit of work
            await using var scope = _scopeFactory.CreateAsyncScope();

            var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
            var service = scope.ServiceProvider.GetRequiredService<IScopedService>();

            await service.ProcessAsync(dbContext, stoppingToken);
            await Task.Delay(TimeSpan.FromSeconds(10), stoppingToken);
        }
    }
}
```

## Queue Processing Pattern

### Message Queue Worker
```csharp
public class QueueWorker : BackgroundService
{
    private readonly ILogger<QueueWorker> _logger;
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly IBackgroundTaskQueue _taskQueue;

    public QueueWorker(
        ILogger<QueueWorker> logger,
        IServiceScopeFactory scopeFactory,
        IBackgroundTaskQueue taskQueue)
    {
        _logger = logger;
        _scopeFactory = scopeFactory;
        _taskQueue = taskQueue;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Queue Worker started");

        while (!stoppingToken.IsCancellationRequested)
        {
            var workItem = await _taskQueue.DequeueAsync(stoppingToken);

            try
            {
                await using var scope = _scopeFactory.CreateAsyncScope();
                await workItem(scope.ServiceProvider, stoppingToken);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error processing queued work item");
                // Handle poison message - retry, dead-letter, etc.
            }
        }
    }
}

// Task queue interface
public interface IBackgroundTaskQueue
{
    ValueTask QueueBackgroundWorkItemAsync(
        Func<IServiceProvider, CancellationToken, ValueTask> workItem);

    ValueTask<Func<IServiceProvider, CancellationToken, ValueTask>> DequeueAsync(
        CancellationToken cancellationToken);
}
```

## Health Checks for Workers

### Adding Health Check Endpoint
```csharp
// Program.cs
var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddHostedService<Worker>();

// Add health checks
builder.Services.AddHealthChecks()
    .AddCheck<WorkerHealthCheck>("worker_health")
    .AddResourceUtilizationHealthCheck();

// Add HTTP endpoint for health checks
builder.Services.AddHealthChecksUI();

// Or use simple TCP listener for Kubernetes
builder.Services.AddSingleton<TcpHealthProbeService>();
builder.Services.AddHostedService(sp => sp.GetRequiredService<TcpHealthProbeService>());

var host = builder.Build();
host.Run();
```

### Custom Health Check
```csharp
public class WorkerHealthCheck : IHealthCheck
{
    private readonly WorkerState _workerState;

    public WorkerHealthCheck(WorkerState workerState)
    {
        _workerState = workerState;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        if (_workerState.LastSuccessfulRun > DateTime.UtcNow.AddMinutes(-5))
        {
            return Task.FromResult(HealthCheckResult.Healthy(
                $"Last successful run: {_workerState.LastSuccessfulRun}"));
        }

        return Task.FromResult(HealthCheckResult.Unhealthy(
            $"No successful run since: {_workerState.LastSuccessfulRun}"));
    }
}

// Shared state
public class WorkerState
{
    public DateTime LastSuccessfulRun { get; set; } = DateTime.UtcNow;
    public bool IsProcessing { get; set; }
}
```

## Graceful Shutdown Pattern

### Proper Shutdown Handling
```csharp
public class GracefulWorker : BackgroundService
{
    private readonly ILogger<GracefulWorker> _logger;
    private int _currentWorkItemId;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Worker starting");

        while (!stoppingToken.IsCancellationRequested)
        {
            _currentWorkItemId = GetNextWorkItemId();

            try
            {
                // Pass cancellation token to all async operations
                await ProcessWorkItemAsync(_currentWorkItemId, stoppingToken);
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                _logger.LogInformation(
                    "Shutdown requested, stopping after work item {Id}", _currentWorkItemId);
                break;
            }
        }
    }

    public override async Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Worker stopping gracefully");
        await base.StopAsync(cancellationToken);
        _logger.LogInformation("Worker stopped");
    }
}
```

## Windows Service Deployment

### Configuring as Windows Service
```csharp
// Program.cs
var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddWindowsService(options =>
{
    options.ServiceName = "My Worker Service";
});

builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Run();
```

### Project File Settings
```xml
<Project Sdk="Microsoft.NET.Sdk.Worker">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <PublishSingleFile>true</PublishSingleFile>
    <SelfContained>true</SelfContained>
  </PropertyGroup>
</Project>
```

## Best Practices

1. **Use BackgroundService as base class** - Handles `StartAsync`/`StopAsync` boilerplate and cancellation management
2. **Create scopes for scoped dependencies** - Use `IServiceScopeFactory` to resolve scoped services like DbContext
3. **Propagate cancellation tokens everywhere** - Pass to all async methods for responsive shutdown
4. **Wrap work in try-catch** - Unhandled exceptions stop the service completely
5. **Use PeriodicTimer for timed tasks** - Cleaner than `Task.Delay` with proper cancellation support
6. **Add health checks** - Essential for Kubernetes liveness/readiness probes
7. **Avoid blocking StartAsync** - Long initialization delays other hosted services
8. **Call base methods when overriding** - Always call `await base.StartAsync()` and `await base.StopAsync()`
9. **Publish as single file for Windows Service** - Reduces deployment complexity and errors
10. **Consider scaling requirements** - Separate worker projects if independent scaling is needed

## Anti-Patterns to Avoid

| Anti-Pattern | Why It's Bad | Better Approach |
|--------------|--------------|-----------------|
| Ad-hoc `while(true)` loops | No graceful shutdown, poor lifecycle | Use `BackgroundService` |
| Ignoring cancellation token | Ungraceful shutdown, resource leaks | Propagate token to all async calls |
| Injecting scoped services directly | Captive dependencies, memory leaks | Use `IServiceScopeFactory` |
| Unhandled exceptions in `ExecuteAsync` | Silently stops the worker | Wrap in try-catch, log, continue |
| Long-running `StartAsync` | Blocks other services from starting | Move work to `ExecuteAsync` |
| `async void` methods | Crashes process on exception | Use `async Task` |
| Missing health checks | No visibility into worker status | Implement `IHealthCheck` |
| Polling with tight loops | CPU waste, no responsiveness | Use `PeriodicTimer` or event-driven |
| Not overriding `StopAsync` | Missed cleanup opportunity | Override for graceful cleanup |
| Singleton DbContext | Not thread-safe, stale data | Create scopes per operation |

## Deliver

- well-behaved worker processes and hosted services
- predictable startup and shutdown behavior
- proper scoped dependency handling
- health checks for production observability
- retry and poison-message handling for queue work

## Validate

- cancellation token propagated and shutdown honored
- scoped services resolved within proper scopes
- exception handling prevents service crashes
- health checks report accurate worker status
- runtime behavior visible through logs or telemetry
- no blocking calls in async context

© managedcode · MIT · managedcode/dotnet-skills

Similar skills

All skills for Backend and APIs →

From the same set38

The whole set →
microsoft-extensions-ai Skill for building provider-agnostic .NET AI integrations with Microsoft.Extensions.AI: chat clients, embeddings, tools, structured output, and evaluation. CX Codex +1 ★ 521repo stars mcp mcp guides building and consuming Model Context Protocol servers and clients in C# on .NET 8+, covering stdio, Streamable HTTP, and tools. CX Codex +1 ★ 521repo stars unit-test-generation The unit-test-generation prompt guides an agent through writing focused unit tests that check behavior and catch plausible bugs. Use it when adding tests to existing code or starting a new test suite. CX Codex +1 ★ 521repo stars wpf Rules and patterns for WPF apps: bindings, commands, threading, styles. Fits UI work, MVVM refactoring, or moving a project from .NET Framework to .NET. CX Codex +1 ★ 521repo stars aspire This skill guides work on Aspire AppHosts for distributed C# and TypeScript applications. Use it to wire services, configure integrations, or test an Aspire topology. CX Codex +1 ★ 521repo stars improve-skill-quality improve-skill-quality — a skill for the dotnet/skills repository that traces regressions, timeouts, activation failures, and inconclusive evaluation results back to their source. CX Codex +1 ★ 521repo stars orleans Guides Microsoft Orleans architecture by matching domain invariants to virtual actor primitives, state models, and test diagnostics. CX Codex +1 ★ 521repo stars rag rag is a Claude Code subagent that adds RAG to Microsoft Agent Framework agents, bringing search context and document citations into their answers. CX Codex ★ 521repo stars

Project sponsors

Companies that keep this analytics open