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
Postar um comentário
Obrigado por Participar do programero, fique a vontade para agradecer, retificar, perguntar ou sugerir.