DEV Community: Paulo Walraven

Do localhost à produção: deployando Worker Services .NET como Windows Service, container Linux e Docker

Paulo Walraven — Wed, 24 Jun 2026 11:00:00 +0000

Seu Worker Service roda lindamente com F5. Mas "roda na minha máquina" não processa pedido nenhum às 3h da manhã. Em produção, um worker é uma aplicação de longa duração que precisa iniciar sozinha, sobreviver a reinícios e se recuperar de falhas — sem ninguém apertando botão.

Neste post você vai ver os três caminhos para colocar um Worker Service .NET em produção — Windows Service, container Docker e Linux — e, mais importante, os requisitos de produção que realmente importam por trás de cada comando.

Por que worker não é API

Antes do "como", vale lembrar o que torna um worker diferente de uma aplicação web. Diferentemente de uma API, um Worker Service não responde a requisições HTTP — ele executa continuamente em background.

Isso muda os requisitos de hosting. O worker precisa:

Iniciar automaticamente, sem intervenção manual.
Se recuperar de falhas sozinho.
Rodar sem supervisão o tempo todo.

É por isso que como você hospeda o worker importa tanto. Vamos aos três modelos.

Opção 1: rodando como Windows Service

O .NET torna trivial rodar um worker como Windows Service. Primeiro, adicione uma linha ao builder no program.cs:

builder.Services.AddWindowsService();

Vai aparecer um erro na hora — falta uma dependência. Instale o pacote NuGet:

dotnet add package Microsoft.Extensions.Hosting.WindowsServices

O que isso faz é dizer ao host que ele deve se integrar com a infraestrutura de serviços do Windows.

Depois, publique o executável (via CLI ou pela GUI do Visual Studio, em configuração Release):

dotnet publish -c Release

Por fim, registre o serviço no Windows com o utilitário SC.exe, num prompt de comando como administrador, apontando o binPath para o executável publicado:

SC create MyJobProcessor binPath= "C:\caminho\para\MyJobProcessor.exe"

Se aparecer SC create service success, está feito. Abra o Services do Windows, procure por MyJobProcessor e você pode iniciar, parar, configurar para subir automaticamente no boot ou desabilitar — tudo que se espera de um Windows Service típico.

Opção 2: rodando dentro de um container (a abordagem moderna)

Em muitos sistemas hoje — especialmente em ambientes cloud — os workers rodam dentro de containers. É a abordagem que costumo recomendar sempre que possível.

Você pode escrever o Dockerfile à mão, mas o Visual Studio tem um atalho ótimo: clique com o botão direito no projeto → Add → Docker Support. Ele gera o Dockerfile para você (escolha Linux como OS do container, que é o mais comum sob o capô).

Com o Dockerfile no lugar, construa a imagem pela CLI:

docker build -t myjobprocessor .

💡 Dois tropeços comuns aqui: a tag da imagem deve ser minúscula (myjobprocessor, não MyJobProcessor) e cuidado com espaços no caminho. Erros nesses dois pontos são fáceis de cometer.

E rode o container:

docker run myjobprocessor

Você verá os logs do worker chegando no terminal. Se parar o container, a aplicação desliga junto — exatamente o comportamento esperado. A partir daí, você pode publicar a imagem para um registry (Docker Hub, um repositório privado, etc.) e deployá-la onde precisar.

Por que essa é a abordagem moderna? Containers são muito escaláveis e cross-platform: a mesma imagem roda em Linux, em Windows nativo, ou onde quer que você precise empurrá-la. Essa flexibilidade é uma das principais vantagens dos Worker Services.

O que realmente importa: os requisitos de produção

Os comandos são a parte fácil. O que separa "deployado" de "confiável" são três requisitos que você leva de qualquer modelo de hosting.

Restart e resiliência

Independentemente de como o worker foi hospedado, ele precisa reiniciar com segurança. Isso significa:

não perder o rastro do trabalho que estava fazendo,
não deixar o sistema em estado inconsistente.

É justamente por isso que, num sistema real, você persiste os jobs e rastreia o estado deles — para que um restart no meio do caminho não jogue trabalho fora.

Configuração por ambiente

Em produção, workers tipicamente rodam em múltiplos ambientes: desenvolvimento, staging e produção. E cada um tem seus próprios valores — connection strings, polling intervals, feature flags.

A boa notícia: como o Worker Service usa o mesmo .NET host do ASP.NET, a configuração funciona exatamente igual. Você usa appsettings.json, user secrets ou variáveis de ambiente, sem nenhuma cerimônia extra.

Escalabilidade

Por enquanto, focamos em rodar uma única instância. Mas o aprendizado fundamental é que um worker é um processo independente — pode ser deployado e gerenciado separadamente da sua API. Isso abre caminho, mais à frente, para rodar múltiplos workers e distribuir o trabalho entre eles.

Conclusão

Levar um Worker Service para produção é menos sobre o comando de deploy e mais sobre a mentalidade: uma vez no ar, o worker vira parte da infraestrutura do seu sistema — espera-se que rode continuamente, se recupere de falhas e se comporte de forma previsível. Windows Service, Docker ou Linux são só o "onde"; restart seguro, configuração por ambiente e independência da API são o "porquê".

É isso que separa processamento em background de um script solto. Qual modelo de hosting faz sentido para o seu cenário — Windows Service ou container? Se puder containerizar, eu sempre aconselharia. Teste os dois caminhos e veja qual encaixa na sua infra.

O que é Arquitetura de Software e por que ela importa

Paulo Walraven — Tue, 23 Jun 2026 15:32:48 +0000

Antes de falar sobre monolitos modulares, microsserviços ou qualquer outro estilo arquitetural, precisamos responder uma pergunta mais fundamental: o que é arquitetura de software e por que deveríamos nos importar com isso?

Se você já participou de uma reunião técnica onde alguém desenhou caixas e setas num quadro branco, você viu arquitetura de software em ação. Mas o conceito vai muito além de diagramas.

Uma definição simples

Arquitetura de software é a organização fundamental de um sistema — os componentes que o compõem e como eles se relacionam entre si.

