DEV Community: Lincoln Zocateli

SignalR no .NET: do primeiro Hub à produção

Lincoln Zocateli — Mon, 02 Nov 2026 17:31:29 +0000

Introdução

SignalR no .NET é uma biblioteca do ASP.NET Core para comunicação em tempo real entre servidor e clientes. Ela negocia um transporte compatível e oferece uma API de alto nível para chamadas entre browser e servidor, envio de eventos, grupos e streaming. Eu a escolheria quando a interface precisa receber atualizações com baixa latência ou enviar comandos interativos sem transformar cada mudança em uma nova consulta periódica. SignalR simplifica o canal; não fornece armazenamento durável, autorização de domínio pronta nem garantia de entrega exatamente uma vez.

Essa diferença muda o desenho: conexões caem, eventos podem se perder e um usuário autenticado ainda pode não ter acesso ao ambiente solicitado. No Dokpod, o browser recebe uma invalidação pequena, consulta o estado pela API REST e só entra no grupo depois que o Hub verifica a autorização. O BFF mantém os tokens fora do navegador; no artigo sobre BFF e segurança em SPAs, explico esse padrão em mais detalhes.

Este é o terceiro artigo da série APIs e Comunicação em .NET. A parte sobre gRPC no .NET 10 explica o canal bidirecional protegido por mTLS entre API e agentes. Já o comparativo Tempo real no Angular e .NET discute em mais detalhe WebSockets, SSE, SignalR e Long Polling. Aqui o foco é outro: ciclo de vida do Hub, chamadas, autorização, grupos, recuperação de assinaturas e decisões operacionais.

ℹ️ Informação: O repositório público do Dokpod não possui uma release ou tag estável no momento da consulta. Os links de código deste artigo apontam para main, que é mutável; os arquivos podem mudar depois desta revisão.

Pré-requisitos

Os exemplos usam ASP.NET Core/.NET 10 e Angular; conhecimento básico de C#, HTTP e autenticação web basta. Os trechos do Dokpod são ilustrativos, não um sample independente.

É útil distinguir quatro termos. Hub é a abstração que expõe métodos do servidor e envia eventos aos clientes. Conexão lógica é a sessão que o SignalR administra, mesmo quando o transporte subjacente muda. Grupo é uma associação efêmera de conexões para envio direcionado. Invalidação é um aviso para o cliente consultar novamente uma fonte de estado, não uma cópia do próprio estado.

O que SignalR abstrai, e o que continua sendo protocolo

SignalR organiza mensagens sobre uma conexão administrada pela biblioteca. O cliente chama métodos do Hub com invoke (e pode aguardar resultado) ou send (sem aguardar o resultado da aplicação). O Hub envia eventos ao chamador, a grupos ou a todos os clientes. Argumentos são serializados pelo protocolo de Hub: JSON é o padrão e MessagePack é uma alternativa binária.

Essa API não é o próprio WebSocket. SignalR negocia um transporte e usa o protocolo de Hub sobre ele: WebSockets é preferido quando disponível; Server-Sent Events (SSE) e Long Polling são alternativas. O fallback depende do suporte e da configuração do cliente, servidor e intermediários. Ele não torna todos os transportes disponíveis em qualquer ambiente nem converte um transporte unidirecional em duplex.

Transporte e formato são camadas distintas: JSON ou MessagePack podem usar um transporte SignalR compatível. WebSockets puros são uma opção quando a aplicação precisa controlar o protocolo, mas então assume detalhes de framing, reconexão e roteamento. O Hub também não é uma sessão de domínio duradoura: instâncias atendem invocações, e estado persistente deve ficar em serviços ou armazenamento. Para enviar mensagens fora de uma invocação, use IHubContext<T>.

Negociação automática é conveniência de compatibilidade, não uma medição de desempenho; valide o transporte real por cliente e ambiente.

Do registro do Hub à autorização por ambiente

No ASP.NET Core, AddSignalR registra a infraestrutura e MapHub expõe o endpoint. O Hub do Dokpod em /hubs/control-plane tem [Authorize], assim como sua rota. Isso impede conexões anônimas, mas autenticação não autoriza o acesso a todo ambiente.

JoinEnvironmentAsync valida o identificador, obtém do contexto autenticado o sub e o access token recebido do BFF e pede ao Keycloak uma decisão para urn:dokpod:environment:{id} com o scope environment:read. Só a decisão permitida leva a Groups.AddToGroupAsync; negação, indisponibilidade ou resultado indeterminado não concedem acesso.

O grupo tem nome determinístico, como environment-{guid}, mas esse nome não é uma credencial. A autorização ocorre na API antes da associação; o identificador recebido não permite ao cliente escolher qualquer grupo. Operações assíncronas recebem ConnectionAborted para cancelar trabalho quando a conexão some.

public async Task JoinEnvironmentAsync(string environmentId)
{
    if (string.IsNullOrWhiteSpace(environmentId) || environmentId.Length > 64 ||
        environmentId.Any(character => !char.IsLetterOrDigit(character) && character != '-'))
        throw new HubException("Identificador de ambiente inválido.");

    var httpContext = Context.GetHttpContext();
    var accessToken = ExtractAccessToken(httpContext);
    var subject = Context.User?.FindFirstValue("sub");
    if (string.IsNullOrWhiteSpace(accessToken) || string.IsNullOrWhiteSpace(subject) ||
        !Guid.TryParse(environmentId, out var environmentGuid))
        throw new HubException("Acesso negado.");

    var decision = await authorizationDecider.DecideAsync(
        $"urn:dokpod:environment:{environmentGuid:D}", EnvironmentResourceScopes.Read,
        AuthenticatedActor.FromSubject(subject), accessToken, GetCorrelationId(httpContext),
        Context.ConnectionAborted);
    if (!decision.Allowed) throw new HubException("Acesso negado.");

    await Groups.AddToGroupAsync(Context.ConnectionId, GroupFor(environmentId),
        Context.ConnectionAborted);
}

📂 Código-fonte: ControlPlaneHub.cs e ApiHost.cs.

O Hub é apropriado para validações ligadas ao chamador e para coordenar esse fluxo curto. Regras maiores ficam em serviços de aplicação: assim, autorização, auditoria, limites e efeitos de domínio não dependem de uma conexão específica. Se várias invocações concorrerem, a implementação não deve assumir que chamadas da mesma conexão serão serializadas em todos os cenários; estado compartilhado precisa de sincronização e de um dono explícito.

Cliente Angular pelo BFF, sem token no browser

O browser usa uma URL same-origin. O HubConnectionBuilder registra handlers, habilita reconexão e envia o cookie de sessão; antes, o serviço obtém do BFF um token antiforgery para X-Dokpod-Antiforgery. O cookie é HttpOnly: o Angular não lê nem encaminha o Bearer da API.

O BFF autentica a sessão e acrescenta o token obtido do ticket server-side apenas no salto BFF → API. No WebSocket downstream, o Bearer vai em Authorization, nunca de volta ao browser. O BFF protege o POST de negociação contra CSRF e valida Origin; a API ainda autoriza cada ambiente.

invoke aguarda a conclusão da invocação e rejeita a promise em caso de falha. send não confirma a conclusão da regra de negócio. Registre handlers antes de start para não perder eventos recebidos logo após a conexão.

const { requestToken } = await firstValueFrom(
  this.http.get<AntiforgeryResponse>('bff/antiforgery'),
);
const connection = new HubConnectionBuilder()
  .withUrl(controlPlaneHubUrl(document.baseURI), {
    headers: { 'X-Dokpod-Antiforgery': requestToken },
    withCredentials: true,
  })
  .withAutomaticReconnect()
  .build();

connection.on('invalidated', (notification: { environmentId: string; kind: InvalidationKind }) =>
  this.publish(notification.environmentId, notification.kind));
connection.onreconnected(() => void this.rejoinEnvironment(connection, environmentId));
await connection.start();
await connection.invoke('JoinEnvironmentAsync', environmentId);

📂 Código-fonte: console-realtime.service.ts e BffHost.cs.

O snippet omite limpeza e tratamento de estado. No serviço real, uma falha de start() é tratada como erro inicial; withAutomaticReconnect() cobre uma conexão já estabelecida que caiu. A interface deve distinguir esses casos, sem inferir conectividade pela existência do serviço.

Grupos e invalidações: aviso rápido, leitura durável

Depois da autorização, o cliente entra no grupo do ambiente. Quando uma projeção muda, SignalRControlPlaneNotifier usa IHubContext<ControlPlaneHub> para enviar invalidated; o publicador não instancia um Hub nem depende de uma chamada do browser.

O payload contém somente identificador do ambiente e tipo de recurso, como inventory, events ou alerts. O notifier agrega emissões por ambiente e tipo, inicialmente a uma por segundo. A tela consulta então o endpoint REST, que autoriza novamente e devolve a representação atual. SignalR reduz latência sem duplicar a fonte de verdade.

await hubContext.Clients
    .Group(ControlPlaneHub.GroupFor(environmentId.ToString("D")))
    .SendAsync("invalidated",
        new InvalidationNotification(environmentId, kind),
        CancellationToken.None);

📂 Código-fonte: SignalRControlPlaneNotifier.cs e AgentControlService.cs.

Um grupo não é fila, histórico ou assinatura durável. Sua associação pode desaparecer com desconexão ou reinício. Não envie snapshots grandes nem interprete a ausência de aviso como prova de que nada mudou; na volta, busque o estado atual pela API.

O retorno de SendAsync também não confirma que o browser recebeu ou processou a invalidação. Se várias alterações forem agregadas, a leitura REST ainda precisa convergir para a representação mais recente.

Autenticação, autorização e limites de confiança

[Authorize] protege a entrada, mas não a autorização de cada recurso. O principal fica associado à conexão e mudanças de roles ou claims não são automaticamente revalidadas em toda invocação. O Dokpod consulta Keycloak ao entrar no grupo e reavalia permissões em alguns fluxos sensíveis de longa duração.

O browser usa cookie same-origin através do BFF, que acrescenta o Bearer somente server-side. Em uma conexão direta autenticada por bearer, APIs de WebSocket e SSE do navegador não permitem configurar livremente Authorization; o cliente pode colocar access_token na query string. HTTPS protege o tráfego, mas URLs podem aparecer em logs. Se essa opção for inevitável, restrinja-a à rota do Hub e remova a query dos logs. O relay do Dokpod evita expor o token ao browser ou à URL downstream.

Cookies também criam risco de CSRF. O BFF valida Origin, restringe origens e exige antiforgery no POST de negociação. CORS controla chamadas cross-origin do browser, mas não autentica usuários nem autoriza ambientes; same-origin tampouco elimina validação de Origin para uma conexão por cookie.

Grupos não são fronteiras de segurança: o servidor deriva recurso e scope do principal e falha fechada quando Keycloak nega ou não consegue decidir. Limite mensagens, duração e concorrência, use TLS e evite registrar tokens, logs ou conteúdo de terminal.

⚠️ Atenção: o cliente JavaScript pode enviar bearer tokens em query string para WebSockets/SSE por limitação das APIs do browser. O relay BFF do Dokpod autentica o browser por cookie e acrescenta o Bearer apenas no salto server-side para a API.

Reconexão, fluxos e eventos que podem se perder

O cliente JavaScript não reconecta por padrão. withAutomaticReconnect() usa atrasos de 0, 2, 10 e 30 segundos; após quatro falhas, para e chama onclose. A política não cobre falhas do start() inicial, que precisam de estratégia própria. onreconnecting, onreconnected e onclose representam estados distintos.

Após reconectar, o servidor vê uma nova conexão. ConsoleRealtimeService guarda os ambientes observados e chama JoinEnvironmentAsync novamente. Atualizar apenas o indicador para “connected” deixa a interface sem receber invalidações se o cliente não restaurar a associação ao grupo.

connection.onreconnecting(() => this.status.set('connecting'));
connection.onreconnected(() => {
  const environmentIds = [...this.joined];
  this.joined.clear();
  this.status.set('connected');
  void this.watch(environmentIds);
});
connection.onclose(() => this.status.set('disconnected'));

📂 Código-fonte: console-realtime.service.ts.

Reconexão não recupera mensagens emitidas durante a queda. Para inventário, faça refresh REST após reconectar e use SignalR para mudanças seguintes. Histórico, replay ou confirmação exigem sequência durável e retomada explícita, não são garantias do Hub.

Essa estratégia funciona melhor quando a consulta é idempotente e retorna uma visão consistente do recurso, em vez de depender de reaplicar cada notificação perdida.

O Hub também oferece fluxos longos. StreamContainerLogs autoriza container:logs, dura no máximo 15 minutos, propaga cancelamento e reavalia o acesso a cada 60 segundos. OpenTerminal recebe e devolve streams, exige WebSocket e aplica limites próprios. Esses recursos transportam conteúdo sob demanda e não devem herdar as garantias de uma invalidação.

Escala e operação sem prometer o que ainda não existe

Uma conexão SignalR consome socket, memória e keep-alive. O Dokpod configura 15 segundos para KeepAliveInterval e 30 para ClientTimeoutInterval, proporção recomendada pela documentação do ASP.NET Core. São valores do projeto: ajuste após medir proxy, latência e custo por conexão.

O proxy precisa encaminhar o upgrade WebSocket, evitar buffering que atrase SSE e alinhar timeouts aos pings. No Dokpod, o browser passa por nginx e BFF; um teste direto ao Kestrel não valida essa borda.

Com múltiplos processos, as requisições de uma conexão normalmente exigem afinidade. Há exceções documentadas, como instância única, Azure SignalR Service e WebSockets exclusivos com negociação ignorada. Redis backplane encaminha mensagens entre servidores, mas geralmente não remove a afinidade nem define ownership de sessões de agente ou roteamento de comandos.

Azure SignalR Service e Redis são opções com topologias, custos e dependências diferentes; o Dokpod não usa nenhuma delas. O plano começa com uma instância de API. Escala horizontal requer decisão sobre ownership, fencing e roteamento durável de comandos, motivada por métricas e ADR.

Observe conexões atuais e encerradas, timeouts, falhas de autorização e latência até o refresh. O ASP.NET Core oferece logs e métricas de conexão. Aumente a verbosidade somente durante diagnóstico: logs, HAR e traces podem conter payloads sensíveis.

Exemplo Prático: browser, BFF, Keycloak e invalidação

O fluxo abaixo usa o console do Dokpod: SignalR não substitui REST nem é o canal do agente.

O Angular registra handlers, solicita antiforgery ao BFF e conecta-se por /hubs/control-plane com o cookie de sessão.
O BFF valida sessão e origem e acrescenta o Bearer server-side no salto até a API.
JoinEnvironmentAsync valida o GUID e consulta Keycloak para environment:read naquele recurso.
Somente uma decisão permitida adiciona a conexão ao grupo determinístico do ambiente.
A API emite invalidated; o Angular consulta REST para obter o estado atual.
Após reconectar, o cliente reinscreve ambientes e atualiza o estado por REST; avisos do intervalo podem ter sido perdidos.

builder.Services.AddSignalR(options =>
{
    options.KeepAliveInterval = TimeSpan.FromSeconds(15);
    options.ClientTimeoutInterval = TimeSpan.FromSeconds(30);
});

app.MapHub<ControlPlaneHub>("/hubs/control-plane")
    .RequireAuthorization();

📂 Código-fonte: ApiHost.cs. A API atual também configura autenticação JWT e uma política que exige usuário autenticado.

ConsoleRealtimeService é o cliente Angular e SignalRControlPlaneNotifier publica fora do Hub. Serviços notificam mudanças de inventário, eventos e hosts; a leitura seguinte continua usando uma rota HTTP autorizada. Agentes permanecem no canal gRPC/mTLS.

O relatório de prontidão de 25/09 registra conexão browser autorizada e negação do ambiente sem acesso; testes também cobrem rotas protegidas, grupo estável e identificador inválido. Isso valida uma fatia, não carga nem release: o veredito geral continua NO-GO, com gates de operação e distribuição pendentes. docs/bff.md preserva status histórico de 13/09, anterior à autorização horizontal; considerei o código e a avaliação mais recentes sem alterar esse registro.

SignalR, gRPC, SSE e WebSockets: escolha pelo fluxo

Use SignalR quando a aplicação ASP.NET Core se beneficia de Hub, grupos e clientes suportados. Para eventos unidirecionais, SSE pode ser menor; para controlar um canal duplex, WebSockets puros; para serviços com contrato explícito e streaming, gRPC.

Em todos os casos, avalie autenticação, observabilidade, semântica de falha e infraestrutura junto com o formato do tráfego.

Tecnologia	Consumidor comum	Fluxo	O que oferece	Trade-off principal
SignalR	Browser e clientes ASP.NET	Mensagens e streams nos dois sentidos	Hub, grupos, negociação de transporte e integração .NET	Conexões persistentes, autorização e estratégia de scale-out
SSE	Browser	Servidor → cliente	Stream HTTP unidirecional simples	Cliente envia comandos por outro canal; proxy não pode acumular o stream
WebSockets	Browser ou serviço	Duplex	Canal persistente de baixo nível	A aplicação administra framing, eventos, reconexão e roteamento
gRPC	Serviços e agentes	Unary ou streaming	Contratos Protobuf, clientes gerados e HTTP/2	Integração com browser e infraestrutura têm requisitos próprios

No Dokpod, REST/OpenAPI atende consultas, SignalR entrega invalidações ao browser e gRPC/mTLS conecta a API aos agentes. O comparativo de tempo real e o guia de gRPC no .NET 10 detalham essas escolhas.

Dicas e Boas Práticas

Não mantenha estado de domínio na instância do Hub. Trate o Hub como uma fronteira de invocação e delegue regras para serviços de aplicação. Para estado que precisa sobreviver à desconexão, persista ou reconstrua por uma API durável.
Autorize antes de adicionar a conexão a um grupo. Derive o recurso e o scope no servidor, a partir do principal autenticado, e não confie em um nome de grupo fornecido pelo cliente. Reavalie permissões em fluxos longos quando a política exigir revogação durante a sessão.
Trate start() separado de reconexão automática. Configure o tratamento de falhas da primeira conexão e apresente os estados connecting, connected, reconnecting e disconnected. A política padrão de withAutomaticReconnect() tem tentativas finitas; não significa reconexão eterna.
Restaure assinaturas e estado após reconectar. Refaça a entrada em grupos porque a conexão nova não herda toda a inscrição anterior. Faça também uma consulta REST para obter o estado atual que pode ter mudado enquanto o cliente estava offline.
Envie invalidações pequenas, não snapshots grandes. O browser pode atualizar a projeção consultando o recurso autorizado. Para histórico, replay ou consumo confirmado, use um mecanismo durável com cursor e semântica explícita.
Mantenha a origem e a borda restritas. Prefira same-origin pelo BFF quando houver tokens server-side, valide Origin em conexões por cookie e não abra CORS com credenciais para qualquer origem. Configure nginx/balanceador para o transporte realmente habilitado.
Meça conexões antes de adicionar infraestrutura. Observe conexões ativas, duração, timeouts, reconexões, limites e tráfego por cliente. Afinidade, backplane ou serviço gerenciado resolvem problemas distintos; escolha depois de conhecer a topologia e a carga.

Conclusão

SignalR oferece uma API produtiva para comunicação em tempo real no ASP.NET Core, mas suas abstrações não eliminam as decisões de segurança e operação. Um Hub organiza chamadas; um grupo direciona mensagens; uma conexão pode cair; e a notificação não se transforma em estado persistente. Quando a aplicação precisa recuperar informação confiável, a consulta deve voltar a uma fonte durável.

O fluxo do Dokpod demonstra essa separação: o browser conecta pelo BFF, a API autoriza cada ambiente com Keycloak, envia uma invalidação e o Angular consulta REST. Reconexão restaura inscrições; gRPC/mTLS continua sendo o canal dos agentes.

Eu adotaria SignalR quando baixa latência, comunicação bidirecional ou integração com Hub compensarem o custo de conexões persistentes. Para stream unidirecional, compararia SSE; para serviços controlados, gRPC. A série percorre REST, GraphQL, gRPC e SignalR conforme a necessidade.

Antes de tratar esse canal como infraestrutura crítica, eu testaria a jornada pela borda real: autorização permitida e negada, reinício da API, perda de conexão, reinscrição e reconciliação pela consulta REST. O resultado precisa ser medido sob a carga esperada, não inferido de um teste local de Hub.

Resumo Objetivo

ASP.NET Core SignalR — biblioteca de tempo real com Hubs e negociação entre WebSockets, SSE e Long Polling compatíveis.
Hub do SignalR — expõe métodos e eventos; sua instância não deve guardar estado de domínio durável.
Grupos SignalR — direcionam mensagens, mas não são armazenamento, fila durável nem autorização.
Reconexão JavaScript — withAutomaticReconnect() tenta em 0, 2, 10 e 30 segundos; falhas de start() exigem tratamento separado.
Autorização por ambiente — JoinEnvironmentAsync consulta Keycloak para environment:read antes de associar a conexão.
Notificações do Dokpod — invalidated leva o browser à API REST, fonte do estado durável.
Escala SignalR — múltiplas instâncias exigem afinidade ou scale-out compatível; Redis e Azure SignalR têm requisitos distintos.
Prontidão do Dokpod — a validação SignalR permitida/negada não altera o veredito geral de release: NO-GO.

Referências

Visão geral do ASP.NET Core SignalR — conceitos, transportes e protocolo de Hub.
Hubs no ASP.NET Core SignalR — ciclo de vida, chamadas e uso de IHubContext.
Cliente JavaScript do SignalR — conexão, invocação, eventos e reconexão.
Autenticação e autorização no SignalR — cookies, bearer tokens, [Authorize] e autorização por método.
Grupos no SignalR — inscrição, roteamento e limites de segurança dos grupos.
Escala e hospedagem do SignalR — afinidade, Redis backplane, Azure SignalR Service e proxy nginx.
Configuração do SignalR — timeouts, keep-alive, limites e protocolos de serialização.
Diagnóstico do SignalR — logs, métricas, tracing e riscos de capturar payloads.
Repositório público do Dokpod — código consultado na branch main, sem uma release ou tag estável identificada. 📬

👉 Artigo completo com todos os exemplos de código: SignalR no .NET: do primeiro Hub à produção

GraphQL para Iniciantes: Guia Completo com .NET

Lincoln Zocateli — Mon, 26 Oct 2026 09:01:26 +0000

Introdução

GraphQL é uma linguagem de consulta para APIs e um runtime que executa essas consultas sobre um schema tipado. Em vez de receber sempre uma representação fixa de um recurso, o cliente descreve os campos de que precisa; o servidor valida a operação, chama os resolvers responsáveis e devolve um JSON com aquele formato. Eu consideraria GraphQL quando diferentes clientes precisam de combinações variadas de dados ou quando uma tela depende de informações relacionadas que hoje exigem várias chamadas, desde que a equipe também esteja preparada para controlar o custo das consultas.

Essa flexibilidade não torna GraphQL automaticamente mais rápido, menor ou mais simples que REST. Ela desloca parte do trabalho para o schema e para os resolvers: o cliente escolhe os campos, mas o servidor continua responsável por autorização, validação, limites de consulta, paginação e acesso eficiente aos dados. Uma query mal controlada ainda pode fazer o backend executar trabalho excessivo.

Neste guia eu explico schema, types, queries, mutations e resolvers, mostro uma implementação executável com GraphQL.NET no ASP.NET Core/.NET 10 e comparo a mesma leitura com um endpoint REST. Também vou separar o que a demo realmente implementa das medidas que uma API de produção precisa acrescentar. Este é o segundo artigo da série APIs e Comunicação em .NET: a parte 1 apresenta gRPC e seus critérios de uso; a próxima será um guia específico de SignalR.

ℹ️ Informação: O sample testado usa GraphQL.NET 8.8.5, GraphQL.Server.Transports.AspNetCore 8.3.3 e .NET SDK 10.0.402. A query, a mutation, a validação e o endpoint REST foram exercitados por HTTP no processo real da API.

Pré-requisitos

Para acompanhar o exemplo, você precisa de C# básico, familiaridade com HTTP e .NET SDK 10.0.400 ou superior. O código completo está no repositório BlogSamples; clone-o e inicie a API com a URL explicitada:

git clone https://github.com/lzocateli/blog-zocateli-sample.git
cd blog-zocateli-sample
dotnet run --project src/BlogSamples --urls http://localhost:5101

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

A API agregadora também inicia outros domínios do repositório. O worker de outbox existente depende de PostgreSQL e registra falhas de conexão se o serviço não estiver disponível; isso não é dependência do tutorial GraphQL. Os endpoints deste exemplo usam o serviço de produtos em memória, e qualquer produto criado desaparece quando o processo termina.

O que GraphQL é e como uma operação é executada

GraphQL não é sinônimo de JSON nem de HTTP. GraphQL define uma linguagem para expressar operações e uma especificação para schemas, tipos, validação e execução. HTTP costuma transportar a operação e a resposta, mas o transporte é uma camada separada. Uma API GraphQL pode usar um endpoint HTTP como /graphql; a query é enviada no corpo de uma requisição POST ou, em cenários apropriados, em uma requisição GET.

O schema (esquema) é o contrato que descreve os tipos, campos, argumentos e operações que o servidor aceita. Uma query percorre esse grafo de campos. Por exemplo, product pode retornar um Product, e esse tipo pode oferecer id, name, price e category. O contrato descreve o que pode ser solicitado, não necessariamente como os dados estão guardados: eles podem vir de uma tabela, de uma API externa, de cache ou de mais de uma fonte.

Em uma requisição, o servidor primeiro interpreta a sintaxe da operação. Depois valida se os campos e argumentos existem no schema e se os tipos são compatíveis. Se a operação passar, o executor resolve os campos solicitados e monta uma resposta JSON com a mesma forma da seleção. Uma falha de validação impede a operação antes de chamar os resolvers; uma falha durante a execução pode retornar data parcial ou nulo junto com errors.

⚠️ Atenção: A linguagem GraphQL define a operação, não uma promessa de transporte universal. O exemplo usa HTTP POST com JSON; WebSockets e subscriptions são outro recorte, não fazem parte desta implementação.

Schema, types, queries, mutations e inputs

Um type é um tipo do schema. O GraphQL define scalars como String, Int, Float, Boolean e ID; o schema também pode declarar enums, tipos de objeto e input objects. Product e Category são tipos de saída: descrevem os dados que o servidor pode devolver. Um input object agrupa valores recebidos, geralmente para uma mutation com vários parâmetros.

O schema tem um root type de leitura, normalmente chamado Query, e pode ter um root Mutation para operações de escrita. Subscription é usado para atualizações contínuas quando a implementação escolhe um transporte compatível. Esses nomes são convenções do contrato, não nomes de tabelas ou classes obrigatórios. Um campo pode receber argumentos e retornar um objeto, uma lista, um scalar ou um valor nullable.

O exemplo usa CreateProductInput para agrupar name, description, price, stock e categoryId. Isso deixa a assinatura da mutation legível e facilita evoluir os dados de entrada. No resolver, os valores são convertidos para o CriarProdutoRequest já usado pela API. A entrada passa por validação explícita de nome, preço, estoque e categoria antes da chamada ao serviço.

Um enum limita um campo a valores nomeados, como DRAFT e PUBLISHED, em vez de aceitar qualquer string. Tipos não-null (Product!) e listas ([Product!]!) também expressam nulabilidade no contrato; use essas garantias somente quando a aplicação consegue cumpri-las.

Uma mutation não substitui regras de domínio nem uma transação. O schema determina a forma de entrada e saída; o resolver chama a aplicação, que deve validar as invariantes, autorizar o usuário e controlar persistência e efeitos colaterais. No sample, o armazenamento é deliberadamente em memória e não existe autenticação. Isso é suficiente para demonstrar o fluxo, não para representar uma API de produção.

O papel dos resolvers e o problema N+1

Um resolver é a função que obtém o valor de um campo. Ele pode ler uma propriedade já carregada, consultar um serviço ou compor resultados de fontes diferentes. Argumentos da query chegam ao resolver pelo contexto de execução; dependências de aplicação podem ser acessadas pelo container de injeção de dependência. O schema não exige que cada campo faça uma consulta própria: campos irmãos podem compartilhar dados, e uma camada de aplicação pode devolver um objeto já preparado.

No sample, o resolver do root product(id:) chama IProdutoService.ObterProdutoPorIdAsync. O campo category usa o CategoriaId do DTO e pede a categoria ao mesmo serviço. Em uma query para um único produto, isso é fácil de acompanhar. Se o schema passasse a listar dezenas de produtos e cada item buscasse sua categoria individualmente, o padrão poderia gerar uma consulta para a lista e mais uma para cada categoria: o problema N+1.

O DataLoader agrupa chaves solicitadas durante uma execução e permite buscar vários valores em lote; ele também pode reaproveitar o resultado para chaves repetidas dentro daquele contexto. Com 50 pedidos que carregam usuários, por exemplo, a aplicação pode fazer uma busca dos pedidos e uma busca em lote dos usuários, em vez de 51 acessos separados. O ganho depende de a fonte oferecer uma operação em lote e de o loader estar configurado no escopo correto; não é uma otimização automática de qualquer resolver.

Por isso, mantenha resolvers finos: encaminhe a operação a serviços que concentrem autorização e regras de domínio, limite listas e propague cancelamento e erros. A demo não implementa DataLoader porque consulta apenas um produto e uma categoria, sem uma lista que exponha N+1.

GraphQL.NET no ASP.NET Core e .NET 10

GraphQL.NET fornece o executor, os tipos e os recursos de integração com injeção de dependência. O transporte ASP.NET Core adiciona middleware HTTP para receber operações no endpoint. No sample, GraphQL e seus pacotes de DI e serialização estão fixados em 8.8.5, enquanto GraphQL.Server.Transports.AspNetCore está em 8.3.3; os pacotes verificados declaram licença MIT e targets compatíveis com frameworks superiores.

A documentação atual de integração GraphQL.NET apresenta um quickstart cujo TargetFramework é net10.0. A página de NuGet do transporte 8.3.3 ainda descreve compatibilidade do middleware até ASP.NET Core 9. Como essas informações não estão alinhadas, eu não trato a declaração de targets do NuGet como prova isolada do runtime: restaurei e compilei os pacotes no SDK 10.0.402 e executei query, mutation e erro de validação no endpoint real do sample em .NET 10.

O registro de serviços liga o schema à implementação JSON. Os graph types que o schema descobre também precisam estar disponíveis no DI:

