Pular para o conteúdo principal

Processando em segundo plano no .NET 8 com BackgroundService e Channel

Todo mundo já passou por isso: o endpoint recebe a requisição, faz um trabalho que demora (gerar um relatório, mandar e-mail, chamar um serviço lento) e o cliente fica esperando até estourar o timeout. A saída clássica é responder logo e fazer o trabalho em segundo plano. Dá para ir direto num broker como RabbitMQ, mas muitas vezes isso é canhão para matar mosquito. No .NET 8 você já tem o necessário em casa: BackgroundService e Channel<T>.

A ideia

A API não processa nada. Ela registra o job, coloca numa fila e devolve 202 Accepted com um Location. Do outro lado, um BackgroundService fica em loop lendo da fila e processando um job por vez. O cliente consulta GET /jobs/{id} para saber o status: Queued, Processing, Completed ou Failed.

O projeto tem três peças: ChannelJobQueue (a fila), JobStore (um dicionário concorrente com o estado de cada job) e JobWorker (o consumidor). Tudo em memória, de propósito, para deixar o mecanismo à mostra.

A fila

O Channel.CreateBounded cria um canal com capacidade fixa, e essa escolha importa: sem limite, uma rajada de requisições vira memória crescendo sem controle. Com limite, você decide o que acontece quando enche. No ChannelJobQueue, o método TryEnqueue usa TryWrite, que devolve false na hora se não houver espaço, em vez de segurar a requisição esperando.

public sealed class ChannelJobQueue : IJobQueue
{
    private readonly Channel<Job> _channel;

    public ChannelJobQueue(int capacity)
    {
        _channel = Channel.CreateBounded<Job>(new BoundedChannelOptions(capacity)
        {
            FullMode = BoundedChannelFullMode.Wait,
            SingleReader = true
        });
    }

    // Returns false immediately when the queue is full, instead of waiting.
    public bool TryEnqueue(Job job) => _channel.Writer.TryWrite(job);

O endpoint

No POST /jobs a ordem importa: primeiro store.Add, depois TryEnqueue. Se fosse o contrário, o worker poderia pegar o job antes de ele existir no JobStore e tentar atualizar um id desconhecido. Se a fila estiver cheia, removo o job do store e respondo 503 com Results.Problem. É o backpressure chegando no cliente: melhor dizer "tente de novo daqui a pouco" do que aceitar o que não dá conta.

var job = new Job(Guid.NewGuid(), request.Name);

// Register the job before enqueueing, so the worker never sees an unknown id.
store.Add(job);

if (!queue.TryEnqueue(job))
{
    store.Remove(job.Id);
    return Results.Problem(statusCode: StatusCodes.Status503ServiceUnavailable, title: "Queue is full.");
}

return Results.Accepted($"/jobs/{job.Id}", new { job.Id });

O worker

O JobWorker herda de BackgroundService e implementa o ExecuteAsync. O await foreach sobre DequeueAllAsync (que por baixo é o ReadAllAsync do canal) dorme quando a fila está vazia e acorda quando chega item, sem polling e sem Task.Delay em loop. Quando o host recebe o sinal de parada, o stoppingToken é cancelado, o enumerador lança OperationCanceledException e eu só registro o log de encerramento.

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    try
    {
        await foreach (var job in queue.DequeueAllAsync(stoppingToken))
        {
            await ProcessAsync(job, stoppingToken);
        }
    }
    catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
    {
        logger.LogInformation("Worker is shutting down.");
    }
}

O outro cuidado é com falha. Se uma exceção escapar do loop, o ExecuteAsync termina e o worker morre calado: a API continua aceitando jobs que ninguém mais processa. Por isso o ProcessAsync captura a exceção de cada job, marca como Failed e segue para o próximo. O filtro when (ex is not OperationCanceledException) deixa passar o cancelamento do shutdown.

catch (Exception ex) when (ex is not OperationCanceledException)
{
    // One bad job must not kill the worker loop.
    store.SetStatus(job.Id, JobStatus.Failed);
    logger.LogError(ex, "Job {JobId} failed.", job.Id);
}

Testando

Os testes usam WebApplicationFactory, uma instância por teste, já que fila e store são singletons em memória. O Worker:DelayMs e o Queue:Capacity entram por AddInMemoryCollection. O teste mais interessante é o da fila cheia: com capacidade 1 e o worker ocupado por 3 segundos, o primeiro job vira Processing, o segundo ocupa a fila e o terceiro leva 503. Esperar o status Processing antes de mandar o segundo evita corrida entre o teste e o worker.