Pense assim: assim como um arquiteto elabora o projeto de um edifício antes de qualquer tijolo ser assentado, um arquiteto de software define a estrutura de um sistema antes (e durante) o desenvolvimento. Esse projeto vai guiar centenas de decisões ao longo da vida do projeto.

Por que isso importa na prática

A escolha arquitetural de hoje é a dívida técnica (ou o dividendo técnico) de amanhã. Ela impacta diretamente:

Custo — algumas arquiteturas são muito mais caras de construir e operar
Desempenho — a estrutura do sistema define seus gargalos
Escalabilidade — crescer 10x é fácil em alguns modelos, impossível em outros
Manutenibilidade — o quanto é difícil mudar algo sem quebrar outra coisa
Velocidade de entrega — times maiores podem trabalhar em paralelo ou ficam se atrapalhando?

Nenhum desses fatores é isolado. Quando você otimiza para um, geralmente está fazendo uma concessão em outro. E é exatamente aí que entra o conceito mais importante da arquitetura de software.

A decisão mais ignorada no desenvolvimento de software

Na maioria dos projetos, a arquitetura não é uma decisão explícita. É o resultado acidental de centenas de pequenas decisões tomadas sem um plano maior.

Um time começa com um projeto simples. As features crescem. O prazo aperta. Atalhos são tomados. Cinco anos depois, você tem um sistema que ninguém quer tocar porque qualquer mudança pode quebrar algo em outro lugar completamente inesperado.

Esse padrão tem até nome: big ball of mud. E é mais comum do que qualquer um gostaria de admitir.

Estilos arquiteturais: a caixa de ferramentas

A boa notícia é que você não precisa inventar a roda. Ao longo de décadas, a indústria consolidou alguns estilos arquiteturais que representam abordagens bem entendidas para organizar sistemas de software:

Monolito padrão — toda a aplicação em um único código deployado junto
Microsserviços — a aplicação dividida em muitos serviços independentes
Monolito modular — uma base de código única, mas organizada em módulos com fronteiras bem definidas

Cada um tem suas vantagens, seus custos e os contextos nos quais faz mais sentido. Não existe "o melhor" em abstrato — existe o mais adequado para o seu problema específico.

Hosted service na API ou worker service dedicado? Um guia de decisão

Paulo Walraven — Tue, 23 Jun 2026 11:00:00 +0000

Você aprendeu a construir um hosted service. Agora vem a pergunta que ninguém respondeu: onde ele deve rodar? Dentro da sua API ASP.NET Core, ou em um worker service separado? Escolher errado aqui custa caro — ou você degrada o desempenho dos seus endpoints, ou adiciona complexidade de infraestrutura sem necessidade.

Ao final deste post você vai ter um critério claro para decidir, caso a caso, onde colocar seu processamento em background.

O mesmo código roda nos dois lugares

Antes da decisão, um fato que dá liberdade: o mesmo BackgroundService e o mesmo AddHostedService<T>() funcionam tanto em um Worker Service quanto em uma API ASP.NET Core.

// funciona idêntico na API e no worker service
builder.Services.AddHostedService<JobProcessor>();

Ou seja, a decisão não é técnica de implementação — é uma decisão de arquitetura. Você não está escolhendo APIs diferentes; está escolhendo onde sua carga de trabalho vive e como ela escala.

Quando o hosted service na API é a escolha certa

Hosted services dentro da própria aplicação brilham para trabalho leve em background que pertence à aplicação em si. Alguns exemplos típicos:

Atualizar dados em cache periodicamente.
Fazer polling de pequenos datasets.
Executar tarefas de manutenção rotineiras.

O fio condutor: essas tarefas são estreitamente acopladas à aplicação e não precisam de escalabilidade independente. Elas vivem e morrem com a API, e está tudo bem assim. Colocá-las num serviço separado só adicionaria partes móveis sem benefício.

Quando mover para um worker service dedicado

Do outro lado estão as cargas mais pesadas. Para trabalho de longa duração ou intensivo em recursos, frequentemente a melhor abordagem é mover esse processamento para um worker service separado.

O benefício central é duplo:

A carga de trabalho em background pode escalar de forma independente.
Você evita impactar o desempenho da sua API — o background pesado não disputa recursos com quem está atendendo requisições.

Se o seu job consome muita CPU/memória ou roda por muito tempo, mantê-lo dentro da API significa que cada pico de processamento pode degradar a latência dos seus endpoints. Separar resolve isso.

A regra prática

Dá para resumir a decisão em uma regra simples:

Tarefa leve e estreitamente acoplada à aplicação? → um hosted service dentro da API é mais apropriado.
Tarefa de longa duração, intensiva em recursos ou que precisa de escalabilidade própria? → mova para um worker service dedicado.

Comece simples. Se o trabalho é leve e nasce junto com a API, não há motivo para criar um serviço separado só por purismo. Mas no momento em que ele começa a pesar, a durar ou a exigir escala própria, esse é o sinal de que chegou a hora de tirá-lo de dentro da API.

Conclusão

A escolha entre hosted service na API e worker service dedicado não é sobre código — é sobre acoplamento e escala. Trabalho leve e acoplado fica na API; trabalho pesado, longo ou que precisa escalar sozinho vai para um worker dedicado. Entender quando usar cada um é o que separa um sistema que aguenta produção de um que trava sob carga.

Olhe para os hosted services que você tem hoje: algum deles está pesando dentro da sua API e merecia virar um worker próprio? Esse é o próximo passo natural — e é exatamente o que construiremos a seguir: um worker service dedicado para processar jobs fora da aplicação web.

Quando tirar o background work de dentro da API: o caso a favor dos Worker Services

Paulo Walraven — Mon, 22 Jun 2026 11:00:00 +0000

Seu endpoint que sempre respondia em 80ms começou a oscilar para 800ms — e ninguém mexeu no código dele. O culpado? Aquele BackgroundService que você colocou na API mês passado para gerar relatórios. Ele está rodando dentro do mesmo processo que suas requisições, e agora os dois estão brigando pela mesma CPU.

Esse é um dos erros arquiteturais mais silenciosos do .NET: começar com hosted services dentro da API e só descobrir o problema quando a produção já está degradada. Neste post você vai entender quando o background work deve sair da API e por que Worker Services são a resposta — não pela sintaxe, mas pelos trade-offs reais.