// Registra os graph types e o schema tipado da API.
builder.Services.AddSingleton<ProdutoGraphType>();
builder.Services.AddSingleton<CategoriaGraphType>();
builder.Services.AddSingleton<CriarProdutoInputGraphType>();
builder.Services.AddGraphQL(options => options
    .AddSchema<ProdutoSchema>()
    .AddSystemTextJson());

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

Depois de construir a aplicação, o middleware recebe operações em /graphql:

app.UseWebSockets();
app.UseGraphQL<ProdutoSchema>("/graphql");

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

O sample registra ProdutoSchema, cujo root Query contém product(id:) e cujo root Mutation contém createProduct(input:). Não há GraphiQL, subscriptions, banco de dados novo ou outra engine GraphQL neste exemplo.

Exemplo Prático

Vou consultar o produto de ID 1, que no seed da API é o Smartphone Galaxy S25. A query pede somente identificador, nome, preço e nome da categoria; as variáveis ficam separadas do texto da operação, o que facilita reutilizar a query sem interpolar valores na string.

# Envia a operação e o argumento id como variável JSON.
curl -i http://localhost:5101/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"query($id:Int!){product(id:$id){id name price category{name}}}","variables":{"id":1}}'

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

Resposta observada no sample:

{"data":{"product":{"id":1,"name":"Smartphone Galaxy S25","price":4299.00,"category":{"name":"Eletrônicos"}}}}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

Agora faço a leitura REST do mesmo ID:

curl -i http://localhost:5101/api/products/1

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

{"id":1,"name":"Smartphone Galaxy S25","description":"Tela AMOLED 6.2\", 256GB, 5G","price":4299.00,"stock":45,"active":true,"categoryId":1,"categoryName":"Eletrônicos"}

O endpoint REST do sample retorna a representação que seu contrato definiu; a query GraphQL do exemplo pediu uma projeção específica no próprio documento. Isso ilustra duas interfaces concretas, não uma limitação intrínseca do REST. Uma API REST também pode ter endpoints especializados, parâmetros de projeção ou representações diferentes. Os dois JSONs são da mesma fonte em memória, mas cada contrato expõe um formato distinto.

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

Para criar um produto, envio um CreateProductInput. O primeiro produto criado em uma execução limpa recebeu o ID 53; a mutation retorna esse valor e os campos selecionados:

curl -i http://localhost:5101/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"mutation($input:CreateProductInput!){createProduct(input:$input){id name price category{name}}}","variables":{"input":{"name":"Mouse GraphQL","description":"Produto de demonstração","price":99.90,"stock":10,"categoryId":1}}}'

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

{"data":{"createProduct":{"id":53,"name":"Mouse GraphQL","price":99.90,"category":{"name":"Eletrônicos"}}}}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

O resolver rejeita um preço igual a zero antes de chamar IProdutoService. O transporte retorna HTTP 200, mas a resposta inclui errors e createProduct: null; por isso, um cliente GraphQL deve examinar o corpo da resposta, não apenas o status HTTP.

curl -i http://localhost:5101/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"mutation($input:CreateProductInput!){createProduct(input:$input){id name price}}","variables":{"input":{"name":"Produto inválido","price":0,"stock":10,"categoryId":1}}}'

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

{"errors":[{"message":"Preço deve ser entre R$ 0,01 e R$ 999.999,99.","path":["createProduct"]}],"data":{"createProduct":null}}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

Uma query que tenta selecionar um campo inexistente é rejeitada antes da execução. No servidor testado, essa falha de validação retornou HTTP 400 com o código FIELDS_ON_CORRECT_TYPE.

curl -i http://localhost:5101/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ product(id:1) { missingField } }"}'

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

{"errors":[{"message":"Cannot query field 'missingField' on type 'Product'.","extensions":{"code":"FIELDS_ON_CORRECT_TYPE","number":"5.3.1"}}]}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/GraphQL/

Segurança e limites operacionais

GraphQL não substitui autenticação nem autorização. Saber o ID de um objeto não prova que o usuário pode lê-lo ou alterá-lo. O servidor deve verificar autorização no nível do recurso e, quando necessário, de cada campo; mutations precisam validar o usuário e a regra de domínio antes de produzir efeitos. Uma checagem apenas no endpoint pode ser insuficiente quando o mesmo schema expõe dados com níveis de acesso diferentes.

A flexibilidade também cria um orçamento de execução. Uma API que aceita listas deve impor paginação com limite máximo, restringir profundidade e complexidade quando o grafo permite consultas caras, controlar batching e aplicar timeouts e rate limits por identidade ou cliente. O tamanho do corpo HTTP também precisa de limite. Contar requests isoladamente não mede o trabalho: uma única operação pode selecionar muitos campos ou repetir chamadas a objetos diferentes.

Introspection permite que clientes consultem o próprio schema. Ela é útil para ferramentas, mas avalie sua exposição; restringi-la não substitui autorização ou limites de custo. Não exponha GraphiQL sem necessidade e evite stack traces e detalhes internos em erros de produção.

O transporte GraphQL.NET 8.3.3 habilita proteção CSRF por padrão e não habilita processamento de formulários POST por padrão. Ainda assim, uma API com autenticação por cookie precisa revisar métodos aceitos, CORS, headers e mecanismos de CSRF na configuração real. Para mutations, use POST; não trate validação de tipos como autorização, e não confie em dados do cliente sem validar invariantes no domínio.

Na demo, a validação de nome, preço, estoque e categoria está implementada, mas a API não tem login, política de autorização, rate limit, limite de complexidade ou persistência. A introspection permanece disponível e não existe interface GraphiQL. Esses são limites deliberados do exemplo didático; não os interprete como configuração recomendada para uma API pública.

⚠️ Atenção: O schema descreve campos disponíveis, não quem pode acessá-los. Cada resolver ou caso de uso precisa aplicar as regras de acesso ao dado e à operação.

GraphQL, REST e gRPC: como escolher

Eu começaria pelos consumidores, contrato e tráfego, não pela preferência da equipe. GraphQL atende combinações variáveis de dados; REST organiza recursos e semântica HTTP; gRPC define métodos e mensagens tipadas para serviços controlados e streaming.

Critério	REST	GraphQL	gRPC
Contrato	Recursos, URLs e semântica HTTP	Schema tipado e campos selecionáveis	Serviços e mensagens em contrato Protobuf
Seleção de dados	Representação definida pelo endpoint; pode ter projeções	Seleção escrita em cada query	Estrutura da mensagem definida pelo método
Cache	Integra-se diretamente às semânticas de cache HTTP para GET	Depende do transporte, da operação e da estratégia de cache adotada	Normalmente exige estratégia da aplicação ou intermediário compatível
Streaming	HTTP permite streaming, conforme endpoint e formato	Subscriptions dependem de um transporte e protocolo configurados	Streaming unary, servidor, cliente ou bidirecional faz parte do modelo RPC
Cliente comum	Navegadores, serviços e ferramentas HTTP	Clientes que entendem o schema e enviam operações GraphQL	Serviços com contrato e cliente gerado; browser pode precisar de gRPC-Web
Custo operacional	Modelar recursos e evoluir representações	Operar schema, resolvers, autorização e limites de query	Gerar/versionar contratos, configurar HTTP/2 e operar streams

No exemplo acima, GET /api/products/1 devolve descrição, estoque e categoria achatada, enquanto a query GraphQL seleciona id, name, price e category { name }. Isso mostra o contrato que implementamos: não prova que REST sempre devolva campos demais. Uma rota REST poderia oferecer projeção ou uma representação menor; compare contratos concretos em vez de padrões caricaturados.

Para cliente web com leituras compostas e requisitos variáveis, GraphQL pode concentrar a coordenação e reduzir chamadas específicas, desde que limites e resolvers sejam bem projetados. Para recursos que se encaixam em métodos HTTP e cache convencional, REST pode ser mais simples. Para serviços internos que precisam de contratos gerados ou streams contínuos, gRPC pode encaixar melhor. É possível usar mais de um estilo em partes diferentes de um produto; nenhum vence em todos os cenários.

Dicas e Boas Práticas

Modele o domínio antes do banco. Os tipos e campos devem representar o contrato útil para os clientes, não espelhar tabelas ou entidades internas. Isso deixa a API evoluir sem expor a estrutura de persistência.
Mantenha resolvers pequenos. Use-os para encaminhar argumentos a serviços e montar resultados, não para concentrar autorização, regra de negócio e consultas ad hoc. A lógica importante precisa ser reutilizável e testável fora do GraphQL.
Coloque limites em toda lista. Paginação com tamanho máximo evita que uma seleção válida peça um volume ilimitado de objetos. Combine esse limite com análise de profundidade ou custo quando o schema tiver relações amplas.
Trate N+1 como risco de acesso a dados. Meça quantas chamadas cada query dispara e use DataLoader quando vários resolvers pedirem chaves que possam ser agrupadas. Batching precisa respeitar tenant, autorização e escopo da requisição.
Valide e autorize mutations no domínio. Tipos GraphQL ajudam a rejeitar formatos inválidos, mas não substituem regras de negócio nem permissão por registro. Retorne erros úteis sem expor stack traces, SQL ou dados internos.
Evolua o schema de forma compatível. Prefira adicionar campos e deprecar os antigos com um prazo claro antes de removê-los. Acompanhe quais clientes ainda usam cada campo e trate mudanças incompatíveis como uma migração explícita.

Conclusão

GraphQL oferece ao cliente uma linguagem para selecionar dados dentro de um contrato tipado. Esse modelo é especialmente útil quando consumidores precisam de combinações diferentes de informações, mas exige atenção ao custo de cada operação, aos resolvers, à autorização e à evolução do schema. A implementação demonstrada usa GraphQL.NET 8.8.5 e o transporte ASP.NET Core 8.3.3 em .NET 10, sobre os mesmos produtos em memória que alimentam um endpoint REST.

Eu não escolheria GraphQL só porque uma query pode pedir poucos campos. REST também admite projeções e representações especializadas, e gRPC resolve outros problemas de contrato e streaming. A decisão deve partir dos clientes, dos fluxos de leitura e escrita, do cache, do transporte e da capacidade de operar a solução. Na próxima parte da série, vou tratar de SignalR como uma opção para comunicação em tempo real no .NET, sem confundir esse problema com consultas de dados.

Resumo Objetivo

GraphQL é uma linguagem de consulta e um runtime que executa operações sobre um schema tipado; o cliente seleciona campos e o servidor valida e resolve cada operação.
Query e Mutation são roots do schema GraphQL normalmente usados para leitura e escrita; mutations ainda precisam de validação de domínio, autorização e controle de efeitos colaterais.
GraphQL.NET 8.8.5 e GraphQL.Server.Transports.AspNetCore 8.3.3 executaram query, mutation e validação HTTP em uma API ASP.NET Core/.NET 10 do sample BlogSamples.
DataLoader pode agrupar buscas feitas por resolvers e reduzir o padrão N+1 quando a fonte de dados oferece uma operação em lote; ele não elimina a necessidade de limites ou autorização.
REST pode oferecer projeções e representações especializadas; a diferença entre os JSONs deste artigo descreve apenas os contratos concretos testados.
GraphQL, REST e gRPC têm modelos e custos operacionais diferentes; a escolha depende dos clientes, do contrato, do transporte e das necessidades de streaming e cache.

Referências

GraphQL Learn — introdução oficial a schemas, queries, mutations e práticas de operação.
GraphQL Specification — September 2025 — semântica normativa da linguagem e do sistema de tipos.
GraphQL.NET ASP.NET Core Integration — configuração atual do transporte e exemplo de integração com .NET 10.
GraphQL.NET DataLoader — batching e cache por requisição para relacionamentos resolvidos por campo.
GraphQL.NET Server — middleware ASP.NET Core, transporte HTTP e configuração de segurança.
OWASP GraphQL Cheat Sheet — recomendações para validação, autorização, introspection e limites de consultas.
GraphQL over HTTP — especificação em desenvolvimento para transportar operações GraphQL sobre HTTP. 📬

👉 Artigo completo com todos os exemplos de código: GraphQL para Iniciantes: Guia Completo com .NET

gRPC sem mistério: o que é e quando usar no .NET 10

Lincoln Zocateli — Sun, 18 Oct 2026 18:31:18 +0000

Introdução

Imagine um plano de controle que precisa conversar continuamente com agentes instalados em vários hosts. A API envia comandos, cada agente publica heartbeats (sinais periódicos de que continua ativo), informa mudanças no inventário e pode abrir um canal interativo para um terminal. Uma sequência de chamadas HTTP independentes ainda funcionaria para operações pontuais, mas não expressaria tão naturalmente esse fluxo persistente nos dois sentidos. É nesse tipo de problema que gRPC no .NET 10 merece ser considerado.

gRPC é uma estrutura de chamadas de procedimentos remotos (RPC, de Remote Procedure Call): o cliente invoca métodos definidos por contrato em um servidor, usando mensagens tipadas que normalmente são serializadas com Protocol Buffers e transportadas por HTTP/2. Eu o escolheria quando os participantes são serviços sob controle da mesma equipe, precisam compartilhar contratos gerados ou manter um fluxo de mensagens contínuo, especialmente bidirecional. Isso não faz de gRPC um substituto universal de REST, nem prova que ele será mais rápido para qualquer aplicação.

No Dokpod, o navegador usa REST/OpenAPI para operações da interface e SignalR para notificações. O gRPC fica no canal interno entre a API e os agentes: o agente inicia uma conexão de saída, autentica-se com certificado de cliente e mantém um stream para trocar mensagens de controle. Essa escolha responde a uma necessidade concreta do sistema, não a uma regra para todos os produtos.

Este é o primeiro de três artigos da série APIs e Comunicação em .NET. A parte 2 será um guia introdutório de GraphQL; a parte 3 explicará SignalR no .NET, do primeiro Hub à produção. Os dois ainda não foram publicados, por isso não incluo links inexistentes.

ℹ️ Informação: Na data desta consulta, o repositório público do Dokpod não possui releases ou tags publicados. Os links de código neste artigo apontam para a branch main e acompanham seu estado atual; por isso, podem mudar e não representam uma release estável.

RPC, REST e a função do HTTP/2

Uma chamada RPC começa com uma pergunta conhecida: “qual operação quero executar e qual mensagem preciso enviar?”. Um cliente chama um método como GetInventory; o servidor recebe os dados, executa a operação e devolve uma resposta. A rede está escondida atrás de uma interface semelhante a uma chamada local, mas a operação continua sendo remota: pode demorar, falhar, ser cancelada ou perder a conexão. Essa distinção importa porque uma rede não oferece as mesmas garantias de uma chamada dentro do processo.

Para uma RPC existir, cliente e servidor precisam concordar sobre o nome do método, os tipos de entrada e saída e como os dados serão representados. Esse acordo é o contrato. Em gRPC, costuma ser descrito em arquivos .proto; ferramentas geram código para construir mensagens e invocar o serviço. O código reduz diferenças de digitação e ajuda a detectar incompatibilidades durante o build, mas não elimina a necessidade de versionar e implantar os dois lados com cuidado.

REST parte de outra organização mental. Em vez de perguntar “qual método remoto chamo?”, o cliente interage com recursos identificados por URLs e usa a semântica HTTP, como GET, POST, PUT e DELETE. Uma API REST normalmente expõe representações, comumente JSON, que podem ser inspecionadas e consumidas por clientes diversos. gRPC descreve operações e mensagens com mais rigidez e costuma priorizar clientes que conhecem o contrato e podem usar código gerado. Não é uma divisão absoluta: ambos podem transportar dados estruturados e ambos dependem de decisões cuidadosas de design.

O gRPC tradicional usa HTTP/2. Essa versão do HTTP organiza mensagens em frames e permite multiplexar vários streams sobre uma conexão. Multiplexação significa que diferentes trocas podem compartilhar a conexão sem abrir uma conexão TCP para cada chamada. O HTTP/2 também define controle de fluxo para limitar quanto dado um receptor aceita. Esses recursos dão uma base adequada para chamadas persistentes, mas não tornam automaticamente uma aplicação mais rápida: serialização, tamanho das mensagens, rede, balanceamento, concorrência e trabalho no servidor continuam determinando o resultado.

Um stream gRPC é uma chamada lógica que pode conter uma mensagem ou várias. Não se deve confundi-lo com “uma conexão TCP por método” nem supor que uma conexão pode permanecer aberta para sempre em qualquer infraestrutura. Proxies, firewalls, NATs, limites de duração, certificados e reinicializações podem interromper o fluxo. A aplicação precisa decidir como detectar a queda, abrir outra sessão e recuperar o estado que ficou incerto.

Há também uma consequência prática: um cliente gRPC tradicional no navegador não é igual a um cliente C# ou Go. Navegadores não dão acesso irrestrito às primitivas HTTP/2 que o gRPC convencional espera. Para cenários web existem gRPC-Web e gateways que traduzem protocolos, mas eles adicionam componentes e restrições. No Dokpod, a interface usa HTTP e SignalR, enquanto os agentes usam gRPC; separar os consumidores evita obrigar o browser a falar o protocolo interno.

⚠️ Atenção: HTTP/2 multiplexa streams, mas a conexão continua sujeita a falhas e limites da rede. Trate toda desconexão como parte normal do desenho, não como um evento impossível.

Protocol Buffers, arquivos .proto e código gerado

Protocol Buffers, ou Protobuf, é um formato de serialização e uma linguagem para descrever mensagens. Serializar é transformar uma estrutura em bytes para transmiti-la ou armazená-la; desserializar é reconstruir a estrutura do outro lado. Um arquivo .proto declara mensagens, campos, números de campo, serviços e métodos. A partir dele, o compilador e os plugins da linguagem geram tipos para o cliente e o servidor.

Um campo tem tipo, nome e um número. O nome ajuda as pessoas que leem o contrato; o número identifica o campo no formato binário. Essa diferença é fundamental: depois de publicado e usado, um número não deve ser reaproveitado para outro significado. Se um campo for removido, reserve seu número e, quando apropriado, seu nome. Acrescentar campos opcionais costuma ser compatível no formato binário, mas isso não garante compatibilidade de comportamento. Um agente antigo pode ignorar um campo novo; já um código de negócio pode depender de uma capability (capacidade anunciada) que o agente não oferece.

Também é importante separar compatibilidade de wire format (formato transmitido) de compatibilidade de aplicação. Uma mudança pode continuar sendo decodificada e ainda quebrar um switch, uma validação ou uma regra de negócio. A implantação pode envolver várias versões de API e agentes ativas ao mesmo tempo. Por isso, mudanças de contrato precisam de uma estratégia de rollout, testes com versões consecutivas e observabilidade suficiente para identificar quem ainda usa o formato antigo.

No Dokpod, AgentControl declara dois métodos de streaming. Connect recebe mensagens do agente e devolve mensagens do plano de controle. Exec usa outro stream, separado, para quadros de terminal. Mensagens de envelope carregam metadados como versão do protocolo, identificador da sessão, fencing token e sequência. Um oneof agrupa tipos de payload alternativos, como AgentHello, Heartbeat, uma página de inventário ou um comando. Isso dá ao leitor uma visão explícita das mensagens possíveis sem transformar o canal em um proxy genérico para a API do engine.

O contrato também registra campos reservados e comentários de evolução. Por exemplo, mensagens de inventário têm revisões e páginas, e capabilities novas são aceitas somente quando o servidor as reconhece. Essa disciplina é parte do custo de um protocolo próprio: a equipe passa a ser responsável por documentar, testar e evoluir os contratos usados pelo produto.

Os quatro modos de chamada gRPC

O tipo de uma RPC é definido pelo número de mensagens que cada lado pode enviar durante a chamada. O método unary recebe uma mensagem e devolve uma mensagem. É o modelo mais simples: buscar detalhes de uma configuração, validar um token ou consultar uma informação pontual. Ele se parece com uma chamada HTTP de request/response, embora use método e mensagens tipados no contrato.

No streaming do servidor, o cliente envia uma requisição e o servidor responde com zero ou mais mensagens ao longo do tempo. Uma exportação paginada, uma sequência de progresso ou atualizações contínuas que não precisam de resposta do cliente são exemplos possíveis. O cliente pode cancelar o stream, e o servidor deve propagar o token de cancelamento para o trabalho assíncrono. Se o servidor tentar enviar uma resposta infinita sem limites, o custo de recursos também pode ser contínuo.

No streaming do cliente, o cliente envia várias mensagens e recebe uma resposta final. Isso pode fazer sentido para enviar lotes, fragmentos de uma tarefa ou amostras que o servidor consolida. O servidor lê até o cliente encerrar o stream e então responde. Esse padrão não é apenas “muitas chamadas unary”: mantém uma chamada aberta e uma sequência ordenada de mensagens.

No streaming bidirecional, ou duplex, os dois lados podem enviar várias mensagens durante a mesma chamada. Eles não precisam alternar uma mensagem de cada lado: cliente e servidor podem ler e escrever independentemente. É útil quando há troca contínua de comandos, respostas, estados e confirmações. O protocolo da aplicação ainda deve definir correlação, ordenação, controle de fluxo, prioridade e o que fazer quando a chamada termina.

Modo	Mensagens do cliente	Mensagens do servidor	Exemplo de uso
Unary	Uma	Uma	Consulta pontual
Streaming do servidor	Uma	Muitas	Progresso ou feed de leitura
Streaming do cliente	Muitas	Uma	Envio de lotes para consolidação
Bidirecional	Muitas	Muitas	Canal interativo de controle

O Connect do Dokpod é bidirecional porque os agentes e a API precisam enviar mensagens enquanto a sessão está ativa. Isso não significa que todo agente precise transmitir dados a cada instante. Heartbeats, inventário e comandos são mensagens de aplicação carregadas no stream; a aplicação ainda define quando e por que cada uma deve circular.

Por que o Dokpod escolheu gRPC para os agentes

O contexto do Dokpod é diferente de uma API pública voltada a qualquer navegador. O produto precisa alcançar engines de containers instalados em hosts que podem estar em redes privadas, atrás de NAT ou protegidos por regras que não permitem conexões iniciadas de fora. Fazer cada API central iniciar uma conexão até o host exigiria endereços acessíveis e regras de rede por ambiente.

Com uma conexão de saída, o agente inicia a sessão até a API. Isso costuma se encaixar melhor em redes restritas porque o host precisa permitir uma saída controlada, não publicar o socket Docker, um endpoint Podman ou SSH para a rede. O padrão não elimina a configuração de rede nem todas as ameaças, mas reduz a necessidade de abrir a interface administrativa do engine para conexões remotas.

O segundo motivo é o contrato de domínio. Um proxy genérico que encaminhasse qualquer chamada para o Docker Engine ampliaria o impacto de uma falha de autorização: a API poderia se tornar uma ponte para operações arbitrárias do host. O Dokpod envia comandos próprios e versionados, como iniciar ou parar um container, e o agente valida o que recebeu antes de usar o adapter do engine. Isso limita a superfície em comparação com um proxy irrestrito. Ainda assim, o agente é um componente privilegiado; o protocolo precisa autorizar cada operação, validar entradas e evitar exposição de dados sensíveis.

O streaming bidirecional permite que o servidor envie comandos e que o agente informe aceitação, resultado, heartbeat e diferenças de inventário no mesmo canal de controle. A escolha também permite que o servidor negocie sessão, versão e capabilities. Isso é valioso para um produto que controla as duas pontas, mas traz o custo de manter uma especificação e garantir compatibilidade entre elas.

Há limites importantes. O plano atual começa com uma instância da API. Escalar horizontalmente requer decidir qual instância é dona de cada stream, como rotear comandos e como recuperar ownership após falhas. O Dokpod adia essa escala distribuída para uma decisão futura. Os testes executados confirmaram o funcionamento do adapter com Podman Linux; isso não substitui a validação de cada combinação de versões e ambiente. O agente Windows ainda depende de gates de qualificação. A escolha do protocolo não certifica automaticamente todos os engines ou sistemas operacionais.

Como o fluxo gRPC do Dokpod funciona

O agente abre AgentControl.Connect e envia AgentHello como primeira mensagem. O hello informa versão do agente, engine e versão, sistema operacional, arquitetura, hostname e capabilities. O servidor obtém o certificado de cliente da conexão TLS e entrega certificado e hello ao negociador de sessão. Se a identidade ou a negociação forem rejeitadas, a chamada termina com um erro gRPC; não existe uma sessão válida apenas porque o TCP conectou.

Quando aceita a sessão, o plano de controle devolve SessionEstablished: versão de protocolo selecionada, identificador da sessão, fencing token, intervalo de heartbeat, limite de mensagem e capabilities aceitas. O agente valida esses metadados antes de iniciar o trabalho da sessão. O intervalo anunciado é de 15 segundos e o serviço usa timeout de heartbeat de 90 segundos. Esses números descrevem o código consultado, não uma recomendação universal para qualquer rede.

Depois da negociação, o agente pode publicar snapshots paginados e deltas do inventário. O snapshot reconstrói o estado completo em partes; o delta representa mudanças a partir de uma revisão-base. Heartbeats incluem a última sequência de comando aplicada e revisões de inventário. A API também pode enviar requisições de reconciliação, consultas e comandos de domínio. Separar “aceito” de “resultado concluído” permite representar que receber a ordem não significa que o engine já terminou a operação.

O trecho abaixo resume a forma do contrato, sem tentar reproduzir todas as mensagens:

// Contrato resumido: os tipos reais são definidos no mesmo arquivo .proto.
service AgentControl {
  rpc Connect(stream AgentMessage) returns (stream ControlPlaneMessage);
  rpc Exec(stream ExecFrame) returns (stream ExecFrame);
}

📂 Código Fonte: O contrato completo está na branch main do Dokpod: agent.proto.

No cliente, o agente escreve o hello, aguarda a confirmação inicial e só então considera a sessão estabelecida. O código gerado fornece os tipos e o proxy do serviço; a lógica abaixo mostra o ponto de validação, não um cliente completo:

// Abre Connect e apresenta o hello antes de enviar outros eventos.
using var call = connect(stoppingToken);
await call.RequestStream.WriteAsync(hello, stoppingToken);

if (!await call.ResponseStream.MoveNext(stoppingToken) ||
    call.ResponseStream.Current.PayloadCase !=
        ControlPlaneMessage.PayloadOneofCase.SessionEstablished)
{
    throw new RpcException(new Status(
        StatusCode.FailedPrecondition, "agent_session_not_established"));
}

📂 Código Fonte: O fluxo de sessão e reconexão está em AgentControlWorker.cs; o processamento no servidor está em AgentControlService.cs.

O terminal usa AgentControl.Exec, um stream separado que começa com handshake vinculado à identidade do certificado, sessão ativa, fencing token e sessão de terminal pendente. Ele transporta frames de entrada, saída, redimensionamento e status. Um canal separado evita misturar o fluxo interativo com heartbeats e inventário, mas exige limites, expiração e encerramento coordenado.

Segurança, reconexão e confiabilidade

gRPC não é uma política de segurança. TLS protege o canal e autentica o servidor; mTLS acrescenta certificado de cliente, que permite ao servidor autenticar a identidade do agente. No fluxo do Dokpod, a API exige o certificado de cliente e negocia a sessão a partir dele e das informações do agente. Certificados precisam ter emissão, rotação, revogação, armazenamento e escopo bem definidos. Um certificado válido identifica um participante, mas não substitui autorização de negócio para cada comando.

É útil separar quatro perguntas: quem estabeleceu o canal? A que ambiente essa identidade pertence? O protocolo aceita a versão e as capabilities anunciadas? A identidade pode executar esta operação, neste recurso e neste momento? Resolver apenas a primeira pergunta com mTLS deixaria o restante sem resposta. O servidor precisa validar autorização antes de persistir ou enviar comandos; o agente também deve recusar payloads inválidos e operações que não implementa.

Conexões persistentes caem. O processo pode reiniciar, a rede pode mudar, um NAT pode expirar o mapeamento ou o servidor pode encerrar uma chamada. O agente tenta reconectar, mas a nova conexão não deve simplesmente continuar como se fosse a antiga. Uma sessão recebe identificador e fencing token: um número crescente que permite distinguir a sessão vigente de uma conexão antiga que reapareceu atrasada. O servidor rejeita mensagens que chegam com sessão ou token obsoleto.

Sequências e identificadores de comando ajudam a detectar mensagens duplicadas e lacunas. Porém, transporte gRPC não fornece entrega exatamente uma vez. Se uma resposta se perde depois de a operação ter sido aplicada, o agente pode não saber se deve repetir. O Dokpod assume entrega at-least-once (ao menos uma vez) em alguns fluxos e combina deduplicação, journal e reconciliação para reduzir efeitos duplicados e recuperar divergências. Isso não é uma garantia de exactly-once (exatamente uma vez): o resultado precisa ser desenhado para lidar com repetição e estados incertos.

O tamanho de mensagem também é parte da segurança. Mensagens grandes podem consumir memória e atrasar outras atividades. O servidor do Dokpod define limite gRPC de 1 MiB, e respostas de consulta são fracionadas com limite documentado de 256 KiB. A aplicação deve validar os próprios limites, limitar filas e taxas, e cancelar operações quando deixam de ser necessárias. Um stream que fica aberto não é licença para acumular mensagens sem controle.

Por fim, alta disponibilidade não vem de um RPC duplex. O desenho atual começa com uma instância da API; ownership distribuído dos streams e roteamento durável ficam adiados. A revisão de prontidão registra pendências de compatibilidade N/N-1, carga e observabilidade de release, além da qualificação do agente Windows. Essa distinção impede que um exemplo arquitetural seja confundido com certificação de produção.

Quando escolher gRPC, REST, GraphQL ou SignalR

Eu começaria pela forma do consumidor e do fluxo, não por uma lista de “vantagens”. Se clientes são serviços controlados e a equipe consegue distribuir contratos e código gerado, gRPC pode simplificar uma integração tipada. Se clientes incluem browser, scripts, parceiros ou ferramentas variadas, REST costuma reduzir atrito e facilita observação com ferramentas HTTP conhecidas. GraphQL atende outro problema: permitir que consumidores consultem campos e relações de um grafo de dados por uma API orientada a consultas. SignalR atende comunicação em tempo real com clientes web e abstrações de alto nível como hubs e grupos no ecossistema ASP.NET Core.

Opção	Consumidor típico	Direção do fluxo	Contrato e payload	Custo operacional
gRPC	Serviços e agentes controlados	Unary e streaming nos dois sentidos	.proto, código gerado, Protobuf por padrão	HTTP/2, contratos coordenados e diagnóstico de streams
REST	Navegadores, apps e integrações	Requisição/resposta; streaming requer desenho específico	Recursos HTTP, OpenAPI e JSON frequentes	Baixo atrito e ampla compatibilidade de ferramentas
GraphQL	Clientes com necessidades variáveis de leitura	Consulta/resposta por schema	Schema GraphQL e seleção de campos	Controle de custo de consultas, resolvers e cache
SignalR	Browser e clientes conectados	Eventos e mensagens em tempo real	Hubs, métodos e payloads da aplicação	Conexões persistentes, grupos e escala/backplane quando necessário

