dotnet-worker-services

Build long-running .NET background services with BackgroundService, graceful shutdown, and health checks.

Updated Mar 31, 2026
One-click install
npx skills add https://github.com/zhenpengLai/myuseskill --skill dotnet-worker-services-zhenpenglai
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dotnet-worker-services
Source: https://github.com/zhenpengLai/myuseskill/tree/main/dotnet-worker-services
Command: npx skills add https://github.com/zhenpengLai/myuseskill --skill dotnet-worker-services-zhenpenglai

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building reliable long-running background services in .NET requires handling cancellation, scoped dependencies, graceful shutdown, and observability correctly—mistakes lead to silent crashes, resource leaks, and ungraceful terminations. ## Core Features & Use Cases - BackgroundService Patterns: Implement workers using BackgroundService, PeriodicTimer, queue consumers, and event-driven designs with proper cancellation token propagation. - Graceful Shutdown & Health Checks: Configure shutdown timeouts, override StopAsync for cleanup, and expose liveness/readiness probes for Kubernetes deployments. - Anti-Pattern Detection: Identify and fix common mistakes like captive scoped dependencies, async void methods, tight polling loops, and unhandled exceptions. - Use Case: You need to extract a background job from an ASP.NET Core app into a standalone worker process that consumes a queue, handles poison messages, and reports health to Kubernetes. ## Quick Start Use the dotnet-worker-services skill to create a BackgroundService worker that processes a queue with scoped DbContext access, graceful shutdown, and health checks.

Frequently Asked Questions about dotnet-worker-services

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a background service in .NET?▼

Create a class inheriting from BackgroundService and override ExecuteAsync with your work loop. Register it with builder.Services.AddHostedService<T>() and the Generic Host manages startup, shutdown, and cancellation token propagation automatically.

How to use DbContext inside a BackgroundService worker?▼

Inject IServiceScopeFactory into the worker and create a new scope per unit of work with CreateAsyncScope. Resolve DbContext from that scope to avoid captive dependencies, stale connections, and thread-safety issues from singleton-scoped contexts.

Should I use PeriodicTimer or Task.Delay in a .NET worker?▼

PeriodicTimer is recommended for scheduled work because it provides consistent intervals and cleaner cancellation semantics via WaitForNextTickAsync. Task.Delay causes interval drift since processing time adds to the delay period.

How do I add health checks to a .NET worker service?▼

Implement IHealthCheck to report worker state such as last successful run time, then register it with builder.Services.AddHealthChecks().AddCheck<T>(). For non-HTTP workers, expose the status through a TCP listener for Kubernetes liveness probes.

Why does my BackgroundService stop silently after an exception?▼

Unhandled exceptions in ExecuteAsync terminate the worker without notification. Wrap the loop body in try-catch, log the exception with ILogger, handle OperationCanceledException separately for shutdown, and add backoff before retrying.

Can a .NET worker run as a Windows Service?▼

Yes, call builder.Services.AddWindowsService with a service name and use the Microsoft.NET.Sdk.Worker SDK. Publishing as a single self-contained file for the win-x64 runtime simplifies deployment.