O problema: hosted services compartilham tudo com a sua API

Hosted services (IHostedService / BackgroundService) são ótimos para tarefas que pertencem à aplicação e são leves: limpar um cache, emitir um heartbeat, recarregar uma configuração de tempos em tempos.

Mas há uma característica fácil de esquecer: eles rodam dentro do mesmo processo da sua API. Isso significa que compartilham:

a mesma memória,
os mesmos recursos de CPU,
o mesmo ciclo de vida.

Para cargas leves, isso é perfeito. O problema aparece quando o trabalho fica pesado.

Imagine que seu serviço em background está processando arquivos grandes, gerando relatórios ou chamando múltiplos sistemas externos. Se esse trabalho executa dentro do processo da API, ele está competindo com as requisições que chegam pelos mesmos recursos.

O resultado é direto: tempos de resposta mais lentos e performance instável. E o pior tipo de instabilidade — aquela que não aparece no código de nenhum endpoint, só na conta de recursos compartilhada.

A segunda dor: você só consegue escalar tudo junto

Essa é a parte que mais machuca em sistemas que crescem.

Se o seu processamento em background vive dentro da API, a única forma de escalá-lo é escalar a API inteira. Precisa de mais poder para processar a fila de jobs? Suba mais instâncias da aplicação web junto — mesmo que o tráfego HTTP nem precise disso.

Isso é ineficiente por definição. Em muitos sistemas reais, as cargas de background têm um perfil de escala completamente diferente da camada web: elas precisam crescer e encolher de forma independente. Acoplar os dois te força a pagar por capacidade que você não precisa, do lado errado.

A terceira dor: uma falha derruba o que não devia

Confiabilidade é o terceiro argumento, e talvez o mais convincente.

Quando o worker mora dentro da API, o raio de explosão de uma falha é a aplicação inteira:

Se o worker quebra, você não quer que a API caia junto — mas, no mesmo processo, esse risco existe.
Se você precisa reiniciar os workers, não deveria ter que reiniciar toda a aplicação web — mas, acoplado, é exatamente isso que acontece.

Separar o trabalho em background cria uma arquitetura muito mais resiliente: cada parte falha, reinicia e se recupera de forma isolada.

A solução: Worker Services como aplicações separadas

Para resolver esses três problemas — contenção de recursos, escala acoplada e falhas que se propagam — o .NET oferece os Worker Services.

Um Worker Service é uma aplicação independente, dedicada ao processamento em background. O modelo de programação parece familiar (ainda é um BackgroundService com seu loop), mas a diferença que importa é estrutural: é outro processo.

Isso destrava exatamente o que faltava:

Recursos próprios — o worker não disputa CPU/memória com as suas requisições HTTP.
Escala independente — você sobe mais instâncias do worker sem tocar na API.
Ciclo de vida isolado — reiniciar ou derrubar o worker não afeta a aplicação web.

O melhor: como o Worker Service usa o mesmo generic host do ASP.NET, tudo que você já sabe — dependency injection, configuração, logging — continua valendo. Você ganha o isolamento sem reaprender a stack.

Checklist: está na hora de extrair o worker?

Use estes sinais como gatilho para tirar o background work de dentro da API:

[ ] O trabalho é pesado (processa arquivos, gera relatórios, chama vários sistemas externos).
[ ] Os tempos de resposta da API oscilam quando o background está ativo.
[ ] Você precisa escalar o processamento sem escalar a camada web.
[ ] Uma falha no processamento não pode colocar a API em risco.
[ ] Você quer reiniciar/deployar o background sem mexer na aplicação web.

Se você marcou dois ou mais, o Worker Service deixou de ser luxo e virou decisão de arquitetura.

Conclusão

Hosted services dentro da API são ótimos — até deixarem de ser. No momento em que o trabalho fica pesado, precisa escalar sozinho ou não pode derrubar a aplicação, o lugar certo para ele é fora da API, em um Worker Service independente.

Já tem um BackgroundService rodando dentro da sua API hoje? Rode o checklist acima e veja se ele já não está te custando latência. No próximo post da série, vamos colocar a mão na massa e criar e estruturar o nosso primeiro Worker Service do jeito certo.

Busy waiting, falhas que derrubam o worker e estado de job: armadilhas ao projetar o loop de processamento

Paulo Walraven — Fri, 19 Jun 2026 11:00:00 +0000

"Pega trabalho, processa, repete." O loop de um Worker Service parece a coisa mais simples do mundo — até ele ir para produção e queimar 100% de CPU sem ter nada para fazer, ou cair inteiro porque um job lançou uma exceção. O loop trivial é uma ilusão.

Neste post você vai percorrer as três armadilhas clássicas ao projetar esse loop — busy waiting, falhas mal tratadas e estado de job inconsistente — e ver a correção idiomática de cada uma. Spoiler: o lugar do try-catch e o lugar do decremento do contador fazem toda a diferença.

O ponto de partida: o padrão "recuperar → processar → repetir"

Quase todo worker segue o mesmo esqueleto. Ele recupera algum trabalho, processa, e repete:

while (!stoppingToken.IsCancellationRequested)
{
    var job = await jobProcessor.GetNextJob();
    await jobProcessor.ProcessJob(job);

    await Task.Delay(loopInterval, stoppingToken);
}

Isso é frequentemente descrito como a fundação de qualquer sistema de processamento em background. Mas, sozinho, não é suficiente para produção. Vamos ver onde ele quebra.

Armadilha 1: busy waiting queimando CPU à toa

O primeiro problema é o busy waiting: quando não há trabalho disponível, o loop continua girando e consumindo CPU desnecessariamente. Você está pagando por ciclos de processador para... processar null.

A correção mais simples é só processar quando realmente existe um job:

var job = await jobProcessor.GetNextJob();

if (job is not null)
{
    await jobProcessor.ProcessJob(job);
}

await Task.Delay(loopInterval, stoppingToken);

Repare: não estamos introduzindo um delay novo — já temos o Task.Delay do fim do loop. Estamos apenas evitando processar à toa quando não há nada. Sem job, o worker dá sua soneca habitual e volta a checar.