No Dokpod, o navegador consome REST/OpenAPI para operações e SignalR para receber notificações segmentadas por ambiente. A relação entre browser e API é diferente da relação entre agente e API. Isso evita fazer a interface web depender do canal interno gRPC. Caso um produto precise de chamadas gRPC originadas pelo browser, gRPC-Web ou um gateway podem ser avaliados; cada opção introduz requisitos de proxy, compatibilidade e suporte a streaming que precisam ser comprovados.

Também não escolheria gRPC só porque o payload binário parece menor ou porque HTTP/2 tem multiplexação. Sem benchmark representativo, não há evidência para afirmar superioridade de desempenho. Se uma operação é pontual, simples e voltada a clientes heterogêneos, REST pode ser a escolha mais clara. Se o problema exige consulta flexível sobre muitos recursos, investigue GraphQL. Se o browser precisa receber eventos, avalie SignalR, SSE ou WebSockets. Se serviços controlados precisam trocar mensagens continuamente com contrato explícito, gRPC merece um protótipo.

Exemplo Prático

Considere o ciclo de vida de um agente do Dokpod. Primeiro, ele abre uma conexão de saída para a API e chama Connect. Em seguida, envia AgentHello com sua identidade operacional e as capacidades que anuncia. O servidor valida o certificado, relaciona-o a um ambiente e negocia a sessão. Se a negociação for aprovada, responde com SessionEstablished, que inclui o protocolo escolhido, o fencing token, o intervalo de heartbeat, o limite de mensagem e as capabilities aceitas.

A partir daí, o agente e a API podem escrever no stream. O agente envia heartbeats e publica inventário paginado ou deltas; o plano de controle envia comandos, consultas ou pedidos de reconciliação. Para uma operação, a mensagem de comando tem metadados de sessão e sequência. O agente valida a sessão ativa, deduplica a operação quando aplicável e devolve estados separados para aceitação e resultado. Se a conexão cair antes de o resultado chegar, a API não deve presumir que o comando falhou nem repeti-lo às cegas: precisa consultar o estado persistido e reconciliar com o agente após reconectar.

Este recorte do contrato ilustra como o payload muda sem criar uma chamada para cada tipo de evento:

// Um envelope transporta exatamente um payload de agente por vez.
message AgentMessage {
  MessageMetadata metadata = 1;
  oneof payload {
    AgentHello hello = 10;
    Heartbeat heartbeat = 11;
    InventorySnapshotPage snapshot_page = 12;
    InventoryDelta inventory_delta = 13;
    CommandAccepted command_accepted = 14;
    CommandResult command_result = 15;
  }
}

📂 Código Fonte: A definição completa, incluindo payloads e numeração dos campos, está no contrato agent.proto.

O valor didático do exemplo está nos limites entre as partes. O protocolo define a forma das mensagens; o cliente mantém a conexão e coordena filas; o serviço da API negocia e processa eventos; os adapters falam com Docker ou Podman. A API não encaminha uma chamada arbitrária para o socket do engine. Essa separação torna mais explícito quem pode solicitar uma operação e qual capacidade do agente é necessária.

O fluxo de terminal é diferente. A API abre um Exec separado depois de validar que a identidade do agente, a sessão e o fencing token correspondem a uma sessão de terminal pendente. Frames transportam dados de entrada, saída, redimensionamento e status. Não é um shell genérico disponibilizado pelo gRPC: é uma funcionalidade de domínio com autorização, expiração e condições de suporte próprias. O repositório documenta que certas ações de terminal são limitadas a agentes Linux e capabilities anunciadas.

Para adaptar o padrão a outro sistema, comece com uma mensagem hello mínima, negociação explícita e um conjunto pequeno de tipos de evento. Defina como uma operação será identificada, como mensagens duplicadas serão tratadas e como o cliente descobre o estado atual depois de uma interrupção. Só adicione streaming bidirecional se os dois lados realmente precisarem produzir mensagens durante a mesma sessão.

Dicas e Boas Práticas

Defina prazos e cancelamento. Chamadas unary devem ter deadline apropriado ao trabalho; operações longas devem observar o token de cancelamento. Streams contínuos precisam de política clara para encerramento e reconexão.
Nunca reutilize números Protobuf. Ao remover um campo, reserve seu número e avalie reservar também o nome. Mudanças no .proto devem passar por revisão de compatibilidade e testes entre versões.
Limite mensagens, filas e frequência. Defina o tamanho máximo, aplique paginação ou fragmentação e use filas limitadas. Sem limites, um cliente lento pode transformar um stream persistente em crescimento ilimitado de memória.
Autentique e autorize separadamente. TLS protege o transporte; mTLS identifica o certificado do agente. Ainda é necessário associar a identidade a um escopo e autorizar cada comando e recurso.
Projete repetição como comportamento normal. Use IDs idempotentes, deduplicação e reconciliação. Não prometa exatamente uma vez porque um RPC retornou sucesso ou porque um canal permaneceu aberto.
Teste versões e interrupções. Exercite queda durante envio, resposta perdida, reinício do servidor, certificado revogado e agente antigo. Compatibilidade teórica do wire format não substitui teste N/N-1.
Meça antes de falar em performance. Compare uma carga representativa, os mesmos dados e a mesma topologia. Registre latência, CPU, memória, bytes, conexões e taxa de erros para gRPC e alternativas.

Conclusão

gRPC combina RPC, contratos definidos em .proto, código gerado, mensagens Protobuf e transporte normalmente baseado em HTTP/2. Seu modelo suporta chamadas unary, streaming do servidor, streaming do cliente e streaming bidirecional. Esse conjunto é especialmente útil quando serviços controlados precisam trocar mensagens tipadas continuamente, mas também exige decisões sobre evolução de contrato, limites de recursos, autenticação, autorização, cancelamento e recuperação.

O caso do Dokpod mostra uma escolha coerente com o problema: agentes em hosts privados iniciam conexões de saída, autenticam-se por mTLS e mantêm um canal para controle e inventário. A API não precisa expor sockets Docker ou SSH e o protocolo transmite comandos de domínio, não chamadas arbitrárias ao engine. A interface web usa REST/OpenAPI e SignalR, pois navegador e agente são consumidores diferentes com necessidades diferentes.

Essa escolha não prova que gRPC seja sempre mais rápido, mais simples ou melhor que REST. Também não significa que a arquitetura já esteja qualificada para toda combinação de engine e sistema operacional: apesar de os testes executados confirmarem o funcionamento com Podman Linux, ainda há gates de carga, compatibilidade N/N-1, qualificação do agente Windows e observabilidade de release. A conclusão correta é mais modesta e útil: use gRPC quando contrato tipado e fluxo contínuo justificarem o custo operacional, valide as condições reais da rede e mantenha alternativas adequadas para outros clientes.

Na parte 2 da série APIs e Comunicação em .NET, vou tratar de GraphQL para iniciantes e dos problemas que uma API orientada a consultas resolve. Na parte 3, vou focar SignalR no .NET, incluindo hubs, clientes, reconexão e operação. Até lá, o artigo publicado sobre tempo real no Angular e .NET continua como leitura complementar sobre WebSockets, SSE, SignalR e Long Polling, mas não faz parte desta nova série.

Resumo Objetivo

gRPC — estrutura de RPC que descreve serviços e mensagens em contratos, gera código cliente/servidor e normalmente transporta chamadas por HTTP/2.
Protocol Buffers — linguagem e formato binário associados ao gRPC; cada campo possui número estável que não deve ser reaproveitado após publicação.
Streaming bidirecional — permite que cliente e servidor enviem várias mensagens durante uma mesma chamada, sem exigir alternância entre cada envio.
Dokpod — usa gRPC com mTLS no canal interno entre API e agentes; o browser usa REST/OpenAPI e SignalR.
Confiabilidade — gRPC não oferece entrega exatamente uma vez nem alta disponibilidade por si só; repetição, deduplicação, fencing e reconciliação pertencem ao desenho da aplicação.
Adoção — gRPC é adequado quando contratos tipados e fluxos contínuos justificam sua operação; REST, GraphQL e SignalR atendem necessidades diferentes de cliente e tráfego.

Referências

Introduction to gRPC — visão geral oficial de RPC, Protobuf, geração de código e streaming.
Overview for gRPC on .NET — suporte de gRPC no ASP.NET Core e clientes .NET.
Create gRPC services and methods — tipos de chamada e implementação de serviços em .NET.
Protocol Buffers: Language Guide (proto3) — mensagens, campos, números, geração e evolução de contratos.
RFC 9113: HTTP/2 — especificação de streams, multiplexação, conexão e controle de fluxo.
Authentication and authorization in gRPC for ASP.NET Core — autenticação por certificado e autorização de chamadas.
Reliable gRPC services with deadlines and cancellation — deadlines, cancelamento e propagação no .NET.
ADR 2026-0001 do Dokpod — motivação arquitetural e trade-offs do canal entre API e agentes. 📬

👉 Artigo completo com todos os exemplos de código: gRPC sem mistério: o que é e quando usar no .NET 10

Transactional Outbox Pattern: Resolvendo o Dual Write

Lincoln Zocateli — Sun, 20 Sep 2026 21:31:24 +0000

Introdução

O dual write problem aparece toda vez que uma aplicação precisa fazer duas escritas em sistemas diferentes — normalmente um banco de dados e um broker de mensagens — e tratar essas duas operações como se fossem uma coisa só. Se eu salvo o pedido no banco e, na sequência, publico um evento no Azure Service Bus como uma chamada separada, eu criei uma janela de inconsistência. Se a aplicação falhar ou a rede cair entre essas duas operações, o sistema termina em um estado que ninguém planejou: o dado existe mas o evento nunca saiu, ou o evento foi publicado mas o commit no banco nunca aconteceu.

Esse problema não é teórico. Eu já vi filas de eventos que anunciavam pedidos que na verdade não existiam no banco, porque a transação local falhou depois da publicação. E vi o oposto: pedidos criados sem nenhum evento de auditoria ou notificação, porque a aplicação caiu no meio do caminho antes de conseguir publicar. Este artigo é a segunda parte da série sobre arquitetura de eventos sem caos com C#, e aqui eu foco especificamente no Transactional Outbox Pattern: o que ele resolve, como implementá-lo em C# com PostgreSQL, e como isso se aplica a um caso real de auditoria transacional publicando no Azure Service Bus.

Pré-requisitos

Para acompanhar os exemplos, é útil ter conhecimento básico de transações ACID em banco relacional, Entity Framework Core ou Npgsql, e alguma familiaridade com filas ou tópicos de mensageria (Azure Service Bus, RabbitMQ ou Kafka seguem o mesmo raciocínio). O exemplo de código completo faz parte do mesmo laboratório de eventos usado no primeiro artigo da série, disponível em BlogSamples/Messaging/EventDriven/.

O problema da dupla escrita (dual write problem)

Toda vez que uma operação de negócio precisa persistir um estado local e notificar esse estado para outro sistema, existem duas escritas fisicamente separadas: um COMMIT no banco de dados e uma chamada de rede para o broker. Bancos de dados relacionais garantem atomicidade dentro de suas próprias transações, mas essa garantia não se estende a um sistema externo. Não existe uma transação distribuída de verdade entre PostgreSQL e Azure Service Bus sem um protocolo como two-phase commit, que na prática quase nenhuma mensageria moderna suporta e que introduz latência e acoplamento que a maioria dos times não quer pagar.

O resultado é que qualquer combinação “salvar e depois publicar” ou “publicar e depois salvar” tem uma janela onde uma das duas operações pode falhar sozinha:

Se eu salvo no banco e a aplicação cai antes de publicar, o evento nunca existiu e nenhum consumidor será notificado.
Se eu publico primeiro e o commit no banco falha depois, o consumidor recebe um evento sobre um dado que nunca foi persistido. > ⚠️ Atenção: um retry ingênuo não resolve o dual write problem sozinho. Se eu simplesmente tentar de novo depois de uma falha, corro o risco de publicar o mesmo evento duas vezes ou de nunca reconciliar o estado quando a falha for definitiva (aplicação reiniciada, processo morto, deploy no meio do fluxo).

Por que transações de banco não resolvem sozinhas

A tentativa mais comum de correção é envolver as duas operações em uma transação e torcer para que tudo funcione. Isso não funciona porque a transação do banco de dados só controla recursos que o próprio banco gerencia. Uma chamada HTTP ou AMQP para o Azure Service Bus não participa do protocolo de commit do PostgreSQL ou do SQL Server. Se eu fizer INSERT no banco, chamar o SDK do Service Bus dentro do mesmo bloco try, e depois dar COMMIT, ainda existem cenários de falha:

O COMMIT local pode ser bem-sucedido, mas a resposta de confirmação do broker nunca chega por timeout de rede — a aplicação não sabe se a mensagem foi ou não entregue.
O broker pode confirmar a entrega, mas o COMMIT subsequente no banco falha por deadlock ou violação de constraint — o evento já foi publicado, mas o dado nunca ficou consistente. Esse é exatamente o motivo pelo qual eu preciso transformar as duas operações em uma única transação local, e tratar a publicação de fato como uma etapa assíncrona e desacoplada.

A solução: Transactional Outbox Pattern

O Transactional Outbox Pattern resolve o dual write problem eliminando a necessidade de uma transação distribuída. Em vez de publicar diretamente no broker, a aplicação grava o dado de negócio e o evento pretendido em uma tabela de “caixa de saída” (outbox) dentro da mesma transação atômica do banco de dados. Como as duas gravações acontecem no mesmo banco e na mesma transação local, elas são atômicas por definição: ou as duas são persistidas, ou nenhuma é.

// Ambos os inserts fazem parte da mesma transação local no PostgreSQL
await using var transaction = await dbContext.Database.BeginTransactionAsync();

var pedido = new Pedido { Id = Guid.NewGuid(), Status = "Criado" };
dbContext.Pedidos.Add(pedido);

// O evento pretendido é gravado como um registro comum na mesma tabela/transação
dbContext.OutboxMessages.Add(new OutboxMessage
{
    Id = Guid.NewGuid(),
    TipoEvento = "PedidoCriado",
    Payload = JsonSerializer.Serialize(pedido),
    CriadoEm = DateTimeOffset.UtcNow,
    Status = OutboxStatus.Pendente
});

await dbContext.SaveChangesAsync();
await transaction.CommitAsync();

📂 Código Fonte: O exemplo completo de Outbox, Inbox e Saga está disponível no repositório de exemplos do blog: BlogSamples/Messaging/EventDriven/

Se o CommitAsync for bem-sucedido, eu tenho a garantia de que o pedido e a intenção de publicar o evento existem juntos no banco. Se ele falhar, nenhum dos dois foi persistido. Não existe mais o cenário em que um foi salvo e o outro não.

Consumo dos eventos: o publisher assíncrono

Salvar o evento na tabela outbox resolve a atomicidade, mas ainda falta o passo que efetivamente entrega a mensagem ao broker. Essa responsabilidade fica com um processo separado — geralmente um worker ou BackgroundService — que lê os registros pendentes da outbox e os publica no Azure Service Bus de forma assíncrona, marcando cada mensagem como publicada somente depois da confirmação do broker.

// Worker que publica mensagens pendentes da outbox, uma de cada vez
public sealed class OutboxPublisherWorker : BackgroundService
{
    private readonly IServiceScopeFactory _scopeFactory;
    private readonly ServiceBusSender _sender;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            using var scope = _scopeFactory.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();

            // SKIP LOCKED evita que múltiplas instâncias do worker peguem a mesma linha
            var pendentes = await db.OutboxMessages
                .Where(m => m.Status == OutboxStatus.Pendente)
                .OrderBy(m => m.CriadoEm)
                .Take(20)
                .ToListAsync(stoppingToken);

            foreach (var mensagem in pendentes)
            {
                var envelope = new ServiceBusMessage(mensagem.Payload)
                {
                    MessageId = mensagem.Id.ToString(),
                    SessionId = mensagem.CorrelationId
                };

                await _sender.SendMessageAsync(envelope, stoppingToken);

                // Só marca como publicada depois da confirmação do broker
                mensagem.Status = OutboxStatus.Publicada;
            }

            await db.SaveChangesAsync(stoppingToken);
            await Task.Delay(TimeSpan.FromSeconds(2), stoppingToken);
        }
    }
}

Esse desenho cria uma janela de latência entre o COMMIT local e a publicação real — normalmente de milissegundos a poucos segundos —, mas nunca perde a garantia de atomicidade entre dado e evento. Se o worker cair depois do SendMessageAsync e antes do SaveChangesAsync, a mensagem pode ser publicada novamente na próxima execução. Isso é esperado e é resolvido do lado do consumidor, não do publisher.

Caso real: auditoria transacional em um sistema de gestão de estoque

Um exemplo concreto desse padrão em produção é a outbox de auditoria de um sistema de gestão de estoque, que publica eventos no Azure Service Bus com semântica at-least-once. O publisher reivindica mensagens disponíveis por lease SQL — um mecanismo equivalente ao SKIP LOCKED do exemplo anterior, mas implementado como um lock otimista com timeout de lease —, envia o envelope versionado para o tópico configurado e só marca a mensagem como Published depois da confirmação do broker.

Esse fluxo reforça um ponto central do Transactional Outbox Pattern: a responsabilidade do publisher termina na confirmação de entrega. Ele nunca assume que uma mensagem enviada uma vez está garantida a chegar exatamente uma vez do outro lado. Por isso, as obrigações relevantes migram para o consumidor.

Obrigações do consumidor: idempotência e ordenação

Como a entrega é at-least-once, todo consumidor de uma outbox transacional precisa tratar duplicidade como parte normal do fluxo, não como exceção:

Idempotência por MessageId. O consumidor deve manter uma Inbox ou uma constraint equivalente por (consumer, messageId) antes de aplicar qualquer efeito colateral. Se a mesma mensagem chegar duas vezes, o segundo processamento precisa ser reconhecido e descartado sem repetir a ação de negócio.
PeekLock sem auto-complete. Processar em modo PeekLock com AutoCompleteMessages desabilitado é obrigatório. A mensagem só deve ser completada depois que a persistência local ou o efeito externo estiver confirmado — nunca antes.
Duplicatas são esperadas, não um bug. Se a API publicar no Service Bus e falhar antes de marcar a mensagem como Published, a mesma mensagem pode ser reenviada com o mesmo MessageId. O consumidor precisa estar preparado para isso desde o design inicial.
SessionId para ordenação por agregado. Quando a subscription exigir processamento sequencial, usar SessionId como chave de ordenação por agregado — no formato Domain:EntityType:EntityId — garante que eventos do mesmo pedido, por exemplo, sejam processados na ordem correta sem bloquear outros agregados.
DLQ apenas após esgotar tentativas. Enviar para Dead Letter Queue somente depois de esgotar as tentativas do consumidor, registrando o erro de forma sanitizada, sem payload sensível em log.
Retries desacoplados entre outbox e consumidor. A outbox controla a publicação; o consumidor controla o próprio processamento. Misturar essas duas políticas de retry cria acoplamento desnecessário e dificulta o diagnóstico de qual lado está falhando.

// Consumidor idempotente com Inbox e PeekLock
public async Task ProcessarMensagemAsync(ProcessMessageEventArgs args)
{
    var messageId = args.Message.MessageId;

    // Verifica se essa combinação (consumer, messageId) já foi processada
    var jaProcessada = await _db.InboxMessages
        .AnyAsync(m => m.Consumer == ConsumerName && m.MessageId == messageId);

    if (jaProcessada)
    {
        // Duplicata esperada: reconhece e sai sem repetir efeito colateral
        await args.CompleteMessageAsync(args.Message);
        return;
    }

    // Aplica o efeito de negócio e registra o inbox na mesma transação
    await using var transaction = await _db.Database.BeginTransactionAsync();
    await AplicarEfeitoDeNegocioAsync(args.Message);
    _db.InboxMessages.Add(new InboxMessage { Consumer = ConsumerName, MessageId = messageId });
    await _db.SaveChangesAsync();
    await transaction.CommitAsync();

    await args.CompleteMessageAsync(args.Message);
}

ℹ️ Informação: o par Outbox (produtor) + Inbox (consumidor) é o que efetivamente entrega consistência ponta a ponta. A outbox garante que o evento não se perde; a inbox garante que o efeito colateral não se repete.

Como saber se você precisa do Outbox Pattern

O Transactional Outbox Pattern resolve um problema específico: consistência entre uma escrita local e uma notificação externa. Ele não é necessário em todo lugar.

Situação	Recomendação
Operação única, síncrona, sem sistema externo dependente	manter transação simples do banco
Persistir dado e notificar outro serviço/domínio de forma confiável	usar Transactional Outbox
Apenas performance de escrita, sem preocupação de consistência distribuída	não é o problema que o Outbox resolve
Auditoria, replicação de eventos ou integração assíncrona entre sistemas	Outbox é a base recomendada

Dicas e Boas Práticas

Grave o dado de negócio e o registro da outbox sempre na mesma transação local — nunca em chamadas separadas, mesmo que pareçam próximas no tempo.
Marque a mensagem como publicada somente depois da confirmação do broker, nunca antes ou de forma otimista.
Use MessageId estável (geralmente o ID do próprio registro da outbox) para permitir deduplicação no consumidor.
Trate duplicidade de mensagens como comportamento esperado do sistema, não como bug a ser eliminado.
Separe a política de retry do publisher da política de retry do consumidor; cada um tem falhas e responsabilidades diferentes.
Use SKIP LOCKED ou lease otimista no publisher para permitir múltiplas instâncias do worker sem duplicar trabalho.
Nunca coloque payload sensível em logs de erro ou de DLQ; sanitize antes de registrar.

Resumo Objetivo

Dual write problem — ocorre quando uma aplicação grava em banco e publica em broker como duas operações separadas, sem garantia de atomicidade entre elas.
Transactional Outbox Pattern — grava o dado de negócio e o evento pretendido na mesma transação local, eliminando a inconsistência entre as duas escritas.
Semântica at-least-once — o publisher garante que a mensagem não se perde, mas pode ser entregue mais de uma vez ao consumidor.
MessageId — chave usada pelo consumidor para deduplicação via padrão Inbox, com constraint por (consumer, messageId).
PeekLock sem auto-complete — modo de processamento que só confirma a mensagem depois do efeito colateral estar persistido.
SessionId — chave de ordenação por agregado (Domain:EntityType:EntityId) usada quando a subscription exige processamento sequencial.
Azure Service Bus — broker usado no caso real do sistema de gestão de estoque para publicar eventos de auditoria a partir da outbox transacional.

Referências

Transactional Outbox Pattern — microservices.io — descrição canônica do padrão e do problema de dual write.
Azure Service Bus messaging documentation — documentação oficial de tópicos, subscriptions e sessões.
Azure Service Bus PeekLock e AutoComplete — comportamento de locks e confirmação de mensagens.
PostgreSQL SKIP LOCKED — locking otimista para publishers concorrentes.
Entity Framework Core Transactions — documentação oficial de transações no EF Core. 📬

👉 Artigo completo com todos os exemplos de código: Transactional Outbox Pattern: Resolvendo o Dual Write

.NET Native AOT: Parte 2 — JIT, R2R e AOT em Benchmarks

Lincoln Zocateli — Fri, 04 Sep 2026 09:01:29 +0000

Introdução

Não existe um vencedor universal na comparação entre .NET Native AOT, JIT e ReadyToRun. Cada modelo de publicação otimiza uma parte diferente do sistema: Native AOT elimina o JIT em execução e reduz muito o tempo até a primeira resposta; ReadyToRun antecipa parte da compilação sem abandonar o runtime dinâmico; uma aplicação JIT framework-dependent pode compartilhar o runtime instalado com outros processos; e uma publicação JIT self-contained prioriza isolamento operacional. Escolher apenas pelo rótulo “CLI”, “servidor” ou “serverless” ignora as restrições que realmente controlam o resultado.

A decisão precisa começar pelo objetivo mensurável da aplicação. Tempo de startup importa para processos efêmeros, mas throughput aquecido, p95 e p99, CPU, memória residente, tamanho de distribuição, frequência de atualização, compatibilidade com código dinâmico e tempo de publicação também podem decidir o projeto. Neste artigo, eu comparo os quatro modelos com o mesmo código em .NET 10 e linux-x64, preservando os resultados brutos. A conclusão não é uma regra pronta: é uma matriz que relaciona métricas e restrições ao contexto de operação.

Este texto complementa o guia .NET Native AOT: Parte 1 — Ecossistema de Compilação. No guia conceitual, eu expliquei Roslyn, IL, ILC, trimming e compatibilidade. Aqui, o foco é corrigir simplificações comuns com um experimento reproduzível: separar aplicação framework-dependent de distribuição autocontida, separar startup de throughput e não confundir alocação gerenciada com RSS.

ℹ️ Informação: todos os números deste artigo vieram dos CSVs e JSONs do laboratório. Valores absolutos descrevem este workload, este hardware e este ambiente; as relações entre perfis são hipóteses para você testar, não garantias para outra aplicação.

Pré-requisitos

.NET SDK 10.0.400 ou uma imagem Docker equivalente.
Docker Desktop com containers Linux para reproduzir o ambiente Ubuntu 24.04 e o RID linux-x64.
Conhecimento básico de publicação framework-dependent, self-contained, ReadyToRun e Native AOT.
uv para executar o consolidador determinístico dos CSVs e JSONs.
Microsoft Crank e Bombardier para repetir a carga HTTP.

O que os comentários revelaram sobre a decisão AOT

Uma discussão técnica sobre o artigo conceitual expôs a principal falha das recomendações baseadas apenas no tipo da aplicação. Dizer que Native AOT serve para CLI e serverless, enquanto JIT serve para servidores longos, parece útil porque cabe em uma frase. O problema é que essa frase omite o objetivo. Uma CLI usada uma vez por mês pode não justificar o esforço de compatibilidade; um backend replicado centenas de vezes pode valorizar densidade e startup; um worker duradouro pode depender de plugins; um serviço estável de CPU pode ter um resultado diferente de um serviço com distribuição de tráfego variável.

Startup também não é sinônimo de cold start de provedor. O laboratório mede o intervalo entre iniciar um processo e receber uma resposta válida de /ready, com cache do sistema de arquivos aquecido. Um cold start de Azure Functions, AWS Lambda ou outra plataforma inclui decisões do provedor, criação de sandbox, pull de imagem, rede, configuração e inicialização da aplicação. Eu não medi esse caminho e, portanto, não atribuo ao Native AOT um ganho universal em serverless gerenciado.

Outro ponto importante é a previsibilidade. Remover o JIT evita compilação de métodos durante a execução, mas não remove pausas de GC, escalonamento do sistema operacional, contenção, I/O ou page faults. Da mesma forma, source generators reduzem descoberta dinâmica e deslocam erros para o build, mas não tornam automaticamente qualquer arquitetura mais rápida. São propriedades relevantes para a decisão, não selos de superioridade.

Minha regra revisada é mais exigente: defina uma meta, escolha as métricas capazes de refutá-la e compare distribuições equivalentes. Se o objetivo é reduzir primeira resposta, meça processos novos. Se é aumentar densidade, meça RSS sob a carga representativa. Se é sustentar throughput, aqueça a aplicação e registre latência de cauda e CPU junto com requisições por segundo.

Metodologia: como tornar a comparação justa

O experimento usa Ubuntu 24.04 em Docker Desktop, processador Intel Core i5-1245U x64, aproximadamente 8 GB de memória disponíveis, SDK 10.0.400 e runtime 10.0.11. Todos os perfis executam em Release, ambiente Production, sem providers de logging e com o mesmo payload. O código não acessa banco, disco ou serviço externo durante a medição.

O workload recebe Seed=42, ItemCount=2048 e Iterations=8. Cada execução aluga um array com ArrayPool<int>, gera valores determinísticos, ordena os dados, calcula média e percentil 95 e produz um SHA-256. A Minimal API serializa a resposta com System.Text.Json source generation. Essa combinação exerce CPU, alocação, genéricos e serialização sem deixar I/O externo dominar.

Os nomes combinam o modo de compilação com o modelo de distribuição:

JIT (Just-In-Time) compila IL em código nativo durante a execução.
FDD (Framework-Dependent Deployment) publica somente a aplicação e exige um runtime .NET compatível instalado no host.
SCD (Self-Contained Deployment) inclui o runtime .NET no diretório publicado.
R2R (ReadyToRun) antecipa a compilação de assemblies elegíveis, mas preserva runtime e JIT.
Native AOT (Native Ahead-Of-Time) gera antes da execução um binário nativo autocontido, sem JIT em produção. Os quatro perfis são:

Perfil	Runtime no diretório	Código antecipado	JIT em execução
JIT FDD (dependente do framework)	Não; usa instalação compatível	Bibliotecas do runtime podem conter R2R	Sim
JIT SCD (autocontido)	Sim	Bibliotecas do runtime podem conter R2R	Sim
R2R SCD (ReadyToRun autocontido)	Sim	Aplicação e dependências elegíveis	Sim
Native AOT (nativo autocontido)	Runtime reduzido incluído	Aplicação fechada em código nativo	Não

O harness restaura dependências antes do cronômetro, executa três pares de publish limpo e incremental e inicia cada perfil 30 vezes em ordem randomizada. Antes de medir startup, ele copia os publishes para o filesystem Linux local do container; executar binários grandes diretamente no bind mount do Windows adicionou quase dez segundos artificiais em testes preliminares.

Para estado aquecido, o BenchmarkDotNet usa jobs out-of-process reais para .NET 10 JIT e Native AOT. A carga HTTP usa Microsoft Crank com Bombardier, 64 conexões, 15 segundos de warm-up e 30 segundos de medição. Aplicação e gerador ficam em containers separados, mas na mesma máquina física. Isso contamina a capacidade absoluta, por isso eu uso os resultados apenas como comparação relativa deste ambiente.

Exemplo Prático: laboratório reproduzível em .NET 10

A API foi construída com o host reduzido do ASP.NET Core. O marcador escrito após Start() permite ao Crank sincronizar a carga sem habilitar logs diferentes entre perfis:

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Logging.ClearProviders();
builder.Services.Configure<JsonOptions>(options =>
    options.SerializerOptions.TypeInfoResolverChain.Insert(
        0,
        DecisionLabJsonContext.Default));

