Worker services in .NET

There are numerous reasons for creating long-running services such as:

• Processing CPU-intensive data.
• Queuing work items in the background.
• Performing a time-based operation on a schedule.

Background service processing usually doesn't involve a user interface (UI), but UIs can be built around them. In the early days with .NET Framework, Windows developers could create Windows Services for these purposes. Now with .NET, you can use the BackgroundService, which is an implementation of IHostedService, or implement your own.

With .NET, you're no longer restricted to Windows. You can develop cross-platform background services. Hosted services are logging, configuration, and dependency injection (DI) ready. They're a part of the extensions suite of libraries, meaning they're fundamental to all .NET workloads that work with the generic host.

Terminology

Many terms are mistakenly used synonymously. This section defines some of these terms to make their intent in this article more apparent.

• Background Service: The BackgroundService type.
• Hosted Service: Implementations of IHostedService, or the IHostedService itself.
• Long-running Service: Any service that runs continuously.
• Windows Service: The Windows Service infrastructure, originally .NET Framework-centric but now accessible via .NET.
• Worker Service: The Worker Service template.

Worker Service template

The Worker Service template is available in the .NET CLI and Visual Studio. For more information, see .NET CLI, dotnet new worker - template. The template consists of a Program and Worker class.

using App.WorkerService;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHostedService<Worker>();

IHost host = builder.Build();
host.Run();

The preceding Program class:

• Creates a HostApplicationBuilder.
• Calls AddHostedService to register the Worker as a hosted service.
• Builds an IHost from the builder.
• Calls Run on the host instance, which runs the app.

Template defaults

The Worker template doesn't enable server garbage collection (GC) by default, as there are numerous factors that play a role in determining its necessity. All of the scenarios that require long-running services should consider performance implications of this default. To enable server GC, add the ServerGarbageCollection node to the project file:

<PropertyGroup>
    <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

Tradeoffs and considerations

For more information regarding performance considerations, see Server GC. For more information on configuring server GC, see Server GC configuration examples.

Worker class

As for the Worker, the template provides a simple implementation.

namespace App.WorkerService;

public sealed class Worker(ILogger<Worker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
            await Task.Delay(1_000, stoppingToken);
        }
    }
}

The preceding Worker class is a subclass of BackgroundService, which implements IHostedService. The BackgroundService is an abstract class and requires the subclass to implement BackgroundService.ExecuteAsync(CancellationToken). In the template implementation, the ExecuteAsync loops once per second, logging the current date and time until the process is signaled to cancel.

The project file

The Worker template relies on the following project file Sdk:

<Project Sdk="Microsoft.NET.Sdk.Worker">

For more information, see .NET project SDKs.

NuGet package

An app based on the Worker template uses the Microsoft.NET.Sdk.Worker SDK and has an explicit package reference to the Microsoft.Extensions.Hosting package.

Containers and cloud adaptability

With most modern .NET workloads, containers are a viable option. When creating a long-running service from the Worker template in Visual Studio, you can opt in to Docker support. Doing so creates a Dockerfile that containerizes your .NET app. A Dockerfile is a set of instructions to build an image. For .NET apps, the Dockerfile usually sits in the root of the directory next to a solution file.

# See https://aka.ms/containerfastmode to understand how Visual Studio uses this
# Dockerfile to build your images for faster debugging.

FROM mcr.microsoft.com/dotnet/runtime:8.0 AS base
WORKDIR /app

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["background-service/App.WorkerService.csproj", "background-service/"]
RUN dotnet restore "background-service/App.WorkerService.csproj"
COPY . .
WORKDIR "/src/background-service"
RUN dotnet build "App.WorkerService.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "App.WorkerService.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "App.WorkerService.dll"]

The preceding Dockerfile steps include:

• Setting the base image from mcr.microsoft.com/dotnet/runtime:8.0 as the alias base.
• Changing the working directory to /app.
• Setting the build alias from the mcr.microsoft.com/dotnet/sdk:8.0 image.
• Changing the working directory to /src.
• Copying the contents and publishing the .NET app:
  • The app is published using the dotnet publish command.
• Relayering the .NET SDK image from mcr.microsoft.com/dotnet/runtime:8.0 (the base alias).
• Copying the published build output from the /publish.
• Defining the entry point, which delegates to dotnet App.BackgroundService.dll.

When you target Docker as a deployment strategy for your .NET Worker Service, there are a few considerations in the project file:

<Project Sdk="Microsoft.NET.Sdk.Worker">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
    <RootNamespace>App.WorkerService</RootNamespace>
    <DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
    <PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.20.1" />
  </ItemGroup>
</Project>

In the preceding project file, the <DockerDefaultTargetOS> element specifies Linux as its target. To target Windows containers, use Windows instead. The Microsoft.VisualStudio.Azure.Containers.Tools.Targets NuGet package is automatically added as a package reference when Docker support is selected from the template.

For more information on Docker with .NET, see Tutorial: Containerize a .NET app. For more information on deploying to Azure, see Tutorial: Deploy a Worker Service to Azure.

Hosted Service extensibility

The IHostedService interface defines two methods:

• IHostedService.StartAsync(CancellationToken)
• IHostedService.StopAsync(CancellationToken)

These two methods serve as lifecycle methods - they're called during host start and stop events respectively.

Signal completion

In most common scenarios, you don't need to explicitly signal the completion of a hosted service. When the host starts the services, they're designed to run until the host is stopped. In some scenarios, however, you may need to signal the completion of the entire host application when the service completes. To signal the completion, consider the following Worker class:

namespace App.SignalCompletionService;

public sealed class Worker(
    IHostApplicationLifetime hostApplicationLifetime,
    ILogger<Worker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // TODO: implement single execution logic here.
        logger.LogInformation(
            "Worker running at: {Time}", DateTimeOffset.Now);

        await Task.Delay(1_000, stoppingToken);

        // When completed, the entire app host will stop.
        hostApplicationLifetime.StopApplication();
    }
}

In the preceding code, the ExecuteAsync method doesn't loop, and when it's complete it calls IHostApplicationLifetime.StopApplication().

For more information, see:

• .NET Generic Host: IHostApplicationLifetime
• .NET Generic Host: Host shutdown
• .NET Generic Host: Hosting shutdown process

See also

• BackgroundService subclass tutorials:
  • Create a Queue Service in .NET
  • Use scoped services within a BackgroundService in .NET
  • Create a Windows Service using BackgroundService in .NET
• Custom IHostedService implementation:
  • Implement the IHostedService interface in .NET