Implementando Background Services com C# e .NET

Quando usar um serviço em segundo plano

Na prática, esse recurso se encaixa bem em três situações. Primeiro, no processamento de tarefas longas ou recorrentes, como a consolidação de relatórios.

Além disso, ele atende tarefas que não exigem interação direta com o usuário, como limpeza de cache ou sincronização com sistemas externos. Por fim, ele brilha no processamento de filas e de tarefas agendadas.

A interface IHostedService

A base de tudo é a interface IHostedService. Ela define apenas dois métodos: StartAsync, chamado na inicialização, e StopAsync, chamado no encerramento.

Implementar a interface diretamente dá controle total sobre o ciclo de vida. Contudo, também obriga você a gerenciar tokens de cancelamento e tarefas em execução por conta própria.

A classe base BackgroundService

Para simplificar esse trabalho, o .NET oferece a classe abstrata BackgroundService. Ela implementa IHostedService e expõe um único método para sobrescrever, o ExecuteAsync.

Esse método devolve uma Task que representa toda a vida útil do serviço. Quando a aplicação começa a encerrar, o host aciona o token de cancelamento e espera o ExecuteAsync terminar.

No .NET 10, houve uma mudança relevante nesse comportamento. A partir dessa versão, todo o ExecuteAsync roda em uma thread de segundo plano, inclusive o trecho síncrono antes do primeiro await.

Nas versões anteriores, esse trecho inicial rodava na thread principal e bloqueava a inicialização dos outros serviços. Portanto, código pesado no começo do método atrasava a subida da aplicação inteira.

O template Worker Service

Nem todo projeto precisa de uma API para hospedar serviços em segundo plano. Para esses casos, o .NET oferece o template Worker Service, criado com o comando dotnet new worker.

Esse template gera uma aplicação de console com host genérico e uma classe Worker que já herda de BackgroundService. Além disso, o arquivo de projeto usa o SDK Microsoft.NET.Sdk.Worker.

Na prática, o worker recebe os mesmos recursos de uma API: configuração, logging e injeção de dependência. Por isso, ele serve como ponto de partida ideal para processadores de fila, integrações e rotinas noturnas.

Outra vantagem aparece na hora de publicar. Um worker pode rodar como serviço do Windows, como daemon do systemd no Linux ou dentro de um contêiner.

Background services temporizados com PeriodicTimer

A documentação mostra o serviço temporizado com System.Threading.Timer. No entanto, ela alerta que esse timer não espera a execução anterior terminar, o que pode causar sobreposição.

Para background services temporizados, uma alternativa moderna é o PeriodicTimer, que aguarda cada ciclo de forma assíncrona. Com isso, uma execução nunca começa antes da anterior acabar.

public class ReportService(ILogger<ReportService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Dispara a cada cinco minutos, sem sobrepor execuções
        using var timer = new PeriodicTimer(TimeSpan.FromMinutes(5));

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            logger.LogInformation("Generating report at {time}", DateTimeOffset.Now);
        }
    }
}

Se o assunto for agendamento mais elaborado, vale ler os artigos sobre agendamento de tarefas com Quartz e sobre processamento em segundo plano com Hangfire.

Background services com escopo de injeção de dependência

Todo hosted service vive como singleton, e isso vale para todos os background services. Por isso, ele não pode receber diretamente um serviço scoped, como um DbContext, pelo construtor.

A solução consiste em injetar o IServiceScopeFactory e criar um escopo a cada ciclo. Assim, cada execução recebe as próprias instâncias e as descarta ao final.

public class CleanupService(IServiceScopeFactory scopeFactory) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Um escopo novo por ciclo, descartado no fim do bloco
            await using var scope = scopeFactory.CreateAsyncScope();
            var repository = scope.ServiceProvider.GetRequiredService<IOrderRepository>();

            await repository.RemoveExpiredAsync(stoppingToken);
            await Task.Delay(TimeSpan.FromHours(1), stoppingToken);
        }
    }
}

Se os ciclos de vida ainda geram dúvida, o artigo sobre AddTransient, AddScoped e AddSingleton explica cada um em detalhes.

Background services baseados em fila com Channel

Em background services baseados em fila, a requisição apenas registra o trabalho e responde rápido. Enquanto isso, um serviço em segundo plano consome os itens no próprio ritmo.