WebApplication app = builder.Build();

app.MapGet("/ready", () => TypedResults.Ok(new ReadyResponse("ready")));
app.MapPost("/work", (WorkloadRequest request) =>
    TypedResults.Ok(WorkloadProcessor.Process(request)));

app.Start();
Console.WriteLine("Application started.");
app.WaitForShutdown();

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/NativeAot/DecisionLab/

O comando principal publica, mede tamanho e executa os 120 startups dentro da imagem fixada:

docker run --rm \
  --volume "$PWD:/workspace" \
  --volume decision-lab-nuget:/root/.nuget/packages \
  decision-lab:10.0.400 \
  run --project src/BlogSamples/NativeAot/DecisionLab/DecisionLab.Harness \
  --configuration Release -- --repository-root /workspace

O manifesto registra commit, estado do worktree, fingerprint dos fontes e ambiente. O fingerprint é necessário porque um hash de HEAD não identifica alterações ainda não commitadas. O consolidador calcula mediana, mínimo, máximo, desvio absoluto mediano (MAD) e razão contra JIT FDD; diferenças de até 3% são marcadas como dentro do limiar operacional de ruído, sem fingir significância estatística.

Publish, tamanho e startup de processo

Native AOT deslocou custo para o build. O publish limpo mediano levou 98,145 segundos, contra 11,589 segundos do JIT FDD, 28,450 segundos do JIT SCD e 25,812 segundos do R2R SCD. No publish incremental, a distância diminuiu: Native AOT ficou em 13,398 segundos; JIT FDD, 11,679; JIT SCD, 14,552; e R2R SCD, 13,787.

Perfil	Publish limpo mediano	Publish incremental mediano
JIT FDD	11,589 s	11,679 s
JIT SCD	28,450 s	14,552 s
R2R SCD	25,812 s	13,787 s
Native AOT	98,145 s	13,398 s

O tamanho exige uma comparação cuidadosa. Os 165.687 bytes do JIT FDD representam somente os arquivos da aplicação; a instalação compartilhada do .NET fica fora do diretório. JIT SCD e R2R SCD incluem runtime e bibliotecas e ficaram perto de 109,7 MB. Native AOT incluiu o runtime reduzido necessário e chegou a 28,3 MB. Compactados, os diretórios ocuparam 81.471 bytes, 48,2 MB, 48,2 MB e 10,9 MB, respectivamente.

Perfil	Unidade comparada	Descompactado	ZIP
JIT FDD	Aplicação, sem runtime instalado	165.687 B	81.471 B
JIT SCD	Distribuição completa	109.703.386 B	48.156.909 B
R2R SCD	Distribuição completa	109.745.882 B	48.177.185 B
Native AOT	Distribuição completa	28.306.209 B	10.865.327 B

No startup de processo, Native AOT apresentou mediana de 63,794 ms e MAD de 8,948 ms. JIT FDD registrou 587,644 ms; JIT SCD, 633,357 ms; e R2R SCD, 585,283 ms. R2R e JIT FDD ficaram dentro do limiar operacional de 3%, portanto este experimento não sustenta declarar R2R vencedor no startup.

Perfil	Mediana de startup	MAD	Amostras
JIT FDD	587,644 ms	100,856 ms	30
JIT SCD	633,357 ms	93,885 ms	30
R2R SCD	585,283 ms	79,038 ms	30
Native AOT	63,794 ms	8,948 ms	30

⚠️ Atenção: esses números medem processo novo com cache de filesystem aquecido. Eles não medem boot da máquina, pull de container nem cold start de um provedor serverless.

Runtime compartilhado e unidades autocontidas

Framework-dependent é uma escolha eficiente quando várias aplicações usam uma instalação compatível do .NET no mesmo host. O custo do runtime não desaparece; ele é instalado, atualizado e potencialmente compartilhado fora do artefato da aplicação. Em containers isolados ou hosts sem runtime, essa premissa muda.

Cada publicação Native AOT é uma unidade autocontida e leva as partes do runtime necessárias. Não existe, no modelo de publicação documentado, um runtime Native AOT comum consumido por vários executáveis gerenciados independentes. O sistema operacional pode compartilhar páginas somente leitura entre processos do mesmo binário, mas isso é um comportamento de memória virtual e não transforma executáveis diferentes em clientes de um runtime comum.

ℹ️ Informação: UnmanagedCallersOnly pode exportar entry points C de um módulo Native AOT para interoperabilidade nativa. Isso não cria uma DLL gerenciada AOT compartilhada entre aplicações .NET.

Throughput, latência e memória sob carga

A campanha HTTP usa o mesmo endpoint e payload nos quatro perfis. Eu registro mediana e dispersão de requisições por segundo, p50, p95, p99, CPU máxima do processo e working set máximo em cinco rodadas randomizadas por perfil. Como aplicação e Bombardier compartilham a mesma máquina física, os números não representam a capacidade máxima de produção.

As 20 rodadas terminaram com zero respostas inválidas. JIT FDD apresentou a maior mediana, 932 RPS, seguido por Native AOT com 810 RPS, JIT SCD com 803 RPS e R2R SCD com 734 RPS. A dispersão foi alta: o MAD variou de 82 RPS no JIT SCD a 240 RPS no R2R SCD, e os intervalos observados se sobrepõem. Neste host compartilhado, a ordem das medianas não sustenta uma regra geral de throughput.

Perfil	RPS mediana	MAD RPS	p50	p95	p99
JIT FDD	932	130	63,936 ms	136,854 ms	194,880 ms
JIT SCD	803	82	78,570 ms	142,288 ms	210,696 ms
R2R SCD	734	240	83,483 ms	191,594 ms	312,714 ms
Native AOT	810	186	79,518 ms	145,527 ms	210,021 ms

O sinal mais nítido apareceu em recursos. Native AOT registrou mediana de 41 MB para o working set máximo, contra 103 MB no JIT FDD, 101 MB no JIT SCD e 96 MB no R2R SCD. A CPU máxima mediana foi 62% no Native AOT, 83% no JIT FDD, 79% no JIT SCD e 86% no R2R SCD. São máximos amostrados pelo Crank, não consumo médio nem memória privada.

Perfil	CPU máxima mediana	Working set máximo mediano	MAD do working set
JIT FDD	83%	103 MB	2 MB
JIT SCD	79%	101 MB	2 MB
R2R SCD	86%	96 MB	2 MB
Native AOT	62%	41 MB	1 MB

ℹ️ Informação: nesta campanha, Native AOT usou cerca de 40% do working set máximo mediano do JIT FDD. O resultado é específico deste workload AOT-friendly e não prevê o RSS de outra aplicação.

JIT, Dynamic PGO e Native AOT no código quente

ReadyToRun não elimina o JIT. Com tiered compilation habilitada, métodos usados com frequência podem ter o código R2R substituído por código produzido pelo optimizing JIT. Dynamic PGO trabalha junto com esse mecanismo: instrumenta a execução, observa tipos e caminhos quentes e usa esses dados para recompilar métodos relevantes.

Native AOT não dispõe de JIT em produção, então não pode adaptar o código durante a execução da mesma forma. Isso é uma diferença de capacidade, não uma prova de que JIT sempre vence. Código AOT evita warm-up de compilação e pode empatar ou superar o JIT em workloads específicos; o JIT pode se beneficiar quando o processo dura o suficiente e a distribuição observada orienta otimizações úteis.

No SDK 10.0.400 e nas fontes públicas consultadas, eu não confirmei um fluxo estável e documentado de PGO de build para Native AOT que pudesse ser recomendado como procedimento de produção neste laboratório. Por isso, a comparação usa os defaults suportados e não inclui opções experimentais. Mesmo quando um perfil offline estiver disponível, ele precisa representar produção: mudanças de tipos, rotas ou distribuição de tráfego podem envelhecer a evidência coletada.

Os dois jobs concluídos pelo mesmo BenchmarkDotNet produziram uma mediana de 1,034 ms para JIT e 1,638 ms para Native AOT. Neste workload aquecido, Native AOT levou 1,585 vez o tempo do baseline JIT. As alocações gerenciadas ficaram próximas: 8.984 bytes por operação no JIT e 9.370 bytes no Native AOT, diferença de 4,3%.

Runtime	Mediana	MAD	Amostras	Alocação por operação
.NET 10 JIT	1,034 ms	0,133 ms	92	8.984 B
Native AOT 10	1,638 ms	0,161 ms	99	9.370 B

O BenchmarkDotNet marcou a distribuição Native AOT como bimodal (mValue = 3,25) e removeu um outlier; no JIT, removeu oito outliers. Portanto, o resultado refuta a hipótese de empate neste ensaio, mas não demonstra que JIT sempre vence código quente. Ele mostra apenas que, para esta carga, neste ambiente e com os defaults suportados, a adaptação disponível no runtime JIT coincidiu com menor duração mediana.

Source generators e reflection mudam o custo

O workload usa System.Text.Json source generation. O contexto JSON registra os contratos usados pela API, permitindo que o compilador veja quais metadados precisam ser preservados. Isso reduz descoberta baseada em reflection e torna o cenário deliberadamente compatível com Native AOT.

Reflection não é um bloco único. Acesso analisável a metadados ou membros preservados pode funcionar com anotações e testes. Os problemas mais fortes aparecem quando o conjunto de código só é conhecido em execução: Assembly.LoadFile, Reflection.Emit, plugins abertos e serializers que descobrem tipos arbitrários. O trimmer precisa enxergar o grafo no build; caso contrário, ele não consegue provar o que pode remover.

Evitar código dinâmico pode ser uma decisão arquitetural saudável, principalmente quando source generators e contratos explícitos antecipam erros. Também pode ser inviável para um produto cujo valor depende de extensibilidade aberta. Compatibilidade deve ocupar uma linha própria na matriz de decisão; não deve ser tratada como detalhe resolvido por um atributo genérico que preserva tudo.

Onde as conclusões não se aplicam diretamente

Hard real-time exige previsibilidade de ponta a ponta. Ausência de JIT não controla pausas de GC, escalonamento do sistema operacional, interrupções, I/O, locks ou page faults. Soft real-time, por outro lado, pode funcionar com um processo JIT aquecido e medido. Este laboratório não mede deadlines nem usa um sistema operacional de tempo real.

Blazor WebAssembly AOT é outro pipeline. Ele compila código .NET para WebAssembly executado pelo navegador e normalmente troca um download maior por melhor desempenho em trechos intensivos de CPU. Não é o mesmo modelo de executável Native AOT para Linux, Windows ou macOS. Blazor Server se aproxima mais da decisão de um backend ASP.NET Core, mas recursos e dependências precisam ser avaliados separadamente.

Também não há resultados de preview do .NET 11, bibliotecas Native AOT exportadas, provedores serverless ou aplicações com banco de dados. Incluir esses cenários sem medi-los aumentaria o alcance aparente e reduziria a utilidade da conclusão.

Matriz de decisão orientada ao objetivo

Objetivo ou restrição	Pergunta de medição	Opções que merecem baseline
Primeira resposta	Quanto leva processo novo até responder?	Native AOT, R2R e JIT
Throughput aquecido	Qual perfil sustenta RPS com p95/p99 aceitáveis?	JIT com tiering/PGO e Native AOT
Memória e densidade	Qual é o RSS sob carga por réplica?	Native AOT, JIT FDD e JIT SCD
Distribuição	Quantos bytes são transferidos e atualizados?	FDD se runtime existe; AOT/SCD se não existe
Runtime compartilhado	Várias aplicações usam o mesmo host administrado?	JIT FDD
Plugins e código dinâmico	O grafo de código é conhecido no build?	JIT; validar trimming antes de AOT
Tempo de build	A frequência de entrega tolera publish AOT?	JIT/R2R como baseline
Operação	Ferramentas de diagnóstico cobrem o modo escolhido?	Validar por ambiente e incidente esperado

Uma CLI distribuída para máquinas sem .NET pode valorizar Native AOT por startup e empacotamento. Muitas aplicações em um host administrado podem aproveitar FDD. Um backend duradouro e variável pode se beneficiar da adaptação do JIT. Edge e IoT podem priorizar bytes, memória e restrições de execução. Esses exemplos orientam quais testes executar; nenhum substitui a medição.

Limitações do experimento

O hardware é um notebook com Docker Desktop 4.81.0, e aplicação e gerador de carga disputam a mesma CPU. O RID é apenas linux-x64, o sistema é Ubuntu 24.04 e o plano de energia Equilibrado foi observado durante a campanha. Isso não controla frequência, temperatura nem tarefas de fundo do host, que podem aumentar a dispersão. A campanha usa cache de filesystem aquecido e não reinicia o sistema operacional entre amostras.

O workload é sintético, determinístico e deliberadamente AOT-friendly. Ele não representa acesso a banco, rede externa, plugins, descoberta aberta de tipos nem uma base de código grande. A memória reportada pelo Crank é working set máximo, enquanto o BenchmarkDotNet registra alocação gerenciada por operação; essas métricas respondem perguntas diferentes.

Três publishes e 30 startups permitem observar dispersão operacional, mas não transformam o laboratório em estudo universal. As cinco rodadas HTTP ajudam a detectar instabilidade, e o limiar de 3% evita anunciar diferenças pequenas como vencedores. Ainda assim, o limiar não é um teste formal de significância.

Dicas e Boas Práticas

Comece com um baseline simples. Compare primeiro a publicação padrão que sua equipe já opera. Native AOT e ReadyToRun precisam melhorar uma métrica relevante o suficiente para pagar o custo de compatibilidade, build e manutenção.
Execute performance em Release e Production. Debug e ambiente Development adicionam trabalho e configuração que distorcem resultados. Mantenha logging, GC, payload e funcionalidade iguais entre os perfis sempre que o modo de publicação permitir.
Meça distribuições, não uma única execução. Use processos novos para startup, warm-up explícito para steady state e ordem randomizada. Registre mediana e dispersão para não confundir ruído térmico, cache ou tarefa de fundo com efeito do compilador.
Separe tamanho de aplicação e tamanho de distribuição. FDD app-only pressupõe runtime instalado; SCD e Native AOT incluem runtime. Declare a unidade comparada e, quando transferência importar, meça também o artefato compactado.
Preserve dados brutos e ambiente. CSV, JSON, manifesto, commit e fingerprint dos fontes tornam cada tabela auditável. Copiar números manualmente para Markdown sem rastreabilidade facilita erros de unidade e arredondamento.
Trate respostas inválidas como falha do teste. RPS alto com HTTP 400, 500 ou timeout não é desempenho da aplicação. Automatize um gate que exija zero respostas ruins antes de consolidar a rodada.
Acompanhe regressões no CI com tolerância ao ruído. Um benchmark isolado não impede que dependências ou mudanças de workload alterem o resultado. Use uma máquina estável e só alerte quando a diferença superar a variabilidade histórica do cenário.

Resumo Objetivo

Decisão entre JIT, ReadyToRun e Native AOT — não existe vencedor universal; primeira resposta, throughput, latência de cauda, CPU, memória, distribuição e compatibilidade respondem perguntas diferentes.
Startup Native AOT neste ambiente — a mediana foi 63,794 ms em 30 processos, contra 587,644 ms no JIT FDD; a medição usa cache de filesystem aquecido e não representa cold start de provedor.
Publish Native AOT neste ambiente — o publish limpo mediano levou 98,145 s, enquanto o incremental levou 13,398 s; o custo mais alto concentrou-se na compilação limpa.
Tamanho JIT FDD — os 165.687 bytes medidos cobrem somente a aplicação e pressupõem um runtime compatível instalado, portanto não são diretamente comparáveis às distribuições autocontidas completas.
Tamanho Native AOT — a distribuição completa ficou em 28.306.209 bytes descompactados e 10.865.327 bytes em ZIP, incluindo as partes necessárias do runtime sem JIT.
ReadyToRun — mantém IL, runtime, JIT e tiered compilation; neste startup, R2R SCD e JIT FDD ficaram dentro do limiar operacional de 3%.
Carga HTTP neste ambiente — JIT FDD teve mediana de 932 RPS, Native AOT 810, JIT SCD 803 e R2R SCD 734; Native AOT registrou 41 MB de working set máximo mediano contra 103 MB no JIT FDD, mas a alta dispersão impede generalizar a capacidade.
Código quente neste workload — a mediana foi 1,034 ms no JIT e 1,638 ms no Native AOT; o relatório marcou a distribuição AOT como bimodal, portanto a conclusão permanece restrita ao ensaio.

Referências

Native AOT deployment overview — modelo de publicação, requisitos, runtime reduzido e limitações oficiais.
Native code interop with Native AOT — P/Invoke direto e exports C com UnmanagedCallersOnly.
ReadyToRun deployment overview — formato R2R, impacto no tamanho e interação com tiered compilation.
Compilation config settings — tiered compilation, ReadyToRun e dynamic PGO.
Known trimming incompatibilities — serializers por reflection, geração dinâmica e carregamento de assemblies.
Blazor WebAssembly AOT — pipeline WebAssembly e trade-off entre download e execução.
BenchmarkDotNet NativeAOT — jobs e toolchains out-of-process para runtimes distintos.
Microsoft Crank — controller, agents e jobs de carga usados pelo time .NET.
ASP.NET Core load and stress testing — orientação para executar carga em Release e Production. 📬

👉 Artigo completo com todos os exemplos de código: .NET Native AOT: Parte 2 — JIT, R2R e AOT em Benchmarks

.NET Native AOT: Ecossistema de Compilação em C#

Lincoln Zocateli — Mon, 24 Aug 2026 09:01:41 +0000

Introdução

Quando penso em binários nativos com .NET, muitos devs imaginam imediatamente executáveis compactos, ultra-rápidos no startup, prontos para serverless. A realidade é mais nuançada. Native AOT (Ahead-Of-Time compilation) é poderoso — mas nem sempre é a resposta. Você pode compilar C# para nativo, sim. Mas qual é o preço real? Como funciona internamente? E em quais cenários faz realmente sentido investir tempo de compilação, limitações de reflection e binários maiores?

Eu criei este artigo porque vi muitos devs tentando usar Native AOT sem entender o tradeoff: ganhar 200–300ms de startup time pode custar +30MB de binário e remover reflexão do seu código. Neste guia, vou levar você através da stack de compilação completa — desde C# interpretado por Roslyn até o native code saindo do ILCompiler — e mostrar exatamente quando (e quando não) usar Native AOT em produção.

Pré-requisitos

Conhecimento de C# e .NET: experiência com .NET 8+ e familiaridade com conceitos como assemblies, IL (Intermediate Language) e garbage collection.
.NET SDK 9.0+: o artigo foca em .NET 9 e .NET 10 (LTS).
Noções de compilação: entender diferenças entre JIT (Just-In-Time) e compilação antecipada é útil, mas vou explicar os conceitos conforme necessário.
Familiaridade com performance: interpretação de métricas básicas de startup, memory footprint e throughput.

O que é Native AOT

Native AOT significa compilar seu código C# em binário nativo antes de executar, não durante a execução. Contraste com o modelo tradicional:

JIT (Just-In-Time):

Você escreve C#, compila para IL (Intermediate Language)
No startup do app, o JIT toma a IL
JIT transforma IL em machine code dinamicamente conforme o código roda
O .NET runtime (incluindo JIT, GC, todas as bibliotecas) rodam na memória
Native AOT:
Você escreve C#, compila para IL
Na máquina de build, o NativeAOT toolchain pega a IL, faz análise estática, remove código desnecessário (trimming)
Transforma tudo em machine code nativo (x86-64, ARM, etc.) antes de você executar
Resultado é um executável standalone — sem JIT, sem interpreter, sem .NET runtime embutido

💡 Dica: Quando digo “sem .NET runtime”, não é 100% preciso. Você ainda tem partes da biblioteca padrão linkadas (GC, allocator, estruturas de dados). Mas é dramaticamente reduzido comparado ao JIT.

Variações de Compilação

Existe um espectro entre JIT puro e AOT puro:

JIT Padrão (Tier 0): Compila tudo no startup; depois otimiza com Tier 1 conforme uso
ReadyToRun (R2R): Compilação antecipada parcial; ainda precisa de runtime e JIT está disponível para código não pré-compilado
Native AOT Completo: Tudo pré-compilado; sem JIT (restrito por trimming e análise estática) Native AOT é o mais agressivo em tradeoffs: ganhos extremos em startup, mas restrições rígidas em reflection.

Stack de Compilação: Roslyn até Binário Nativo

Aqui está o coração técnico. Vou descrever exatamente o que acontece quando você roda dotnet publish -c Release --self-contained -r win-x64 /p:PublishAot=true.

1. Análise Estática com Roslyn

Roslyn é o compilador C# da Microsoft. Ele:

Lê .cs files
Monta uma árvore sintática (AST)
Resolve tipos, namespaces, símbolos
Gera IL (Intermediate Language) — um pseudocódigo agnóstico de plataforma Para Native AOT, Roslyn não faz nada especial nesta etapa — a emissão de IL é idêntica. A “mágica” acontece depois.

2. IL (Intermediate Language)

IL é como “bytecode universal” do .NET. Um exemplo simples:

public int Add(int a, int b) => a + b;

Vira IL assim:

.method public int32 Add(int32 a, int32 b) cil managed {
  ldarg.0
  ldarg.1
  add
  ret
}

Isso é agnóstico de plataforma. Qualquer processador pode executar essas instruções (com uma VM ou compilador).

3. ILCompiler & Trimming (Análise de Reachability)

ILCompiler é o núcleo da magia Native AOT. Ele:

Lê a IL gerada por Roslyn
Analisa reachability: Começa do entry point (Main), segue cada chamada, cada campo acessado. “Se Main chamar Foo(), e Foo() chamar Bar(), então Bar() é alcançável.”
Remove código desnecessário — tree-shaking. Se MetodoX nunca é chamado, é deletado do executável final.
Detecta reflection problemática: Se você escreve Type.GetType("MinhaClasse"), o compilador não consegue saber estaticamente qual tipo você quer. Isso é um problema.
Emite código nativo via crossgen2 ou diretamente

4. crossgen2 & RyuJIT

crossgen2 é o componente que pega IL otimizada e transforma em native code (x86-64, ARM64, etc.). Usa parte do RyuJIT (o otimizador do JIT do .NET).

Não é o JIT tradicional (que roda em tempo de execução). É um compilador offline, com mais tempo para otimização.

Output: .obj files (objetos nativos), depois linkados em executável final.

5. Linkedição & Executável Final

Os .obj files são linkados com:

Runtime libraries (.NET GC, allocators, etc.)
Stdlib linkada (Collections, I/O, etc.)
Seu código compilado Resultado: app.exe (ou .so no Linux). Standalone. Nenhuma dependência externa do .NET runtime.

Fluxo Visual Completo

C# Code
  ↓
[Roslyn Compiler]
  ↓ (emite)
IL (Intermediate Language)
  ↓
[ILCompiler - Análise de Reachability & Trimming]
  ↓ (remove dead code)
Otimized IL
  ↓
[crossgen2 / RyuJIT]
  ↓ (transforma em)
Native Code (.obj files)
  ↓
[Linker]
  ↓ (linkado com runtime)
Standalone Executable (app.exe / app.so)

📝 Exemplo: Um app “Hello World” simples em JIT ocupa ~100MB (runtime + libs). Em AOT, o executável sozinho é ~5MB.

Trimming e Análise Estática: O Grande Obstáculo

Trimming é onde Native AOT brilha — e onde quebra.

O Problema da Reflection

Reflection permite código descobrir tipos, campos, métodos em tempo de execução:

// Reflection clássica
Type tipo = Type.GetType("MyApp.MyClass");
MethodInfo method = tipo.GetMethod("MyMethod");
object result = method.Invoke(instance, params);

Por que isso quebra AOT? O compilador estático não consegue saber em tempo de build qual tipo você vai pedir em Type.GetType(). Então, por segurança:

Ou compila todos os tipos (aumenta o binário)
Ou falha em runtime (crash)

Solução: TrimmerRootAssembly e Atributos

A Microsoft oferece atributos para “avisar” o compilador:

// Diga ao trimmer: não remova tipos deste assembly
[assembly: TrimmerRootAssembly]

// Ou, mais fino: diga que este método acessa esses tipos
[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods)]
public void ProcessTypes(Type tipo) { ... }

Isso torna your código “AOT-compliant” mas exige esforço e disciplina.

Análise Conservative vs Aggressive

Conservative: Trimmer presume que qualquer Type.GetType() pode ser usado; mantém tudo (maior binário, mas seguro)
Aggressive: Trimmer remove tudo que não é provado alcançável (menor binário, mas pode quebrar em runtime) Artigos sobre Native AOT sempre recomendam “teste bastante” — e com razão.

Trade-offs de Performance

Native AOT não é uma bala de prata. Aqui estão os reais tradeoffs:

1. Startup Time (Vencedor: AOT)

Cenário	JIT	AOT
Console App simples	150–500ms	20–100ms
Web API mínima	300–800ms	50–200ms
Função serverless (cold start)	1–3s	100–500ms

AOT é claramente vencedor. Em serverless, onde você paga por latência do cold start, é transformador.

⚠️ Atenção: AOT coloca todo o tempo de compilação na máquina de build, não no cliente. Se você demora 15 minutos compilando sua app em AOT, bem… existem tradeoffs.

2. Memory Footprint

Métrica	JIT	AOT
Runtime + Libs	~60MB	~2–5MB
App Binário	~1MB (IL)	5–50MB (native)
Total	~61MB	~7–55MB

Aqui parece que JIT ganha. Mas há nuances:

O runtime JIT cresce com uso (warm-up, optimizations)
AOT é fixo — tudo linkado estaticamente
Em containers, AOT binário é melhor (smaller image, faster pull/start)

3. Throughput e Otimização

Aspecto	JIT	AOT
Tiering	Sim (Tier 0 → 1 otimização)	Não (fixo)
Profiling	Jit ajusta conforme uso	Estático (sem profiling)
Hotpath	Melhora com tempo	Fixo (sem warm-up)

JIT vence em throughput puro, especialmente em long-running apps (servers, workers). JIT tem mais tempo para otimizar hotpaths. AOT é “congelado” em tempo de build.

Resumo: Quando Usar?

Startup-bound (AOT wins): Serverless, containers, CLI tools, batch jobs
Throughput-bound (JIT wins): Web servers, long-running workers, real-time systems

Exemplo Prático: CLI Tool em Native AOT

Vou mostrar um exemplo real: um String Analyzer CLI que conta frequência de caracteres em arquivos.

A razão de escolher CLI: reflection mínima, I/O puro, ideal para AOT.

Estrutura do Projeto

BlogSamples/
├── NativeAot/
│   ├── CliExample/
│   │   ├── StringAnalyzer.Console.csproj
│   │   ├── Program.cs
│   │   ├── AnalyzerService.cs
│   │   ├── README.md

Arquivo .csproj com AOT Enabled

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PublishAot>true</PublishAot>
    <TrimMode>link</TrimMode>
    <RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>
    <SelfContained>true</SelfContained>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="System.CommandLine" Version="2.0.0-beta4.24416.1" />
  </ItemGroup>
</Project>

Destaques:

PublishAot=true ativa o compilador Native AOT
TrimMode=link ativa trimming agressivo
RuntimeIdentifiers lista plataformas alvo
System.CommandLine é AOT-friendly (sem reflection para CLI parsing)

Código Exemplo: Program.cs

using System.CommandLine;
using StringAnalyzer.Console;

var fileArgument = new Argument<FileInfo>(
    name: "file",
    description: "Arquivo para análise");

var rootCommand = new RootCommand("Analisa frequência de caracteres");
rootCommand.AddArgument(fileArgument);

rootCommand.SetHandler((file) =>
{
    if (file == null || !file.Exists)
    {
        Console.WriteLine("Arquivo não encontrado.");
        return;
    }

    var analyzer = new AnalyzerService();
    var result = analyzer.Analyze(file.FullName);

    Console.WriteLine($"Arquivo: {file.Name}");
    Console.WriteLine($"Total de caracteres: {result.TotalChars}");
    Console.WriteLine("\nFrequência dos 10 mais comuns:");

    foreach (var (ch, count) in result.TopFrequent.Take(10))
    {
        Console.WriteLine($"  '{ch}': {count}");
    }
}, fileArgument);

return await rootCommand.InvokeAsync(args);

Por que isso é AOT-friendly:

System.CommandLine é otimizado para AOT
Zero reflection dinamicamente (argumentos são resolvidos em compile-time)
I/O simples, sem patterns avançados

Compilar e Executar

# Restore
dotnet restore

# Publish para AOT (windows x64)
dotnet publish -c Release -r win-x64 /p:PublishAot=true

# Executável sai em: bin/Release/net10.0/win-x64/publish/StringAnalyzer.Console.exe
# Tamanho típico: 8–12 MB

# Teste
./StringAnalyzer.Console.exe myfile.txt

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/NativeAot/CliExample/

Dicas e Boas Práticas

Use System.CommandLine para CLI parsing
System.CommandLine é otimizado para AOT e não usa reflection. Evite bibliotecas mais antigas que dependem de reflection para atributos de argumentos.
Minimize reflection; use source generators quando possível
Se você precisa de serialização, use System.Text.Json com source generators (JsonSourceGenerationContext). Evite Newtonsoft.Json ou reflection pura em AOT.
Teste AOT warnings durante desenvolvimento
Compile com dotnet build e cheque warnings. Não deixe para descobrir problemas em produção. Use -Werror para converter warnings em erros durante CI.
Perfil o tamanho do binário
Use dotnet publish --analyze-warnings ou dotnet size para entender onde o tamanho está indo. Às vezes, remover uma dependência economiza MB.
Considere ReadyToRun como alternativa
Se você quer startup rápido mas não pode abrir mão de reflection, ReadyToRun é um meio-termo. Compile com PublishReadyToRun=true em vez de PublishAot=true.
Teste em ambientes similares ao produção
AOT binário compilado em Windows pode não rodar em Linux (arquivos Object linkam diferente). Sempre compile/teste para o target runtime específico.
Prepare-se para binários maiores
AOT geralmente resulta em binários 5–50× maiores que IL puro. Se seu deployment é bandwidth-constrained (edge devices, IoT), considere R2R ou JIT.
Documente dependências AOT-compatibility
Se você usa bibliotecas de terceiros, confirme explicitamente que são AOT-compatible. Mantenha isso em seu README de deployment.

Resumo Objetivo