await using var factory = CreateFactory(delayMs: 3000, capacity: 1);
var client = factory.CreateClient();

// The worker takes the first job and stays busy with it.
var firstId = await CreateJobAsync(client, "first");
await WaitForStatusAsync(client, firstId, "Processing");

// The second job fills the queue (capacity 1).
await CreateJobAsync(client, "second");

// The third one has no room left.
var response = await client.PostAsJsonAsync("/jobs", new { name = "third" });

Assert.Equal(HttpStatusCode.ServiceUnavailable, response.StatusCode);

Tem ainda testes para o 202, o 400, o 404, o job que completa e o worker que sobrevive a um job que falha (o nome fail simula o erro).

Rodando com Docker

O docker-compose.yml tem o serviço app, que sobe a API na porta 8080, e o serviço tests, que roda o xUnit. Com a API no ar, é só criar um job e consultar o status:

docker compose up --build
curl -X POST http://localhost:8080/jobs -H "Content-Type: application/json" -d '{"name":"report"}'
curl http://localhost:8080/jobs/<id>
docker compose run --rm tests

Quando isso não basta

Fila em memória não sobrevive a reinício e não divide trabalho entre várias instâncias. Se o job não pode ser perdido, ou se você tem mais de uma réplica, o caminho é um broker (RabbitMQ, Azure Service Bus) ou uma tabela de outbox. Para tarefas curtas e tolerantes a perda, como notificações ou aquecimento de cache, o Channel resolve com pouquíssimo código.

O código completo está aqui: programero-csharp/2026-11-background-service-channel.

Exibindo 2026-11-16-background-service-channel.html…

Comentários

Mais visitadas

Como pegar valor de coluna invisível do GridView

Em determinado momento nos deparamos com a seguinte situação, nossa tabela do banco de dados possui como campo chave, um ID por exemplo, incrementado por uma rotina da aplicação, do banco ou algum outro mecanismo de incremento (sequences, increment, etc), logo não há porque mostrar essa coluna para o usuário porque o mesmo não sabe de sua existência, e seu valor não tem qualquer relevância para ele, sendo assim o mais lógico a se fazer é não mostra-lá na aplicação. Seu valor é necessário já que por se tratar de uma chave primária precisaremos dela para atualizar, inserir ou excluir os dados, então o que fazer? A resposta seria simples, deixemos ele invisível, buscaremos seu valor e o usuário não perceberá, porém a partir da versão 2005 do visual Studio as colunas setadas com "visible = false" não são renderizadas, com isso ao se tentar acessar seu valor o que recebemos é nada. Para contornarmos essa situação podemos codificar o seguinte: protected void GridView1_R...

Lista de políticos com ficha suja

ATUALIZAÇÃO (08/03/2012 ano de eleição) Representantes de duas pessoas da lista (Eliseu Padilha e Alex Canziani) entraram em contato e pediram que esses fossem removidos, alegando que não houve condenação. É justo essa requisição, porém vale lembrar que escândalos nacionalmente reconhecidos de corrupção não deram em nada, por isso o que realmente conta nesse ano de eleição é uma pesquisa minuciosa sobre os candidatos escolhidos, eu particularmente, por não estar nem um pouco satisfeito, não irei votar em ninguém que já tenha sido eleito. Estou voltando a postar por um motivo nobre, meu tempo continua apertado mas esse post é rápido, na verdade nem meu ele é (visitem o espaço de nosso amigo Lord ), estou apenas repassando essa valiosa informação. Teremos eleição esse ano, e é importante não repetirmos erros passados, vamos ficar atentos em relação a esses nomes e exclui-los de vez do cenário politico nacional. Façamos nossa parte, publicando em nossos blog...

Iniciar e Parar Serviços do Windows (Delphi)

Em certas ocasiões nos deparamos com a necessidade de manipular determinadas atividades do SO, como iniciar ou parar um banco de dados, ou qualquer outro serviço que esteja funcionando no momento. Segue abaixo um código que encontrei na Internet para tal finalidade (não me recordo à fonte, assim que eu a encontrar colocarei). Iniciar Serviço: uses WinSvc; // // start service // // return TRUE if successful // // sMachine: //   machine name, ie: \SERVER //   empty = local machine // // sService //   service name, ie: Alerter // function ServiceStart(   sMachine,   sService : string ) : boolean; var   //   // service control   // manager handle   schm,   //   // service handle   schs   : SC_Handle;   //   // service status   ss     : TServiceStatus;   //   // te...