A versão melhor: verifique quantos jobs existem

Se você consegue saber quantos jobs estão pendentes, dá para ser mais esperto e processá-los em lote — garantindo que só trabalha quando há trabalho:

var pendingJobs = await jobProcessor.GetTotalPendingJobs();

if (pendingJobs > 0)
{
    var job = await jobProcessor.GetNextJob();
    // processa...
}

Contar jobs costuma ser uma operação barata (o tamanho de uma coleção ou de uma fila, por exemplo), então o overhead é baixo.

Mas atenção ao contexto — essa é a nuance que quase ninguém comenta:

Múltiplos workers compartilhando a fila: use uma checagem condicional simples. Se há 42 jobs e você pega um, não sabe quantos sobraram (outro worker pode ter pegado) — você teria que verificar de novo a cada vez.
Você é o único worker (a fila vive dentro do próprio serviço): aí não há risco da contagem mudar por baixo dos panos. Você pode processar em batch até esgotar:

var pendingJobs = await jobProcessor.GetTotalPendingJobs();

while (pendingJobs > 0)
{
    var job = await jobProcessor.GetNextJob();
    await jobProcessor.ProcessJob(job);
    pendingJobs--;
}

await Task.Delay(loopInterval, stoppingToken);

A ideia: você acorda, processa os 42 jobs, dorme por dois segundos, volta e checa se surgiu mais alguma coisa. Esse modelo te deixa acelerar quando há trabalho acumulado — mas só é seguro se você for o único consumidor daquela fila. Com vários serviços competindo pelo mesmo conjunto centralizado de jobs, não use essa abordagem.

Armadilha 2: uma falha que derruba o worker inteiro

Aqui está a regra que você nunca pode violar: uma única falha no processamento jamais pode derrubar o worker inteiro.

Se um job lança uma exceção e você não trata, o loop morre e o processo cai — junto com todos os outros jobs que processariam normalmente. A solução básica é um try-catch ao redor do processamento específico, registrando a exceção:

while (pendingJobs > 0)
{
    var job = await jobProcessor.GetNextJob();

    try
    {
        await jobProcessor.ProcessJob(job);
    }
    catch (Exception ex)
    {
        logger.LogError(ex, "Falha ao processar o job");
    }

    pendingJobs--; // FORA do try — sempre decrementa
}

Como não há UI em um worker, o log é a sua única fonte de verdade. Capturar a exceção e logá-la é o que te permite ver, depois, que um job específico falhou — enquanto o resto continua rodando.

O detalhe fatal: onde fica o decremento

Olhe de novo para o exemplo acima. O pendingJobs-- está fora do try. Isso é intencional e crítico.

Se você colocar o decremento dentro do try, e o job sempre falha, você nunca decrementa — e o loop fica preso para sempre com a mesma contagem, ou o contador sai de sincronia. Por isso: o try envolve só o trabalho que você quer proteger contra falha; o controle do loop fica de fora. Seja cuidadoso com essa fronteira.

Armadilha 3: estado de job inconsistente

A terceira armadilha é mais sutil: conforme processa, o worker precisa rastrear o estado do job — pendente, em progresso, completo, falho.

O padrão geral é marcar o job ao longo do ciclo de vida:

var job = await jobProcessor.GetNextJob();

try
{
    await jobProcessor.MarkJobInProgress(job);
    await jobProcessor.ProcessJob(job);
    await jobProcessor.MarkJobComplete(job);
}
catch (Exception ex)
{
    logger.LogError(ex, "Falha ao processar o job");
    await jobProcessor.MarkJobFailed(job);
}

A ideia é simples: recuperou o job → marca como em progresso → processa → marca como completo. Se falhar, marca como falho no catch, mantendo o estado consistente. Você precisa ser bem cuidadoso ao atualizar esse estado, justamente para que uma falha não deixe um job pendurado em "em progresso" para sempre.

Não esqueça: respeite sempre o cancellation token

Por mais que pareça repetitivo, vale insistir: sempre respeite o CancellationToken. Poder sinalizar que algo foi cancelado é uma prática crucial em qualquer worker. Repare que ele aparece tanto na condição do while quanto no Task.Delay dos exemplos — é assim que o worker desliga de forma graciosa quando a aplicação está parando.

Conclusão

O loop "pega, processa, repete" é enganosamente simples. Em produção, ele exige três cuidados: não queimar CPU em busy waiting, isolar falhas para que um job ruim não derrube o worker e rastrear o estado do job de forma consistente — tudo isso respeitando o cancellation token. A mentalidade certa: um worker não é "só mais um loop em background", é um componente de sistema de longa duração que precisa se comportar de forma previsível.

Revise o loop do seu worker hoje: o try-catch está ao redor só do processamento? O decremento está fora dele? Se respondeu "não" para alguma, você já encontrou a próxima refatoração. No próximo post, vamos tirar o worker do localhost e colocá-lo para rodar em produção.

Worker fino, processador gordo: estruturando Worker Services testáveis

Paulo Walraven — Thu, 18 Jun 2026 11:00:00 +0000

Abra um Worker Service de seis meses de idade que ninguém estruturou direito e você vai encontrar a mesma cena: uma classe Worker de duzentas linhas, com lógica de banco, regra de negócio e tratamento de erro, toda enrolada dentro de um while. Tente escrever um teste unitário pra isso. Não dá — você teria que subir o host inteiro.

A diferença entre um worker que vira essa bola de neve e um que se mantém manutenível está em uma decisão simples de design: manter a classe Worker fina e empurrar a lógica para um JobProcessor injetável. Neste post você vai ver como essa separação destrava testabilidade e evolução — e por que ela é uma questão de arquitetura, não de configuração.

O instinto errado: colocar a lógica no worker

Quando você cria um Worker Service (dotnet new worker), o template te dá um Worker.cs com um loop pronto. É tentador começar a escrever ali mesmo: pega o job, valida, processa, salva, repete. Tudo dentro do ExecuteAsync.

O problema é que o worker passa a ter duas responsabilidades misturadas:

Orquestrar — manter o loop de pé, controlar o intervalo, respeitar o cancellation.
Executar — a regra concreta de processar cada job.