Native AOT — compilação antecipada de C# em binário nativo (x86-64, ARM), eliminando JIT em runtime e criando executáveis standalone sem dependência de .NET runtime.
Stack de compilação — Roslyn (análise estática em C#) → IL (pseudocódigo universal) → ILCompiler (análise de reachability & trimming) → crossgen2 (transformação IL → nativo) → Linker (executável final).
Trimming — remoção automática de código não alcançável (tree-shaking); quebra com reflection dinâmica (Type.GetType()), requer TrimmerRootAssembly e DynamicallyAccessedMembers para avisar o compilador.
Startup time — ganho de 200–500ms em apps pequenas, 1–2s em serverless; vantagem crítica em cold starts e containers.
Throughput — JIT vence em long-running apps (warm-up, tiering); AOT é fixo e congelado no build.
Cenários ideais — serverless (AWS Lambda, Azure Functions), containers, CLI tools, batch jobs, IoT, edge computing.
Tradeoffs — startup 3–10× mais rápido, binário 5–50× maior, sem reflection, tempo de compilação substancial, análise estática rigorosa.

Referências

Microsoft Docs — Native AOT — documentação oficial, configuração e limitações
RyuJIT and Native Code Generation — source code do compilador JIT/AOT
Roslyn — C# Compiler — analysis e code generation
IL Compiler & Trimming — NativeAOT toolchain
System.CommandLine — AOT-Compatible CLI — library para argumentos sem reflection
Trimming .NET Applications — guia de trimming e troubleshooting 📬

👉 Artigo completo com todos os exemplos de código: .NET Native AOT: Ecossistema de Compilação em C#

Como Publicar uma Biblioteca .NET no NuGet.org

Lincoln Zocateli — Thu, 20 Aug 2026 02:01:24 +0000

Introdução

Publicar uma biblioteca .NET no NuGet.org não é apenas empacotar um projeto e enviar o .nupkg para o servidor. O ponto mais importante é tratar a API pública como um contrato que outras pessoas e outros times vão consumir. Se eu publicar uma API sem pensar em compatibilidade, o problema não fica só no pacote: ele se espalha para dependências, pipelines e aplicações que dependem do mesmo assembly. Por isso, a publicação segura combina três pilares: contrato estável, versionamento consciente e validação real do artefato em um ambiente de consumidor separado.

A ideia deste artigo é explicar a jornada completa de uma biblioteca .NET: preparar a API, decidir o tipo de distribuição, validar localmente, publicar em um ambiente de teste e, por fim, divulgar a versão estável em nuget.org. Também vou mostrar quando o pacote deve ficar em um feed público e quando ele precisa ir para Azure Artifacts ou GitHub Packages. O objetivo é dar uma visão prática para quem está publicando o primeiro pacote ou tentando organizar a distribuição interna da empresa.

Se você já usou pacotes NuGet em projetos de aplicação, sabe que o fluxo de consumo parece simples na superfície: restaurar, compilar e executar. O ponto delicado é o contrato. A biblioteca que parece compatível no build pode gerar erros de runtime quando o pacote é consumido em um projeto externo com metadados ou dependências diferentes. Por isso, vale separar a publicação em etapas: feed local, ambiente de teste do NuGet, publicação pública e feeds privados. O percurso é simples de entender, mas a disciplina é o que evita retrabalho e quebrar clientes.

⚠️ Atenção: o ambiente de teste do NuGet não substitui um feed privado. Ele serve para validar o fluxo de publicação antes de subir a versão definitiva. Azure Artifacts e GitHub Packages existem para distribuição interna persistente e autenticada.

Pré-requisitos

Antes de empacotar o primeiro pacote, eu gosto de validar alguns preceitos básicos para evitar a sensação de que a publicação foi bem-sucedida e, depois, o pacote não ficou útil para quem vai consumir. Em primeiro lugar, você precisa do .NET SDK instalado e funcional; a checagem mínima é dotnet --info. O lado operacional também importa: uma conta no nuget.org e uma API key com escopo limitado para o pacote. Isso reduz o impacto de vazamento ou uso indevido.

O próximo passo é separar o cenário de distribuição. Se o pacote é público, um fluxo de publicação no nuget.org exige revisão e indexação. Se ele é interno, a melhor alternativa costuma ser Azure Artifacts ou GitHub Packages, com autenticação e controle de acesso. Em qualquer caso, o ideal é nunca expor tokens em arquivos versionados ou em comandos de terminal que fiquem no histórico do shell.

Também vale deixar claro que esse processo não é só de “empacotar e publicar”. É de “empacotar e validar”. A rotina de publicação tem um exercício importante: criar um projeto consumidor separado e instalar o pacote que acabou de ser gerado. Só assim é possível verificar se README, dependências, arquivos e metadados estão corretos.

Defina o Contrato e a Estratégia de Versionamento SemVer

A publicação de bibliotecas .NET exige que o versionamento seja tratado como parte do contrato público. O SemVer é a convenção mais usada no ecossistema e define que a versão siga a estrutura MAJOR.MINOR.PATCH. Cada componente comunica algo diferente:

MAJOR indica alteração incompatível de API pública
MINOR indica adição de funcionalidade compatível
PATCH indica correção de defeito sem mudar a API Não é só uma convenção estética. O número da versão comunica ao consumidor o risco da atualização. Se eu remover um método público ou mudar o comportamento de forma que um cliente dependa do antigo contrato, a mudança é de MAJOR. Se eu adiciono um novo método a uma API que não quebra ninguém, a mudança é de MINOR. Se eu corrijo um bug internalmente sem alterar a interface, a mudança é de PATCH.

Eu também gosto de reforçar a importância das versões pré-release. Em bibliotecas, 1.5.0-beta.1, 1.5.0-rc.1 e 1.6.0-alpha.3 são úteis para validar uma funcionalidade antes de o pacote ser publicado como estável. Isso reduz o risco de anunciar uma versão definitiva sem testar os impactos reais. A regra mais importante é simples: uma versão publicada é imutável. Se ela estiver errada, você corrige em uma nova versão, não reescreve a antiga.

Mudança no contrato público	Próxima versão	Exemplo
Remover método ou alterar comportamento incompatível	MAJOR	1.4.2 → 2.0.0
Adicionar método sem quebrar consumidores	MINOR	1.4.2 → 1.5.0
Corrigir defeito sem alterar contrato	PATCH	1.4.2 → 1.4.3
Validar versão futura	Sufixo pré-release	1.5.0-beta.1

💡 Dica: o chamado SemVer 2 também permite pré-releases com rótulos e regras de normalização que o NuGet aceita. Isso é importante quando você quer testar uma nova funcionalidade com consumidores que ainda não querem depender dela em produção.

Prepare a Biblioteca para Distribuição

Uma biblioteca pode ser pequena e ainda assim precisa de itens mínimos de qualidade para ser publicada. O projeto de exemplo usado neste artigo está no repositório de exemplos do blog e chama-se Contoso.TextRules. Ele expõe regras reutilizáveis para validação e normalização de texto. A estrutura do pacote é simples, mas a forma como ele é descrito no .csproj é o que permite que o NuGet gere uma página útil no site e que o pacote seja reconhecido corretamente pelo tooling do .NET.

No arquivo de projeto, alguns metadados são fundamentais:

PackageId — identifica o pacote
Version — define a versão da distribuição
Authors — informa autoria
Description — resumo útil para busca e descoberta
PackageTags — pesquisa e classificação no NuGet.org
PackageReadmeFile — inclui README dentro do pacote
PackageLicenseExpression — licença SPDX para transparência
RepositoryUrl e RepositoryType — ajuda na navegação e rastreabilidade Além disso, vale empacotar símbolos quando a biblioteca é relevante para depuração e diagnósticos. O dotnet pack também consegue incluir arquivos do pacote, como README.md e LICENSE, o que melhora bastante a experiência de quem vai consumir a biblioteca.

A separação entre abstração e implementação também é relevante como boa prática. O NuGet tem uma cultura muito forte de pacotes pequenos e de responsabilidade clara. Em projetos maiores, é comum separar um contrato da implementação: por exemplo, projetar uma biblioteca de abstração com interfaces e contratos e outra biblioteca com a implementação concreta. Isso evita que consumidores dependam de todo o conjunto de funcionalidades e permite que a API pública evolua com mais clareza. Isso não é obrigatório para todo projeto pequeno, mas é um padrão útil para bibliotecas de plataforma ou componentes de domínio.

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/Packaging/NuGetPublish/

Empacote e Valide Localmente Antes do Push

Depois de preparar a biblioteca, o próximo passo é empacotar o artefato em modo Release. Isso é o ponto em que eu verifico se o projeto realmente gera um pacote completo. O comando principal é:

dotnet pack src/BlogSamples/Packaging/NuGetPublish/Contoso.TextRules/Contoso.TextRules.csproj -c Release

O resultado esperado é um .nupkg na pasta bin/Release. Mas o simples fato de existir um arquivo não basta. Eu sempre inspeciono o pacote para confirmar que ele contém o README, a licença e as dependências corretas. O pacote pode compilar e ainda assim ter metadados incompletos ou arquivos faltando, o que costuma aparecer quando a biblioteca é consumida por um projeto externo.

A validação mais importante é consumir o pacote em outro projeto. Isso muda o cenário: o consumidor não está dentro do mesmo repositório nem do mesmo assembly. Ele instala o pacote via dotnet add package ou via feed local, e aí aparecem erros de integração que os testes da própria biblioteca não capturam. Um erro clássico é um arquivo que fica ausente no pacote ou um README que não foi incluído corretamente. O pacote precisa funcionar como um item distribuído, não apenas como um projeto compilado localmente.

Valide no Ambiente de Teste do NuGet

Depois que o pacote está funcionando localmente, o próximo ambiente natural é o teste do NuGet. O endereço oficial é https://int.nugettest.org. Esse ambiente foi criado para validar o fluxo de publicação antes do envio ao feed público. O objetivo não é substituir o processo de produção, e sim confirmar que o pacote pode ser enviado, restaurado e consumido em um cenário semelhante ao real.

Em geral, o fluxo é simples: configurar uma fonte de pacote nomeada para o ambiente de teste, autenticar com o usuário e enviar a versão. Com o pacote em mãos, um projeto consumidor diferente pode restaurá-lo e executar o código real. Essa validação reduz o risco de uma falha de packaging ou de uma API pública que ainda não está pronta para o feed público.

ℹ️ Informação: a documentação oficial do NuGet usa int.nugettest.org como ambiente para testar a publicação antes do nuget.org. Pacotes enviados para esse ambiente podem não ser preservados, por isso ele é útil para validação, não para distribuição persistente.

Publique uma Versão Estável no NuGet.org

Quando a API pública está pronta e o pacote passou pela validação de consumo, a próxima etapa é publicar a versão estável em nuget.org. Esse processo exige uma API key do NuGet com escopo mínimo: o ideal é restringir o token ao prefixo do pacote e ao tempo de validade necessário. Isso reduz muito o impacto de vazamento de credenciais.

O comando mais comum é o dotnet nuget push, geralmente com o pacote já empacotado em Release:

dotnet nuget push ./artifacts/Contoso.TextRules.1.0.0.nupkg --api-key $NUGET_API_KEY --source https://api.nuget.org/v3/index.json

Na prática, a publicação no nuget.org não é o fim do processo: ela também dispara a indexação e a disponibilidade do pacote para busca e restauração. O pacote passa por validações do NuGet e, em alguns casos, demora alguns minutos para aparecer como disponível para instalação. Isso é normal e faz parte do fluxo oficial. Também vale deixar claro que a decisão de usar unlist faz sentido para remover uma versão da visibilidade pública sem apagá-la por completo; já “excluir” uma versão não é a abordagem recomendada para distribuir um artefato público de forma segura.

A regra mais importante é reservar a primeira estável 1.0.0 para o momento certo. Em bibliotecas, eu prefiro validar a API em pré-release primeiro. Isso dá tempo de ajustar comportamento sem a pressão de “uma versão potencialmente quebrada” já disponível publicamente.

Distribua Bibliotecas Internas com Azure Artifacts e GitHub Packages

Nem todo pacote merece ir para nuget.org. Quando a biblioteca é interna, um feed privado é a opção mais segura e fácil de operar. Azure Artifacts e GitHub Packages atendem a esse cenário com autenticação e controle de acesso. A decisão geralmente depende da assinatura da plataforma usada pela organização.

Azure Artifacts

O Azure Artifacts funciona muito bem quando a organização já usa Azure DevOps e tem pipelines centralizados. O feed de pacotes fica associado à organização e ao projeto do Azure DevOps, e a autenticação pode ser integrada a pipelines e regras de segurança. Para times usando Azure como plataforma principal, essa é uma forma natural de publicar bibliotecas internas com políticas de acesso e revisão de versões.

GitHub Packages

O GitHub Packages se encaixa bem em times que já vivem dentro do GitHub. A autenticação usa token com escopo e permissões mínimas, e a integração com GitHub Actions costuma ser direta. Isso facilita muito a publicação de componentes internos, bibliotecas compartilhas e dependências para repositórios privados e públicos em diferentes fluxos de desenvolvimento.

Critério	Azure Artifacts	GitHub Packages
Plataforma principal	Azure DevOps	GitHub
Integração de CI	Azure Pipelines	GitHub Actions
Controle de acesso	Organização e projeto	Organização e repositório
Melhor cenário	Times centralizados no Azure DevOps	Times que já usam GitHub

⚠️ Atenção: nunca deixe tokens em NuGet.Config versionado. O arquivo de configuração pode apontar para diferentes fontes, mas os segredos devem sair do repositório e entrar por variáveis de ambiente ou secret stores do CI.

Automatize Releases sem Quebrar Consumidores

A automação de publicação é importante, mas ela precisa ser um guard rail, não um atalho. O fluxo ideal de CI/CD para uma biblioteca .NET é: validar testes, empacotar, verificar se a versão já existe no feed e só então publicar. Isso evita que uma tentativa de push reescreva uma versão já publicada ou publique um pacote quebrado para o feed errado.

Uma boa estratégia é separar release e publicação em dois momentos. O processo de tag e changelog fica em Git; a publicação de pré-release pode ir para feed privado ou ambiente de teste; a versão estável vai para nuget.org somente após revisão de compatibilidade. Isso ajuda a manter o controle da API pública e faz com que a decisão de publicar uma nova versão seja uma decisão mais consciente.

Em pipelines, a regra é proteger os segredos. O principal é manter o token em um secret do CI, usá-lo em um passo específico de publish e restringir as permissões. O código da biblioteca pode ser automático, mas a decisão de liberar uma nova versão estável continua sendo algo que exige atenção humana e documentação de breaking change.

Exemplo Prático

Vou usar o mesmo cenário do projeto de exemplo: uma biblioteca chamada Contoso.TextRules com regras de validação reutilizáveis. O objetivo é demonstrar a parte do contrato: a API pública fica estável, a versão de pacote inicia como 1.0.0-alpha.1, e a promoção para 1.0.0 acontece depois que a biblioteca é validada em um ambiente de consumidor separado.

Primeiro, a biblioteca em si. O trecho principal mostra como a API pública é simples e previsível:

namespace BlogSamples.Packaging.NuGetPublish;

public sealed class TextRuleSet
{
    public bool IsValidEmail(string value)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(value);

        return value.Contains('@')
            && value.Contains('.')
            && value.IndexOf('@', StringComparison.Ordinal) > 0;
    }

    public string NormalizeWhitespace(string value)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(value);

        return string.Join(' ', value.Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries));
    }
}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/Packaging/NuGetPublish/Contoso.TextRules/

Em seguida, acrescento os metadados importantes para o pacote:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <PackageId>Contoso.TextRules</PackageId>
    <Version>1.0.0-alpha.1</Version>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <RepositoryUrl>https://github.com/lzocateli/blog-zocateli-sample</RepositoryUrl>
    <RepositoryType>git</RepositoryType>
  </PropertyGroup>
</Project>

A geração do pacote acontece em Release:

dotnet pack src/BlogSamples/Packaging/NuGetPublish/Contoso.TextRules/Contoso.TextRules.csproj -c Release

Para consumo em um projeto separado, eu também gosto de configurar uma fonte local ou de teste e instalar o pacote em um consumidor mínimo:

dotnet new classlib -n Contoso.TextRules.Consumer
cd Contoso.TextRules.Consumer

dotnet add package Contoso.TextRules --version 1.0.0-alpha.1 --source /caminho/para/o/feed

Esse passo é essencial. Ele confirma que a biblioteca não depende apenas do projeto em que ela foi compilada, mas do artefato que será entregue ao consumidor final. Depois da validação, a promoção para 1.0.0 fica muito mais segura e a decisão de publicar em nuget.org passa a ser uma escolha tecnológica, não só uma sensação de “está funcionando”.

Dicas e Boas Práticas

Trate a API pública como contrato. Qualquer alteração de assinatura, comportamento observável ou semântica documentada precisa ser avaliada pelo impacto em consumidores antes de escolher a versão SemVer.
Consuma o .nupkg em outro projeto. Testar apenas a biblioteca compilada não verifica se o pacote contém README, dependências e assemblies corretos.
Crie API keys e tokens com escopo mínimo. Uma credencial limitada ao prefixo do pacote e à operação de push reduz o impacto de vazamento acidental.
Nunca reutilize uma versão publicada. Corrija o problema em uma nova versão PATCH ou publique uma nova pré-release; isso preserva reprodutibilidade de restore.
Separe fontes públicas e privadas no NuGet.Config. Dê nomes claros às fontes, restrinja mapeamento de pacotes quando apropriado e evite que dependências internas sejam procuradas no nuget.org.
Automatize, mas preserve revisão. O CI deve garantir testes e empacotamento repetíveis; a decisão de uma release estável ainda exige revisão de compatibilidade e changelog.

Resumo Objetivo

SemVer — em uma biblioteca .NET, MAJOR representa mudança incompatível, MINOR adiciona funcionalidade compatível e PATCH corrige defeito compatível; pré-releases usam um sufixo como -beta.1.
NuGetVersion — o NuGet normaliza versões como 1, 1.0 e 1.0.0 como equivalentes e suporta recursos do SemVer 2 em clientes modernos.
Feed local — consumir o .nupkg em um projeto separado verifica o artefato distribuído, incluindo dependências, metadados e arquivos anexados.
int.nugettest.org — é o ambiente de teste documentado pelo NuGet para validar publicação antes do nuget.org, mas os pacotes podem não ser preservados.
nuget.org — exige uma versão exata no pacote e valida o upload antes de indexá-lo; API keys devem ter escopo e expiração mínimos.
Feeds privados — Azure Artifacts e GitHub Packages distribuem bibliotecas internas com autenticação e controle de acesso, função diferente da homologação no ambiente de teste público.

Referências

How to publish NuGet packages — documentação oficial para publicação, API keys, indexação e ambiente de teste.
NuGet Package Version Reference — regras de versão, pré-releases, normalização e SemVer 2.
Overview of Hosting Your Own NuGet Feeds — alternativas para distribuição privada de pacotes.
Semantic Versioning 2.0.0 — especificação do contrato de versionamento semântico.
Azure Artifacts documentation — publicação e consumo de pacotes NuGet no Azure DevOps.
Working with the NuGet registry — configuração e publicação no GitHub Packages.
Nuuvify.CommonPack — exemplo real de coleção de bibliotecas .NET publicada no NuGet, organizada por responsabilidade e projetos de abstração. 📬

👉 Artigo completo com todos os exemplos de código: Como Publicar uma Biblioteca .NET no NuGet.org

Thread-safety em .NET 10 e Python: GIL e race conditions

Lincoln Zocateli — Wed, 12 Aug 2026 01:31:34 +0000

Introdução

Quando alguém diz que “esse serviço é thread-safe”, a frase está dizendo algo simples e sério: ele pode ser acessado por múltiplas threads ao mesmo tempo sem criar corrupção de estado, resultados intermitentes ou condições de corrida. Em produção, isso é matéria de arquitetura, não apenas de curiosidade acadêmica. Um Singleton com Dictionary interno pode funcionar em testes e falhar em produção sob carga. Um cache compartilhado sem controle de concorrência pode perder itens sem qualquer erro aparente. E o problema não é novo: ele acompanha aplicações web, workers, filas, serviços de background e processamento em lote.

O objetivo deste artigo é mostrar exatamente como isso acontece em duas plataformas muito usadas no ecossistema moderno: .NET 10 e Python. Em .NET, a resposta costuma passar por System.Threading.Lock, Interlocked, ConcurrentDictionary e escolhas de lifetime em DI. Em Python, a conversa rapidamente entra no GIL (Global Interpreter Lock), no modelo de threading, em queue.Queue e, hoje, em um cenário mais relevante: o Python free-threaded, que remove parte dessa garantia e devolve ao desenvolvedor a responsabilidade direta pela sincronização.

A boa notícia é que o raciocínio é o mesmo nos dois lados: estado mutável compartilhado exige proteção ou eliminação do compartilhamento. Se o estado é imutável, a coisa fica mais simples. Se o estado é compartilhado e mutável, você precisa pensar em invariantes, acesso atômico e testabilidade. Isso é o que vou mostrar aqui com exemplos práticos e com um padrão de teste que prova se o serviço aguenta concorrência de verdade.

⚠️ Atenção: O problema não é “muitas threads ao mesmo tempo” em si. O problema é o acesso simultâneo a estado compartilhado sem uma regra de sincronização. Sem esse detalhe, qualquer serviço pode parecer estável em ambiente de laboratório e quebrar sob carga real.

O que significa thread-safe na prática

Thread-safe é uma propriedade do comportamento do componente, não apenas da linguagem. Uma implementação é thread-safe quando, sob qualquer interleaving válido de threads, a estrutura de dados e o comportamento observável continuam consistentes. Em outras palavras: o objeto continua correto mesmo quando duas ou mais threads tentam usar o mesmo recurso ao mesmo tempo.

Para ajudar a ser mais concreto, pense em um contador simples:

public class CounterService
{
    private int _count;

    public void Increment()
    {
        _count++;
    }

    public int GetValue()
    {
        return _count;
    }
}

Esse código parece trivial. Na prática, ++ em um inteiro não é uma operação atômica. A sequência real é algo como: ler o valor, somar 1, escrever de volta. Se duas threads fizerem isso ao mesmo tempo, ambas podem ler o mesmo valor antigo e escrever o mesmo resultado final. O contador “perde” um incremento, e a falha é chamada de race condition.

Isso é importante porque muitos serviços de produção têm estado compartilhado em um Singleton, em um cache em memória, em um acumulador de estatísticas, em um processamento em lote e em filas. Quando isso acontece sem sincronização, o problema é não apenas teórico — ele aparece como contadores inconsistentes, listas parcialmente preenchidas, dicionários quebrados ou erros intermitentes que parecem aleatórios.

Quatro propriedades que importam

Quando você trabalha com concorrência, normalmente quer responder quatro perguntas:

O estado pode ser acessado por múltiplas threads ao mesmo tempo?
Essa operação tem semântica atômica?
A leitura e a escrita têm visibilidade consistente entre threads?
A mutação preserva invariantes do objeto? Se a resposta for “sim” para a primeira, você precisa considerar sincronização ou imutabilidade. A operação x++ falha na primeira e na segunda. O ConcurrentDictionary tenta resolver isso sem exigir lock manual em cada operação. O Interlocked resolve o caso mais simples de contador ou valor atômico.

.NET 10: o que mudou e quando usar `System.Threading.Lock`

No .NET, a forma clássica de proteger um bloco era usar lock em um objeto: lock (_lock) { ... }. Isso funciona, mas o padrão antigo deixa o desenvolvedor escrever suporte de sincronização de forma pouco explícita. A partir do .NET 9, a biblioteca padrão passou a oferecer o tipo System.Threading.Lock, que deixa a intenção mais clara.

public sealed class CounterWithLock
{
    private readonly Lock _lock = new();
    private int _count;

    public void Increment()
    {
        lock (_lock)
        {
            _count++;
        }
    }

    public int GetValue()
    {
        lock (_lock)
        {
            return _count;
        }
    }
}

A ideia do Lock é muito parecida com o lock tradicional, mas a API tem uma intenção mais explícita e ajuda a evitar armadilhas de sincronização com objetos escolhidos de forma ingênua. Isso é importante porque lock (this) ou lock (new object()) costumam causar bugs reais em arquitetura. O Lock também deixa o código mais legível e mais específico ao que está protegendo.

Quando usar `lock` e quando usar `Interlocked`

A regra prática é simples:

use lock quando você precisa proteger um bloco de código com múltiplas operações e invariantes mais complexos;
use Interlocked quando você precisa apenas proteger uma variável primitiva com uma operação simples. Exemplo com Interlocked:

public sealed class CounterWithInterlocked
{
    private int _count;

    public void Increment() => Interlocked.Increment(ref _count);

    public int GetValue() => Interlocked.CompareExchange(ref _count, 0, 0);
}

O Interlocked opera em nível mais baixo e evita contensão desnecessária em operações simples. Ele é especialmente útil para contadores, flags de estado e regras de sincronização rápidas. Já o lock continua sendo a ferramenta certa quando a correção exige isolar uma sequência de passos e garantir que a operação inteira execute de forma indivisível.

`ConcurrentDictionary` e coleções concorrentes

Uma parte importante de thread-safety em .NET está nas coleções do namespace System.Collections.Concurrent.

private readonly ConcurrentDictionary<string, int> _acessosPorChave = new();

_acessosPorChave.AddOrUpdate(
    key: "requests",
    addValue: _ => 1,
    updateValueFactory: (_, current) => current + 1);

Esse padrão é usado em serviços de cache e agregações concorrentes. A ideia é que a estrutura já sabe como sincronizar a escrita e a leitura internamente. Isso é muito melhor que um Dictionary compartilhado e acessado por várias threads, especialmente em cenários de alta carga. Em um singleton, um Dictionary comum é uma armadilha clássica. Em um Scoped ou Transient, geralmente não exigirá sincronização porque o objeto não será compartilhado entre requisições.

DI em ASP.NET Core: Singleton é o ponto crítico

O container de DI do ASP.NET Core muda a regra do jogo. O lifetime do serviço define se o mesmo objeto será compartilhado por múltiplas requisições ou não.

Regra prática

AddSingleton — o mesmo objeto vive para toda a aplicação. Se ele tiver estado mutável, ele precisa ser thread-safe.
AddScoped — normalmente cada requisição recebe sua própria instância. Em geral, não exige thread-safety.
AddTransient — cria uma instância por injeção. Em geral, também não exige thread-safety. Isso é direto, mas a parte perigosa é a seguinte: muita gente registra um “cache em memória” como singleton porque parece simples, mas depois o mesmo objeto é consultado e atualizado por múltiplas requisições ao mesmo tempo. O desenho leva a race condition, KeyNotFoundException inesperado, lista mutável exposta, ou simplesmente dados inconsistentes.

Um exemplo clássico:

builder.Services.AddSingleton<UserCache>();

public sealed class UserCache
{
    private readonly Dictionary<int, User> _users = new();

    public void Add(User user) => _users[user.Id] = user;
    public User? Get(int id) => _users.TryGetValue(id, out var user) ? user : null;
}

Esse serviço parece inofensivo, mas ele não é thread-safe. Se a mesma instância for usada por múltiplas requisições simultaneamente, a mutação de Dictionary causa problemas reais. A correção é usar ConcurrentDictionary, ImmutableDictionary ou encapsular a mutação em lock quando a operação exige uma sequência de passos.

ℹ️ Informação: DbContext nunca deve ser singleton por projeto. Ele não é thread-safe e também não foi desenhado para abertura compartilhada entre requisições.

Python: o GIL e o mundo em que ele não resolve tudo

Em Python, o cenário é diferente. O interpretador CPython usa o GIL (Global Interpreter Lock), que serializa a execução de bytecode em cada processo. Em outras palavras, em uma mesma máquina com o interprete padrão, a linguagem evita que duas threads Python interpretem bytecode ao mesmo tempo.

Isso cria um mito recorrente: “se o Python tem GIL, então a aplicação é thread-safe por padrão”. Isso é falso. O GIL não resolve invariantes compostos e não torna o código thread-safe em sentido de arquitetura. Ele apenas impede a execução simultânea de bytecode Python dentro do mesmo processo.

O GIL ajuda em cenários I/O-bound, como chamadas de rede, arquivos e sockets, porque uma thread pode ficar esperando e outra pode executar. Mas ele não protege um objeto mutável compartilhado quando a operação real exige várias etapas, e não dá nenhuma garantia de consistência para estruturas mutáveis complexas.

Exemplo clássico em Python:

counter = 0

# thread A
counter += 1

# thread B
counter += 1

Esse código parece simples, mas não é atomicamente seguro em termos de semântica do programa. O GIL não garante que a sequência inteira de leitura + cálculo + escrita ocorra sem interferência. Os detalhes implementacionais podem variar e a correção exige sincronização explícita com threading.Lock ou uma estrutura projetada para concorrência.

Python 3.13 e o free-threaded mode

A comunidade Python tem discutido muito a ideia de remover ou tornar opcional o GIL. Em 2023/2024, o projeto passou para um estágio mais realista com o free-threaded Python (ou Python sem GIL em execução), uma mudança importante para o ecossistema. Isso significa que, em algumas builds, múltiplas threads podem executar bytecode Python em paralelo, o que faz o problema de sincronização voltar ao centro da discussão.

Em outras palavras:

com GIL, a concorrência em Python ainda exige cuidado;
sem GIL, a necessidade de sincronização explícita fica mais óbvia;
o dia a dia real da engenharia continua sendo: proteger estado compartilhado e testar invariantes.

Primitivas de concorrência em Python

Python oferece opções bem conhecidas:

import threading

lock = threading.Lock()
value = 0


def increment():
    global value
    with lock:
        value += 1

Também existem:

threading.RLock — lock reentrante;
threading.Semaphore — limite de acesso concorrente;
threading.Event — sinalização entre threads;
queue.Queue — fila thread-safe para comunicação entre producer/consumer;
concurrent.futures — executa tarefas em pool de threads ou processos. Essas ferramentas têm equivalência conceitual com o que o .NET oferece, mas a semântica do runtime muda. Em Python, especialmente em CPython, a arquitetura do GIL e a presença de free-threaded mode podem mudar o nível de paralelismo e as dicas de design.

Comparativo lado a lado: .NET 10 vs Python

A tabela abaixo ajuda na análise prática:

Necessidade	.NET 10	Python
Bloqueio simples	System.Threading.Lock	threading.Lock
Contador atômico	Interlocked.Increment	threading.Lock ou itertools.count
Dicionário concorrente	ConcurrentDictionary	dict com lock ou queue
Limite de concorrência	SemaphoreSlim	threading.Semaphore
Fila produtor/consumidor	Channel	queue.Queue / asyncio.Queue
Estado imutável	ImmutableDictionary	frozenset, tuple, MappingProxyType
Parallelismo assíncrono	Task, await	asyncio, ThreadPoolExecutor
Processamento CPU-bound	Parallel.ForEach, Task	ProcessPoolExecutor