public class EmailQueueService(Channel<string> queue, ILogger<EmailQueueService> logger)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Lê os itens assim que chegam, até o cancelamento
        await foreach (var email in queue.Reader.ReadAllAsync(stoppingToken))
        {
            logger.LogInformation("Sending email to {email}", email);
        }
    }
}

O canal precisa existir como singleton, criado com Channel.CreateUnbounded<string>() ou com uma capacidade limitada. O artigo sobre Channels em C# aprofunda esse padrão em APIs de alto volume.

Definição da classe e dependências

O primeiro bloco do nosso background service define a classe e recebe as dependências pelo construtor.

public class MyBackgroundService : BackgroundService
{
    private readonly ILogger<MyBackgroundService> _logger;

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

Aqui, a classe MyBackgroundService herda da classe base BackgroundService. Em seguida, a injeção de dependência entrega uma instância de ILogger, que permite registrar logs durante a execução do serviço.

Método ExecuteAsync

O segundo bloco implementa o método ExecuteAsync, o principal ponto de execução do serviço.

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

        while (!stoppingToken.IsCancellationRequested)
        {
            _logger.LogInformation("Service running at: {time}", DateTimeOffset.Now);
            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
        }

        _logger.LogInformation("Service stopped.");
    }
}

O host invoca esse método automaticamente quando o background service inicia. Então, ele roda continuamente até que alguém solicite o encerramento, sinalizado pelo stoppingToken.

Durante a execução, o método registra um log periódico indicando que o serviço está ativo. Depois, ele aguarda um minuto antes de repetir o ciclo e, ao ser cancelado, registra que o serviço parou.

O papel do stoppingToken

A propriedade stoppingToken.IsCancellationRequested verifica se o token de cancelamento foi acionado. Quando isso acontece, o serviço sabe que precisa parar.

Assim que o valor se torna verdadeiro, o laço while termina. Dessa forma, o serviço consegue realizar qualquer limpeza necessária antes de finalizar.

Essa abordagem garante que os background services tenham uma interrupção graciosa e controlada. Ela importa principalmente quando o sistema operacional, um orquestrador de contêineres ou o próprio ambiente pede o encerramento.

Repare também que o token vai para o Task.Delay. Com isso, a espera termina imediatamente no cancelamento, em vez de segurar o encerramento por até um minuto.

Nesse caso, o Task.Delay lança uma OperationCanceledException, que o BackgroundService trata como encerramento normal. Por isso, a mensagem final só aparece quando o cancelamento chega durante o log, e não durante a espera.

Registrando o serviço no container

Para que o host conheça o background service, registre-o no container de injeção de dependência com AddHostedService. No modelo atual, isso acontece no arquivo Program.cs.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHostedService<MyBackgroundService>();

var app = builder.Build();
app.Run();

Em projetos mais antigos, o mesmo registro fica no método ConfigureServices da classe Startup. O comportamento, porém, continua igual.

Logging

Use a injeção de dependência para incluir o ILogger e acompanhar o status do serviço. Registre o início, o fim e cada ciclo relevante, sempre com mensagens estruturadas.

Para centralizar esses registros, o artigo sobre Serilog no ASP.NET mostra como enviar logs para destinos externos. Assim, o time acompanha os serviços em produção sem acessar o servidor.

Controle de erros

Implemente um tratamento robusto de exceções dentro do laço principal. Dessa forma, uma falha em um ciclo não derruba o serviço inteiro.

Esse cuidado ficou ainda mais importante a partir do .NET 6. Desde essa versão, uma exceção não tratada no ExecuteAsync encerra o host por padrão, conforme a opção BackgroundServiceExceptionBehavior.StopHost.

while (!stoppingToken.IsCancellationRequested)
{
    try
    {
        await ProcessAsync(stoppingToken);
    }
    catch (Exception ex) when (ex is not OperationCanceledException)
    {
        // Registra a falha e segue para o próximo ciclo
        _logger.LogError(ex, "Error while processing the cycle");
    }

    await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
}

Se preferir o comportamento antigo, configure HostOptions.BackgroundServiceExceptionBehavior como Ignore. Ainda assim, tratar o erro dentro do serviço costuma ser a escolha mais segura e previsível.

Encerramento gracioso

Por padrão, o host espera até 30 segundos para que os serviços terminem. Para aumentar esse prazo, configure a propriedade ShutdownTimeout em HostOptions.

Vale lembrar que o StopAsync pode não executar quando o processo cai de forma inesperada. Portanto, background services que manipulam dados críticos precisam tolerar interrupções a qualquer momento.