Misturar essas duas coisas é o que torna o worker impossível de testar e difícil de evoluir. Cada mudança na regra de negócio mexe na mesma classe que controla o ciclo de vida do processo.

A regra de ouro: o worker deve ser fino

A mentalidade certa é: a classe Worker tem uma responsabilidade muito específica — orquestrar a execução, recuperar o trabalho e delegar o processamento. Nada mais.

Toda a lógica de "o que fazer com o job" mora em outro lugar: um componente separado, injetável, que você registra no DI. Vamos chamá-lo de JobProcessor.

Primeiro, extraia a lógica para a sua própria classe:

public class JobProcessor
{
    public Task ProcessNextJob()
    {
        // toda a regra de processamento vive aqui
        return Task.CompletedTask;
    }
}

Registre no program.cs como scoped — porque, na prática, esse processador vai depender de coisas como um DbContext:

builder.Services.AddScoped<JobProcessor>();

E deixe o worker apenas coordenar e delegar:

public class Worker(IServiceScopeFactory serviceScopeFactory) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            using var scope = serviceScopeFactory.CreateScope();
            var jobProcessor = scope.ServiceProvider.GetRequiredService<JobProcessor>();

            await jobProcessor.ProcessNextJob();

            await Task.Delay(2000, stoppingToken);
        }
    }
}

Repare no que o worker faz agora: ele vai no nível mais alto de abstração — "pega o próximo job e faz algo com ele" — e só. É tudo o que essa classe precisa saber. Esse é o padrão que se usa o tempo todo em produção: o worker puxa trabalho de uma fila ou event bus, e delega o resto.

Por que essa separação destrava os testes

Aqui está o ganho concreto. Com a lógica isolada no JobProcessor, você consegue testá-lo de forma independente do host.

O JobProcessor é só uma classe comum, com dependências injetadas. Em um teste unitário, você instancia ela com mocks/fakes das dependências, chama ProcessNextJob() e verifica o comportamento — sem subir o generic host, sem loop, sem Task.Delay, sem cancellation token.

Enquanto isso, o Worker fica tão fino que quase não há o que testar nele: ele só orquestra. A complexidade que realmente merece cobertura de teste — a regra de negócio — está num lugar onde testar é trivial.

É exatamente isso que a dependency injection te dá: a capacidade de separar responsabilidades e testar cada componente isoladamente. Como bônus, a mesma lógica do JobProcessor pode ser reutilizada em outros contextos, porque ela não está presa ao loop do worker.

A nuance: não deixe o worker engordar de novo

Conforme o sistema cresce, é fácil o worker começar a inchar de novo — uma condicional aqui, um if (job != null) ali, um contador de jobs pendentes acolá. Antes que perceba, a classe que devia ser fina virou o centro da lógica outra vez.

Fique atento a esse drift. Sempre que notar o worker crescendo, pergunte: isso é orquestração ou execução? Se for execução, o lugar é o JobProcessor. O worker coordena; outro componente realiza o trabalho. Manter essa fronteira nítida é o que torna o sistema mais fácil de testar, estender e evoluir ao longo do tempo.

Conclusão

Um Worker Service bem feito não é sobre o loop — é sobre quem faz o quê. Worker fino que orquestra, JobProcessor que executa: essa única decisão de design separa os workers testáveis e duráveis dos que viram dívida técnica.

Da próxima vez que for escrever lógica dentro de um ExecuteAsync, pare e pergunte se aquilo não pertence a um processador injetável. Seu eu do futuro — e a sua suíte de testes — vão agradecer. No próximo post, vamos olhar para dentro desse loop e as armadilhas de projetá-lo para produção.

Graceful shutdown no .NET: o CancellationToken que você está ignorando vai corromper seus dados

Paulo Walraven — Wed, 17 Jun 2026 11:00:00 +0000

Seu serviço está no meio de processar um pagamento quando o container é reiniciado. Se você não tratou o cancelamento, parabéns: você acabou de deixar dados em memória que nunca chegaram ao banco — e um registro que ninguém mais consegue confiar.

Ao final deste post você vai entender por que o CancellationToken no seu loop de background não é detalhe de estilo, mas uma questão de integridade de dados — e qual é o único padrão correto para respeitá-lo.

Em produção, sua aplicação reinicia o tempo todo

Talvez no seu ambiente local a aplicação suba uma vez e fique de pé por horas. Em produção é o oposto. Aplicações são reiniciadas constantemente:

Serviços são atualizados em novos deploys.
Containers são reimplementados (redeploy).
Serviços escalam para cima e para baixo conforme a carga.

Toda vez que isso acontece, o trabalho em background precisa parar de um jeito específico: graciosamente, não abruptamente. A diferença entre os dois é onde mora o bug.

O CancellationToken é o sinal de "hora de parar"

Quando a aplicação começa a desligar, o host dispara um sinal. Esse sinal chega ao seu hosted service através do CancellationToken recebido no ExecuteAsync:

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    // stoppingToken é acionado quando a aplicação começa o shutdown
}

O token é acionado quando a aplicação começa a desligar. Ele é o seu aviso prévio. O problema é que respeitá-lo é opcional do ponto de vista do compilador — e é muito fácil simplesmente não usá-lo.

O padrão correto (e o erro silencioso)

O ExecuteAsync te entrega o token, mas nada te obriga a verificá-lo dentro do loop. Esse é o erro silencioso: escrever um loop que ignora o sinal de shutdown.

O padrão absolutamente correto é verificar o token na condição do loop:

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    while (!stoppingToken.IsCancellationRequested)
    {
        // faz o trabalho em background

        // repassa o token para as chamadas async também
        await Task.Delay(1000, stoppingToken);
    }
}

Dois pontos que fazem esse padrão funcionar:

while (!stoppingToken.IsCancellationRequested) garante que, no início de cada iteração, o loop verifica se já é hora de parar.
Repassar o token para chamadas assíncronas (como Task.Delay) faz a espera ser interrompida imediatamente quando o shutdown chega — em vez de segurar a aplicação até o fim do delay.

O resultado: a tarefa para rapidamente quando o shutdown começa, em vez de ser morta no meio do caminho.