A principal diferença conceitual é esta: no .NET, o modelo de threads e o memory model são mais explícitos; no Python, a existência do GIL e do modelo cooperativo de asyncio cria mais camadas de abstração. Mas, em ambos os casos, o problema é o mesmo: a sincronização precisa existir quando você tem estado compartilhado mutável.

Como testar se um serviço é thread-safe

O melhor jeito de testar não é “olhar o código” e achar que parece seguro. O melhor jeito é construir um teste de estresse com múltiplas threads, executar várias operações e validar uma invariante. O padrão é simples: N threads, K iterações, um total esperado e uma assertiva para garantir que o valor final seja sempre o mesmo.

Em .NET, isso fica assim:

public static void ExecutarConcorrencia(IContadorService contador)
{
    const int threads = 32;
    const int iteracoes = 50_000;
    var barreira = new Barrier(threads);

    var tarefas = Enumerable.Range(0, threads)
        .Select(_ => Task.Run(() =>
        {
            barreira.SignalAndWait();
            for (var i = 0; i < iteracoes; i++)
            {
                contador.Incrementar();
            }
        }))
        .ToArray();

    Task.WaitAll(tarefas);

    var totalEsperado = (long)threads * iteracoes;
    Console.WriteLine($"Esperado: {totalEsperado} | Atual: {contador.Valor}");
}

Se a implementação for insegura, o total final será menor do que o esperado em algumas execuções. Isso é típico de race condition: o problema aparece de forma probabilística e intermitente. Não basta rodar uma vez. Vale repetir várias rodadas para validar.

Isso é exatamente o que o repositório de exemplos do blog demonstra: um serviço sem proteção, um serviço com Lock e um serviço com Interlocked. O mesmo padrão é fácil de repetir em Python com threading.Thread e threading.Lock.

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog: BlogSamples/AsyncParallel/ThreadSafety/

Exemplo prático em C

Abaixo está um exemplo mínimo com duas versões do mesmo serviço: uma insegura e outra segura. O objetivo aqui não é mostrar um framework completo; é demonstrar o conceito com precisão.

public interface IContadorService
{
    void Incrementar();
    long Valor { get; }
}

public sealed class ContadorNaoSeguro : IContadorService
{
    private long _valor;

    public long Valor => _valor;

    public void Incrementar() => _valor++;
}

public sealed class ContadorComLock : IContadorService
{
    private readonly Lock _sincronizacao = new();
    private long _valor;

    public long Valor
    {
        get
        {
            lock (_sincronizacao)
            {
                return _valor;
            }
        }
    }

    public void Incrementar()
    {
        lock (_sincronizacao)
        {
            _valor++;
        }
    }
}

A estrutura acima já explica muita coisa. A versão insegura perde incrementos sob concorrência; a versão protegida mantém o valor consistente. O próximo passo, em um serviço real, é decidir se a solução correta é lock, Interlocked, ConcurrentDictionary ou imutabilidade completa. Isso depende do tipo de operação e do grau de mutação que o objeto precisa suportar.

Exemplo realista: `ConcurrentDictionary` em singleton

Um singleton com agregação de estatísticas é um caso clássico de uso correto de ConcurrentDictionary:

public sealed class EstatisticasService
{
    private readonly ConcurrentDictionary<string, long> _contagemPorChave = new();

    public void Registrar(string chave, long incremento = 1)
    {
        _contagemPorChave.AddOrUpdate(
            chave,
            _ => incremento,
            (_, atual) => atual + incremento);
    }

    public long Obter(string chave) =>
        _contagemPorChave.TryGetValue(chave, out var valor) ? valor : 0;
}

Esse padrão é muito útil quando a aplicação registra eventos, métricas, contadores por usuário ou por endpoint. A estrutura já implementa a sincronização interna, então o serviço pode continuar sendo um singleton sem virar uma fonte de race condition.

Dicas e boas práticas

Prefira imutabilidade quando possível. Objetos imutáveis são mais fáceis de compartilhar sem sincronização.
Em .NET 10, prefira System.Threading.Lock em blocos complexos em vez de usar objetos arbitrários como sincronizadores.
Em Singleton, assuma que o estado mutável precisa de proteção; em Scoped e Transient, a maioria das instâncias não é compartilhada.
Em Python, GIL não é a mesma coisa que thread-safety; sincronize sempre quando o estado compartilhado é mutável.
Teste concorrência com múltiplas threads e assertivas sobre invariantes, não apenas com execução unitária simples.
Quando o padrão exige para cada operação, use ConcurrentDictionary, Channel<T> ou filas em vez de Dictionary e List expostos.
Preserve snapshots quando for expor estado interno para leitura; evite retornar dicionários ou listas mutáveis do objeto compartilhado.

Resumo Objetivo

Thread-safety — é a garantia de que um componente mantém estado consistente mesmo sob acesso simultâneo de múltiplas threads.
System.Threading.Lock no .NET 10 — oferece uma primitiva explícita e mais legível para proteger blocos de código e invariantes complexos.
Interlocked — é ideal para contadores simples e operações atômicas de variável única, sem bloquear o sistema inteiro.
Singleton em ASP.NET Core — exige atenção redobrada porque o mesmo serviço pode atender múltiplas requisições em paralelo.
Dictionary e List em singleton — são clássicos exemplos de código que funciona em testes e falha em produção sob carga.
GIL em Python — ajuda em algumas situações, mas não substitui sincronização de estado compartilhado nem elimina race conditions.
Python free-threaded — reforça ainda mais que sincronização explícita continua sendo responsabilidade do desenvolvedor.
Teste de concorrência — N threads × K iterações com invariant check é o jeito mais confiável de determinar se o serviço realmente aguenta carga.

Referências

Threading in .NET — Microsoft Learn
System.Threading.Lock — .NET API
ConcurrentDictionary<TKey,TValue> — .NET API
PEP 703 — Making the Global Interpreter Lock Optional in CPython
Python threading — documentos oficiais
Python queue — documentos oficiais
ASP.NET Core dependency injection lifetimes 📬

👉 Artigo completo com todos os exemplos de código: Thread-safety em .NET 10 e Python: GIL e race conditions

Apache Airflow com .NET 10: dispare e monitore DAGs

Lincoln Zocateli — Sat, 25 Jul 2026 09:01:20 +0000

Introdução

Integrar Apache Airflow com .NET 10 não significa portar o orquestrador, reescrever DAGs em C# ou executar o runtime Python dentro da aplicação. A solução correta é manter o Airflow responsável por criar, agendar e monitorar workflows e fazer o serviço .NET consumir sua API REST pública. O serviço autentica, dispara um DAG Run com parâmetros, guarda o identificador retornado e consulta o estado até receber success, failed ou canceled. Essa separação preserva o papel de cada tecnologia e cria um contrato claro entre a aplicação transacional e a plataforma de dados.

Neste guia, eu vou implementar esse fluxo de ponta a ponta usando .NET 10, HttpClient, autenticação JWT e a API /api/v2 do Apache Airflow 3.3. O exemplo não se limita a um POST: ele gera um dag_run_id rastreável, serializa conf corretamente, reutiliza o token até perto da expiração, renova a credencial após uma resposta 401, aplica timeout ao monitoramento e propaga cancelamento. Também vou expor a integração por uma Minimal API, para que outro sistema possa iniciar o processo sem conhecer os detalhes do Airflow.

O nome atual da plataforma da Microsoft é .NET 10, e não “.NET Core 10”. A marca “.NET Core” foi usada até a versão 3.1; desde o .NET 5, o produto unificado passou a se chamar apenas .NET. Essa diferença não altera o código, mas evita confusão ao procurar documentação, imagens de container e pacotes compatíveis.

O cenário prático será um serviço de pedidos que solicita a execução do DAG etl_vendas. A configuração enviada contém a data de referência e um identificador de correlação. O Airflow continua executando tarefas Python, SQL, containers ou jobs distribuídos; o C# apenas controla o ciclo de vida da execução pela fronteira HTTP.

ℹ️ Informação: no Airflow 3, os endpoints públicos estáveis ficam sob /api/v2. Rotas internas de UI não são um contrato de integração e podem mudar conforme o frontend.

Pré-requisitos

Para acompanhar o exemplo, você precisa do .NET 10 SDK, do Docker Compose 2.14 ou superior e de pelo menos 4 GB de memória disponíveis para o Docker. O repositório inclui uma instância do Apache Airflow 3.3.0, PostgreSQL 16 e o DAG etl_vendas, portanto não é necessário instalar Airflow ou Python diretamente na máquina. A autenticação usa JWT obtido por POST /auth/token.

O exemplo foi escrito para a API pública v2. Se sua empresa ainda usa Airflow 2, a API estável normalmente aparece sob /api/v1, com contratos e mecanismos de autenticação que podem variar. Não troque apenas o número na URL: valide o OpenAPI da versão instalada, porque nomes de campos, estados e recursos disponíveis não são necessariamente idênticos.

Você também deve confirmar estes pontos antes de codificar:

O serviço .NET consegue resolver o DNS e abrir uma conexão TLS com o endpoint do Airflow.
O usuário técnico possui somente as permissões necessárias para disparar e ler o DAG escolhido.
O proxy reverso aceita os verbos POST e GET, o header Authorization e o tamanho máximo previsto para conf.
O DAG é idempotente ou recebe uma chave de negócio que impeça processamento duplicado.
O timeout do serviço é compatível com a duração esperada do workflow. Em produção, armazene a senha em um cofre, secret de container ou variável de ambiente. A chave hierárquica do .NET será Airflow__Senha; os dois sublinhados representam o separador de configuração. Nunca publique a credencial em appsettings.json, imagem Docker, log ou telemetria.

Subindo o Airflow 3 com dados persistentes no Docker

O exemplo usa uma stack menor que o quick-start oficial porque o objetivo é testar a integração REST, não demonstrar o CeleryExecutor. O LocalExecutor executa tarefas no mesmo ambiente do scheduler e elimina Redis e workers Celery. Permanecem os componentes necessários do Airflow 3: API server, scheduler, DAG processor, triggerer, inicializador e PostgreSQL.

Todos os dados relevantes usam bind mounts, isto é, diretórios explícitos do repositório montados nos containers. DAGs ficam em dags/, logs em logs/, configuração em config/, plugins em plugins/ e o cluster PostgreSQL em data/postgres/. Os diretórios gerados estão no .gitignore; apenas o DAG, o Compose e arquivos .gitkeep são versionados. Executar docker compose down pode destruir containers e rede sem apagar banco, usuários, histórico ou logs.

No Airflow 3, o executor também precisa conversar com a Execution API. Por isso, todos os serviços recebem AIRFLOW__CORE__EXECUTION_API_SERVER_URL=http://airflow-api-server:8080/execution/. Usar localhost nessa variável faria o scheduler procurar a API dentro do próprio container e as tasks falhariam com Connection refused, mesmo com o healthcheck externo saudável.

O recorte abaixo mostra os mounts. O arquivo completo também define healthchecks e dependências de inicialização:

services:
  postgres:
    image: postgres:16-alpine
    volumes:
      # Metadados e histórico sobrevivem à recriação do container.
      - ./data/postgres:/var/lib/postgresql/data

  airflow-api-server:
    image: apache/airflow:3.3.0
    command: api-server
    ports:
      # A porta 8081 evita conflito com outros serviços locais.
      - "8081:8080"
    volumes:
      - ./dags:/opt/airflow/dags
      - ./logs:/opt/airflow/logs
      - ./config:/opt/airflow/config
      - ./plugins:/opt/airflow/plugins

📂 Código Fonte: A stack, o DAG e as instruções completas estão disponíveis no repositório de exemplos:
BlogSamples/Orchestration/Airflow/

Inicialize o banco e crie o usuário na primeira execução. O comando up -d --wait só retorna quando os healthchecks terminarem:

# Execute a partir da pasta Orchestration/Airflow do exemplo.
Copy-Item .env.example .env
docker compose up airflow-init
docker compose up -d --wait

A interface web e a API pública estarão em http://localhost:8081. As credenciais padrão do exemplo são usuário dotnet-service e senha airflow; altere-as no .env em qualquer ambiente compartilhado. Para configurar o cliente .NET sem gravar senha em arquivo, use uma variável de ambiente:

# Os dois sublinhados representam Airflow:Senha na configuração .NET.
$env:Airflow__Senha = "airflow"
dotnet run --project src/BlogSamples

⚠️ Atenção: esta stack é destinada a desenvolvimento e demonstração. Credenciais padrão, LocalExecutor e API HTTP sem TLS não atendem requisitos de produção.

Como o Apache Airflow divide as responsabilidades

O Apache Airflow representa workflows por DAGs, grafos acíclicos direcionados que descrevem tarefas e dependências. Um DAG é a definição; um DAG Run é uma execução concreta dessa definição em determinado contexto. Vários DAG Runs do mesmo DAG podem coexistir, e cada um possui seu próprio dag_run_id, estado, datas e configuração. Essa distinção é essencial para o cliente .NET não confundir o pipeline com uma de suas execuções.

O scheduler avalia agendas e dependências. O executor encaminha tarefas para o ambiente de execução, que pode usar processos locais, Celery ou Kubernetes, conforme a implantação. Workers executam as tarefas. A interface web apresenta grids, grafos, logs e histórico. A API pública oferece uma fronteira programática sobre esses recursos. Portanto, o serviço .NET não precisa conhecer filas internas, banco de metadados nem detalhes dos workers.

Essa arquitetura funciona bem em pipelines de ETL, treinamento de modelos, geração de relatórios e automações com muitas etapas. Um checkout em .NET pode publicar um evento e retornar rapidamente, enquanto o Airflow coordena um processamento posterior. Em outro cenário, uma API administrativa pode disparar o DAG e aguardar o resultado porque o operador precisa de confirmação síncrona. A escolha entre esperar e desacoplar depende da duração e do impacto no usuário, não da capacidade técnica da API.

O estado do DAG Run é derivado das tarefas folha. Segundo a documentação oficial, os estados finais normais de um DAG Run são success e failed; o endpoint experimental de espera também considera canceled. Estados como queued e running indicam que a execução ainda pode mudar. Um cliente não deve interpretar HTTP 200 no disparo como conclusão bem-sucedida: essa resposta confirma a criação do DAG Run, não o resultado do workflow.

API REST v2, JWT e contrato de autenticação

O fluxo de autenticação documentado para o Airflow 3 começa em POST /auth/token. O corpo contém username e password, e a resposta contém access_token. As chamadas seguintes enviam Authorization: Bearer <token>. Como o endpoint de token é fornecido pelo auth manager, uma implantação corporativa pode usar outro mecanismo ou acrescentar requisitos. Consulte a configuração do ambiente antes de assumir que credenciais locais estarão habilitadas.

Depois da autenticação, o disparo usa POST /api/v2/dags/{dag_id}/dagRuns. No Airflow 3.3, o corpo exige dag_run_id, conf e logical_date; envie logical_date: null quando quiser que o servidor determine a data lógica. A configuração é um objeto JSON entregue ao contexto do DAG. A consulta usa GET /api/v2/dags/{dag_id}/dagRuns/{dag_run_id}. O identificador precisa ser escapado na URL, mesmo quando os nomes atuais parecem conter apenas letras e sublinhados.

No C#, eu mapeio os nomes em snake case explicitamente. Isso é importante porque JsonSerializerDefaults.Web produz camel case, não dag_run_id. O trecho abaixo mostra os contratos principais:

public sealed record DispararDagRequest(
    [property: JsonPropertyName("dag_run_id")] string DagRunId,
    [property: JsonPropertyName("conf")]
  IReadOnlyDictionary<string, object?> Configuracao,
  // O campo é obrigatório na API 3.3, mas pode ser nulo.
  [property: JsonPropertyName("logical_date")]
  DateTimeOffset? DataLogica = null);

public sealed record DagRunResponse(
    [property: JsonPropertyName("dag_run_id")] string DagRunId,
    [property: JsonPropertyName("dag_id")] string DagId,
    [property: JsonPropertyName("state")] string Estado,
    [property: JsonPropertyName("start_date")] DateTimeOffset? Inicio,
    [property: JsonPropertyName("end_date")] DateTimeOffset? Fim);

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/Orchestration/Airflow/

Um cliente robusto não solicita um novo token em cada polling. Ele lê o claim exp do JWT e reutiliza a credencial enquanto houver margem de validade. Um SemaphoreSlim impede que várias requisições concorrentes renovem o token ao mesmo tempo. Se o servidor responder 401 ou 403 após uma rotação da chave JWT, o cliente invalida o cache, autentica novamente e repete a chamada uma única vez. Uma permissão realmente insuficiente continuará retornando 403 na segunda tentativa. Repetições ilimitadas esconderiam credenciais incorretas e poderiam pressionar o endpoint de autenticação.

Identidade da execução, parâmetros e idempotência

O dag_run_id é a ponte de rastreabilidade entre as duas plataformas. No exemplo, ele segue o formato dotnet__<timestamp UTC>__<guid>. O timestamp ajuda durante uma investigação manual, enquanto o GUID evita colisões entre instâncias do serviço. Eu registro esse identificador junto ao dag_id, ao estado e ao correlation ID da requisição de origem. Assim, uma busca no log do .NET leva ao DAG Run correspondente na interface do Airflow.

Para processos de negócio, aleatoriedade não basta. Imagine que o cliente envie o mesmo pedido duas vezes após um timeout de rede. O primeiro POST pode ter criado a execução, mesmo que a resposta não tenha chegado. Repetir automaticamente o disparo com outro GUID produziria dois workflows. Uma estratégia mais forte deriva o identificador de uma chave idempotente, como pedido__8f32..., e trata 409 Conflict consultando a execução já existente. Outra alternativa persiste uma outbox antes da integração e deixa um worker controlar as tentativas.

O objeto conf deve conter referências pequenas e imutáveis, não arquivos nem grandes lotes de registros. Envie pedido_id, data_referencia, URI de um objeto ou correlation ID. O DAG usa essas referências para buscar os dados na origem autorizada. A própria documentação alerta que payloads muito grandes podem afetar a estabilidade do webserver e recomenda limites no proxy.

⚠️ Atenção: não aplique uma política genérica de retry ao POST de disparo sem uma chave idempotente. Falha de transporte não prova que o Airflow deixou de criar o DAG Run.

Também evite colocar segredos em conf. A configuração aparece em metadados do DAG Run e pode ficar visível para operadores autorizados. Passe apenas identificadores; recupere credenciais em um secrets backend do Airflow, como HashiCorp Vault, AWS Secrets Manager ou outro provider compatível com sua infraestrutura.

Arquitetura do disparo e monitoramento

O fluxo síncrono possui três fases. Primeiro, o serviço .NET obtém ou reutiliza um JWT. Depois, cria o DAG Run e recebe o estado inicial, geralmente queued. Por fim, consulta a mesma execução em intervalos controlados até um estado terminal. O cancelamento da requisição e um timeout próprio precisam interromper o laço para não manter conexões e tarefas indefinidamente.

Eu prefiro polling explícito com GET no exemplo principal porque os endpoints usados são estáveis. O Airflow 3 oferece também GET /api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/wait, que transmite atualizações em NDJSON, mas a documentação o classifica como experimental. Ele pode ser útil em automações controladas, porém não é a melhor fundação para um contrato de longa duração sem encapsulamento e testes de compatibilidade.

O intervalo de polling deve equilibrar latência e carga. Consultar a cada 100 milissegundos não acelera o DAG e multiplica requisições ao webserver. Para workflows de minutos, cinco ou dez segundos costumam ser um ponto inicial razoável. Adicione jitter quando muitas instâncias puderem iniciar juntas, evitando que todas consultem no mesmo instante. Para milhares de workflows simultâneos, prefira um worker central, callbacks ou eventos em vez de manter uma requisição HTTP por execução.

O timeout do HttpClient limita uma chamada individual; ele não limita todo o monitoramento. Por isso, o exemplo usa um CancellationTokenSource vinculado ao token recebido e chama CancelAfter com o tempo máximo do workflow. Essa distinção evita um erro comum: configurar 30 segundos no cliente HTTP e acreditar que o laço inteiro terminará nesse prazo.

Exemplo Prático

O núcleo do exemplo é um cliente tipado registrado com IHttpClientFactory. O BaseAddress vem de configuração, e cada chamada cria seu próprio HttpRequestMessage. O header Bearer fica na mensagem, não em DefaultRequestHeaders, o que evita disputa quando requisições concorrentes usam tokens diferentes durante uma renovação.

O método abaixo cria um identificador, monta conf e dispara a execução:

public async Task<DagRunResponse> DispararAsync(
    string dagId,
    IReadOnlyDictionary<string, object?>? configuracao = null,
    CancellationToken cancellationToken = default)
{
    // O ID único permite correlacionar logs do .NET e do Airflow.
    var dagRunId = $"dotnet__{DateTimeOffset.UtcNow:yyyyMMddTHHmmssfff}__{Guid.NewGuid():N}";
    var payload = new DispararDagRequest(
        dagRunId,
        configuracao ?? new Dictionary<string, object?>());

    var caminho = $"api/v2/dags/{Uri.EscapeDataString(dagId)}/dagRuns";
    return await EnviarAutenticadoAsync<DagRunResponse>(
        () => new HttpRequestMessage(HttpMethod.Post, caminho)
        {
            Content = JsonContent.Create(payload)
        },
        cancellationToken);
}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/Orchestration/Airflow/

O monitor usa a resposta do disparo e só consulta novamente enquanto o estado não for terminal:

public async Task<DagRunResponse> DispararEMonitorarAsync(
    string dagId,
    IReadOnlyDictionary<string, object?>? configuracao,
    CancellationToken cancellationToken)
{
    var execucao = await DispararAsync(dagId, configuracao, cancellationToken);
    using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
    timeout.CancelAfter(TimeSpan.FromMinutes(10));

    while (!EstadosFinais.Contains(execucao.Estado))
    {
        // Polling moderado evita sobrecarregar o webserver do Airflow.
        await Task.Delay(TimeSpan.FromSeconds(5), timeout.Token);
        execucao = await ObterExecucaoAsync(dagId, execucao.DagRunId, timeout.Token);
    }

    return execucao;
}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/Orchestration/Airflow/

A aplicação registra o cliente e chama uma Minimal API com o seguinte corpo:

{
  // Parâmetros pequenos e não confidenciais entregues ao DAG.
  "configuracao": {
    "data_referencia": "2026-07-21",
    "correlation_id": "pedido-8f328ba9"
  },
  // O endpoint permanece aberto até success, failed ou canceled.
  "aguardarConclusao": true
}

# Dispara o DAG e aguarda um estado terminal.
curl -X POST "https://localhost:7063/api/airflow/dags/etl_vendas/runs" \
  -H "Content-Type: application/json" \
  -d '{"configuracao":{"data_referencia":"2026-07-21","correlation_id":"pedido-8f328ba9"},"aguardarConclusao":true}'

Uma resposta concluída preserva os nomes JSON do contrato do Airflow, facilitando a correlação com sua API e interface web:

{
  // Use este ID para correlacionar a execução nas duas plataformas.
  "dag_run_id": "dotnet__20260721T130000000__8f328ba9...",
  "dag_id": "etl_vendas",
  "state": "success",
  "start_date": "2026-07-21T13:00:01Z",
  "end_date": "2026-07-21T13:02:44Z"
}

Falhas, observabilidade e segurança em produção

Integração robusta exige separar falhas de autenticação, autorização, validação, disponibilidade e execução. Um 401 normalmente pede renovação do token; um 403 indica que a identidade não possui permissão; um 404 pode significar DAG ou DAG Run incorreto; um 409 pode indicar conflito de identidade; 429 e respostas 5xx sugerem pressão ou indisponibilidade temporária. O cliente deve registrar status, endpoint lógico e correlation ID, mas nunca token, senha ou conteúdo sensível de conf.

O exemplo inclui uma repetição única após 401. Para GET, retries exponenciais com jitter são seguros porque a operação não altera estado. Para POST, a política depende de idempotência. Uma biblioteca de resiliência pode automatizar timeout, circuit breaker e retries, mas a regra de negócio ainda precisa decidir se repetir o disparo é válido. Nenhuma biblioteca consegue inferir isso apenas pelo verbo HTTP.

Crie métricas para tempo de autenticação, latência de disparo, duração total, quantidade de DAG Runs por estado e timeouts. Registre dag_id, dag_run_id e correlation ID como propriedades estruturadas. Trace a chamada HTTP com OpenTelemetry e propague um identificador no conf para que tarefas do DAG também o incluam nos logs. Dessa forma, uma investigação percorre API, Airflow e sistemas de dados sem depender de busca textual frágil.

Na segurança, use HTTPS com validação normal de certificado, conta técnica de menor privilégio e rotação de credenciais. Não desabilite validação TLS em produção. Restrinja a API do Airflow por rede, firewall ou gateway; a existência de JWT não torna desejável expor o webserver publicamente. Se o serviço roda em Kubernetes, injete a senha por Secret ou integre um cofre. Em ambientes com auth manager corporativo, prefira identidades de workload e tokens de curta duração quando houver suporte.

Quando usar API, mensageria ou execução em containers

A API REST é adequada quando o serviço precisa iniciar um workflow específico, fornecer parâmetros e acompanhar uma execução identificável. Ela oferece feedback imediato, contrato HTTP claro e boa rastreabilidade. O custo é o acoplamento temporal: Airflow precisa estar acessível no disparo, e esperar a conclusão prende recursos do chamador. Para operações administrativas e baixo volume, esse compromisso costuma ser aceitável.

Mensageria é melhor quando o produtor deve continuar funcionando durante indisponibilidades do orquestrador ou quando o volume é alto. O .NET publica em Azure Service Bus, RabbitMQ ou Kafka, e um componente consumidor transforma mensagens em DAG Runs ou ativa pipelines orientados a eventos. A fila oferece buffering e entrega controlada, mas introduz semântica de duplicidade, dead-letter, ordenação e observabilidade adicional. Airflow não deve substituir um broker em um fluxo transacional de baixa latência.

Containers e Kubernetes resolvem outro problema: onde executar a carga. Um DAG pode iniciar um job que usa a mesma imagem de uma ferramenta .NET, ou chamar um serviço C# por HTTP. Isso não exige que o Airflow entenda a implementação interna. A imagem deve expor uma operação determinística, retornar exit code correto e gravar saída em armazenamento durável. Logs locais do pod não são uma integração de dados.

Em muitos sistemas, as três estratégias coexistem. A API .NET grava uma transação e uma outbox; um worker publica um evento; o Airflow inicia um DAG; uma tarefa Kubernetes executa um utilitário .NET. O desenho deve seguir requisitos de consistência, latência e recuperação. Escolher API, fila ou container apenas porque a equipe já conhece a tecnologia tende a esconder o verdadeiro contrato operacional.

Dicas e Boas Práticas

Use uma identidade técnica de menor privilégio. Autorize somente os DAGs e operações exigidos pelo serviço. Separe a conta da integração das contas humanas para facilitar auditoria e rotação.
Torne o disparo idempotente. Derive dag_run_id de uma chave de negócio ou persista a associação antes da chamada. Trate respostas ambíguas consultando a execução existente, em vez de criar outra silenciosamente.
Mantenha conf pequeno e sem segredos. Envie IDs, datas e URIs para dados duráveis. Payloads volumosos pressionam o webserver e informações sensíveis podem aparecer nos metadados da execução.
Diferencie timeout de chamada e timeout de workflow. Use um limite curto para cada requisição HTTP e outro para o ciclo completo de polling. Propague CancellationToken em autenticação, disparo, espera e consulta.
Aplique retry conforme a semântica. Repetir GET após falha transitória é previsível; repetir POST pode duplicar processamento. Combine backoff exponencial, jitter e circuit breaker somente depois de definir idempotência.
Registre identificadores, não credenciais. Inclua dag_id, dag_run_id, correlation ID, estado e duração em logs estruturados. Nunca registre JWT, senha ou configuração sensível.
Teste contratos sem depender do Airflow real. Um HttpMessageHandler falso valida URLs, headers, JSON, renovação após 401 e transições de estado. Mantenha também um teste de integração contra uma versão suportada antes do deploy.

Resumo Objetivo

Apache Airflow 3 — expõe uma API pública estável sob /api/v2; endpoints internos da interface web não devem ser usados como contrato de integração.
.NET 10 — integra-se ao Airflow por HTTP e não executa DAGs em C#; o Airflow continua responsável por agendamento, dependências, workers e estado.
Autenticação JWT — a documentação padrão usa POST /auth/token e envia o token em Authorization: Bearer; o cliente renova a credencial uma vez após 401 ou 403 causado por token inválido.
DAG Run — é uma execução concreta de um DAG e deve ser rastreada por dag_id e dag_run_id; HTTP 200 no disparo não significa que o workflow terminou com sucesso.
Monitoramento — consulta GET /api/v2/dags/{dag_id}/dagRuns/{dag_run_id} até success, failed ou canceled, com intervalo moderado, timeout total e cancelamento propagado.
Idempotência — retries automáticos de POST podem duplicar workflows; uma chave de negócio no dag_run_id permite reconhecer uma execução já criada.
Configuração do DAG — no Airflow 3.3, o payload inclui dag_run_id, conf e logical_date; o último pode ser null, enquanto conf deve carregar referências pequenas e não confidenciais.

Referências

Airflow Public REST API Reference — contrato OpenAPI dos endpoints públicos estáveis sob /api/v2.
Airflow Public API Authentication — autenticação JWT, endpoint de token e recomendações para payloads e CORS.
Airflow DAG Runs — estados, data intervals, disparos externos e endpoint experimental de espera.
Airflow Best Practices — práticas oficiais para escrever e operar DAGs confiáveis.
Use the IHttpClientFactory — documentação do .NET para clientes HTTP tipados, handlers e gerenciamento de conexões.
Options pattern in .NET — configuração tipada, validação e separação de credenciais por ambiente.
Código completo: BlogSamples/Orchestration/Airflow — implementação .NET 10 e contratos usados neste artigo. 📬

👉 Artigo completo com todos os exemplos de código: Apache Airflow com .NET 10: dispare e monitore DAGs

Git History para Debug e Auditoria em Escala

Lincoln Zocateli — Wed, 22 Jul 2026 22:31:37 +0000

Introdução