Por que isso importa de verdade

Vale insistir nesse ponto, porque ele é fácil de subestimar. Imagine que seu serviço está processando pagamentos ou processando documentos.

Se a aplicação desliga, você está no meio de uma operação e não tratou o cancelamento, o estrago pode ser:

Alguns dados ficaram em memória e nunca foram consolidados no banco.
Ou os dados no banco mudaram, mas a operação não terminou.
Resultado: dados incompletos e não confiáveis — você não pode confiar na precisão deles.

É exatamente esse tipo de inconsistência entre memória e banco que respeitar o CancellationToken evita. Não é sobre código bonito; é sobre não corromper o estado do seu sistema toda vez que um deploy acontece.

Conclusão

Em produção o shutdown não é exceção — é rotina. O CancellationToken que o ExecuteAsync te entrega é o que separa um serviço que para de forma limpa de um que deixa rastros de dados corrompidos a cada reinício. Use while (!stoppingToken.IsCancellationRequested) e repasse o token para suas chamadas async, sempre.

Vá ao seu hosted service e verifique agora: seu loop realmente checa o token? E suas operações longas conseguem ser interrompidas no meio sem deixar lixo? Se a resposta for não, você tem um candidato a bug de produção esperando o próximo deploy. No próximo post, fechamos o módulo decidindo quando manter o hosted service na API e quando movê-lo para um worker service dedicado.

IServiceScopeFactory em BackgroundService: por que injetar serviços scoped diretamente quebra

Paulo Walraven — Tue, 16 Jun 2026 11:00:00 +0000

Você cria um JobProcessor, registra como scoped, injeta no seu worker, dá F5 — e o app explode com Cannot consume scoped service ... from singleton. Bem-vindo a uma das armadilhas mais confusas do .NET: o erro não está no seu JobProcessor, está em como você o injetou.

Neste post você vai entender a causa raiz desse erro de lifetime e ver o padrão correto com IServiceScopeFactory — além de descobrir por que criar um escopo novo a cada iteração do loop não é detalhe, é a parte que importa.

O cenário: tudo parece certo, mas não roda

Imagine um worker bem estruturado. Você tirou a lógica de dentro da classe Worker e criou um componente separado, o JobProcessor, registrado como scoped no program.cs:

builder.Services.AddScoped<JobProcessor>();

Por que scoped? Porque, na vida real, o JobProcessor provavelmente vai depender de um DbContext — e contexto de banco de dados é um caso clássico de serviço com lifetime scoped. Até aqui, tudo idiomático.

Aí você injeta direto no worker:

public class Worker(JobProcessor jobProcessor) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            await jobProcessor.ProcessNextJob();
            await Task.Delay(2000, stoppingToken);
        }
    }
}

Roda? Não. Você encontra exatamente o erro que estava tentando evitar.

A causa raiz: um BackgroundService é um singleton

Aqui está o detalhe que quase todo mundo esquece: um BackgroundService (hosted service) é tratado como singleton pelo container de DI. Ele é criado uma vez e vive enquanto a aplicação existe.

E o container do .NET tem uma regra de proteção: um singleton não pode consumir um serviço scoped diretamente. Faz sentido — um serviço scoped tem vida curta e amarrada a um escopo (uma requisição, uma unidade de trabalho), enquanto o singleton vive "para sempre". Se o container deixasse você capturar o scoped no construtor do singleton, você prenderia aquele DbContext de vida curta a um objeto eterno. É o caminho garantido para vazamento de recursos e bugs sutis.

Por isso o container barra na largada, com o erro de "scoped from singleton". Não é um capricho — é o runtime te protegendo de um problema pior lá na frente.

A correção: injete a factory, não o serviço

A solução é não pedir o JobProcessor no construtor. Em vez disso, injete um IServiceScopeFactory e use-o para criar um escopo dentro do loop, resolvendo o serviço scoped a cada iteração:

public class Worker(IServiceScopeFactory serviceScopeFactory) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            using var scope = serviceScopeFactory.CreateScope();
            var jobProcessor = scope.ServiceProvider.GetRequiredService<JobProcessor>();

            await jobProcessor.ProcessNextJob();

            await Task.Delay(2000, stoppingToken);
        }
    }
}

Repare no que mudou. Estamos fazendo a mesma coisa de antes — chamar ProcessNextJob() — mas:

Injetamos IServiceScopeFactory (que é singleton-safe), não o JobProcessor.
A cada volta do loop, CreateScope() cria um escopo fresco.
GetRequiredService<JobProcessor>() resolve o serviço scoped dentro daquele escopo.
O using garante que o escopo é descartado no fim da iteração.

O JobProcessor continua registrado como scoped — está tudo bem. O que muda é que agora respeitamos o lifetime dele em vez de tentar furá-lo.

Por que um escopo fresco a cada iteração importa

É tentador pensar "ok, criei o escopo, problema resolvido". Mas o ganho real é mais profundo: um escopo novo por iteração mantém o worker seguro ao longo do tempo.

O worker em si pode ter vida longa (ele é o coordenador, fica de pé o tempo todo).
Os serviços que fazem o trabalho ganham o lifetime scoped correto — nascem e morrem dentro de cada iteração.
O using descarta as dependências de forma limpa ao fim de cada ciclo. Se há um DbContext ali dentro, ele é criado, usado e liberado a cada job, sem acumular estado de uma iteração para a outra.

É essa combinação que dá o melhor dos dois mundos: um worker de longa duração coordenando, e serviços de vida curta executando sem riscos de estado compartilhado ou conexões penduradas.

Conclusão

Quando você vê Cannot consume scoped service from singleton no seu Worker Service, a mensagem está dizendo uma verdade incômoda: seu BackgroundService é singleton, e ele não pode segurar um scoped direto. A correção não é mudar o lifetime do JobProcessor — é injetar IServiceScopeFactory e criar um escopo fresco a cada iteração do loop.

Da próxima vez que esbarrar nesse erro, lembre: o worker coordena, o escopo isola, o serviço executa. Já caiu nessa armadilha em algum projeto seu? Teste o padrão acima e veja como o loop fica mais previsível — e seguro com banco de dados.

O erro do scoped em singleton: por que injetar um DbContext num BackgroundService quebra tudo

Paulo Walraven — Fri, 12 Jun 2026 11:00:00 +0000

Você cria um BackgroundService, injeta um DbContext no construtor, roda — e por um tempo parece funcionar. Até começarem os bugs que ninguém consegue reproduzir: estado obsoleto, conexões descartadas, dados que não batem. Esse é, talvez, o erro mais comum ao construir hosted services no .NET.

Ao final deste post você vai entender por que esse padrão quebra os tempos de vida (lifetimes) das suas dependências e qual é o jeito correto de acessar serviços scoped dentro de um hosted service.

O conflito de tempos de vida

Aqui está o detalhe que muita gente não percebe: hosted services são registrados como Singletons. Uma única instância é criada para toda a vida da aplicação.

Só que muitos serviços comuns no ASP.NET são scoped — uma instância por escopo (tipicamente, por requisição web). Os exemplos clássicos:

DbContext (Entity Framework)
Repositórios
Serviços de unit of work

Quando você registra um DbContext, isso acontece de forma padrão:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

AddDbContext registra o AppDbContext como scoped. Esse é o comportamento padrão do EF Core, e é o correto para o ciclo de uma requisição.

Por que injetar direto quebra tudo

Um hosted service vive durante toda a vida da aplicação. Um serviço scoped foi feito para viver apenas dentro de um escopo específico — por exemplo, uma requisição web.

Então, se você injetar a dependência scoped diretamente no construtor do hosted service, você viola esse limite de tempo de vida:

public class JobProcessor : BackgroundService
{
    private readonly AppDbContext _dbContext; // ⚠️ scoped dentro de um singleton

    public JobProcessor(AppDbContext dbContext) // isto é o que NÃO queremos
    {
        _dbContext = dbContext;
    }
    // ...
}

As consequências de quebrar essa fronteira:

Tempos de vida incorretos de serviço
Dependências descartadas sendo usadas
Estado obsoleto preso em memória pela vida inteira da aplicação
Comportamento imprevisível geral

E imprevisibilidade é a última coisa que você quer quando o assunto é falar com o banco de dados.

O padrão correto: IServiceScopeFactory

Em vez de injetar a dependência scoped, você injeta um IServiceScopeFactory e cria um escopo sempre que precisar resolver serviços scoped.

A fábrica de escopos foi projetada exatamente para isso: te entregar um escopo que você controla, dentro do seu hosted service.

public class JobProcessor : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;

    public JobProcessor(IServiceScopeFactory scopeFactory)
    {
        _scopeFactory = scopeFactory;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            Console.WriteLine("Verificando jobs...");

            // 1. cria um escopo (com using, para ser descartado depois)
            using var scope = _scopeFactory.CreateScope();

            // 2. resolve o DbContext dentro desse escopo
            var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();

            // 3. usa normalmente
            await ProcessJob(dbContext);

            await Task.Delay(1000, stoppingToken);
        }
    }
}

Os três pontos que fazem isso funcionar:

CreateScope() dentro do loop cria um IServiceScope novo a cada iteração.
A declaração using garante que o escopo (e tudo o que ele resolveu) seja descartado ao final.
GetRequiredService<AppDbContext>() resolve o DbContext a partir do ServiceProvider daquele escopo — respeitando o lifetime scoped.

A ideia central: você cria o escopo para o DbContext porque o DbContext é scoped, mas o lugar onde o processamento acontece roda como singleton. O escopo é a ponte segura entre os dois mundos.

O aprendizado que evita horas de debug

Guarde essa frase: um hosted service é um singleton. Então, sempre que precisar de uma dependência scoped — como um DbContext — você deve criar um escopo primeiro.

Fazer isso garante duas coisas críticas:

As dependências scoped são criadas corretamente a cada uso.
E, igualmente importante, são descartadas corretamente ao final — sem conexões vazando nem estado preso por toda a vida da aplicação.

Conclusão

Injetar um DbContext direto no construtor de um BackgroundService é o tipo de erro que não estoura na hora — ele apodrece silenciosamente até virar um bug intermitente em produção. A correção é barata: injete IServiceScopeFactory, crie um escopo com using dentro do loop e resolva suas dependências scoped a partir dele.

Abra seu hosted service agora e confira: tem algum serviço scoped no construtor? Se tiver, você já sabe o que refatorar. No próximo post, vamos falar sobre outro pilar de hosted services em produção: graceful shutdown e o CancellationToken que você não pode ignorar.

IHostedService vs. BackgroundService: qual usar e por quê

Paulo Walraven — Wed, 10 Jun 2026 00:00:09 +0000

Você herda de BackgroundService, sobrescreve ExecuteAsync, e tudo "simplesmente funciona". Mas você sabe o que essa classe esconde de você? Por baixo do açúcar sintático existe uma interface, um host genérico e um ciclo de vida que decide quando seu código começa e — mais importante — quando ele para.

Ao final deste post você vai saber exatamente o que é o IHostedService, o que o BackgroundService abstrai por cima dele, e quando vale a pena descer um nível e implementar a interface na mão.

O ponto de partida: o ciclo de vida da aplicação

Toda aplicação ASP.NET Core moderna se constrói sobre o generic host (.NET host). É ele quem gerencia injeção de dependência, configuração, logging e, principalmente, o startup e o shutdown da aplicação.

Os hosted services se conectam diretamente a esse ciclo de vida. A regra é simples:

Quando a aplicação inicia, o hosted service inicia.
Quando a aplicação para, o hosted service para.

Essa amarração ao ciclo de vida não é um detalhe — é justamente o que permite que uma tarefa em background pare graciosamente e libere seus recursos em vez de morrer no meio do trabalho.

IHostedService: a interface por baixo de tudo

A forma mais simples de rodar trabalho em background no .NET é um hosted service, e na base dele está a interface IHostedService. Ela define apenas dois métodos:

public interface IHostedService
{
    Task StartAsync(CancellationToken cancellationToken);
    Task StopAsync(CancellationToken cancellationToken);
}

Esses dois métodos definem o ciclo de vida do serviço:

StartAsync é chamado quando a aplicação inicia.
StopAsync é chamado quando a aplicação para.