Usar Git history para debug e auditoria significa tratar o repositório como um grafo consultável de evidências, e não como uma lista de mensagens ordenadas por data. Para depurar uma regressão, o histórico permite localizar quando um comportamento mudou, quais revisões carregaram a mudança até a branch principal e qual intervalo mínimo precisa ser testado. Para auditar, ele fornece autoria declarada, assinatura, trailers, paths alterados, volume de churn e relações de ancestralidade que podem ser correlacionados com revisão de código, CI/CD e logs da plataforma.

A resposta prática é combinar consultas com semânticas diferentes. git log -S e -G encontram alterações; git blame explica a origem das linhas sobreviventes; git bisect automatiza a busca da primeira revisão ruim; git reflog recupera referências locais perdidas; e a topologia de merges mostra como uma mudança chegou à integração. Nenhum comando isolado reconstrói todo o incidente. O valor aparece quando cada ferramenta responde a uma pergunta precisa e suas limitações são registradas.

Imagine um incidente fictício em um monorepo corporativo: a regra CanApproveInvoice deixou de exigir a permissão finance:approve. O método foi refatorado, movido de AuthorizationService.cs para InvoicePolicy.cs, passou por uma branch de manutenção e chegou à main dentro de um merge com dezenas de commits. O alerta surgiu três semanas depois, quando a data do autor já não representava a ordem em que a mudança entrou em produção.

Eu vou investigar esse caso de forma interativa e depois transformar a investigação em um analisador para alto volume. O exemplo completo usa .NET 10, um único processo git log, parsing incremental delimitado por NUL, Channel<T> limitado, consumidores paralelos, cancelamento e JSON determinístico. A fixture processa 500 mil registros commit-arquivo e compara execução sequencial, Parallel.ForEachAsync e pipeline produtor-consumidor sem prometer que paralelismo sempre vence.

Pré-requisitos

Você precisa de um Git recente, do SDK .NET 10 e de PowerShell ou Bash. Os comandos pressupõem familiaridade com processos, programação assíncrona e a ideia de grafo direcionado acíclico: um commit aponta para um ou mais pais, nunca para um descendente.

Use um clone com histórico completo. Um shallow clone criado com --depth não contém todos os ancestrais; um partial clone pode exigir objetos remotos durante a análise. Antes de concluir que uma revisão não existe, verifique git rev-parse --is-shallow-repository e documente os filtros do clone.

Também é importante separar duas atividades. A investigação interativa aceita comandos especializados e inspeção humana. A auditoria recorrente precisa de formato estável para máquina, limites de memória, registro de parâmetros e falha explícita quando o Git não entrega uma saída completa.

Git History é um Grafo, Não uma Linha do Tempo

Um commit contém uma árvore, metadados e referências para seus pais. Uma ref, como refs/heads/main, aponta para um commit; HEAD aponta para uma ref ou diretamente para um commit no estado detached. Um merge normalmente possui dois ou mais pais. Portanto, duas revisões com datas próximas podem pertencer a linhas de desenvolvimento independentes.

A data do autor registra quando o trabalho foi originalmente criado. A data do committer registra quando aquele objeto foi gravado, inclusive após rebase ou aplicação com cherry-pick. Ordenar por uma dessas datas ajuda na leitura humana, mas não prova causalidade. Para isso, consulte ancestralidade e pais.

Consulta	Semântica	Uso na investigação
A..B	commits alcançáveis por B, excluindo os alcançáveis por A	mudanças presentes em uma branch e ausentes na outra
A...B	diferença simétrica entre os dois lados	trabalho exclusivo de cada branch desde o merge-base
--first-parent	segue apenas o primeiro pai de merges	visão das integrações na branch principal
--ancestry-path A..B	mantém commits que estão no caminho ancestral entre os extremos	provar por qual cadeia uma mudança chegou a uma release
--topo-order	evita mostrar um pai antes de seus descendentes	leitura coerente do grafo sem depender só da data

No incidente, começo comparando a branch de manutenção e a release:

git log --graph --decorate --oneline --topo-order release/2026.07...main
git log --first-parent --merges --oneline release/2026.07..main
git log --ancestry-path commit-suspeito..release/2026.07 --oneline

--first-parent responde “qual integração apareceu na main?”, não “qual commit interno criou a linha?”. Essa distinção evita culpar o merge automático quando a alteração causal nasceu dias antes em outra branch.

Pickaxe, Blame e Histórico de Funções Localizam a Mudança

O Git chama de Pickaxe os filtros que procuram alterações no conteúdo dos patches. -S<string> seleciona commits nos quais a quantidade de ocorrências da string mudou. Se finance:approve foi removida, este é o primeiro corte:

git log --all -S'finance:approve' --oneline --decorate -- \
  'src/**/*.cs'

git show --stat --patch <commit-encontrado>

-G<regex> tem outra semântica: seleciona commits cujo patch contém uma linha adicionada ou removida que corresponda à expressão regular. Ele é útil quando a contagem líquida da string não muda, por exemplo, quando uma chamada é removida de um ponto e adicionada em outro no mesmo commit.

git log --all -G'CanApproveInvoice|finance:approve' \
  --pickaxe-regex --oneline -- '*.cs'

git log -L '/CanApproveInvoice/',+45:src/Auth/InvoicePolicy.cs

git log -L acompanha a evolução de um intervalo ou função em um arquivo. Ele funciona melhor depois que o path e a assinatura foram reduzidos. Para entender as linhas atuais, uso git blame -w -M -C: -w ignora whitespace, -M detecta movimento dentro do arquivo e -C procura cópias ou movimentos vindos de outros arquivos.

💡 Dica: -S encontra mudanças na quantidade de uma string, enquanto -G encontra linhas de patch por regex. Uma movimentação que remove e adiciona a mesma string pode escapar de -S e aparecer em -G.

Commits de formatação podem ser excluídos da atribuição com um arquivo versionado e git config blame.ignoreRevsFile .git-blame-ignore-revs. Isso melhora o sinal, mas o arquivo deve conter apenas revisões mecânicas revisadas. git blame não mostra linhas removidas; para elas, volte ao Pickaxe, ao diff ou ao log do arquivo.

Git Bisect Automatiza a Caça à Regressão

Depois de encontrar um estado bom e um estado ruim, git bisect escolhe revisões intermediárias para reduzir o espaço de busca. Em um histórico aproximadamente linear com 1.024 candidatos, a busca binária exige cerca de dez decisões, em vez de executar até 1.024 testes sequencialmente.

Crio um teste automatizado que falha quando um usuário sem finance:approve consegue aprovar e executo:

git bisect start
git bisect bad main
git bisect good release/2026.06
git bisect run dotnet test tests/Auth.Tests/Auth.Tests.csproj \
  --filter CanApproveInvoiceRequiresPermission
git bisect reset

O programa chamado por git bisect run deve retornar 0 para bom, 1 a 127 para ruim, exceto 125. O código 125 significa “não testável” e instrui o Git a pular aquela revisão. Isso é necessário quando commits antigos dependem de SDKs removidos, fixtures incompatíveis ou arquivos ausentes.

#!/usr/bin/env bash
dotnet build tests/Auth.Tests/Auth.Tests.csproj --no-restore || exit 125
dotnet test tests/Auth.Tests/Auth.Tests.csproj --no-build \
  --filter CanApproveInvoiceRequiresPermission

📝 Exemplo: um erro de compilação histórico não prova que a regressão já existia. Retornar 125 preserva a semântica da bisseção e evita classificar como ruim um commit que apenas não pode ser testado no ambiente atual.

Quando o objetivo é descobrir o merge que introduziu a falha na branch principal, git bisect start --first-parent pode produzir uma resposta operacional melhor. Depois, uma segunda bisseção dentro da branch integrada encontra o commit causal. O resultado depende do predicado ser determinístico; teste instável produz fronteiras falsas.

Reflog e Topologia de Merges Reconstruem o Incidente

Se alguém executou reset, rebase ou mudou uma branch, git reflog registra atualizações locais das refs. git reflog show HEAD e git show HEAD@{3} podem recuperar o ponto anterior, enquanto git branch recuperacao HEAD@{3} cria uma ref antes que o objeto fique inalcançável.

Reflog não é histórico compartilhado. Ele é local, tem políticas de expiração e pode não existir no clone usado pela auditoria. Um force push também pode remover commits da visão central sem removê-los imediatamente de todos os clones. Por isso, reflog é excelente para recuperação e investigação de estação de trabalho, mas fraco como evidência permanente de compliance.

Para entender merges, a simplificação padrão de git log pode omitir commits que não alteram o resultado final de um path. Três opções ajudam:

--full-history percorre todos os pais relevantes e evita simplificação excessiva;
--show-pulls inclui merges que trouxeram para o primeiro pai uma alteração existente em outro pai;
--simplify-merges remove merges redundantes depois de reescrever a topologia. --simplify-merges pode precisar percorrer todo o histórico antes de emitir resultados. Em repositórios grandes, comece por intervalo, path ou --first-parent; amplie apenas quando a pergunta exigir. Para o incidente, --show-pulls --ancestry-path identifica o merge que levou a política alterada até a release sem confundir integração com autoria.

⚠️ Atenção: reflog local, commits não assinados e histórico regravável não constituem sozinhos uma trilha imutável. Preserve logs da plataforma, eventos de pull request, execuções de CI/CD e políticas de retenção fora do Git.

Extração Segura de Centenas de Milhares de Registros

Executar um processo Git por commit ou arquivo multiplica o custo de inicialização e abre espaço para inconsistência entre consultas. O analisador inicia um único git log --numstat -z com formato customizado. Cada campo de commit termina em NUL (%x00), e --numstat -z preserva paths sem depender de escaping por linha.

private const string Format =
    "GIT-HISTORY-COMMIT%x00%H%x00%P%x00%aN%x00%aE%x00%aI%x00" +
    "%cN%x00%cE%x00%cI%x00%G?%x00%s%x00" +
    "%(trailers:only,unfold=true)%x00";

var arguments = new[]
{
    "-C", repositoryPath, "log", "--topo-order", "--find-renames",
    "--numstat", "-z", $"--format={Format}", revisionRange, "--"
};

foreach (var argument in arguments)
{
    startInfo.ArgumentList.Add(argument);
}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/AsyncParallel/GitHistoryAnalysis/

O parser consome StandardOutput.BaseStream incrementalmente. Ele não usa ReadToEndAsync para stdout e não materializa todos os registros. stderr é drenado em paralelo para evitar deadlock, e o exit code é validado antes de aceitar o relatório. No cancelamento, a árvore do processo é encerrada.

O object ID é texto opaco. Não presumo SHA-1 com 40 caracteres, pois repositórios podem usar SHA-256. Renames em --numstat -z têm um registro com path vazio seguido pelos paths antigo e novo em tokens separados. Arquivos binários usam - para adições e exclusões. Paths podem conter espaço, tab ou quebra de linha; somente NUL não é permitido pelo modelo de paths do Git.

Channel Limitado Aplica Backpressure ao Pipeline .NET 10

O produtor precisa ler e interpretar a sequência do Git em ordem. As análises independentes e CPU-bound podem ser distribuídas. Um Channel<FileChangeRecord> limitado separa essas responsabilidades sem permitir que um produtor rápido consuma memória indefinidamente.

var channel = Channel.CreateBounded<FileChangeRecord>(
    new BoundedChannelOptions(options.ChannelCapacity)
    {
        FullMode = BoundedChannelFullMode.Wait,
        SingleWriter = true,
        SingleReader = options.EffectiveParallelism == 1
    });

var producer = ProduceAsync(records, channel.Writer, cancellationToken);
var workers = Enumerable.Range(0, options.EffectiveParallelism)
    .Select(_ => ConsumeAsync(channel.Reader, cancellationToken))
    .ToArray();

await Task.WhenAll(workers.Cast<Task>().Append(producer));

ℹ️ Informação: BoundedChannelFullMode.Wait suspende a escrita quando o canal atinge a capacidade. Esse backpressure limita itens em trânsito e não descarta evidências, ao contrário dos modos DropNewest, DropOldest e DropWrite.

Cada worker mantém contadores, dicionários e achados locais. No final, o agregador combina esses estados e ordena autores, diretórios e achados com comparadores ordinais. Essa abordagem reduz contenção em coleções concorrentes e garante saída determinística mesmo quando a distribuição entre workers muda.

O mesmo CancellationToken alcança processo, parser, produtor e consumidores. Se uma regra lança exceção, uma fonte vinculada cancela o produtor; o writer é concluído com a falha e nenhum worker fica esperando indefinidamente. Testes cobrem canal com capacidade 1, conclusão com exceção, cancelamento do fluxo e equivalência entre um e quatro consumidores.

Regras de Auditoria e Detecção de Hotspots

O analisador demonstra regras independentes para assinatura, trailers, paths sensíveis e churn. %G? retorna o estado da assinatura: G indica assinatura válida de chave confiável e U, assinatura válida de chave com confiança desconhecida. A política da organização deve decidir quais estados aceita; assinatura válida autentica uma chave, não garante que a mudança foi correta.

A normalização de identidades deve ocorrer com .mailmap. Ela consolida variações de nome e e-mail nas opções que respeitam mailmap, como %aN e %aE, e reduz falsos múltiplos autores. Ainda assim, autor e committer são campos declarados; associe-os a assinaturas verificadas e identidade da plataforma quando a exigência for forte.

Trailers como Reviewed-by: ou identificador de ticket podem sinalizar aderência ao processo. Eles não provam revisão por si mesmos, porque qualquer autor pode escrever um trailer. A evidência robusta correlaciona o trailer com aprovação registrada no pull request e com a identidade autenticada do revisor.

Paths sensíveis incluem workflows, permissões, manifests, configurações de produção e regras de autorização. Churn elevado ou muitos arquivos alterados ajudam a priorizar revisão, mas não significam fraude. Outros indicadores úteis são diretórios com alta frequência de mudança, correlação entre mudanças e falhas, autoria concentrada em componentes críticos e commits fora da janela ou do --ancestry-path esperado para uma release.

Performance: Sequencial, Parallel.ForEachAsync e Channel

A fixture determinística gera 500 mil registros commit-arquivo distribuídos entre 32 autores, 64 componentes e 2.048 nomes de arquivo. As três estratégias executam a mesma função CPU-bound e produzem o mesmo checksum. O teste registra tempo, throughput, bytes alocados pelo runtime e PeakWorkingSet64 aproximado do processo.

Em uma execução local de Debug com .NET 10.0.8, os resultados foram:

Estratégia	Tempo	Throughput	Alocações	Pico aproximado
Sequencial	480 ms	1.040.887 registros/s	238,6 MiB	70,8 MiB
Parallel.ForEachAsync	759 ms	658.332 registros/s	264,1 MiB	72,2 MiB
Channel limitado	1.041 ms	480.327 registros/s	364,8 MiB	75,4 MiB

O resultado não é um ranking universal. A análise sintética por registro é barata; coordenação, Interlocked, tasks e canal custam mais do que o trabalho distribuído. Regras criptográficas, parsing pesado ou correlações CPU-bound podem mudar o ponto de equilíbrio. Execute em Release, faça aquecimento, repita amostras e registre hardware, SDK e configuração antes de tomar decisão.

Também separe as etapas. O tempo do git log, o parsing e a análise têm gargalos diferentes. Paralelizar consumidores não acelera a travessia do grafo pelo Git. Variar MaxDegreeOfParallelism e capacidade do canal mostra quando há saturação; aumentar ambos indiscriminadamente costuma elevar alocação e contenção.

Para consultas recorrentes por path, mantenha o commit-graph atualizado com git commit-graph write --reachable --changed-paths. Os Bloom filters de changed paths permitem que o Git descarte commits que provavelmente não tocaram o path consultado. Eles ajudam filtros por arquivo ou diretório, mas não substituem medição no repositório real.

Limites de uma Auditoria Baseada em Git

History rewriting cria novos object IDs; rebase e filter-repo podem alterar ou remover a visão compartilhada. Force push move refs e pode tornar commits inalcançáveis. Reflogs expiram e não são centralizados. Shallow e partial clones podem esconder ancestrais ou objetos ainda não materializados.

Autoria e data também exigem cautela. Os campos podem ser definidos pelo cliente, e data do autor não representa necessariamente a entrada na branch principal. Assinaturas ajudam a verificar autenticidade e integridade do objeto, mas dependem de gestão de chaves, confiança e políticas de verificação.

Um relatório auditável deve registrar pelo menos: refs observadas, intervalo de revisões, versão do Git, horário UTC, estado do clone e hash da configuração de regras. Preserve também a saída bruta ou um artefato derivado verificável. Para compliance, combine Git com retenção imutável, proteção de branch, logs de administração, pull requests, identidade corporativa, CI/CD e artefatos assinados.

Exemplo Prático: GitHistoryAnalyzer

A fachada recebe caminho, intervalo e regras. Ela inicia o processo, entrega registros ao pipeline e produz um relatório contextualizado. O chamador controla concorrência e capacidade sem expor detalhes do parser.

var rules = new IAuditRule[]
{
    new SignatureAuditRule(),
    new RequiredTrailerAuditRule("Reviewed-by", "Ticket"),
    new SensitivePathAuditRule(".github/workflows/", "deploy/", "src/Auth/"),
    new HighChurnAuditRule(1_000)
};

var analyzer = new GitHistoryAnalyzer(
    rules,
    new HistoryAnalysisOptions(
        MaxDegreeOfParallelism: Environment.ProcessorCount,
        ChannelCapacity: 2_048));

var report = await analyzer.AnalyzeAsync(
    repositoryPath: args[0],
    revisionRange: "release/2026.06..main",
    references: ["release/2026.06", "main"],
    cancellationToken);

await new AuditReportWriter().WriteAsync(Console.OpenStandardOutput(), report);

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/AsyncParallel/GitHistoryAnalysis/

O exemplo inclui parser para renames e binários, rules independentes, fixture, comparação de performance e testes xUnit. O JSON ordena mapas e achados para que duas execuções sobre a mesma entrada e contexto produzam conteúdo estável. O horário da análise faz parte do contexto; para comparação byte a byte, fixe-o ou compare apenas a seção de resultados.

Dicas e Boas Práticas

Prefira formatos próprios para máquina e NUL. Saídas visuais de git log mudam com configuração, locale e escaping. Campos %x00 e --numstat -z preservam limites mesmo quando paths contêm espaços, tabs ou quebras de linha.
Use .mailmap para identidades canônicas. Nomes e e-mails históricos variam por máquina e época. Normalize antes de calcular concentração de autoria, mas não confunda canonicalização com identidade verificada.
Limite o canal para controlar memória. Capacidade finita transforma pressão de consumo em espera do produtor. Escolha o valor medindo throughput e memória; um buffer enorme apenas adia a saturação.
Meça antes de aumentar o paralelismo. Na fixture de 500 mil registros, o sequencial venceu porque o trabalho unitário era barato. Paralelismo só compensa quando o custo distribuível supera coordenação, agendamento e contenção.
Valide exit code e drene stderr. Ler apenas stdout pode bloquear o processo quando o buffer de erro enche. Um relatório parcial nunca deve ser apresentado como auditoria concluída.
Preserve dados brutos e parâmetros. Registre refs, range, versão do Git, horário, clone e hash das regras. Esses dados permitem explicar por que duas execuções observaram universos diferentes.
Mantenha commit-graph em repositórios grandes. git commit-graph write --reachable --changed-paths prepara geração e Bloom filters para acelerar travessia e filtros por path. Confirme o benefício com consultas representativas.
Cruze Git com sistemas externos. CI/CD, code review, logs administrativos e identidade da plataforma respondem perguntas que os objetos Git não conseguem responder. A correlação é mais forte do que qualquer trailer ou campo de autoria isolado.

Resumo Objetivo

Git Pickaxe — git log -S seleciona commits em que a contagem de uma string mudou; git log -G seleciona patches cujas linhas adicionadas ou removidas correspondem a uma regex.
Git Bisect — git bisect run usa código 0 para bom, 1–127 exceto 125 para ruim e 125 para revisão não testável, reduzindo a busca de regressões de forma aproximadamente logarítmica.
Git Reflog — reflogs registram movimentos locais de refs e ajudam a recuperar commits após reset ou rebase, mas expiram e não formam uma evidência centralizada.
Channel<T> — um canal limitado com BoundedChannelFullMode.Wait suspende o produtor quando o buffer enche, preservando registros e limitando itens em trânsito.
Backpressure — backpressure controla a diferença de velocidade entre produtor e consumidores; ele melhora previsibilidade de memória, não garante maior throughput.
Commit-Graph — commit-graph com Bloom filters de changed paths pode acelerar consultas por arquivo ou diretório ao descartar commits provavelmente irrelevantes.
Assinaturas Git — uma assinatura válida autentica a chave que assinou o objeto, mas não substitui revisão, proteção de branch, retenção imutável ou gestão de identidade.
Auditoria Git — um relatório reproduzível registra refs, range, versão do Git, horário, configuração e limitações do clone, além de correlacionar evidências com CI/CD e plataforma.

Referências

git-log — filtros, formatos, Pickaxe, ranges, ordenação e simplificação de histórico.
git-rev-list — travessia do grafo, conjuntos de commits, bitmaps e suporte à bisseção.
git-bisect — busca binária automatizada, códigos de saída e modo --first-parent.
git-blame — atribuição de linhas, detecção de movimentos, cópias e revisões ignoradas.
git-reflog — histórico local de atualizações de referências e políticas de expiração.
git-cat-file — consulta batch de objetos e formatos delimitados por NUL.
git-commit-graph — geração de commit-graph e Bloom filters para changed paths.
Channels no .NET — canais limitados, produtor-consumidor e modos de backpressure.
Parallel.ForEachAsync — processamento assíncrono com paralelismo limitado no .NET. 📬

👉 Artigo completo com todos os exemplos de código: Git History para Debug e Auditoria em Escala

Tempo real no Angular e .NET: WebSockets, SSE e SignalR

Lincoln Zocateli — Tue, 21 Jul 2026 02:31:41 +0000

Introdução

Tempo real no Angular e .NET parece simples até o momento em que a equipe precisa escolher a tecnologia certa para sair do “funciona na minha máquina” e chegar em produção sem fragilidade. Em geral, a discussão começa com um pedido vago do produto: “precisamos que a tela atualize sozinha”. A partir daí aparecem quatro caminhos muito diferentes: WebSockets, Server-Sent Events (SSE), SignalR e Long Polling. Eles não são equivalentes, não resolvem o mesmo cenário com o mesmo custo e não devem ser tratados como sinônimos.

Eu escrevi este tutorial para responder a pergunta que realmente importa: quando usar cada abordagem sem superengenharia. Em alguns casos, um stream unidirecional já resolve. Em outros, a aplicação precisa de canal bidirecional, fallback automático e uma abstração que esconda a complexidade do protocolo. E, em certos ambientes corporativos, a solução mais feia na teoria vira a mais confiável na prática porque atravessa proxies, balanceadores e políticas de rede com menos atrito.

O ponto central aqui é pragmático. WebSockets oferecem comunicação bidirecional persistente. SSE entrega atualização do servidor para o navegador sobre HTTP com uma API simples. SignalR é uma abstração de alto nível para ASP.NET Core que escolhe o melhor transporte disponível e ainda oferece hubs, grupos e reconexão. Long Polling continua existindo porque compatibilidade e previsibilidade ainda ganham de elegância em ambientes onde WebSockets e SSE são bloqueados.

💡 Dica: quando o requisito é só empurrar eventos do servidor para o cliente, comece por SSE ou SignalR antes de partir para WebSockets. Em muitos produtos, a menor solução suficiente é a que sobrevive melhor ao longo do tempo.

Neste artigo eu também uso o repositório de exemplos do blog como apoio prático. O sample em .NET e Angular foi preparado para mostrar o mesmo fluxo de processamento em quatro transportes diferentes, sem esconder o que muda no frontend, no backend e na operação.

Pré-requisitos

Para acompanhar o tutorial, você vai precisar de:

.NET 10 SDK para executar o backend do sample
Node.js ou Bun para rodar o frontend Angular de demonstração
Conhecimento básico de ASP.NET Core, Angular e HTTP
Familiaridade com o conceito de endpoint, hub e requisição assíncrona Clone o repositório de exemplos:

git clone https://github.com/lzocateli/blog-zocateli-sample.git
cd blog-zocateli-sample

Se você quiser reproduzir o cenário localmente, o backend fica em src/BlogSamples e o frontend de demonstração em frontend/search-ui-bun/. O sample foi pensado para exibir uma tarefa de processamento com evolução incremental, justamente para evidenciar a diferença entre transporte, latência e complexidade de cliente.

⚠️ Atenção: SSE depende de resposta em streaming. Em Nginx, Cloudflare e outros proxies, buffering pode atrasar ou quebrar a experiência se o backend não escrever e flushar os eventos corretamente.

Quando cada tecnologia faz sentido

Antes de entrar na implementação, eu gosto de reduzir a discussão a um critério simples: qual direção o fluxo de dados precisa seguir? Se a aplicação só precisa publicar estados, notificações ou progresso, não há motivo para pagar o custo cognitivo de uma conexão bidirecional completa. Se o cliente também precisa enviar comandos frequentes em tempo real, aí a conversa muda.

O Long Polling é o ponto de partida mais conservador. Ele funciona com qualquer infraestrutura HTTP tradicional, atravessa proxies mais restritivos e é fácil de entender: o cliente faz uma requisição, o servidor segura até haver dado novo ou até o timeout. Em troca, você paga com latência e overhead de conexões repetidas. É um compromisso útil quando compatibilidade vence elegância.

O SSE é um meio-termo muito interessante para dashboards, trilhas de auditoria, status de jobs e feeds de notificação. Ele usa uma conexão HTTP aberta e o navegador recebe eventos continuamente via EventSource. O cliente não envia mensagens pelo mesmo canal, então a solução fica naturalmente unidirecional. Isso reduz a superfície do problema, simplifica a implementação e ainda é mais compatível do que muita equipe imagina.

WebSockets entram quando a conversa precisa ser bidirecional de verdade. Chat, colaboração, jogos, telemetria interativa, edição simultânea e comandos em tempo real são cenários em que o modelo full-duplex faz sentido. O preço é conhecido: conexão persistente, atenção extra com escalabilidade, afinidade em balanceadores e maior sensibilidade a intermediários de rede.

SignalR resolve outra categoria de problema: eu quero um contrato de tempo real em ASP.NET Core sem me obrigar a escolher o transporte manualmente em cada caso. O framework negocia WebSockets, SSE e Long Polling conforme a plataforma permite. Em projetos .NET, isso reduz atrito e ainda oferece recursos de alto nível como hubs, grupos e reconexão.

Em resumo: Long Polling é a rede de segurança, SSE é o stream simples e eficiente, WebSockets é o canal persistente e bidirecional, e SignalR é a abstração que distribui a decisão para o runtime.

WebSockets na prática com .NET e Angular

WebSockets começam como HTTP e depois fazem upgrade para um canal persistente. Esse detalhe muda tudo: a conexão deixa de ser um ciclo de requisição e resposta e passa a ser um tubo aberto para ambos os lados. Isso significa menos overhead por mensagem, baixa latência e um modelo mental muito útil para aplicações que precisam reagir a interações do usuário e eventos do servidor sem reabrir conexão a cada ação.

Na prática, o ganho vem com responsabilidades extras. WebSockets exigem atenção com escalabilidade horizontal, porque a conexão permanece viva e pode depender de afinidade de sessão ou de um backplane para distribuição de mensagens. Também é comum encontrar proxy corporativo, gateway ou CDN que não trata WebSockets tão bem quanto o tráfego HTTP comum. Isso não torna a tecnologia ruim; só obriga a uma análise mais séria do ambiente.

O cenário mais forte para WebSockets em Angular e .NET é quando o cliente também envia comandos frequentes: iniciar uma tarefa, cancelar uma operação, ajustar parâmetros de execução ou manter uma sessão interativa. Em vez de abrir novas requisições para cada passo, o cliente e o servidor compartilham um canal contínuo.

📝 Exemplo: num painel de supervisão de jobs, o usuário pode disparar uma tarefa, receber progresso incremental e cancelar a operação sem sair do mesmo canal de comunicação.

SSE na prática com .NET e Angular

SSE, ou Server-Sent Events, é o oposto do glamour tecnológico e exatamente por isso ele costuma ser tão útil. O browser abre uma conexão HTTP com EventSource e fica escutando eventos nomeados enviados pelo servidor. Não há bidirecionalidade no mesmo canal; o servidor escreve, o cliente lê. Parece limitado, mas para atualização de status, notificações, progresso de processamento e feeds de eventos isso é frequentemente suficiente.

O ponto forte do SSE é a simplicidade operacional. Como ele permanece muito próximo de HTTP, costuma ser mais fácil de atravessar infraestrutura existente do que uma conexão WebSocket. A API no browser é enxuta e a reconexão pode ser tratada com comportamento nativo ou com pequena camada de código. Para aplicações Angular, isso combina bem com uma interface reativa que só precisa refletir o estado mais recente.

O cuidado principal está na entrega do stream. Se o backend escreve o evento mas o proxy segura o buffer, o usuário não vê nada até o flush ou até o buffering ser desativado. É exatamente por isso que SSE precisa ser documentado junto com a arquitetura de borda, e não apenas como um detalhe de controller.

SignalR como camada de abstração

SignalR é onde muita discussão fica confusa, então vale separar bem os papéis. SignalR não é “um protocolo concorrente” de WebSockets. Ele é uma abstração de alto nível para aplicações em ASP.NET Core que escolhe o transporte disponível e entrega uma experiência mais simples para o desenvolvedor. Se WebSockets está disponível, ótimo. Se não estiver, SignalR pode cair para SSE ou Long Polling sem quebrar o contrato do aplicativo.

Para times .NET, isso costuma ser valioso porque reduz decisões repetitivas. Em vez de cada tela decidir sozinha como falar com o backend, eu centralizo a conversa em hubs, métodos e eventos. O frontend chama um método, o hub responde com um evento, e o framework negocia o transporte no meio. Isso também ajuda quando você quer grupos, broadcast seletivo, reconexão automática e um modelo de domínio mais claro.

O trade-off é que essa camada pode esconder detalhes que a equipe deveria entender. SignalR ajuda, mas não elimina a necessidade de saber quando WebSockets, SSE ou Long Polling estão por trás da abstração. Se a aplicação precisa de previsibilidade extrema em um ambiente específico, é melhor medir o comportamento real do que assumir que o framework resolverá tudo sozinho.

Long Polling como fallback e compatibilidade máxima

Long Polling é frequentemente tratado como técnica antiga, mas isso é um erro de leitura. Ele continua sendo importante porque existe uma quantidade enorme de ambientes em que o melhor protocolo é simplesmente o que passa pelo firewall, pelo proxy e pela política de segurança sem discussão. Em vez de abrir um canal persistente, o cliente faz uma requisição e o servidor segura a resposta até haver atualização ou timeout.