Repare no CancellationToken: ele não está ali por enfeite. É o que permite que a tarefa em background participe com segurança do shutdown, sinalizando "hora de parar" para que recursos como arquivos abertos ou conexões sejam liberados corretamente.

Tecnicamente, você pode implementar essa interface diretamente. Mas se fizer isso, todo o controle do loop, do estado e do encerramento fica nas suas mãos — e é aí que entra muito código repetitivo (boilerplate).

BackgroundService: o wrapper que você realmente usa

Para evitar esse boilerplate, o ASP.NET fornece uma classe base: BackgroundService. A maioria dos hosted services que você vê em produção usa exatamente essa classe.

A diferença é direta: em vez de implementar dois métodos de ciclo de vida, você sobrescreve um só:

public class JobProcessor : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            Console.WriteLine("Verificando jobs...");
            await Task.Delay(1000, stoppingToken);
        }
    }
}

O que está acontecendo aqui:

ExecuteAsync roda durante toda a vida da aplicação.
Dentro dele há um loop que continua até a aplicação desligar.
O stoppingToken é acionado no shutdown, o loop sai, e a tarefa termina de forma controlada.

E o ponto que confunde muita gente: você não implementa IHostedService aqui porque o BackgroundService já faz isso por você. Se você olhar dentro da classe (no namespace Microsoft.Extensions.Hosting), vai ver que ela implementa IHostedService e cuida do StartAsync/StopAsync internamente. O BackgroundService é, em essência, um wrapper elegante sobre a interface.

Registrando o serviço

Implementar a classe é metade do trabalho. Para o host realmente iniciar o serviço, você o registra no container de injeção de dependência, no program.cs:

builder.Services.AddHostedService<JobProcessor>();

Feito isso, o host inicia o serviço automaticamente quando a aplicação sobe. E você pode registrar quantos hosted services quiser — eles rodam lado a lado. Sobe a aplicação e ambos passam a executar seus loops em paralelo, cada um controlado pelo mesmo ciclo de vida que o IHostedService fornece.

Outro detalhe importante: isso funciona tanto em um Worker Service quanto em uma API ASP.NET Core. O mesmo AddHostedService<T>() e o mesmo BackgroundService servem nos dois cenários — a diferença é só onde o serviço vive.

Então, quando implementar IHostedService na mão?

Na prática, a resposta para a maioria dos casos é: use BackgroundService. Ele trata da estrutura de ciclo de vida, garante que a tarefa inicie com a aplicação, pare no shutdown e respeite o cancelamento — deixando você focar no trabalho que realmente importa.

Você só desce para IHostedService direto quando precisa de controle total sobre o start e o stop, por exemplo: lógica de inicialização que precisa rodar e terminar antes da aplicação ficar pronta, ou um encerramento que não combina com o modelo de "um loop único" do ExecuteAsync. Fora esses casos, o wrapper é a escolha certa — e mais segura.

Conclusão

IHostedService é o contrato; BackgroundService é a conveniência construída sobre ele. Entender essa relação faz você parar de tratar ExecuteAsync como mágica e passar a enxergar o ciclo de vida real por trás do seu código em background — o que é o primeiro passo para escrever serviços que param tão bem quanto começam.

Agora abra seu program.cs, crie um BackgroundService simples e observe-o iniciar e parar junto com a aplicação. No próximo post, vamos atacar um dos erros mais comuns com hosted services: injetar dependências scoped em um serviço que, na verdade, é singleton.

O que você precisa para rodar um Teste de Carga de sucesso? (Checklist Prático)

Paulo Walraven — Tue, 07 Apr 2026 10:32:55 +0000

Você já se perguntou o que é necessário para garantir que sua aplicação não saia do ar no primeiro pico de acessos? A resposta está no Teste de Carga. Mas, antes de começar a simular milhares de usuários acessando seu sistema, o que exatamente você precisa ter em mãos?

Aqui está um checklist simples e direto para estruturar um teste de carga eficiente:

1. Ambiente de Teste (Mirroring)

O ideal é não fazer o teste no ambiente de produção para não afetar os usuários reais que estão utilizando o sistema.

Isolamento: Utilize um ambiente de homologação ou staging que seja, se possível, uma réplica do hardware e da infraestrutura de produção.
Dados: Utilize uma base de dados com volume realista. Testar a carga em um banco com apenas 10 registros é completamente diferente de testar em um com 10 milhões. A volumetria muda o comportamento do sistema.

2. Ferramenta de Geração de Carga

Você vai precisar de um software focado em disparar essas requisições simultâneas.

Escolha da Ferramenta: Utilize opções consolidadas no mercado, como JMeter, K6 ou Locust.

Regra de Ouro: A ferramenta deve ser instalada em uma máquina separada do alvo. Se você rodar a ferramenta de teste e o sistema alvo na mesma máquina, o teste será inválido, pois ambos estarão competindo pelos mesmos recursos de processador e memória.

3. Monitoramento

Apenas gerar carga não adianta se você não souber o que está acontecendo "por baixo dos panos". Você precisa de visibilidade:

APMs (Application Performance Monitoring): Ferramentas como New Relic, Datadog ou Dynatrace ajudam a ver o que acontece no nível da aplicação.
Dashboards de Infra: Se estiver na nuvem (AWS, Azure, GCP), utilize o CloudWatch ou soluções similares para acompanhar o uso de CPU, uso de memória, I/O de disco e tráfego de rede.
Logs: Tenha acesso fácil aos logs de erro do servidor para identificar falhas silenciosas ou gargalos durante o pico de carga.

4. Plano de Teste

Não basta "bombardear" a página inicial do site sem critério. É preciso simular o mundo real.

Caminho do Usuário: O que o usuário realmente vai fazer? Desenhe as jornadas (Ex: Login -> Busca -> Adicionar ao carrinho -> Checkout).
Carga Esperada: Quantos usuários simultâneos você quer atingir? Qual o tempo de rampa (quanto tempo leva para subir gradualmente de 0 a 1000 usuários)?

Com esse planejamento em mãos, você deixa de "adivinhar" o comportamento do seu software e passa a ter dados reais para escalar com segurança. Boa sorte nos testes!