O efeito prático é previsibilidade. Você pode pagar com latência maior e mais overhead de requisição, mas ganha compatibilidade quase universal. Para usuários atrás de proxies muito restritivos, ambientes corporativos com regras conservadoras e stacks legadas, Long Polling ainda é uma solução válida. É melhor ter um fallback mais lento do que não ter atualização alguma.

O problema real é tentar usar Long Polling como primeira escolha quando a aplicação claramente pede um canal mais eficiente. Se o produto depende de muitos eventos por segundo ou de interação instantânea, o custo de repetição de requisições rapidamente aparece em CPU, rede e observabilidade. Nessa situação, Long Polling deve ficar na reserva, não no volante.

Matriz de decisão para escolher a abordagem

Quando eu preciso decidir rápido, uso uma matriz simples:

Cenário	Melhor ponto de partida	Motivo
Somente servidor → cliente	SSE	Menor complexidade, stream HTTP simples
Cliente também envia comandos frequentes	WebSockets	Canal bidirecional real
Quero abstração em ASP.NET Core e fallback automático	SignalR	Negociação de transporte e hubs
Infraestrutura restritiva ou legado	Long Polling	Maior compatibilidade
UI de dashboard com progresso de jobs	SSE ou SignalR	Baixa complexidade e boa UX
Chat ou colaboração em tempo real	WebSockets ou SignalR	Bidirecionalidade e latência baixa

Essa matriz não substitui medições, mas evita a armadilha mais comum: usar a tecnologia mais poderosa só porque ela é mais empolgante. Em produção, o menor mecanismo que cumpre o requisito é frequentemente o que dá menos trabalho para operar.

Exemplo Prático

O sample do blog foi montado para mostrar o mesmo fluxo de tarefa com quatro transportes. No backend, eu exponho um endpoint de criação, um endpoint de consulta e um stream para SSE e WebSocket. No frontend Angular, eu alterno a conexão conforme o transporte escolhido e atualizo a mesma interface com o mesmo modelo de evento.

Backend .NET

var grupo = app.MapGroup("/api/tempo-real")
    .WithTags("Tempo real")
    .RequireCors("TempoReal");

grupo.MapPost("/tarefas", (TempoRealProcessamentoService processamentoService, TempoRealCriacaoRequest request) =>
{
    if (string.IsNullOrWhiteSpace(request.Descricao))
    {
        return Results.BadRequest(new { erro = "A descrição da tarefa é obrigatória." });
    }

    var resposta = processamentoService.CriarTarefa(request.Descricao.Trim());
    return Results.Created($"/api/tempo-real/tarefas/{resposta.TarefaId}", resposta);
});

grupo.MapGet("/tarefas/{tarefaId:guid}/stream", async (
    Guid tarefaId,
    HttpContext context,
    TempoRealProcessamentoService processamentoService,
    CancellationToken cancellationToken) =>
{
    context.Response.ContentType = "text/event-stream";
    await foreach (var proximoEstado in processamentoService.ObterFluxoAsync(tarefaId, cancellationToken))
    {
        await context.Response.WriteAsync($"data: {JsonSerializer.Serialize(proximoEstado)}\n\n", cancellationToken);
        await context.Response.Body.FlushAsync(cancellationToken);
    }
});

📂 Código Fonte: O exemplo completo do backend está disponível no repositório de exemplos do blog em BlogSamples/Messaging/TempoReal/.

Angular com SignalR

const connection = new signalR.HubConnectionBuilder()
  .withUrl('/hubs/tempo-real', { withCredentials: true })
  .withAutomaticReconnect()
  .build();

connection.on('estado', (estado: TempoRealEstadoResponse) => onEstado(estado));

await connection.start();
await connection.invoke('AcompanharTarefa', tarefaId);

📂 Código Fonte: O frontend de demonstração está no repositório de exemplos do blog em frontend/search-ui-bun/, onde eu adaptei a interface para alternar entre os quatro transportes.

O detalhe importante aqui não é a quantidade de linhas, mas o modelo mental. O mesmo backend produz o mesmo estado de tarefa; o que muda é como esse estado cruza a rede e como a interface decide escutar as atualizações.

Dicas e Boas Práticas

Comece pelo requisito de direção de dados. Se o fluxo é apenas servidor → cliente, eu prefiro SSE ou SignalR antes de pensar em WebSockets. Isso reduz complexidade, facilita a operação e evita abrir um canal mais caro do que o necessário.
Desative buffering quando usar SSE. Streaming sem flush de resposta vira “quase streaming”. Em produção, eu sempre valido a cadeia completa de proxy, CDN e servidor para garantir que os eventos chegam ao navegador no tempo esperado.
Trate SignalR como contrato, não como mágica. Ele resolve muita coisa, mas continua dependendo de transporte, reconexão e política de rede. Entender o que acontece por baixo evita surpresas quando o ambiente troca de WebSocket para Long Polling.
Use Long Polling como fallback consciente. Ele é útil quando a infraestrutura é restritiva, mas não é a escolha ideal para alto volume. Se a aplicação cresce, a diferença de custo em requisições e latência aparece rápido.
Modele o estado do evento de forma estável. O cliente não deveria precisar adivinhar o significado de cada payload. Um modelo único de evento simplifica logs, debug, reconexão e renderização na UI.
Observe o ambiente de borda desde o início. Proxies, balanceadores, políticas de segurança e timeouts são parte da arquitetura de tempo real, não detalhes operacionais. Ignorar isso gera um sistema que funciona no dev e falha fora dele.

Resumo Objetivo

WebSockets — oferecem comunicação bidirecional persistente sobre uma conexão única, o que reduz overhead por mensagem e favorece cenários interativos como chat e colaboração.
SSE — entregam eventos do servidor para o navegador via text/event-stream, com API nativa no browser e simplicidade operacional para dashboards e notificações.
SignalR — é uma abstração de alto nível do ASP.NET Core que negocia WebSockets, SSE ou Long Polling e expõe hubs, grupos e reconexão.
Long Polling — mantém a compatibilidade máxima com infraestrutura HTTP tradicional, mas paga com mais latência e mais requisições ao servidor.
Angular + .NET — funcionam muito bem para aplicações de tempo real quando o modelo de evento é estável e o transporte é escolhido pelo requisito, não pela moda.
Infraestrutura de borda — pode ser o fator decisivo entre uma solução elegante e uma solução operacionalmente confiável; buffering e proxies influenciam SSE e WebSockets diretamente.

Referências

ASP.NET Core WebSockets — documentação oficial sobre upgrade de conexão e uso de WebSockets no ASP.NET Core.
ASP.NET Core SignalR — visão geral oficial de hubs, conexões e transporte.
MDN: EventSource — API do navegador usada por SSE.
MDN: WebSocket — API nativa do browser para conexões WebSocket.
Angular HttpClient — cliente HTTP usado no long polling e na criação das tarefas no demo.
Microsoft Learn: SignalR client-side JavaScript — integração do cliente SignalR no frontend web. 📬

👉 Artigo completo com todos os exemplos de código: Tempo real no Angular e .NET: WebSockets, SSE e SignalR

Certificados SSL/TLS: Como Funcionam e Como Validar

Lincoln Zocateli — Mon, 13 Jul 2026 22:01:36 +0000

Introdução

Quando eu falo de certificados SSL/TLS em times de backend, quase sempre encontro o mesmo atalho perigoso: “não conecta no ambiente de teste, então coloca verify=False no Python ou callback => true no .NET e segue”. Esse atalho parece inofensivo porque resolve o erro de conexão na hora, mas ele remove justamente o mecanismo que impede ataques de man-in-the-middle (MITM). Em outras palavras: a aplicação continua “funcionando”, mas deixa de saber se está falando com o servidor legítimo.

Neste artigo, eu vou explicar como certificados SSL/TLS funcionam de forma prática e, principalmente, como eu valido certificado corretamente em aplicações .NET e Python em cenários reais de produção. Vou cobrir handshake TLS 1.3, cadeia de confiança X.509, trust store, mTLS e implicações em containers. A ideia é sair da teoria abstrata e ir para código que você pode colocar em produção sem vergonha de auditoria.

Este é o quarto artigo da série Segurança para Devs. Nos artigos anteriores eu tratei de autenticação, BFF e API Gateway. Agora eu foco na camada de transporte, porque sem um TLS validado corretamente todo o resto fica frágil: JWT forte não salva um canal comprometido, OAuth2 correto não protege contra interceptação de tráfego e mTLS mal configurado pode virar teatro de segurança.

ℹ️ Informação: TLS 1.3 (RFC 8446) reduziu o handshake para 1-RTT no caso comum e removeu suites e algoritmos antigos inseguros. Isso melhora segurança e latência ao mesmo tempo.

Se você quer um resumo da tese logo no início: validar certificado não é opcional. É controle de integridade do canal. Quando eu desativo verificação para “fazer funcionar”, eu troco um erro explícito por um risco silencioso. O objetivo daqui é te mostrar como manter conexão segura sem cair nesses atalhos.

Pre-requisitos

Para acompanhar os exemplos sem fricção, eu recomendo este ambiente:

.NET 10 SDK instalado para compilar os samples C#.
Python 3.12+ com requests disponível.
Conhecimento básico de HTTP/HTTPS, status codes e cabeçalhos.
Familiaridade mínima com Docker e imagens Linux (Debian/Ubuntu) para a parte de container. Também ajuda ter acesso a um endpoint HTTPS de teste com certificado próprio (CA interna) e, se quiser reproduzir mTLS, um certificado de cliente (.pfx no .NET ou par .crt/.key no Python).

O que é TLS/SSL e por que “SSL” é termo legado

No uso diário, eu ainda ouço “certificado SSL” o tempo todo, inclusive em documentação de produtos. Tecnicamente, porém, SSL (Secure Sockets Layer) é o nome histórico. SSL 2.0 e SSL 3.0 estão obsoletos há anos por problemas graves de segurança. O protocolo atual é TLS (Transport Layer Security), com foco moderno em TLS 1.2 e TLS 1.3.

Por que essa distinção importa? Porque linguagem molda decisão técnica. Quando eu trato TLS como “SSL”, eu costumo herdar mentalidade antiga: compatibilidade acima de segurança, cifra fraca para atender cliente legado, tolerância a certificados mal emitidos. Quando eu trato como TLS moderno, eu priorizo suites seguras, validação estrita e observabilidade de expiração/revogação.

Na prática, o certificado digital é um documento X.509 que vincula uma identidade (domínio, organização, serviço) a uma chave pública. O TLS usa esse certificado para estabelecer um canal criptografado e autenticado entre cliente e servidor. O cliente valida se o certificado é confiável, se o nome do host bate com SAN/CN e se a cadeia até uma CA raiz confiável fecha corretamente.

Eu gosto de resumir assim:

Criptografia protege confidencialidade do tráfego.
Integridade garante que o pacote não foi alterado.
Autenticidade confirma com quem eu estou falando. Sem validação de certificado, eu mantenho criptografia, mas perco autenticidade. É exatamente esse o ponto que um atacante MITM explora.

⚠️ Atenção: Se o cliente aceita qualquer certificado, o TLS vira túnel criptografado para o atacante certo. Criptografado, porém comprometido.

Como funciona o handshake TLS 1.3

O handshake TLS 1.3 é o processo de negociação entre cliente e servidor antes dos dados de aplicação trafegarem. Eu acho útil enxergar esse fluxo em cinco blocos:

ClientHello: o cliente envia versões de TLS suportadas, suites criptográficas, extensões (como SNI e ALPN) e chave efêmera para ECDHE.
ServerHello: o servidor escolhe versão/suite, responde com sua chave efêmera e inicia parâmetros da sessão.
Certificate + CertificateVerify: o servidor envia cadeia de certificados e prova posse da chave privada.
Finished: ambos confirmam que chegaram às mesmas chaves de sessão.
Application Data: tráfego HTTP passa a ser protegido pelo canal estabelecido.

A mudança mais importante em relação a versões antigas é a redução de complexidade. TLS 1.3 removeu renegociação insegura, removeu RSA key exchange e tornou ECDHE o padrão para perfect forward secrecy (PFS). Em termos práticos, mesmo que a chave privada do servidor vaze no futuro, sessões antigas não são descriptografadas retroativamente.

Outro ponto que eu observo em produção: erro de handshake costuma apontar mais para configuração de certificado/trust store do que para bug de código. Por isso, log detalhado de falha TLS é essencial. Quando eu capturo hostname, issuer, thumbprint e status da cadeia, eu resolvo incidente muito mais rápido.

ℹ️ Informação: TLS 1.3 usa apenas suites AEAD modernas (como AES-GCM e ChaCha20-Poly1305), reduzindo superfície de ataque e simplificando hardening operacional.

Cadeia de confiança: CA raiz, intermediária e certificado de entidade final

Certificado não é uma entidade isolada. Ele participa de uma cadeia de confiança. Em geral, eu tenho:

Certificado de entidade final: pertence ao servidor (por exemplo api.minhaempresa.com).
CA intermediária: emite certificados de servidor e reduz exposição da raiz.
CA raiz: âncora de confiança presente no trust store do sistema cliente. Quando o cliente recebe o certificado do servidor, ele tenta montar essa cadeia até uma raiz confiável localmente. Se a raiz não estiver no trust store, a validação falha com erro de untrusted root. Isso é comum em ambientes corporativos com PKI interna, laboratórios e ambientes air-gapped.

Em certificados públicos de internet, a cadeia normalmente termina em uma CA raiz já presente no trust store do sistema ou navegador. É o caso de certificados emitidos por ACs públicas (autoridades certificadoras) como Certisign, DigiCert, GlobalSign e Let’s Encrypt. Nesses cenários, eu não preciso distribuir CA interna para clientes externos; o foco passa a ser enviar a cadeia intermediária correta no servidor e manter renovação em dia.

No dia a dia, os problemas mais frequentes que eu vejo sao:

Servidor sem enviar intermediária correta.
Certificado expirado ou fora da janela de validade.
SAN sem hostname esperado.
Cadeia confiável no host, mas não no container. Esse último é traiçoeiro: no meu notebook funciona, no pod não. O motivo normalmente é simples: a imagem não recebeu a CA interna no trust store do sistema.

Quando eu trabalho com CA privada, minha abordagem é dupla:

Instalo a CA no trust store do sistema no ambiente controlado.
Quando necessário, uso trust customizado na aplicação para cenários isolados. Essa segunda opção precisa de disciplina. Trust customizado é ferramenta boa quando bem delimitada, mas perigosa se virar regra geral sem governança.

Validando certificados corretamente em .NET

No .NET, minha referência para cliente HTTP moderno é HttpClient com SocketsHttpHandler. Ele permite configurar TLS sem truques inseguros. O ponto chave é: eu nunca retorno true de forma incondicional no callback.

Quando o endpoint usa certificado público emitido por AC pública confiável, o caminho padrão do .NET já resolve a validação usando o trust store do sistema. Eu só adiciono trust customizado quando tenho CA privada ou requisito de isolamento específico.

Trecho de sample com trust customizado e validação real da cadeia:

public static SocketsHttpHandler CriarHandlerComCaPrivada(string caminhoCaRaiz)
{
    var caRaiz = X509CertificateLoader.LoadCertificateFromFile(caminhoCaRaiz);

    return new SocketsHttpHandler
    {
        SslOptions = new SslClientAuthenticationOptions
        {
            EnabledSslProtocols = SslProtocols.Tls12 | SslProtocols.Tls13,
            CertificateRevocationCheckMode = X509RevocationMode.Online,
            RemoteCertificateValidationCallback = (_, certificado, cadeia, erros) =>
                CertificadoTlsValidator.ValidarServidor(certificado, cadeia, erros, caRaiz)
        }
    };
}

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/Security/Certificates/

No validator, eu recuso imediatamente RemoteCertificateNotAvailable e RemoteCertificateNameMismatch, depois reconstruo a cadeia com política estrita (NoFlag) e revogação online. Se houver CA personalizada, aplico TrustMode = CustomRootTrust e adiciono a raiz no CustomTrustStore.

Exemplo de criação de cliente mTLS:

var cliente = HttpsClientesSeguros.CriarClienteComMtls(
    caminhoCaRaiz: "/etc/ssl/custom/minha-ca.pem",
    caminhoPfxCliente: "/run/secrets/cliente.pfx",
    senhaPfxCliente: senha);

var response = await cliente.GetAsync("https://api.interna.local/health");
response.EnsureSuccessStatusCode();

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/Security/Certificates/

Dois detalhes operacionais fazem diferença em produção:

Eu prefiro X509CertificateLoader em vez de construtores legados para evitar warnings e garantir compatibilidade atual.
Eu monitoro erros de cadeia e expiração em logs estruturados para acionar alerta antes da queda.

Validando certificados corretamente em Python

No Python, eu vejo o mesmo anti-pattern do .NET: verify=False para “destravar” integração. Em produção, isso não pode existir. O caminho correto com requests é informar o bundle de CA confiável em verify, ou manter o trust store padrão quando usa CA pública.

Exemplo seguro com requests:

def requisicao_https_com_ca_privada(url: str, ca_bundle: Path) -> requests.Response:
    response = requests.get(url, verify=str(ca_bundle), timeout=10)
    response.raise_for_status()
    return response

Se eu preciso de controle mais fino, crio SSLContext explícito:

def criar_contexto_ssl(ca_bundle: Path) -> ssl.SSLContext:
    context = ssl.create_default_context(purpose=ssl.Purpose.SERVER_AUTH)
    context.verify_mode = ssl.CERT_REQUIRED
    context.check_hostname = True
    context.minimum_version = ssl.TLSVersion.TLSv1_2
    context.load_verify_locations(cafile=str(ca_bundle))
    return context

📂 Código Fonte: O exemplo completo está disponível no repositório de exemplos do blog:
BlogSamples/python/

Para mTLS no requests, eu passo par certificado/chave do cliente no parâmetro cert:

response = requests.get(
    url,
    verify=str(ca_bundle),
    cert=(str(client_cert), str(client_key)),
    timeout=10,
)

Essa abordagem me atende bem para automações, workers e integrações backend-to-backend. Em APIs sensíveis, eu combino mTLS com token de aplicação para defesa em camadas.

Para certificado público de servidor (por exemplo, domínio público com emissão por Certisign ou outra AC pública), o padrão costuma ser manter verify=True e usar o trust store nativo, sem CA bundle customizado. Eu só uso verify apontando arquivo quando preciso confiar em CA privada ou cadeia fora do padrão do sistema.

mTLS: quando o cliente também apresenta certificado

No TLS tradicional, só o servidor apresenta certificado. No mTLS (mutual TLS), cliente e servidor apresentam certificado. Eu uso isso quando quero identidade forte de serviço para serviço sem depender apenas de segredo estático.

Cenários comuns onde mTLS vale o custo:

Comunicação interna entre API Gateway e serviços críticos.
Integração B2B com parceiros fixos e requisitos de compliance.
Ambientes financeiros e industriais onde identidade criptográfica é obrigatória. mTLS não substitui autorização de negócio. Ele prova identidade técnica do cliente, mas ainda preciso decidir se aquele cliente pode executar aquela ação. Na prática, eu trato mTLS como controle de borda e mantenho autorização por escopo/claims na aplicação.

Se você quiser contexto arquitetural da série, este artigo conversa diretamente com API Gateway: A Peça que Falta na Segurança da Sua SPA, onde eu mostro como gateway aplica políticas em escala.

Certificados em containers

Container muda bastante o jogo porque o trust store do host não é herdado automaticamente da forma que muita gente imagina. Cada imagem tem seu próprio conjunto de CAs. Quando eu recebo erro de TLS só no pod, quase sempre é CA ausente no filesystem da imagem.

No Debian/Ubuntu, o fluxo padrão é:

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates \
    && rm -rf /var/lib/apt/lists/*

COPY certs/minha-ca.crt /usr/local/share/ca-certificates/minha-ca.crt
RUN update-ca-certificates

Com isso, bibliotecas que usam trust store do sistema passam a confiar na CA interna. Eu evito colocar certificado sensível em variável de ambiente. Para certificado de cliente e chave privada, eu monto secret em tmpfs (como /run/secrets) e limito permissão de leitura ao processo da aplicação.

Também tomo cuidado com rotação:

CA e certs com data de vencimento monitorada.
Pipeline de imagem preparado para troca sem downtime desnecessario.
Health checks que falham cedo quando cadeia não valida. Em Kubernetes, isso normalmente significa combinar Secret/CSI driver com rollout controlado e observabilidade de handshake.

NGINX com certificado público e interno

Quando eu uso NGINX como web server/reverse proxy, o ponto central é sempre o mesmo: o certificado apresentado ao cliente fica no bloco server HTTPS, via ssl_certificate e ssl_certificate_key.

No cenário público (AC pública como Certisign, DigiCert, GlobalSign ou Let’s Encrypt), minha prática é configurar o NGINX com cadeia completa (fullchain) para evitar erro de cadeia incompleta no cliente:

server {
  listen 443 ssl http2;
  server_name api.minhaempresa.com;

  ssl_certificate     /etc/nginx/tls/fullchain.pem;
  ssl_certificate_key /etc/nginx/tls/privkey.pem;

  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_session_timeout 1d;
  ssl_session_cache shared:SSL:50m;

  location / {
    proxy_pass http://app:8080;
  }
}

No cenário interno com CA privada, a configuração do certificado no NGINX é parecida, mas os clientes só vão confiar se a CA interna estiver no trust store deles. Se o endpoint exigir mTLS de cliente, eu habilito verificação explícita:

server {
  listen 443 ssl http2;
  server_name api.interna.local;

  ssl_certificate     /etc/nginx/tls/api.interna.local.fullchain.pem;
  ssl_certificate_key /etc/nginx/tls/api.interna.local.key;

  ssl_client_certificate /etc/nginx/tls/ca-clientes-interna.crt;
  ssl_verify_client on;
  ssl_verify_depth 2;

  location / {
    proxy_pass http://app:8080;
  }
}

Quando o NGINX também atua como cliente TLS para um upstream HTTPS interno, eu ativo validação de certificado no proxy para não cair no anti-pattern de confiar cegamente:

location /backend/ {
  proxy_pass https://backend.interno.local;

  proxy_ssl_server_name on;
  proxy_ssl_name backend.interno.local;

  proxy_ssl_trusted_certificate /etc/nginx/tls/ca-upstream-interna.crt;
  proxy_ssl_verify on;
  proxy_ssl_verify_depth 2;
}

Com isso, eu cubro os dois lados da segurança: o certificado que o NGINX apresenta para fora e a validação do certificado quando ele chama serviços HTTPS internos.

Exemplo Prático

No repositório de samples eu deixei dois blocos prontos para uso:

.NET em src/BlogSamples/Security/Certificates/ com HttpClient seguro, trust customizado e mTLS.
Python em python/ssl_validation_example.py com requests e SSLContext estrito.
Fluxo que eu recomendo para validar ponta a ponta:
Suba um endpoint HTTPS de teste com CA privada.
Execute cliente .NET com CriarClienteComCaPrivada.
Execute script Python passando TLS_CA_BUNDLE, TLS_CLIENT_CERT e TLS_CLIENT_KEY.
Verifique logs de cadeia e hostname em ambos.
Force erro (hostname errado ou cert expirado) para confirmar que a aplicação falha de forma segura.

📝 Exemplo: Se o endpoint for https://api.interna.local e o certificado tiver SAN apenas para api.dev.local, a conexão deve falhar por mismatch de nome. Esse é o comportamento correto e esperado.

Com esse fluxo, eu provo duas coisas para o time: que o caminho feliz funciona e que o caminho de falha falha do jeito certo. Segurança madura não é apenas “funciona quando tudo está bonito”; é previsível quando algo sai do esperado.

Dicas e Boas Práticas

Nunca desabilite validação (verify=False, CERT_NONE, callback => true).
Quando eu removo validação, eu elimino autenticidade do canal e abro caminho para MITM. Em vez disso, eu corrijo trust store, SAN ou cadeia.
Prefira pin de CA/intermediária ao invés de pin de certificado de entidade final.
Pin no leaf quebra com renovação frequente. Pin em CA bem governada reduz manutenção sem perder controle.
Monitore expiração e falhas de handshake como métrica de plataforma.
Eu trato erro TLS como sinal operacional de alto valor. Alertar 30 dias antes da expiração evita incidente evitável.
Use mTLS em tráfego lateral sensível, especialmente entre gateway e backend.
Isso reduz risco de chamada direta indevida a serviços internos. Ainda assim, mantenha autorização por claims/escopos no app.
Padronize instalação de CAs em imagens e ambientes locais.
Eu documento o passo de trust store por distro e automatizo no Dockerfile. Isso elimina “na minha máquina funciona” de TLS.
Em domínio público, prefira AC pública bem suportada e automação de renovação.
Isso reduz fricção de distribuição de confiança para clientes externos. Mesmo com AC pública, eu valido cadeia enviada pelo servidor e monitoro expiração para evitar indisponibilidade.
Teste cenários negativos de forma intencional.
Inclua casos com hostname inválido, cert expirado e cadeia incompleta no pipeline de qualidade. Se o cliente aceitar esses cenários, algo está errado.

Resumo Objetivo

TLS 1.3 — é o protocolo moderno de transporte seguro; SSL é legado obsoleto e não deve ser alvo de configuração nova.
Validação de certificado — precisa confirmar cadeia de confiança, hostname (SAN/CN), validade temporal e, quando aplicável, revogação.
.NET com SocketsHttpHandler — permite validação segura com CustomRootTrust para CA privada sem usar bypass inseguro.
Python com requests/ssl — deve usar verify com CA bundle, CERT_REQUIRED e check_hostname=True para manter autenticidade do canal.
mTLS — adiciona autenticação do cliente por certificado e é especialmente útil em comunicação service-to-service crítica.
Containers — exigem trust store próprio; instalar CA na imagem e montar cert/key como secret em tmpfs evita falhas e vazamentos.
Certificado público (ex.: Certisign) — normalmente valida no trust store padrão do sistema; CA bundle customizado fica para cenários com PKI privada.
NGINX com HTTPS — usa ssl_certificate e ssl_certificate_key no server; em proxy HTTPS interno, proxy_ssl_verify on com CA confiável evita conexão insegura com upstream.

Referências

RFC 8446 - The Transport Layer Security (TLS) Protocol Version 1.3 — especificação oficial do TLS 1.3.
RFC 5280 - Internet X.509 Public Key Infrastructure Certificate and CRL Profile — perfil de certificados X.509 e validação de cadeia.
Microsoft Docs - X509Chain — API de construção e validação de cadeia no .NET.
Microsoft Docs - SocketsHttpHandler — configuração de cliente HTTP moderno no .NET.
Python Docs - ssl — configuração de contexto TLS no Python.
Requests Docs - SSL Cert Verification — verificação de certificado na biblioteca requests.
OWASP Transport Layer Security Cheat Sheet — guia prático de hardening TLS.
NGINX Docs - ngx_http_ssl_module — diretivas ssl_certificate, ssl_certificate_key e configuração HTTPS no bloco server.
NGINX Docs - ngx_http_proxy_module — diretivas proxy_ssl_verify e proxy_ssl_trusted_certificate para validação TLS de upstream. 📬

👉 Artigo completo com todos os exemplos de código: Certificados SSL/TLS: Como Funcionam e Como Validar

DEV Community: Lincoln Zocateli

SignalR no .NET: do primeiro Hub à produção

Introdução

Pré-requisitos

O que SignalR abstrai, e o que continua sendo protocolo

Do registro do Hub à autorização por ambiente

Cliente Angular pelo BFF, sem token no browser

Grupos e invalidações: aviso rápido, leitura durável

Autenticação, autorização e limites de confiança

Reconexão, fluxos e eventos que podem se perder

Escala e operação sem prometer o que ainda não existe

Exemplo Prático: browser, BFF, Keycloak e invalidação

SignalR, gRPC, SSE e WebSockets: escolha pelo fluxo

Dicas e Boas Práticas

Conclusão

Resumo Objetivo

Leia Também

Referências

GraphQL para Iniciantes: Guia Completo com .NET

Introdução

Pré-requisitos

O que GraphQL é e como uma operação é executada

Schema, types, queries, mutations e inputs

O papel dos resolvers e o problema N+1

GraphQL.NET no ASP.NET Core e .NET 10

Exemplo Prático

Segurança e limites operacionais

GraphQL, REST e gRPC: como escolher

Dicas e Boas Práticas

Conclusão

Resumo Objetivo

Leia Também

Referências

gRPC sem mistério: o que é e quando usar no .NET 10

Introdução

RPC, REST e a função do HTTP/2

Protocol Buffers, arquivos .proto e código gerado

Os quatro modos de chamada gRPC

Por que o Dokpod escolheu gRPC para os agentes

Como o fluxo gRPC do Dokpod funciona

Segurança, reconexão e confiabilidade

Quando escolher gRPC, REST, GraphQL ou SignalR

Exemplo Prático

Dicas e Boas Práticas

Conclusão

Resumo Objetivo

Leia Também

Referências

Transactional Outbox Pattern: Resolvendo o Dual Write

Introdução

Pré-requisitos

O problema da dupla escrita (dual write problem)

Por que transações de banco não resolvem sozinhas

A solução: Transactional Outbox Pattern

Consumo dos eventos: o publisher assíncrono

Caso real: auditoria transacional em um sistema de gestão de estoque

Obrigações do consumidor: idempotência e ordenação

Como saber se você precisa do Outbox Pattern

Dicas e Boas Práticas

Resumo Objetivo

Leia Também

Referências

.NET Native AOT: Parte 2 — JIT, R2R e AOT em Benchmarks

Introdução

Pré-requisitos

O que os comentários revelaram sobre a decisão AOT

Metodologia: como tornar a comparação justa

Exemplo Prático: laboratório reproduzível em .NET 10

Publish, tamanho e startup de processo

Runtime compartilhado e unidades autocontidas

Throughput, latência e memória sob carga

JIT, Dynamic PGO e Native AOT no código quente

Source generators e reflection mudam o custo

Onde as conclusões não se aplicam diretamente

Matriz de decisão orientada ao objetivo

Limitações do experimento

Dicas e Boas Práticas

Resumo Objetivo

Leia Também

Referências

.NET 10: o que mudou e quando usar `System.Threading.Lock`

Quando usar `lock` e quando usar `Interlocked`

`ConcurrentDictionary` e coleções concorrentes

Exemplo realista: `ConcurrentDictionary` em singleton