DEV Community: Unhacked

Singleton em C# e .NET 10: o padrão que todo mundo conhece e quase todo mundo usa errado

Cristiano Rodrigues — Wed, 08 Jul 2026 17:18:14 +0000

Todo desenvolvedor .NET conhece o Singleton. É o primeiro padrão que a maioria aprende, o mais fácil de desenhar num quadro branco e, por uma ironia cruel, o mais fácil de implementar errado. A versão que aparece em tutoriais de dez linhas funciona perfeitamente na sua máquina, com uma thread só, e falha silenciosamente no primeiro pico de tráfego em produção.

A pergunta que separa quem conhece o padrão de quem o domina é esta: o que acontece quando duas requisições chegam no mesmo milissegundo, antes de a instância existir? A resposta ingênua cria dois objetos que deveriam ser um. O Google resolveu variações desse problema de inicialização única em escala, o C# ganhou ferramentas específicas para ele ao longo de várias versões, e o Lazy<T> existe justamente porque escrever a versão thread-safe à mão é mais sutil do que parece.

Vamos implementar o Singleton do jeito certo em .NET 10, medir o custo de cada abordagem com dados reais, e terminar com a parte que os tutoriais escondem: quando o Singleton é a ferramenta errada e está sabotando o seu projeto.

Este é o primeiro artigo da série sobre Design Patterns em C# e .NET 10. Começamos pelos padrões criacionais, e nenhum é mais emblemático que o Singleton.

O que o Singleton resolve

O Singleton garante que uma classe tenha uma única instância durante toda a vida da aplicação e oferece um ponto de acesso global a ela. Dois problemas em um: unicidade e acesso.

A unicidade importa quando o objeto representa algo que é logicamente único no sistema ou é caro demais para duplicar. Um catálogo de configuração carregado de disco, um pool de conexões, um cache em memória, um cliente HTTP com sua própria fila de conexões. Criar dois desses é desperdício no melhor caso e bug no pior, quando dois caches divergem e passam a responder valores diferentes para a mesma chave.

O acesso global é a parte controversa, e voltaremos a ela na seção de limitações. Por ora, guarde a intuição: o Singleton troca a flexibilidade de passar uma dependência explicitamente pela conveniência de acessá-la de qualquer lugar.

Por que a solução óbvia falha

A primeira implementação que quase todo mundo escreve é esta:

// ATENÇÃO: esta versão NÃO é thread-safe.
// Ela está aqui para mostrar onde o problema mora.
public sealed class ConfiguracaoIngenua
{
    private static ConfiguracaoIngenua? _instancia;

    public string AmbienteAtual { get; }

    private ConfiguracaoIngenua()
    {
        // Simula uma carga cara: arquivo, banco, chamada externa
        AmbienteAtual = "Production";
    }

    public static ConfiguracaoIngenua Instancia
    {
        get
        {
            // Duas threads podem passar por este if ao mesmo tempo
            if (_instancia is null)
            {
                _instancia = new ConfiguracaoIngenua();
            }
            return _instancia;
        }
    }
}

Repare no que acontece quando duas threads chegam juntas, antes de a instância existir:

Duas instâncias foram criadas. A thread A recebeu a instância A, a thread B recebeu a B, e a partir de t5 todo o resto do sistema recebe a B. Se essa classe carrega um arquivo de dez megabytes, você pagou a carga duas vezes. Se ela abre um pool de conexões, você tem dois pools. O padrão que existe para garantir unicidade acabou de produzir duplicidade.

O construtor privado é a única parte que a versão ingênua acerta: ele impede que código externo faça new ConfiguracaoIngenua(), forçando todo mundo a passar pela propriedade Instancia. Sem ele, não há Singleton, há apenas uma variável estática que qualquer um pode ignorar.

Anatomia do padrão

A estrutura do Singleton é a mais enxuta de todos os padrões do catálogo:

Três elementos, e só:

Construtor privado: bloqueia a criação externa. Ninguém consegue escrever new, então a classe controla sozinha quantas instâncias existem.

Campo estático: guarda a referência para a única instância. Estático porque precisa sobreviver a qualquer chamada individual e ser compartilhado por todos.

Ponto de acesso estático: a propriedade ou método que devolve a instância, criando-a na primeira vez se necessário.

A dificuldade toda mora no ponto de acesso, especificamente em como criar a instância exatamente uma vez quando várias threads chegam juntas. Vamos percorrer as soluções em ordem de qualidade.

Implementação: da trava ao Lazy

Trava em toda leitura

A correção mais direta é serializar o acesso com uma trava. No .NET 9 ganhamos o tipo Lock, dedicado a esse propósito, mais rápido que travar num object genérico:

// Versão thread-safe com o tipo Lock, introduzido no .NET 9
public sealed class ConfiguracaoComLock
{
    private static ConfiguracaoComLock? _instancia;
    private static readonly Lock _trava = new();

    public string AmbienteAtual { get; }

    private ConfiguracaoComLock()
    {
        AmbienteAtual = "Production";
    }

    public static ConfiguracaoComLock Instancia
    {
        get
        {
            // Toda leitura paga o custo da trava, mesmo depois de criada
            lock (_trava)
            {
                _instancia ??= new ConfiguracaoComLock();
                return _instancia;
            }
        }
    }
}

Correto, mas caro. O comentário aponta o problema: a instância é criada uma vez, mas a trava é adquirida em toda leitura, para sempre. Depois que o objeto existe, o lock não protege mais nada, só cobra pedágio. Numa propriedade acessada milhões de vezes por segundo, isso pesa, como o benchmark vai mostrar.

Double-checked locking

A técnica clássica para pagar a trava só enquanto ela importa é a dupla checagem:

// Double-checked locking: só entra na trava se ainda não existe instância
public sealed class ConfiguracaoDoubleChecked
{
    private static volatile ConfiguracaoDoubleChecked? _instancia;
    private static readonly Lock _trava = new();

    public string AmbienteAtual { get; }

    private ConfiguracaoDoubleChecked()
    {
        AmbienteAtual = "Production";
    }

    public static ConfiguracaoDoubleChecked Instancia
    {
        get
        {
            // Primeira checagem: sem trava, caminho rápido
            if (_instancia is null)
            {
                lock (_trava)
                {
                    // Segunda checagem: outra thread pode ter criado
                    // enquanto esta esperava a trava
                    _instancia ??= new ConfiguracaoDoubleChecked();
                }
            }
            return _instancia;
        }
    }
}

A ideia: a primeira checagem, fora da trava, é o caminho rápido para o caso comum em que a instância já existe. Só quando ela ainda é null pagamos a trava, e aí a segunda checagem cobre o caso de duas threads terem passado juntas pela primeira.

Nota: o volatile no campo não é decoração. Sem ele, o modelo de memória permite que uma thread veja a referência já atribuída antes de o construtor ter terminado de rodar, entregando um objeto meio construído. O volatile garante que a escrita da referência só fique visível depois que tudo dentro do construtor completou. Errar isso produz o pior tipo de bug: o que aparece uma vez a cada milhão de execuções, só em produção, e nunca no debugger.

O double-checked locking funciona, mas é um código que você precisa acertar com cuidado. A boa notícia é que, em C#, você quase nunca deveria escrevê-lo.

Inicialização estática

O runtime do .NET já garante que campos estáticos são inicializados uma única vez, de forma thread-safe, sem você escrever trava nenhuma:

// Inicialização estática: o runtime garante a criação única
public sealed class ConfiguracaoEstatica
{
    private static readonly ConfiguracaoEstatica _instancia = new();

    public string AmbienteAtual { get; }

    // O construtor estático explícito impede a marcação beforefieldinit,
    // garantindo que a instância só nasce no primeiro acesso ao tipo
    static ConfiguracaoEstatica() { }

    private ConfiguracaoEstatica()
    {
        AmbienteAtual = "Production";
    }

    public static ConfiguracaoEstatica Instancia => _instancia;
}

O construtor estático vazio parece inútil, mas tem função. Sem ele, o compilador marca o tipo com o atributo beforefieldinit, que dá ao runtime liberdade de inicializar os estáticos mais cedo do que você espera. Com o construtor estático explícito, a garantia é firme: a instância nasce no primeiro acesso ao tipo, não antes. É elegante e correto, mas tem uma limitação: a inicialização não é preguiçosa de verdade se a classe tiver outros membros estáticos, porque tocar qualquer um deles dispara a criação da instância.

Lazy<T>: a forma idiomática

Para inicialização preguiçosa e thread-safe sem escrever uma linha de sincronização, o C# oferece Lazy<T> desde o .NET Framework 4.0. É a resposta que a linguagem quer que você use:

// Lazy<T>: a forma idiomática em C# moderno
public sealed class ConfiguracaoLazy
{
    private static readonly Lazy<ConfiguracaoLazy> _instancia =
        new(() => new ConfiguracaoLazy());

    public string AmbienteAtual { get; }

    private ConfiguracaoLazy()
    {
        AmbienteAtual = "Production";
    }

    public static ConfiguracaoLazy Instancia => _instancia.Value;
}

O Lazy<T> encapsula toda a complexidade que percorremos. Por padrão ele usa o modo LazyThreadSafetyMode.ExecutionAndPublication, que garante que a fábrica roda uma única vez mesmo sob concorrência e que nenhuma thread vê um objeto meio construído. Você ganha o double-checked locking correto, com a barreira de memória certa, sem escrever nem depurar nada disso. A instância só é criada no primeiro acesso a .Value.

Testar a garantia de unicidade sob concorrência é uma linha:

// 100 threads acessando ao mesmo tempo, deve resultar em 1 instância
var instancias = new ConfiguracaoLazy[100];
Parallel.For(0, 100, i => instancias[i] = ConfiguracaoLazy.Instancia);
Console.WriteLine(instancias.Distinct().Count()); // 1

Cem threads, uma instância. É o que o Lazy<T> promete e cumpre.

Performance: por que o benchmark ingênuo mente

Todas as versões corretas produzem uma única instância. A pergunta natural é qual delas custa menos a cada acesso, depois que a instância existe. O benchmark ingênuo para responder isso é o que quase todo mundo escreve, e é o que vai te enganar. Vamos escrevê-lo, rodá-lo, e entender por que o resultado não quer dizer o que parece.

O harness mede o custo de um acesso com a instância já criada e o JIT aquecido:

[MemoryDiagnoser]
public class SingletonBenchmark
{
    [Benchmark(Baseline = true)]
    public object LockSempre() => ConfiguracaoComLock.Instancia;

    [Benchmark]
    public object DoubleChecked() => ConfiguracaoDoubleChecked.Instancia;

    [Benchmark]
    public object Lazy() => ConfiguracaoLazy.Instancia;

    [Benchmark]
    public object StaticReadonly() => ConfiguracaoEstatica.Instancia;
}

Rodando na minha máquina, o resultado é este:

Olhe para o Lazy<T> marcando 0,00 ns. Nenhuma operação real custa zero. Esse valor não significa que o Lazy<T> é infinitamente rápido, significa que não sobrou nada para medir. E ele não está sozinho: o double-checked e o estático também caíram abaixo do piso confiável do BenchmarkDotNet. Resultado sub-nanossegundo quase sempre quer dizer a mesma coisa, o JIT otimizou o trabalho para fora do loop.

A razão é a invariância. Depois que a instância existe, esses três métodos apenas devolvem uma referência que já está pronta. O BenchmarkDotNet chama cada um milhares de vezes num loop, e o JIT percebe que a chamada devolve exatamente a mesma referência em toda iteração. Sendo invariante, ele calcula uma vez e reaproveita, e o custo por chamada desaba para perto de zero. Não há o que medir, porque uma leitura de campo cacheada é essencialmente de graça. O [MemoryDiagnoser] confirma o outro lado da moeda: nenhuma das quatro aloca no acesso, porque todas só devolvem uma referência que já existe.

Repare que só o lock sobreviveu com um número honesto, e sobreviveu justamente porque tem um lock. A trava é uma barreira que o JIT não pode eliminar nem mover para fora do loop, então cada iteração de fato adquire e libera a trava. Ou seja, os 2,88 ns não medem o acesso ao Singleton, medem o custo do lock em toda leitura, que é o único trabalho real que restou na tabela.

A leitura correta, então, é a mais simples possível. Na via quente, com a instância já criada, as três estratégias corretas são de graça, porque se reduzem a uma leitura de campo. A única que paga um custo recorrente é a ingênua, com lock em toda leitura. Não existe a mais rápida das três, existe as três livres e a quarta cobrando pedágio.

Isso muda o motivo pelo qual você escolhe o Lazy<T>. Não é por um nanossegundo que ele não te dá. É porque é o código correto mais simples de escrever, thread-safe sem uma linha de sincronização à mão. O argumento de performance, quando você mede direito, não separa as boas opções entre si, ele só condena a ingênua.

E onde as estratégias divergem de verdade é sob concorrência, não em acesso sequencial. O benchmark que importa dispara várias threads lendo a instância ao mesmo tempo, e passa cada leitura por um delegate. Esse delegate é o que faz o teste medir alguma coisa: como o JIT não enxerga através dele, não consegue provar que a leitura é invariante e não a move para fora do loop, ao contrário do benchmark ingênuo. Cada uma das milhões de leituras executa de fato. O tempo medido é o do lote inteiro rodando em paralelo, por isso a escala agora é de milissegundos, não de nanossegundos. Rodando com 1, 2, 4 e 8 threads, a diferença salta:

Leia a primeira linha e depois as outras três. O lock em toda leitura desmorona conforme as threads aumentam: de 4,2 ms com uma thread para 717 ms com oito, quase duzentas vezes mais lento, apesar de o trabalho por thread ser o mesmo. As três estratégias sem trava mal se mexem, porque as leituras acontecem em paralelo, sem ninguém esperando ninguém.

A coluna de Lock Contentions do BenchmarkDotNet mostra a causa exata: zero com uma thread, 3 com duas, 607 com quatro, e 11.107 com oito. Cada contenção é uma thread que chegou na trava, encontrou ela ocupada, e foi estacionada pelo sistema operacional até a vez chegar. Quanto mais threads, mais elas brigam pela mesma trava, e a vazão colapsa. O lock não cobra um pedágio fixo, ele cobra um pedágio que piora quanto mais movimento passa, exatamente o oposto do que você quer num sistema de alto tráfego.

Nota: este benchmark é o pior caso de propósito. O loop faz só uma coisa, pegar a instância, um milhão de vezes sem pausa, então as threads batem na trava sem parar e a serialização aparece no seu extremo. Em produção não é assim. Cada thread pega a instância e depois faz trabalho, uma consulta, uma serialização, um cálculo, e esse trabalho espalha as chegadas na trava ao longo do tempo. A direção do resultado se mantém, o lock serializa e degrada com a concorrência, mas a magnitude dos 717 ms é um teto, não o número que você verá no seu sistema. Leia a tabela como ranking e tendência, não como custo absoluto.

Vale uma observação na via de uma thread só, onde não há contenção. O double-checked (1,9 ms) é mensuravelmente mais lento que o Lazy (0,65 ms) e o estático (0,50 ms), e a razão é o volatile. Ele obriga uma leitura com barreira de memória a cada acesso, enquanto o Lazy e o estático, depois de criados, são leituras de campo comuns. Não é uma diferença que pese na prática, mas explica por que a técnica clássica que você escreveria à mão perde para as duas que a linguagem te dá de graça.

Escolha o Lazy<T>. Ele fica a um passo do piso, escala plano sob qualquer concorrência, e você não escreve nem uma linha de sincronização. O lock em toda leitura não é só mais lento, é uma bomba-relógio que só aparece quando o tráfego chega.

Exemplo da vida real

Imagine uma API de emissão de notas fiscais que precisa calcular o ICMS de cada item. As alíquotas por unidade federativa moram num arquivo JSON, carregado do disco na inicialização. Ler e desserializar esse arquivo a cada requisição seria absurdo: os dados mudam raramente e cabem folgados na memória. É um caso de Singleton de manual.

// Catálogo de alíquotas de ICMS por UF, carregado uma única vez
public sealed class CatalogoAliquotas
{
    private static readonly Lazy<CatalogoAliquotas> _instancia =
        new(() => new CatalogoAliquotas("aliquotas.json"));

    private readonly IReadOnlyDictionary<string, decimal> _aliquotas;

    public static CatalogoAliquotas Instancia => _instancia.Value;

    private CatalogoAliquotas(string caminhoArquivo)
    {
        // Carga cara: leitura de disco e desserialização,
        // paga uma única vez na vida do processo
        var json = File.ReadAllText(caminhoArquivo);
        var dados = JsonSerializer.Deserialize<Dictionary<string, decimal>>(json)
            ?? throw new InvalidOperationException(
                $"Arquivo {caminhoArquivo} vazio ou inválido");

        _aliquotas = dados;
    }

    public decimal ObterAliquota(string uf) =>
        _aliquotas.TryGetValue(uf, out var aliquota)
            ? aliquota
            : throw new KeyNotFoundException($"UF desconhecida: {uf}");
}

Repare em três decisões de produção. A validação no construtor transforma um arquivo corrompido em falha explícita na inicialização, não em NullReferenceException três horas depois. O dicionário é exposto como IReadOnlyDictionary, porque um Singleton compartilhado por todas as threads jamais pode ser mutável sem sincronização, e a imutabilidade elimina o problema pela raiz. E ObterAliquota falha alto para uma UF desconhecida, em vez de devolver zero e gerar uma nota fiscal com imposto errado.

Integração com ASP.NET Core: o Singleton que você deveria usar

Na maioria dos casos, você não deveria escrever o padrão Singleton à mão. O container de injeção de dependência do ASP.NET Core já implementa o ciclo de vida singleton para você, e melhor.

var builder = WebApplication.CreateBuilder(args);

// O container é o singleton: uma instância para toda a vida da aplicação
builder.Services.AddSingleton<CatalogoAliquotas>(_ =>
    CatalogoAliquotas.CarregarDe("aliquotas.json"));

var app = builder.Build();

app.MapGet("/aliquota/{uf}", (string uf, CatalogoAliquotas catalogo) =>
    Results.Ok(new { uf, aliquota = catalogo.ObterAliquota(uf) }));

app.Run();

E a classe fica mais limpa, porque ela não é mais responsável pelo próprio ciclo de vida:

// A classe não precisa mais de campo estático nem construtor privado:
// o ciclo de vida é responsabilidade do container
public sealed class CatalogoAliquotas
{
    private readonly IReadOnlyDictionary<string, decimal> _aliquotas;

    private CatalogoAliquotas(IReadOnlyDictionary<string, decimal> aliquotas) =>
        _aliquotas = aliquotas;

    public static CatalogoAliquotas CarregarDe(string caminhoArquivo)
    {
        var json = File.ReadAllText(caminhoArquivo);
        var dados = JsonSerializer.Deserialize<Dictionary<string, decimal>>(json)
            ?? throw new InvalidOperationException(
                $"Arquivo {caminhoArquivo} vazio ou inválido");

        return new CatalogoAliquotas(dados);
    }

    public decimal ObterAliquota(string uf) =>
        _aliquotas.TryGetValue(uf, out var aliquota)
            ? aliquota
            : throw new KeyNotFoundException($"UF desconhecida: {uf}");
}

O AddSingleton garante uma única instância para toda a aplicação, com a mesma segurança de thread do Lazy<T>, mas com uma vantagem decisiva: o CatalogoAliquotas chega ao endpoint como parâmetro, injetado, e não como uma chamada a uma propriedade estática global. A diferença parece cosmética e não é, como a próxima seção explica.

Quando não usar: o lado escuro do padrão

O Singleton é o padrão mais criticado do catálogo GoF, e a crítica é justa. O problema não é a unicidade, é o acoplamento que o acesso global estático arrasta junto.

Testabilidade comprometida. Uma classe que chama CatalogoAliquotas.Instancia lá dentro tem uma dependência invisível e impossível de substituir. No teste, você não consegue injetar um catálogo falso com alíquotas controladas, porque a dependência não passa por lugar nenhum que você possa interceptar. Ela está soldada ao código estático. Compare com a versão via DI: ali o catálogo é um parâmetro, e no teste você passa a implementação que quiser.

Estado global disfarçado. Um Singleton é uma variável global com um paletó. Todo o problema que aprendemos a temer em variáveis globais continua ali: qualquer parte do sistema pode depender dele, mudanças no seu estado afetam todo mundo de forma difícil de rastrear, e a ordem de inicialização vira um campo minado quando um Singleton depende de outro.

Acoplamento oculto. As dependências de um método deveriam estar visíveis na sua assinatura. Quando um método usa três Singletons por dentro, a assinatura mente: ela diz que o método não precisa de nada, quando na verdade precisa de três coisas. Isso torna o código mais difícil de entender e de refatorar.

Nota: o Singleton também é traiçoeiro em cenários de concorrência quando carrega estado mutável. Se dois requests escrevem no mesmo Singleton sem sincronização, você tem uma race condition clássica. Se sincroniza, cria um gargalo onde todas as threads se enfileiram. O Singleton seguro é o imutável, e imutabilidade é uma disciplina, não um padrão que se ativa sozinho.

Some tudo e chega a uma regra prática. Você quase nunca precisa do padrão Singleton escrito à mão. Precisa é do ciclo de vida singleton, e esse o container de DI entrega sem nenhum dos malefícios acima:

Use o AddSingleton do container quando: você está numa aplicação ASP.NET Core ou em qualquer host com DI, o que hoje é o caso normal. Você ganha a instância única, a segurança de thread e a testabilidade, tudo de graça.

Use o Singleton clássico com Lazy<T> quando: você está numa biblioteca sem acesso a um container, ou num utilitário estático genuíno sem dependências, ou num ponto de entrada onde a DI ainda não subiu. São casos reais, mas são a minoria.

Não use nenhum dos dois quando: o objeto tem estado mutável por request, precisa de tempo de vida diferente em contextos diferentes, ou você está alcançando o global só para evitar passar um parâmetro. Esse último caso é o mais comum e o mais danoso: o Singleton vira desculpa para não pensar no fluxo de dependências.

Conclusão

O Singleton é uma solução elegante para um problema real: garantir uma instância única e cara de criar. A implementação correta em C# moderno não é difícil, porque o Lazy<T> embrulha toda a sutileza de thread safety que a versão ingênua erra, entregando a melhor performance com o código mais simples.

O que é difícil no Singleton não é fazê-lo funcionar, é decidir se você deveria usá-lo. Os detalhes que importam ficam quase todos na fronteira: o volatile no double-checked locking, a imutabilidade obrigatória do estado compartilhado, o acoplamento estático que envenena os testes. Acertar a mecânica é a parte fácil, resistir ao uso indevido é a parte difícil.

O trade-off, no fim, é entre conveniência e desenho. O acesso global estático é conveniente hoje e caro amanhã, quando você tenta testar, refatorar ou evoluir. Em .NET moderno, o container de DI resolve a unicidade sem cobrar esse preço, e é por isso que o AddSingleton deveria ser o seu reflexo antes de escrever private static instância.

Na próxima vez que você for criar um campo estático para guardar a única instância de algo, pare um segundo e pergunte se um AddSingleton não resolveria melhor. Na maioria das vezes, o melhor Singleton é aquele que você não escreve.

No próximo artigo da série, vamos ao Factory Method, o padrão que resolve o problema oposto: quando você precisa criar objetos mas não quer decidir agora qual classe concreta instanciar.

Backpressure sem drama: pipelines in-process com System.Threading.Channels

Cristiano Rodrigues — Fri, 03 Jul 2026 11:48:26 +0000

Passar dados de quem produz para quem consome dentro do mesmo processo parece o problema mais simples da computação concorrente. Uma fila no meio, um lock para proteger, pronto. Mas essa simplicidade é uma armadilha: o problema real não é mover os dados, é decidir o que acontece quando o produtor é mais rápido que o consumidor. Esse fenômeno tem nome, backpressure, e é ele que derruba serviços em produção às três da manhã.

Como você segura uma API que recebe 5.000 eventos por segundo quando o consumidor só consegue gravar 2.000 por segundo no banco? Deixa a fila crescer até estourar a memória? Bloqueia a thread do request? Descarta eventos em silêncio?

A equipe do .NET enfrentou exatamente esse dilema ao construir a infraestrutura do ASP.NET Core e do SignalR, e a resposta se chama System.Threading.Channels: nasceu como pacote NuGet em 2018, na época do .NET Core 2.1, e entrou no shared framework no .NET Core 3.0. Não é uma biblioteca de terceiros: é mantida pelo time do runtime e usada internamente por componentes da própria plataforma, do SignalR ao Kestrel. Hoje, no .NET 10, ela é a peça padrão para pipelines in-process, com direito a melhorias de runtime que aceleram seu código sem você mudar uma linha.

Vamos entender por que as soluções óbvias falham, como um Channel funciona por dentro e como levar isso para produção com backpressure tratado como cidadão de primeira classe.

O problema em detalhe: por que as soluções óbvias falham

Antes de aceitar uma abstração nova, vale esgotar as alternativas que todo mundo tenta primeiro.

Queue<T> + lock: a implementação manual. Funciona no teste local com um produtor e um consumidor. Em produção, o consumidor precisa fazer polling (dormir, acordar, checar a fila, dormir de novo), o que desperdiça CPU quando a fila está vazia e adiciona latência quando ela está cheia. E não existe nenhum mecanismo para segurar o produtor: a fila cresce sem limite.

ConcurrentQueue<T>: resolve o lock, não resolve o resto. Continua sem sinalização assíncrona (o consumidor ainda faz polling com TryDequeue num loop) e continua sem limite de capacidade. Você trocou um problema de sincronização por um problema de coordenação.

BlockingCollection<T>: finalmente tem capacidade limitada e bloqueia o produtor quando enche. O defeito é a palavra "bloqueia": Add e Take seguram uma thread inteira do thread pool enquanto esperam. Num servidor ASP.NET Core com 200 requests concorrentes esperando espaço na fila, são 200 threads paradas. Threads são caras (cerca de 1 MB de stack cada) e o thread pool leva tempo para injetar novas. É a receita clássica de thread starvation.

Fila externa (RabbitMQ, Redis, Kafka): resolve backpressure e ainda dá durabilidade, mas ao custo de uma viagem de rede por mensagem, serialização, infraestrutura para operar e um novo ponto de falha. Para comunicação entre serviços, é a escolha certa. Para passar trabalho entre duas partes do mesmo processo, é adicionar rede, operação e um novo modo de falha a um problema que acontece inteiramente dentro do processo.

Repare no padrão: cada alternativa resolve um pedaço e deixa outro exposto. O que falta é uma estrutura que seja assíncrona de ponta a ponta, tenha capacidade limitada e trate a fila cheia como um evento esperado, não como uma exceção.

Anatomia de um Channel

Um Channel<T> é duas metades coladas numa estrutura só:

ChannelWriter<T>: o lado do produtor. Expõe WriteAsync (escreve, aguardando se preciso), TryWrite (tenta escrever sem esperar), WaitToWriteAsync (aguarda até haver espaço, sem escrever) e Complete (sinaliza o fim).

ChannelReader<T>: o lado do consumidor. Expõe ReadAsync, TryRead, WaitToReadAsync e o mais elegante de todos, ReadAllAsync, que devolve um IAsyncEnumerable<T>.

Os pares Try/Wait merecem um comentário, porque são o caminho de alto desempenho. TryRead devolve um item de forma síncrona se houver um disponível, sem criar nenhuma operação assíncrona. O padrão clássico de consumidor eficiente combina os dois: aguarde com WaitToReadAsync e, quando houver sinal, drene tudo que estiver no buffer com TryRead num loop apertado antes de voltar a esperar. Do lado do produtor, WaitToWriteAsync seguido de TryWrite cumpre o mesmo papel. E todos os métodos assíncronos (WriteAsync, ReadAsync, WaitToReadAsync, ReadAllAsync) aceitam CancellationToken, o que vai ser essencial quando chegarmos no shutdown.

A decisão mais importante você toma na criação, escolhendo entre três fábricas:

// Sem limite: nunca segura o produtor, memória é o limite
var unbounded = Channel.CreateUnbounded<TelemetryEvent>();

// Com limite: aqui mora o backpressure
var bounded = Channel.CreateBounded<TelemetryEvent>(
    new BoundedChannelOptions(capacity: 1_000)
    {
        FullMode = BoundedChannelFullMode.Wait
    });

// Com prioridade: itens "menores" saem primeiro (API adicionada no .NET 9)
var prioritized = Channel.CreateUnboundedPrioritized<TelemetryEvent>();

Vamos focar nas duas primeiras agora e voltar à variante priorizada mais adiante, depois de entender performance.

O FullMode do canal bounded é literalmente a sua política de backpressure escrita em código:

Wait: o produtor espera (de forma assíncrona, sem bloquear thread) até abrir espaço. É a escolha padrão quando nenhum dado pode ser perdido.

DropOldest: descarta o item mais antigo para abrir espaço. Perfeito para telemetria de posição: se o buffer encheu, a coordenada de 10 segundos atrás vale menos que a atual.

DropNewest: descarta o item mais recente já enfileirado.

DropWrite: descarta o item que está tentando entrar.

Vamos acompanhar passo a passo o que acontece num canal bounded de capacidade 3 com FullMode.Wait, um produtor rápido e um consumidor lento:

Tempo	Produtor	Consumidor	Itens no buffer
t0	`WriteAsync(A)` completa síncrono	ocupado	A
t1	`WriteAsync(B)` completa síncrono	ocupado	A, B
t2	`WriteAsync(C)` completa síncrono	ocupado	A, B, C
t3	`WriteAsync(D)` retorna ValueTask pendente	ocupado	A, B, C
t4	ainda aguardando, sem thread presa	`ReadAsync()` consome A	B, C
t5	continuação dispara, D entra	processando A	B, C, D

O mesmo fluxo, desenhado:

Repare no que acontece em t3 e t4: o produtor não travou uma thread, ele devolveu uma ValueTask incompleta e liberou a thread para outro trabalho. Quando o consumidor abriu espaço, o runtime agendou a continuação. Isso é backpressure assíncrono: a velocidade do consumidor se propaga naturalmente para o produtor, sem polling, sem thread bloqueada, sem fila infinita.

Por que funciona

A elegância do Channel está em três decisões de design:

Async nativo, não adaptado. WriteAsync e ReadAsync devolvem ValueTask, e a escolha desse tipo não é cosmética. No caminho mais comum (há espaço no buffer, há um item disponível), a operação completa imediatamente, e a ValueTask permite devolver esse resultado sem alocar um objeto Task no heap. Só quando existe espera real a operação vira assíncrona de fato, e mesmo aí as implementações atuais reutilizam os objetos de espera. O resultado é pressão quase nula no GC no caminho feliz.

Backpressure é configuração, não código. Nas soluções manuais, a política de fila cheia fica espalhada em ifs pelo código do produtor. No Channel, ela é declarada uma vez, na criação, e vale para todos os produtores.

Separação de leitura e escrita no sistema de tipos. Você injeta ChannelWriter<T> no produtor e ChannelReader<T> no consumidor. O compilador garante que o controller não consegue consumir a fila e o worker não consegue escrever nela. Arquitetura imposta por tipo, não por convenção.

O que acontece por baixo dos panos

Vale abrir o capô, porque é aí que mora a explicação da performance. Um aviso honesto antes: os detalhes a seguir descrevem as implementações atuais do runtime, que não fazem parte do contrato público da API e podem mudar entre versões. Os princípios, porém, são estáveis.

O buffer do canal unbounded é uma fila concorrente segmentada. Nas implementações atuais, é a mesma estrutura da ConcurrentQueue<T>: uma lista de segmentos (blocos contíguos de memória) com enqueue e dequeue lock-free na maioria dos caminhos. Itens vizinhos ficam próximos em memória, o que melhora a localidade de cache em relação a estruturas concorrentes baseadas em nós encadeados.

O buffer do canal bounded é um deque sobre array circular, protegido por um lock de curtíssima duração. Parece um retrocesso em relação ao lock-free, mas não é: o lock cobre apenas algumas instruções (inserir num array, remover, checar capacidade) e nunca é mantido durante uma espera. É uma contenção de outra natureza, e de outro custo, comparada a alternativas que bloqueiam threads inteiras enquanto aguardam espaço.

A espera é uma lista de awaiters reutilizáveis. Quando um consumidor chama ReadAsync num canal vazio, o Channel não cria uma Task: ele registra um objeto interno (AsyncOperation, que implementa IValueTaskSource) numa lista de leitores pendentes. Quando um produtor escreve, ele completa diretamente o awaiter do primeiro leitor da fila, muitas vezes entregando o item sem sequer passar pelo buffer. Esses objetos de espera são reaproveitados entre operações, e é por isso que o benchmark mais adiante mostra alocação em kilobytes, não megabytes.

As flags escolhem implementações especializadas. SingleReader = true num canal unbounded troca a implementação inteira por uma classe dedicada ao cenário de consumidor único, que mantém um único awaiter cacheado em vez de uma fila deles. Combinada com SingleWriter, você chega no clássico SPSC (Single Producer Single Consumer), o cenário em que quase toda sincronização pode ser eliminada.

Em resumo: o Channel é rápido porque quase nunca aloca, quase nunca bloqueia e escolhe o algoritmo certo para as promessas que você faz na criação.

Implementação: do básico ao pipeline

O padrão mínimo, completo e funcional:

using System.Threading.Channels;

var channel = Channel.CreateBounded<int>(new BoundedChannelOptions(100)
{
    FullMode = BoundedChannelFullMode.Wait
});

// Produtor
var producer = Task.Run(async () =>
{
    try
    {
        for (var i = 1; i <= 1_000; i++)
        {
            // Se o buffer estiver cheio, aguarda sem bloquear thread
            await channel.Writer.WriteAsync(i);
        }

        // Sinaliza que não vem mais nada: sem isso, o consumidor espera para sempre
        channel.Writer.Complete();
    }
    catch (Exception ex)
    {
        // Propaga a falha: o await foreach do consumidor vai relançá-la
        channel.Writer.Complete(ex);
    }
});

// Consumidor
var consumer = Task.Run(async () =>
{
    // ReadAllAsync encerra o loop quando o writer chama Complete()
    // e relança a exceção se o writer chamou Complete(ex)
    await foreach (var item in channel.Reader.ReadAllAsync())
    {
        await ProcessAsync(item);
    }
});

await Task.WhenAll(producer, consumer);

O Complete() merece atenção: ele é o encerramento gracioso do pipeline. Quando o produtor termina, o ReadAllAsync do consumidor drena o que restou no buffer e o await foreach termina sozinho. E a sobrecarga Complete(exception) é uma funcionalidade pouco conhecida e muito útil: a exceção atravessa o canal e ressurge no consumidor, no ponto onde ele estava lendo. O erro do produtor não morre num log esquecido, ele chega em quem precisa reagir.

Dois parentes do Complete valem registro. TryComplete() faz o mesmo sem lançar exceção se o canal já foi completado, o que é essencial quando vários produtores podem disputar o encerramento. E do outro lado, Reader.Completion é uma Task que completa quando o canal terminou de verdade (writer completou e o buffer foi drenado), falhando com a exceção original se o encerramento veio de Complete(ex). Um await channel.Reader.Completion é a forma limpa de esperar o fim de um pipeline sem ser o consumidor dele.

E quando o throughput importa de verdade, o consumidor eficiente usa o padrão Wait + drenagem:

// Aguarda haver dados, depois drena tudo de forma síncrona
while (await channel.Reader.WaitToReadAsync(ct))
{
    while (channel.Reader.TryRead(out var item))
    {
        await ProcessAsync(item);
    }
}

A diferença para o await foreach é sutil mas real: dentro do loop interno, TryRead consome itens já disponíveis sem criar nenhuma operação assíncrona. Só quando o buffer esvazia o código volta a esperar.

Integração real: fila de trabalho em ASP.NET Core

O caso de uso mais comum em produção: um endpoint precisa disparar trabalho pesado (enviar e-mail, processar imagem, gravar auditoria) sem segurar o request. Vamos montar a versão completa, com o Channel como fila e um BackgroundService como consumidor. A arquitetura inteira cabe num desenho:

Primeiro, os tipos que circulam pelo pipeline:

public sealed record SignupRequest(string Email);

public sealed record EmailJob(string Email)
{
    public Guid Id { get; } = Guid.NewGuid();
}

Em seguida, a fila como um serviço com contrato explícito:

public sealed class WorkQueue<T>
{
    private readonly Channel<T> _channel;

    public WorkQueue(int capacity)
    {
        if (capacity <= 0)
            throw new ArgumentOutOfRangeException(nameof(capacity));

        _channel = Channel.CreateBounded<T>(new BoundedChannelOptions(capacity)
        {
            FullMode = BoundedChannelFullMode.Wait,
            SingleReader = true,   // um único BackgroundService consome
            SingleWriter = false   // vários requests produzem
        });
    }

    public ValueTask EnqueueAsync(T item, CancellationToken ct = default)
        => _channel.Writer.WriteAsync(item, ct);

    public bool TryEnqueue(T item)
        => _channel.Writer.TryWrite(item);

    public IAsyncEnumerable<T> DequeueAllAsync(CancellationToken ct = default)
        => _channel.Reader.ReadAllAsync(ct);
}

O consumidor, como BackgroundService:

public sealed class EmailWorker : BackgroundService
{
    private readonly WorkQueue<EmailJob> _queue;
    private readonly ILogger<EmailWorker> _logger;

    public EmailWorker(WorkQueue<EmailJob> queue, ILogger<EmailWorker> logger)
    {
        _queue = queue;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var job in _queue.DequeueAllAsync(stoppingToken))
        {
            try
            {
                await SendAsync(job, stoppingToken);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                // Uma falha de item não pode derrubar o pipeline inteiro
                _logger.LogError(ex, "Falha ao processar job {JobId}", job.Id);
            }
        }
    }

    private Task SendAsync(EmailJob job, CancellationToken ct)
        => Task.Delay(50, ct); // aqui entra o envio real
}

E o registro no Program.cs:

builder.Services.AddSingleton(new WorkQueue<EmailJob>(capacity: 5_000));
builder.Services.AddHostedService<EmailWorker>();

No endpoint, você decide a política de sobrecarga de forma explícita:

app.MapPost("/signup", (SignupRequest req, WorkQueue<EmailJob> queue) =>
{
    // TryEnqueue: se a fila está cheia, o sistema está sobrecarregado.
    // Melhor responder 503 agora do que travar o request esperando.
    if (!queue.TryEnqueue(new EmailJob(req.Email)))
        return Results.StatusCode(StatusCodes.Status503ServiceUnavailable);

    return Results.Accepted();
});

Repare na decisão: em vez de await EnqueueAsync (que seguraria o request sob sobrecarga), o endpoint usa TryWrite e devolve 503. A fila cheia deixou de ser um acidente e virou um sinal de load shedding. Isso é backpressure chegando até o cliente HTTP, que é exatamente onde ele deve chegar.

O CancellationToken que atravessa todo esse código não é decoração. É ele que conecta o pipeline ao ciclo de vida do host: quando o ASP.NET Core inicia o shutdown, o stoppingToken dispara, o ReadAllAsync é cancelado e o worker encerra de forma cooperativa em vez de ser morto no meio de um job.

Vale ainda situar o Channel no ecossistema: ele aparece com frequência ao lado de System.IO.Pipelines. Enquanto o PipeReader resolve o fluxo eficiente de bytes entre um socket e um parser, o Channel<T> resolve o fluxo de objetos entre produtores e consumidores dentro da aplicação. Um pipeline de rede típico lê bytes com PipeReader, converte em mensagens tipadas e as publica num Channel<T> para processamento assíncrono. As duas peças resolvem o mesmo problema conceitual (backpressure) em camadas diferentes: bytes numa, objetos na outra.

Nota: essa fila vive na memória do processo. Se o pod reiniciar num deploy, tudo que estava no buffer se perde. Para e-mail de boas-vindas, tolerável. Para cobrança, inaceitável: aí a fila certa é durável (RabbitMQ, Azure Service Bus, Kafka). Channel não substitui message broker, ele resolve outro problema.

Alta performance: as opções que a maioria ignora

Depois do pipeline funcionando, vale extrair o máximo. UnboundedChannelOptions e BoundedChannelOptions têm três flags que mudam o código que o runtime escolhe por baixo:

SingleReader = true: promete que só um consumidor lê por vez. Como vimos nos internals, no canal unbounded o runtime troca a implementação por uma versão especializada com um único awaiter cacheado. No canal bounded as flags não trocam a implementação, e o benchmark logo abaixo mostra essa diferença na prática.

SingleWriter = true: a promessa equivalente do lado do produtor. As duas juntas configuram o cenário SPSC (Single Producer Single Consumer), que dispensa boa parte da sincronização exigida pelas implementações gerais.

AllowSynchronousContinuations = true: permite que a continuação do consumidor rode na thread do produtor, eliminando um hop de agendamento. Ganha latência, mas o produtor passa a executar código do consumidor. Use apenas quando você controla os dois lados e o trabalho do consumidor é curto.

E é com dados que comprovamos o ganho. Vamos medir em duas etapas: primeiro o pipeline completo, como ele roda em produção, depois a estrutura de dados isolada.

Benchmark 1: o pipeline completo

BenchmarkDotNet, movendo 100.000 inteiros de um produtor para um consumidor em tasks separadas:

[MemoryDiagnoser]
public class QueueBenchmarks
{
    private const int N = 100_000;

    [Benchmark(Baseline = true)]
    public async Task Channel_Bounded_Default()
        => await RunChannelAsync(Channel.CreateBounded<int>(
            new BoundedChannelOptions(1_000)));

    [Benchmark]
    public async Task Channel_Bounded_SingleReaderWriter()
        => await RunChannelAsync(Channel.CreateBounded<int>(
            new BoundedChannelOptions(1_000)
            {
                SingleReader = true,
                SingleWriter = true
            }));

    [Benchmark]
    public async Task BlockingCollection_Bounded()
    {
        // async e await aqui são obrigatórios: o using só pode
        // descartar a collection depois que as tasks terminarem
        using var collection = new BlockingCollection<int>(1_000);

        var producer = Task.Run(() =>
        {
            for (var i = 0; i < N; i++)
                collection.Add(i);
            collection.CompleteAdding();
        });

        var consumer = Task.Run(() =>
        {
            foreach (var _ in collection.GetConsumingEnumerable()) { }
        });

        await Task.WhenAll(producer, consumer);
    }

    private static async Task RunChannelAsync(Channel<int> channel)
    {
        var producer = Task.Run(async () =>
        {
            for (var i = 0; i < N; i++)
                await channel.Writer.WriteAsync(i);
            channel.Writer.Complete();
        });

        var consumer = Task.Run(async () =>
        {
            await foreach (var _ in channel.Reader.ReadAllAsync()) { }
        });

        await Task.WhenAll(producer, consumer);
    }
}

Resultados na minha máquina (os números absolutos variam com o hardware, a proporção é o que importa). Ambiente: Apple M4 Pro (14 núcleos), macOS Tahoe 26.5.1, .NET 10.0.9 (Arm64 RyuJIT), BenchmarkDotNet v0.15.8:

Método	Média	Ratio	Alocação
Channel_Bounded_Default	3,43 ms	1,00	10,31 KB
Channel_Bounded_SingleReaderWriter	3,47 ms	1,01	10,3 KB
BlockingCollection_Bounded	20,02 ms	5,85	22,98 KB

A leitura tem duas partes, e uma delas contraria a intuição. A primeira é a esperada: o Channel foi quase 6 vezes mais rápido que BlockingCollection, alocou menos da metade e não bloqueou nenhuma thread no caminho. Os 10 KB para mover 100.000 itens confirmam o que os internals prometeram: no caminho feliz, ValueTask completa síncrono, os awaiters são reutilizados e quase nada vai para o heap.

A segunda parte é a surpresa: SingleReader/SingleWriter não mudou nada, e isso não é erro de medição. Como vimos nos internals, a implementação especializada existe para o canal unbounded. No canal bounded, as flags não trocam a implementação, e o custo deste pipeline é dominado pelo agendamento entre threads, não pela estrutura de dados. Benchmark serve exatamente para isso: corrigir a intuição antes que ela vire decisão de arquitetura.

Nota: sobre metodologia. Esse benchmark mede o pipeline completo, incluindo Task.Run, o agendamento no thread pool e o custo do scheduler, porque é isso que você paga em produção. É uma medida honesta do cenário real, mas não isola o custo do Channel em si. Para isso, o segundo benchmark.

Benchmark 2: isolando a estrutura de dados

Aqui, uma única thread alterna escrita e leitura. Como sempre há espaço no buffer e sempre há um item disponível, toda operação completa de forma síncrona: o que sobra é o custo puro da estrutura, sem scheduler no caminho.

[Benchmark]
public async Task Channel_SingleThread_Default()
{
    var channel = Channel.CreateBounded<int>(new BoundedChannelOptions(8));

    for (var i = 0; i < N; i++)
    {
        // Ambas completam síncrono: não há espera real
        await channel.Writer.WriteAsync(i);
        _ = await channel.Reader.ReadAsync();
    }
}

[Benchmark]
public async Task Channel_SingleThread_SingleReaderWriter()
{
    var channel = Channel.CreateBounded<int>(new BoundedChannelOptions(8)
    {
        SingleReader = true,
        SingleWriter = true
    });

    for (var i = 0; i < N; i++)
    {
        await channel.Writer.WriteAsync(i);
        _ = await channel.Reader.ReadAsync();
    }
}

Método	Média	Alocação
Channel_SingleThread_Default	1,29 ms	760 B
Channel_SingleThread_SingleReaderWriter	1,30 ms	760 B

O empate entre as duas variantes se repete, pelo mesmo motivo do primeiro benchmark: canal bounded, mesma implementação, flags sem efeito. E a comparação entre os dois benchmarks conta a história completa: dos 3,4 ms do pipeline concorrente, pouco mais de um terço (1,3 ms) é o Channel em si. O resto é agendamento, thread pool e a concorrência real entre produtor e consumidor. E os 760 bytes para 200.000 operações (100.000 pares de write e read) confirmam na prática o que os internals prometeram: no caminho síncrono, praticamente nada vai para o heap.

E aqui entra o contexto de versão: no .NET 10, melhorias no ThreadPool (como o escape de work items da fila local quando uma thread bloqueia) e otimizações em Task beneficiam pipelines com Channels sem nenhuma mudança no seu código. É o tipo de ganho que você colhe só por atualizar o TargetFramework.

Nota: só ative SingleReader/SingleWriter se a promessa for verdadeira. As flags não são validadas em todos os caminhos: dois consumidores num canal SingleReader produzem comportamento indefinido, do tipo que passa no teste e corrompe estado em produção.

Outras variantes: o canal com prioridade

Com o modelo de performance em mãos, vale voltar à terceira fábrica. Nem toda fila é justa de propósito: numa fila de notificações, o alerta de segurança precisa furar a fila da newsletter. O Channel.CreateUnboundedPrioritized<T>, adicionado no .NET 9 e presente no .NET 10, resolve isso trocando o buffer FIFO por uma PriorityQueue<T> interna: o ReadAsync sempre entrega o menor item segundo o comparador.

public sealed record Notification(int Priority, string Message);

var channel = Channel.CreateUnboundedPrioritized<Notification>(
    new UnboundedPrioritizedChannelOptions<Notification>
    {
        // Menor prioridade numérica sai primeiro
        Comparer = Comparer<Notification>.Create(
            static (a, b) => a.Priority.CompareTo(b.Priority))
    });

await channel.Writer.WriteAsync(new(3, "Newsletter semanal"));
await channel.Writer.WriteAsync(new(1, "Alerta de segurança"));
await channel.Writer.WriteAsync(new(2, "Fatura disponível"));

// Sai: Alerta de segurança, Fatura disponível, Newsletter semanal

Os casos de uso naturais: filas de notificação com níveis de severidade, jobs de clientes premium à frente dos demais, retries reagendados atrás do trabalho novo.

A prioridade tem preço, e ele é conhecido: enfileirar e desenfileirar num heap custa O(log n), contra O(1) do buffer FIFO. Para filas de milhares de itens é irrelevante, mas num hot path de milhões de operações por segundo a diferença aparece, e o benchmark decide.

Nota: a priorização vale apenas entre os itens que estão no buffer naquele momento, e itens de prioridade igual não têm ordem FIFO garantida (a PriorityQueue do .NET não é estável). Se a ordem de chegada importa dentro da mesma prioridade, inclua um número de sequência no comparador.

Quando escolher cada um

Aspecto	Channel	BlockingCollection	TPL Dataflow	Fila externa	Pipelines
Unidade de trabalho	Objetos	Objetos	Objetos	Mensagens	Bytes
Backpressure assíncrono	Nativo	Não (bloqueia thread)	Nativo	Nativo	Nativo
Alocação no caminho feliz	Quase zero	Alta	Média	Alta (rede + serialização)	Quase zero
Sobrevive a restart	Não	Não	Não	Sim	Não
Pipelines multi-estágio	Manual	Manual	Nativo	Nativo	Manual
Complexidade operacional	Nenhuma	Nenhuma	Baixa	Alta	Nenhuma

Escolha Channel quando:

Produtor e consumidor vivem no mesmo processo
Você precisa de backpressure sem bloquear threads
Perder o buffer num restart é aceitável ou mitigável
Throughput e alocação importam

Escolha TPL Dataflow quando:

O pipeline tem muitos estágios com transformação, broadcast e agregação, e você quer isso declarativo

Escolha uma fila externa quando:

As mensagens precisam sobreviver a deploy e crash
Produtor e consumidor são serviços diferentes
Você precisa de reprocessamento, DLQ e auditoria

Escolha System.IO.Pipelines quando:

O fluxo é de bytes, não de objetos: parsing de protocolo, leitura de socket, streaming de arquivo. Pipelines e Channels não competem, se complementam.

Fique longe de BlockingCollection quando:

O código é assíncrono. Num servidor ASP.NET Core, cada Add ou Take bloqueado é uma thread do pool fora de combate.

Erros comuns

A lista de verificação antes de mandar um Channel para produção:

Usar CreateUnbounded sem monitoramento: todo canal ilimitado merece uma métrica de profundidade e um alerta.

Esquecer Complete(): o consumidor fica preso no await foreach para sempre.

Ignorar CancellationToken: sem ele, o shutdown do host vira um kill disfarçado.

Mentir nas flags: SingleReader com dois consumidores é comportamento indefinido.

Bloquear dentro do consumidor: chamar .Result ou .Wait() no worker reintroduz exatamente o problema de thread que o Channel eliminou.

Trabalho pesado e serial no consumidor único: se o processamento é lento, um SingleReader vira o gargalo. Escale com múltiplos consumidores (e SingleReader = false) ou paralelize dentro do worker.

Usar Channel entre processos: ele é uma estrutura de memória. Entre processos ou serviços, a resposta é IPC ou message broker.

Considerações e limitações

Honestidade sobre o que dói em produção, agora em detalhe:

Nota: Channel.CreateUnbounded é o vazamento de memória mais educado do .NET. Ele nunca falha, nunca avisa, só cresce. Todo unbounded em produção merece uma métrica de profundidade da fila (um contador que você incrementa no write e decrementa no read) e um alerta. Se você não consegue justificar por que o canal precisa ser ilimitado, ele deve ser bounded.

Nota: esquecer Complete() é o deadlock mais comum com Channels: o consumidor fica preso no await foreach para sempre e o BackgroundService nunca encerra, segurando o shutdown do host até o timeout. Trate Complete() como você trata Dispose(): parte do contrato, não cortesia.

Nota: o graceful shutdown merece desenho. Quando o stoppingToken dispara, ReadAllAsync lança OperationCanceledException e o que estava no buffer morre com o processo. Se esses itens importam, o padrão é: parar de aceitar escritas, chamar Complete(), e drenar o restante com um CancellationToken separado e um prazo (o ASP.NET Core dá 30 segundos por padrão, configuráveis via HostOptions.ShutdownTimeout). Reader.Completion é o sinal certo para saber que a drenagem terminou.

Nota: Channel distribui itens, não faz broadcast. Com dois consumidores no mesmo reader, cada item vai para um deles, nunca para os dois. Se você precisa que todo consumidor veja toda mensagem, o padrão é um canal por assinante, com um loop de fan-out no meio.

Conclusão

O Channel<T> é uma solução elegante para um problema que quase todo sistema tem e quase ninguém enxerga até doer: a diferença de velocidade entre quem produz e quem consome. A implementação não é difícil, mas os detalhes importam: escolher bounded com o FullMode certo, sinalizar Complete() sempre (e Complete(ex) quando algo falha), propagar CancellationToken de ponta a ponta, ativar SingleReader/SingleWriter só quando a promessa é verdadeira e desenhar o shutdown antes do primeiro deploy.

O trade-off central é claro: Channels compram throughput altíssimo e backpressure de graça ao custo de viverem na memória do processo. Quando a durabilidade importa mais que a latência, a fila externa vence. Quando o problema é in-process, o Channel é imbatível, e no .NET 10 ele fica mais rápido sem você fazer nada.

Na próxima vez que você se pegar escrevendo Queue<T> com lock e um Task.Delay de polling, pare e pense em Channels. Backpressure não é um bug para tratar, é um contrato para desenhar: sistemas resilientes não são os que nunca enchem, são os que sabem exatamente o que fazer quando enchem.

Referências

Documentação oficial de System.Threading.Channels: https://learn.microsoft.com/dotnet/core/extensions/channels
Stephen Toub, "An Introduction to System.Threading.Channels", .NET Blog: https://devblogs.microsoft.com/dotnet/an-introduction-to-system-threading-channels/
Código-fonte da biblioteca no runtime: https://github.com/dotnet/runtime/tree/main/src/libraries/System.Threading.Channels
Documentação de System.IO.Pipelines: https://learn.microsoft.com/dotnet/standard/io/pipelines

Gerenciando Feature Flags no Azure App Configuration com Minimal APIs em .NET

Cristiano Rodrigues — Wed, 01 Jul 2026 16:00:06 +0000

Antes de configurar, vale alinhar o que é o Azure App Configuration. Ele é um serviço gerenciado da Azure para centralizar configurações e Feature Flags fora do binário da aplicação. A diferença prática em relação ao appsettings.json é direta: você altera um valor no portal e todas as instâncias passam a enxergar a mudança, sem rebuild e sem redeploy.

Em uma aplicação com vinte réplicas atrás de um load balancer, isso deixa de ser conveniência e vira a única forma sã de manter as flags coerentes entre todas elas. Editar vinte appsettings.json na mão, ou redistribuir o serviço inteiro só para virar uma flag, é exatamente a dor que esse serviço existe para resolver.

Como o `WithFeatureGate` funciona por dentro

Quando implementei o suporte ao WithFeatureGate para Minimal APIs, a meta não era criar uma API diferente da que já existia no MVC. Era preservar o mesmo modelo mental: quem já usava FeatureGateAttribute deveria migrar para Minimal APIs sem reaprender o conceito. Por isso a decisão de design foi apoiar tudo em endpoint filters, não em um middleware global.

E é aí que mora uma dúvida comum: existe um middleware verificando as flags em toda requisição? Não existe, e isso é proposital. O WithFeatureGate não registra nada no pipeline de middlewares. Ele instala um endpoint filter, que só roda quando aquela rota específica é selecionada pelo roteamento. Nenhuma requisição paga o custo de avaliar uma flag de um endpoint que ela nem acessou.

Vamos acompanhar o caminho de uma requisição passo a passo:

A avaliação é delegada à infraestrutura do Feature Management, implementada sobre IVariantFeatureManager, a interface atual da biblioteca. Um detalhe que vale registrar: o gate resolve especificamente o IVariantFeatureManagerSnapshot, e não o manager simples. Na prática, isso significa que, se o handler voltar a checar a mesma flag depois de passar pelo gate, ele enxerga o mesmo resultado, porque o snapshot congela a avaliação pelo tempo de vida da requisição. É o mesmo comportamento que detalho na seção de avaliação assíncrona.

Repare no que acontece quando a flag está desligada: o filtro encerra a requisição com 404, não com 403. A escolha é deliberada. Um 403 confirmaria que o endpoint existe e está apenas bloqueado. O 404 faz o recurso desaparecer do mapa, que é o comportamento esperado para uma funcionalidade que ainda não deveria ser visível. É o mesmo princípio do FeatureGateAttribute no MVC, onde o handler padrão de features desabilitadas também responde 404.

FeatureGate e autorização: quem decide primeiro

Cedo ou tarde você vai escrever isto:

app.MapGet("/api/relatorio", GerarRelatorio)
   .RequireAuthorization()
   .WithFeatureGate("RelatorioAvancado");

E a pergunta surge na hora: se um usuário não autenticado bater nesse endpoint com a flag desligada, o que ele recebe? 401? 403? 404? E mais: a ordem em que eu encadeio RequireAuthorization e WithFeatureGate muda o resultado?

A resposta tranquiliza, porque ela não depende da ordem do encadeamento. RequireAuthorization e WithFeatureGate atuam em estágios diferentes do pipeline. A autorização é um middleware, que roda logo depois do roteamento. O FeatureGate é um endpoint filter, que roda mais tarde, já dentro da execução do endpoint. Então a sequência real é sempre esta:

Na prática: um usuário sem credencial válida nunca chega a ser avaliado pela flag, ele leva 401 antes disso. Um usuário autenticado mas sem permissão leva 403, também antes da flag. Só quem passa pela autorização é que descobre, via 404, que a funcionalidade está desligada.

Nota: trocar a ordem para .WithFeatureGate(...).RequireAuthorization() não inverte nada. O middleware de autorização continua rodando antes do endpoint filter, porque essa precedência é definida pela posição de cada um no pipeline do ASP.NET Core, não pela ordem de chamada no builder. Tentar reordenar isso no fluent API é uma armadilha que rende horas de depuração.

A avaliação assíncrona das flags

A chamada IsEnabledAsync parece uma simples leitura de booleano, mas o Async no nome não é decorativo. Quando a flag tem filtros configurados, é nesse momento que cada um deles roda, e todos são assíncronos por natureza:

Nota: um filtro de Targeting pode consultar o HttpContext, e um filtro customizado seu pode bater em um banco ou em um cache distribuído. Por isso a avaliação é await de verdade, não açúcar sintático. Se você precisa que o resultado da flag não mude no meio de uma requisição, mesmo que a configuração seja atualizada nesse intervalo, use IVariantFeatureManagerSnapshot, que congela o primeiro valor avaliado pelo tempo de vida da requisição.

O "tempo real" do refresh, sem a ilusão

A promessa de mudar uma flag e ver o efeito sem redeploy é real, mas a expressão "tempo real" engana. O que existe por baixo é polling, não push. Vale entender o ciclo para não esperar do mecanismo algo que ele não faz:

O intervalo padrão de cache das Feature Flags é de trinta segundos, ajustável via SetRefreshInterval. O ponto fino é que o refresh não bloqueia a requisição que o disparou. Ela ainda serve o valor antigo, e a mudança aparece nas requisições seguintes. Para a maioria dos rollouts isso é mais do que suficiente, mas é bom saber que essa janela existe.

Nota: esse refresh automático vale apenas para Feature Flags, porque UseFeatureFlags() já as registra para atualização. Key-values comuns do App Configuration não herdam esse comportamento. Para eles você ainda precisa de ConfigureRefresh() e, em geral, de uma sentinel key para sinalizar quando recarregar. Misturar os dois modelos mentais é uma fonte clássica do "mas eu mudei a config e nada aconteceu".

Segurança: a role que todo mundo esquece

Um detalhe que derruba muita gente no primeiro deploy: a Managed Identity não nasce com permissão de leitura. Atribuir a identidade ao recurso não basta. Ela precisa da role App Configuration Data Reader no escopo do seu App Configuration. Sem ela, a aplicação autentica mas recebe um 403 ao tentar ler as configurações, e o erro nem sempre é óbvio no log.

Targeting na prática

O TargetingFilter é o único filtro embutido que não entra automaticamente, então lembre de registrá-lo:

builder.Services
    .AddFeatureManagement()
    .WithTargeting();

O WithTargeting() registra o filtro, mas ele não adivinha quem é o usuário sozinho. Ele depende de uma implementação de ITargetingContextAccessor, responsável por dizer ao filtro qual é o usuário atual e a quais grupos ele pertence. Em aplicações web, a biblioteca já traz um acessor padrão que extrai isso do HttpContext, então o WithTargeting() sem argumentos costuma bastar. Em cenários sem HttpContext, como um worker ou um console, é você quem precisa fornecer esse contexto.

Um exemplo torna o targeting concreto. Imagine liberar uma funcionalidade para dois usuários nomeados, para todo o grupo Ring0, para metade do grupo Ring1 e para uma fração pequena do restante:

{
  "id": "RelatorioAvancado",
  "enabled": true,
  "conditions": {
    "client_filters": [
      {
        "name": "Microsoft.Targeting",
        "parameters": {
          "Audience": {
            "Users": [ "ana", "bruno" ],
            "Groups": [
              { "Name": "Ring0", "RolloutPercentage": 100 },
              { "Name": "Ring1", "RolloutPercentage": 50 }
            ],
            "DefaultRolloutPercentage": 5
          }
        }
      }
    ]
  }
}

O caminho da avaliação fica assim:

Repare que a decisão é determinística por usuário. O mesmo usuário cai sempre no mesmo lado do percentil, porque o cálculo usa um hash estável do identificador. Um rollout de cinco por cento não sorteia gente nova a cada requisição, ele escolhe os mesmos cinco por cento de forma consistente. É isso que permite aumentar a fatia aos poucos sem nunca tirar o acesso de quem já estava dentro.

Do interruptor binário às variants

Tudo o que vimos até aqui trata a flag como um interruptor binário: ligada ou desligada. Mas o mesmo IVariantFeatureManager que avalia IsEnabledAsync também expõe GetVariantAsync, e é aí que mora o próximo nível. Em vez de responder apenas sim ou não, uma variant feature flag devolve uma configuração inteira, um tamanho, uma cor, um algoritmo, alocada por usuário, grupo ou percentil. É o que transforma Feature Flags em A/B testing de verdade. Fica para um próximo artigo, mas quando você cruzar com GetVariantAsync na assinatura de IVariantFeatureManager, já sabe de onde vem.

Quando NÃO usar Feature Flags

Feature Flags resolvem tão bem o problema de rollout que a tentação é usá-las para tudo. Vale traçar a fronteira, porque cada uso fora do propósito vira dívida técnica disfarçada de flexibilidade.

Evite Feature Flags para:

Autorização e permissões: decidir se um usuário pode acessar algo é papel do sistema de autorização, com claims e policies. Uma flag não conhece o usuário de forma estruturada, e tratar permissão como flag espalha regra de acesso por lugares que ninguém vai auditar.
Multi-tenancy: a separação entre tenants é arquitetura, não configuração. Resolver isso com uma flag por tenant não escala e abre brechas sutis de isolamento.
Configuração permanente: se um valor nunca vai voltar a mudar, ele não é uma flag, é uma constante ou uma configuração comum. Flag pressupõe que existe uma decisão de ligar e desligar.
Parâmetros de negócio: limites, taxas e prazos que mudam por regra de negócio pertencem ao domínio, não a um interruptor de release.

A regra que cabe em uma frase: Feature Flags servem para controlar a exposição de código ao longo do tempo, rollout e experimentação. No instante em que você usa uma para decidir quem pode o quê, ou para guardar um valor que define o comportamento do negócio, ela parou de ser uma flag e virou a ferramenta errada no lugar errado.

Conclusão

Fechamos o ciclo, do problema de separar deploy de lançamento até os detalhes de quem decide o quê dentro do pipeline. Vimos o Azure App Configuration centralizar as flags, o WithFeatureGate barrar o endpoint com um endpoint filter antes do handler, a autorização rodar antes dele, o refresh por polling com sua janela de trinta segundos, o targeting determinístico por usuário e a fronteira do que não deveria virar flag.

A implementação não é difícil, mas os detalhes importam, e quase todos eles moram fora do happy path: o 404 em vez de 403, a role de leitura que a Managed Identity não ganha de graça, o refresh que não é instantâneo e a tentação de resolver autorização com uma flag. Acertar esses pontos é o que separa o uso ingênuo do uso sólido.

No fundo, Feature Flags não servem só para esconder código novo. Elas separam a entrega técnica da decisão de negócio. O deploy continua sendo responsabilidade da engenharia, o momento do lançamento vira uma decisão operacional, e desligar uma funcionalidade deixa de ser um novo deploy para virar o toque de um botão.

Na próxima vez que você for amarrar o lançamento de uma feature ao próximo deploy, pare um instante: talvez o que falte não seja subir código mais rápido, e sim parar de subir código para tomar decisões que já poderiam ser apenas um clique.

Streaming de JSON no ASP.NET Core: o endpoint de ingestão que para de estourar a memória

Cristiano Rodrigues — Mon, 29 Jun 2026 10:03:48 +0000

Receber um array de JSON parece a operação mais banal do mundo. Você declara um List<T> no parâmetro, decora com [FromBody], e o ASP.NET Core entrega a coleção pronta. Funciona em todo tutorial, funciona no Postman, funciona no ambiente de desenvolvimento. Funciona até o dia em que um cliente manda cem mil objetos numa única requisição e o seu processo de 8 GB cai com OutOfMemoryException.

Como um único POST derruba um servidor inteiro? E por que trocar três linhas de código resolve o problema sem mexer numa vírgula da sua regra de negócio? O System.Text.Json ganhou no .NET 6 um método pouco usado, DeserializeAsyncEnumerable, que muda o momento em que os objetos passam a existir na memória. Vamos entender por que isso importa, medir o ganho com cuidado e, principalmente, ver onde essa abordagem cobra o seu preço.

O cenário concreto

Imagine um endpoint de ingestão. Um sistema parceiro consolida cadastros e, uma vez por hora, despeja tudo de uma vez:

[
  { "id": 1, "name": "Ana",   "email": "ana@exemplo.dev" },
  { "id": 2, "name": "Bruno", "email": "bruno@exemplo.dev" },
  ...
]

O modelo é trivial:

public sealed class Person
{
    public int Id { get; init; }

    [Required]
    [StringLength(120)]
    public string Name { get; init; } = string.Empty;

    [Required]
    [EmailAddress]
    public string Email { get; init; } = string.Empty;
}

E o endpoint que todo mundo escreve primeiro é este:

[ApiController]
[Route("people")]
public sealed class PeopleController : ControllerBase
{
    private readonly IPersonRepository _repository;

    public PeopleController(IPersonRepository repository)
        => _repository = repository;

    [HttpPost]
    public async Task<IActionResult> Ingest([FromBody] List<Person> people, CancellationToken ct)
    {
        foreach (var person in people)
            await _repository.InsertAsync(person, ct);

        return Ok(new { count = people.Count });
    }
}

Com mil objetos, ele voa. Com cem mil, ele engasga. Com um cliente mal comportado mandando lotes grandes em paralelo, ele leva o processo inteiro junto. A pergunta é por quê, e a resposta não é a óbvia.

O que realmente acontece com `[FromBody]`

Existe um mito de que o ASP.NET Core "recebe o corpo inteiro primeiro" e só depois começa a trabalhar. Não é bem assim, e a distinção importa.

O Kestrel lê o corpo da requisição direto do socket de forma incremental, em blocos, alimentando um PipeReader. Essa parte já é streaming desde sempre. O problema não está na leitura do socket.

O problema é o que vem depois. O input formatter de JSON chama JsonSerializer.DeserializeAsync<List<Person>> sobre esse stream. O desserializador consome o corpo em pequenos blocos, mas o objetivo dele é construir a List<Person> completa. Cada objeto do array vira uma instância viva, e todas permanecem vivas, porque a lista segura uma referência para cada uma delas. Só quando o último elemento é reconhecido e a lista está montada é que o seu método de action começa a rodar.

Resumindo a frase mais precisa que o seu mapa mental precisa guardar:

O corpo já é lido em streaming pelo servidor, mas o model binder precisa concluir a desserialização inteira e segurar a List<Person> completa na memória antes que a sua action execute.

O pico de memória é proporcional ao tamanho do payload, e você não tem nenhum controle sobre ele. Cem mil objetos viram cem mil instâncias vivas ao mesmo tempo, mais o array interno da lista, mais os buffers transitórios do parser. Multiplique isso por requisições concorrentes e você tem a receita do OutOfMemoryException.

Por que o streaming funciona

A virada de chave é JsonSerializer.DeserializeAsyncEnumerable<Person>. Ele lê exatamente o mesmo stream do corpo, em blocos, mas em vez de acumular tudo numa lista, ele devolve um IAsyncEnumerable<Person> e produz cada objeto conforme o parser o reconhece.

A diferença não está na lógica de negócio. Está no momento em que os objetos passam a existir na memória, e por quanto tempo eles permanecem vivos.

Quando você consome esse IAsyncEnumerable com await foreach e processa cada item sem guardá-lo, o objeto anterior fica elegível para coleta pelo GC no instante em que você avança para o próximo. Elegível não quer dizer coletado na hora, mas quer dizer que ele não impede mais a memória de ser reaproveitada. O conjunto de objetos vivos ao mesmo tempo deixa de crescer com o array e passa a ser um valor pequeno e aproximadamente constante.

Repare na palavra "aproximadamente". É honesto não vender mais do que se entrega. Mesmo em streaming, ao mesmo tempo existem na memória o buffer interno de leitura, o estado do Utf8JsonReader, os buffers do PipeReader, o objeto que está sendo construído e algumas strings temporárias. Não é literalmente um único objeto. É um número pequeno e constante de objetos vivos por vez, em vez de um número que cresce na proporção do payload. Essa é a propriedade que muda tudo.

Lado a lado, a diferença entre os dois caminhos fica visível. No tradicional, a List<Person> inteira precisa existir antes que a action comece:

, a requisição passa por Cliente, Kestrel, PipeReader e DeserializeAsync>, materializando os 100.000 objetos vivos numa List completa antes de a action executar, com a memória crescendo proporcionalmente ao payload. No fluxo streaming com DeserializeAsyncEnumerable, a mesma sequência termina em await foreach processando um item por vez, mantendo aproximadamente um lote vivo e memória constante independente do tamanho do payload." width="800" height="533">

À esquerda, todo o array vira objeto vivo antes do primeiro passo de processamento. À direita, cada objeto existe apenas durante o processamento daquele passo e, em seguida, torna-se elegível para coleta pelo GC.

Guarde esta frase, porque ela é a ponte para a seção de benchmark mais adiante: o número total de objetos criados é praticamente o mesmo nas duas abordagens. O que muda é quantos permanecem vivos ao mesmo tempo.

O detalhe que quase ninguém comenta: backpressure

O ganho de memória é o motivo mais citado, mas existe um segundo benefício que sustenta o primeiro: backpressure ponta a ponta.

Como o await foreach é pull-based, ninguém puxa o próximo item enquanto você não terminar de processar o atual. Quando o seu processamento aguarda algo lento, um await repository.InsertAsync(...), por exemplo, o desserializador simplesmente para de consumir o stream. Se ele para de consumir, o PipeReader para de ler, o Kestrel deixa de drenar o socket e a janela de recepção TCP fecha. O cliente é segurado na origem.

Com [FromBody] List<Person>, esse mecanismo não existe. O cliente despeja o payload inteiro o mais rápido que conseguir, e o servidor é obrigado a materializar tudo independente da velocidade com que você processa. Com streaming, a velocidade do seu processamento regula naturalmente a velocidade da ingestão, e isso limita a memória de ponta a ponta, não só na hora de parsear.

A implementação em streaming

Em Minimal APIs você pode vincular o corpo da requisição direto a um Stream ou a um PipeReader, o que deixa a assinatura limpa:

app.MapPost("/people/stream", async (
    Stream body,
    IPersonRepository repository,
    CancellationToken ct) =>
{
    var options = new JsonSerializerOptions(JsonSerializerDefaults.Web);

    var people = JsonSerializer.DeserializeAsyncEnumerable<Person>(body, options, ct);

    var count = 0;

    await foreach (var person in people)
    {
        if (person is null)
            continue;

        await repository.InsertAsync(person, ct);
        count++;
    }

    return Results.Ok(new { count });
});

Três pontos merecem atenção. O DeserializeAsyncEnumerable<Person> devolve Person?, porque um elemento do array pode ser null no JSON, então o if (person is null) não é paranoia. O CancellationToken é passado adiante, de modo que um cliente que desconecta interrompe a desserialização e o processamento, sem deixar trabalho órfão rodando. E a memória dessa action é praticamente plana, dez ou cem mil objetos, o consumo é o mesmo.

O streaming só vale se o processamento também for streaming

Aqui mora a armadilha que apaga todo o ganho. Se em algum ponto você reconstrói a lista, voltou à estaca zero:

// Anula o ganho: reconstroi a colecao inteira na memoria
var todos = new List<Person>();

await foreach (var person in people)
    todos.Add(person!);

await repository.InsertManyAsync(todos, ct);

Esse código usa DeserializeAsyncEnumerable, parece moderno, e não economiza um único byte de pico. Você trocou o List<Person> do model binder por um List<Person> montado na mão.

O caminho que mantém o ganho processa e descarta:

// Mantem o ganho: cada item e processado e descartado
await foreach (var person in people)
    await repository.InsertAsync(person!, ct);

Na prática, nenhum dos dois extremos costuma ser o ideal. Um insert por item gera um round-trip de banco por objeto, e isso mata o throughput. A solução de produção é o meio termo: processar em lotes pequenos, com a memória limitada ao tamanho do lote.

const int batchSize = 500;
var batch = new List<Person>(batchSize);

await foreach (var person in people)
{
    if (person is null)
        continue;

    batch.Add(person);

    if (batch.Count == batchSize)
    {
        await repository.InsertManyAsync(batch, ct);
        batch.Clear();
    }
}

if (batch.Count > 0)
    await repository.InsertManyAsync(batch, ct);

O pico de objetos vivos fica preso em quinhentos, não em cem mil, e você corta os round-trips de banco por um fator de quinhentos. Esse é o equilíbrio entre memória e throughput que você quer num endpoint de ingestão real.

Nota: o ganho do streaming só se sustenta se o seu repositório também não acumular entidades por baixo dos panos. O caso clássico é o EF Core, que rastreia toda entidade adicionada no ChangeTracker. Se você nunca limpa o contexto, ele segura referência a cada Person inserida e reconstrói o problema de memória que você veio resolver, mesmo com o await foreach perfeito. Use um DbContext de vida curta por lote, chame ChangeTracker.Clear() depois de cada SaveChanges, ou prefira inserção em massa fora do tracking. O mesmo vale para o NHibernate sem Session.Clear(). O streaming é só metade do contrato, a outra metade é a sua camada de persistência não segurar o que você acabou de soltar.

Validação passa a ser sua responsabilidade

Com [FromBody] e [ApiController], a validação por DataAnnotations roda automática e você recebe um ModelState pronto, mais um 400 limpo se algo estiver inválido. Ao desviar do model binding, você abre mão disso. A validação volta para as suas mãos, item a item:

app.MapPost("/people/stream", async (
    Stream body,
    IPersonRepository repository,
    CancellationToken ct) =>
{
    var options = new JsonSerializerOptions(JsonSerializerDefaults.Web);
    var people = JsonSerializer.DeserializeAsyncEnumerable<Person>(body, options, ct);

    var accepted = 0;
    var rejected = new List<object>();
    var index = -1;

    await foreach (var person in people)
    {
        index++;

        if (person is null)
        {
            rejected.Add(new { index, error = "objeto nulo" });
            continue;
        }

        var context = new ValidationContext(person);
        var results = new List<ValidationResult>();

        if (!Validator.TryValidateObject(person, context, results, validateAllProperties: true))
        {
            rejected.Add(new { index, errors = results.Select(r => r.ErrorMessage) });
            continue;
        }

        await repository.InsertAsync(person, ct);
        accepted++;
    }

    return Results.Ok(new { accepted, rejected });
});

O mesmo padrão se aplica ao FluentValidation, trocando o Validator.TryValidateObject por await validator.ValidateAsync(person, ct).

Nota: repare que a lista rejected cresce com o número de itens inválidos. Se um cliente mandar um payload com tudo errado, você acabou de criar de novo o problema de memória que veio resolver. Em produção, limite o número de erros coletados, algo como parar de acumular depois de cem rejeições e responder com um resumo, em vez de devolver um relatório com cem mil entradas.

Há também uma tensão mais profunda. Com [FromBody], ou a requisição inteira é válida ou ela falha antes de qualquer efeito colateral, all-or-nothing. Em streaming, quando você descobre que o item 5000 é inválido, os 4999 anteriores já podem ter sido inseridos. Você precisa decidir conscientemente a semântica: pular inválidos e seguir, abortar tudo dentro de uma transação, ou aceitar inserções parciais com idempotência. Não existe resposta única, mas existe uma obrigação de escolher.

Medindo o ganho

Aqui é onde vale corrigir um erro comum, presente até em quem já domina o assunto. As duas abordagens alocam aproximadamente o mesmo total de objetos. Tanto faz se você materializa a lista ou processa item a item, cem mil objetos Person são criados nos dois casos. O ganho do streaming não está no total de alocações. Está no pico de memória viva, ou seja, em quantos objetos existem ao mesmo tempo.

Isso tem uma consequência prática direta no benchmark. Um [MemoryDiagnoser] do BenchmarkDotNet mede o total alocado, e por isso a coluna Allocated das duas abordagens vai parecer parecida. Ela não captura o que importa aqui.

[MemoryDiagnoser]
public class JsonIngestionBenchmark
{
    private byte[] _payload = Array.Empty<byte>();

    [Params(10_000, 100_000)]
    public int ItemCount { get; set; }

    [GlobalSetup]
    public void Setup()
    {
        var people = Enumerable.Range(0, ItemCount)
            .Select(i => new Person
            {
                Id = i,
                Name = $"Person {i}",
                Email = $"person{i}@unhacked.dev"
            })
            .ToList();

        _payload = JsonSerializer.SerializeToUtf8Bytes(people);
    }

    // Materializa a lista inteira antes de processar
    [Benchmark(Baseline = true)]
    public async Task<int> BufferAll()
    {
        await using var stream = new MemoryStream(_payload);
        var people = await JsonSerializer.DeserializeAsync<List<Person>>(stream);

        var sum = 0;
        foreach (var person in people!)
            sum += person.Name.Length;

        return sum;
    }

    // Processa um objeto por vez, sem acumular
    [Benchmark]
    public async Task<int> StreamItems()
    {
        await using var stream = new MemoryStream(_payload);

        var sum = 0;
        await foreach (var person in JsonSerializer.DeserializeAsyncEnumerable<Person>(stream))
            sum += person!.Name.Length;

        return sum;
    }
}

Estimando o pico, que é o que importa

Para enxergar o que o Allocated esconde, dá para estimar o pico do heap gerenciado com um amostrador simples rodando em paralelo ao trabalho. Não é uma medição exata, é uma amostragem: o Thread.Sleep(1) e o GC.GetTotalMemory(false) capturam fotos periódicas, e o pico real pode acontecer entre duas fotos. Para a ordem de grandeza que nos interessa aqui, serve bem:

static long MeasurePeakHeap(Func<Task> work)
{
    var peak = 0L;
    var running = true;

    var sampler = new Thread(() =>
    {
        while (Volatile.Read(ref running))
        {
            var current = GC.GetTotalMemory(forceFullCollection: false);
            if (current > peak)
                peak = current;

            Thread.Sleep(1);
        }
    });

    sampler.Start();
    work().GetAwaiter().GetResult();
    Volatile.Write(ref running, false);
    sampler.Join();

    return peak;
}

O teste que mais convence: carga real

E, porque o cenário real é um endpoint sob carga, o teste que mais convence é de carga de verdade. Suba a aplicação, dispare o payload com bombardier ou k6 e observe o working set do processo com dotnet-counters:

# Dispara 100 requisicoes concorrentes com um payload de 100 mil objetos
bombardier -c 100 -n 500 -m POST \
  -H "Content-Type: application/json" \
  -f payload-100k.json \
  https://localhost:5001/people

# Em outro terminal, acompanha GC Heap Size e Working Set
dotnet-counters monitor --process-id <PID> --counters System.Runtime

A tabela abaixo é ilustrativa. Ela mostra a ordem de grandeza e o formato da curva, não resultados que você deve esperar reproduzir número a número. Trate-a como um molde a ser substituído pelos valores que você medir no seu ambiente, com payload de cem mil objetos por requisição (cerca de 45 MB de JSON) numa máquina de 4 vCPU e 8 GB:

Cenário	Estratégia	Pico de heap gerenciado	Working set do processo
100k objetos, 1 requisição	`[FromBody] List<Person>`	dezenas a centenas de MB	proporcional ao payload
100k objetos, 1 requisição	`DeserializeAsyncEnumerable`	poucos MB, aprox. constante	baixo e estável
100k objetos, 100 concorrentes	`[FromBody] List<Person>`	cresce até estourar, risco de `OutOfMemoryException`	pode derrubar o processo
100k objetos, 100 concorrentes	`DeserializeAsyncEnumerable`	limitado pelo lote e pela concorrência	estável e previsível

Os números exatos dependem de hardware, do tamanho de cada objeto e do nível de concorrência. Em um workload o fator de redução pode ser 8x, em outro 12x ou 40x. O que não muda é o formato da curva: o pico do streaming permanece aproximadamente constante enquanto o do [FromBody] cresce com o payload e multiplica com a concorrência. Meça no seu ambiente e publique os seus próprios números antes de prometer qualquer coisa para alguém.

Quando escolher cada abordagem

Aspecto	`[FromBody] List<T>`	`DeserializeAsyncEnumerable`
Pico de memória	proporcional ao payload	aproximadamente constante, limitada ao tamanho do lote
Validação automática e ModelState	sim	não, manual
400 limpo para payload inválido	sim	difícil depois de começar a processar
Backpressure ponta a ponta	não	sim
Exige array JSON na raiz	não	sim
Reaproveita o pipeline de model binding	sim	não
Complexidade do código	baixa	média

Escolha [FromBody] List<T> quando:

O payload é pequeno e tem limite garantido.
Você precisa de validação all-or-nothing com um 400 limpo.
Simplicidade vale mais que o controle fino de memória.

Escolha DeserializeAsyncEnumerable quando:

O endpoint é de ingestão em lote, com payloads grandes ou sem limite claro.
Você processa item a item ou em pequenos lotes, sem acumular.
Memória previsível sob carga importa mais que um 400 perfeito para o payload inteiro.

Não é só para payloads gigantes

É fácil ler tudo isso e concluir que a técnica só vale para os tais cem mil objetos. Não é o caso. O que justifica o streaming não é apenas o número de elementos, é a combinação de tamanho, custo de processamento e concorrência. Um array de duzentos itens já se beneficia quando cada item é grande, quando o processamento de cada um é lento, ou quando muitas requisições assim chegam ao mesmo tempo. O gatilho não é "o array é enorme". É "o conjunto vivo na memória, multiplicado pela concorrência, é grande o suficiente para doer". Use o critério, não o número redondo.

Limitações que você precisa conhecer antes de produção

Nota: DeserializeAsyncEnumerable<T> espera um array JSON na raiz do corpo. Se o seu payload é um objeto que envolve o array, como { "items": [ ... ] }, ele não funciona direto. Você precisa navegar até o token do array com um Utf8JsonReader antes de iniciar a enumeração, ou ajustar o contrato.

Nota: ao desviar do model binding, você perde mais do que a validação automática. Perde o 400 automático do [ApiController], perde a integração natural com a negociação de conteúdo e assume a responsabilidade por limites que antes vinham de graça. Continue aplicando um teto de tamanho de corpo, seja pelo MaxRequestBodySize do Kestrel, seja por uma verificação própria, para não trocar um estouro de memória por uma porta aberta de ingestão ilimitada.

Nota: o tratamento de erro no meio do stream é seu. Se o objeto de número 5000 está malformado, a desserialização lança no meio do await foreach, e os 4999 anteriores já foram processados. Pense em idempotência, em lotes transacionais e em como reportar uma falha parcial de forma que o cliente consiga reenviar com segurança.

Nota: o streaming resolve o array com muitos elementos, não um objeto único gigante. Se um elemento individual for enorme, ele ainda precisa caber na memória enquanto é construído. O ganho está em não segurar todos os elementos ao mesmo tempo, não em fatiar um objeto grande.

Conclusão

DeserializeAsyncEnumerable é uma solução elegante para um problema que parece banal e quebra feio em escala. Você troca pouquíssimo código e ganha um pico de memória que para de crescer com o payload, mais o backpressure que segura o cliente quando o seu processamento desacelera.

A implementação não é difícil, mas os detalhes importam, e quase todos são fáceis de errar. O ganho some se você reacumular a lista. A validação e o tratamento de erro voltam a ser seus. A semântica de falha parcial precisa de uma decisão consciente, não de um descuido. E o número que você vai prometer só é verdade depois que você o mediu no seu ambiente.

A escolha não é universal. Para payloads pequenos e validação all-or-nothing, o bom e velho [FromBody] é mais simples e mais seguro. Para ingestão em lote, o streaming é a diferença entre um endpoint que escala e um que derruba o processo.

No fim, a lição cabe numa frase. Um endpoint de ingestão não escala quando aprende a processar mais rápido. Ele escala quando aprende a nunca segurar, ao mesmo tempo, mais do que precisa para dar o próximo passo.

Snowflake e UUID v7: Gerando identificadores únicos em sistemas distribuídos

Cristiano Rodrigues — Mon, 30 Mar 2026 19:44:48 +0000

Em sistemas distribuídos, gerar identificadores únicos é um problema surpreendentemente complexo. Como garantir que dois servidores em continentes diferentes não gerem o mesmo ID no mesmo milissegundo? O Twitter enfrentou esse desafio em 2010 e criou o Snowflake, um algoritmo elegante que se tornou referência na indústria. Em 2024, a RFC 9562 padronizou o UUID v7, uma alternativa que resolve o mesmo problema de forma diferente. Vamos explorar ambos.

O problema dos IDs distribuídos

Imagine um sistema de pagamentos rodando em múltiplas regiões: 20 servidores em Frankfurt, 15 em Virginia, 10 em Singapura. Cada servidor precisa gerar IDs para novas transações. Esses IDs precisam ser únicos globalmente, ordenáveis por tempo, gerados sem consultar um banco central, e rápidos o suficiente para milhões de operações por segundo. Esse é exatamente o tipo de problema que o Snowflake foi criado para resolver.

Antes de entender como ele faz isso, vale considerar as alternativas e seus problemas:

Auto-increment do banco de dados: Funciona bem para uma única instância, mas em sistemas distribuídos cria um gargalo central. Cada insert precisa consultar o banco para obter o próximo ID.

UUIDs (v4): Aleatórios e únicos, mas ocupam 128 bits (36 caracteres como string), não são ordenáveis por tempo, e têm péssima performance em índices de banco de dados por causa da fragmentação.

Timestamp puro: Dois servidores podem gerar o mesmo timestamp no mesmo milissegundo.

O Snowflake resolve todos esses problemas com uma estrutura de 64 bits que é única, ordenável, e não requer coordenação central.

Anatomia de um Snowflake ID

Um Snowflake ID é um inteiro de 64 bits dividido em segmentos:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
├─┼─────────────────────────────────────────────────────────────┤
│0│                         Timestamp                           │
├─┼─────────────────────────────────────────────────────────────┤
 0                   4                   5           6
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
├─────────────────────────────────────────┼─────────────────────┤
│                 Timestamp (cont.)       │    Machine ID       │
├─────────────────────────────────────────┼─────────────────────┤
                                          5           6
                                          0 1 2 3 4 5 6 7 8 9 0 1
                                         ├─────────┼─────────────┤
                                         │ Mach.ID │  Sequence   │
                                         ├─────────┼─────────────┤

A estrutura clássica do Twitter:

Segmento	Bits	Descrição
Sign bit	1	Sempre 0 (garante número positivo)
Timestamp	41	Milissegundos desde epoch customizado
Machine ID	10	Identificador do datacenter/worker
Sequence	12	Contador sequencial por milissegundo

O que cada parte significa

Timestamp (41 bits): Armazena milissegundos desde um epoch customizado (não 1970). Com 41 bits, suporta aproximadamente 69 anos de IDs únicos. O Twitter usa epoch de novembro de 2010.

2^41 milissegundos = 2.199.023.255.552 ms
                   = ~69,7 anos

Machine ID (10 bits): Identifica qual máquina gerou o ID. Pode ser dividido em datacenter (5 bits) + worker (5 bits), permitindo 32 datacenters com 32 workers cada, ou usado como um único identificador para 1024 máquinas.

Sequence (12 bits): Contador que incrementa quando múltiplos IDs são gerados no mesmo milissegundo pela mesma máquina. Reseta para 0 a cada novo milissegundo. Permite 4096 IDs por milissegundo por máquina.

4096 IDs/ms × 1000 ms × 1024 máquinas = ~4 bilhões de IDs/segundo (teórico)

Como o ID é montado na prática

Para entender por que essa estrutura funciona, vamos acompanhar a geração de um ID real passo a passo.

Suponha os seguintes valores:

Timestamp:  1718451000000 ms (desde o epoch customizado)
Machine ID: 42
Sequence:   7

Cada valor é posicionado nos bits corretos usando shift e OR:

timestamp  = 1718451000000                        (41 bits)
machineId  = 42                                   (10 bits)
sequence   = 7                                    (12 bits)

timestamp  << 22  = 7.209.067.135.365.095.424
machineId  << 12  =               172.032
sequence          =                     7

ID final = 7.209.067.135.365.095.424
         |                   172.032
         |                         7
         = 7.209.067.135.365.267.463

Repare no que acontece: como o timestamp ocupa os bits mais altos, ele domina o valor do ID. Isso significa que um ID gerado um milissegundo depois será sempre maior, independente do Machine ID ou do Sequence. É exatamente isso que garante a ordenação temporal sem nenhuma coordenação entre servidores.

Por que essa estrutura é genial

Ordenação temporal: Como o timestamp ocupa os bits mais significativos, IDs gerados depois são sempre maiores. Isso significa que ordenar por ID é equivalente a ordenar por tempo de criação.

Sem coordenação: Cada máquina gera IDs independentemente. Não há necessidade de consultar um servidor central ou banco de dados.

Compacto: 64 bits cabem em um long, são eficientes em índices B-tree, e ocupam apenas 8 bytes.

Extraível: Você pode extrair o timestamp de qualquer ID para saber quando foi criado.

Implementação em "C#"

Uma implementação completa e thread-safe:

public sealed class SnowflakeIdGenerator
{
    // Epoch customizado: 1 de Janeiro de 2024 00:00:00 UTC
    private static readonly DateTimeOffset CustomEpoch = 
        new(2024, 1, 1, 0, 0, 0, TimeSpan.Zero);

    // Configuração de bits
    private const int TimestampBits = 41;
    private const int MachineIdBits = 10;
    private const int SequenceBits = 12;

    // Shifts para posicionar cada segmento
    private const int MachineIdShift = SequenceBits;
    private const int TimestampShift = SequenceBits + MachineIdBits;

    // Máscaras para extrair valores
    private const long MaxSequence = (1L << SequenceBits) - 1;      // 4095
    private const long MaxMachineId = (1L << MachineIdBits) - 1;    // 1023

    private readonly long _machineId;
    private readonly object _lock = new();

    private long _lastTimestamp = -1L;
    private long _sequence = 0L;

    public SnowflakeIdGenerator(long machineId)
    {
        if (machineId < 0 || machineId > MaxMachineId)
        {
            throw new ArgumentOutOfRangeException(
                nameof(machineId), 
                $"Machine ID must be between 0 and {MaxMachineId}");
        }

        _machineId = machineId;
    }

    public long NextId()
    {
        lock (_lock)
        {
            var timestamp = GetCurrentTimestamp();

            if (timestamp < _lastTimestamp)
            {
                throw new InvalidOperationException(
                    $"Clock moved backwards. Refusing to generate ID for {_lastTimestamp - timestamp}ms");
            }

            if (timestamp == _lastTimestamp)
            {
                // Mesmo milissegundo: incrementa sequence
                _sequence = (_sequence + 1) & MaxSequence;

                if (_sequence == 0)
                {
                    // Sequence overflow: aguarda próximo milissegundo
                    timestamp = WaitNextMillis(_lastTimestamp);
                }
            }
            else
            {
                // Novo milissegundo: reseta sequence
                _sequence = 0;
            }

            _lastTimestamp = timestamp;

            return (timestamp << TimestampShift) |
                   (_machineId << MachineIdShift) |
                   _sequence;
        }
    }

    private static long GetCurrentTimestamp()
    {
        return (long)(DateTimeOffset.UtcNow - CustomEpoch).TotalMilliseconds;
    }

    private static long WaitNextMillis(long lastTimestamp)
    {
        var timestamp = GetCurrentTimestamp();

        while (timestamp <= lastTimestamp)
        {
            Thread.SpinWait(100);
            timestamp = GetCurrentTimestamp();
        }

        return timestamp;
    }

    // Utilitários para extrair informações do ID
    public static DateTimeOffset ExtractTimestamp(long id)
    {
        var timestamp = id >> TimestampShift;
        return CustomEpoch.AddMilliseconds(timestamp);
    }

    public static long ExtractMachineId(long id)
    {
        return (id >> MachineIdShift) & MaxMachineId;
    }

    public static long ExtractSequence(long id)
    {
        return id & MaxSequence;
    }

    public static SnowflakeComponents Decode(long id)
    {
        return new SnowflakeComponents
        {
            Id = id,
            Timestamp = ExtractTimestamp(id),
            MachineId = ExtractMachineId(id),
            Sequence = ExtractSequence(id)
        };
    }
}

public record SnowflakeComponents
{
    public long Id { get; init; }
    public DateTimeOffset Timestamp { get; init; }
    public long MachineId { get; init; }
    public long Sequence { get; init; }

    public override string ToString() =>
        $"ID: {Id}, Created: {Timestamp:O}, Machine: {MachineId}, Seq: {Sequence}";
}

Uso básico

// Cada instância/pod deve ter um machineId único
var generator = new SnowflakeIdGenerator(machineId: 1);

// Gerar IDs
var id1 = generator.NextId();
var id2 = generator.NextId();
var id3 = generator.NextId();

Console.WriteLine(id1); // 123456789012345678
Console.WriteLine(id2); // 123456789012345679
Console.WriteLine(id3); // 123456789012345680

// Decodificar um ID
var components = SnowflakeIdGenerator.Decode(id1);
Console.WriteLine(components);
// ID: 123456789012345678, Created: 2024-06-15T14:30:00Z, Machine: 1, Seq: 0

Integração com ASP.NET Core

Registro como Serviço Singleton

public static class SnowflakeServiceExtensions
{
    public static IServiceCollection AddSnowflakeIdGenerator(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        var machineId = GetMachineId(configuration);
        var generator = new SnowflakeIdGenerator(machineId);

        services.AddSingleton(generator);
        services.AddSingleton<IIdGenerator>(provider => 
            new SnowflakeIdGeneratorAdapter(provider.GetRequiredService<SnowflakeIdGenerator>()));

        return services;
    }

    private static long GetMachineId(IConfiguration configuration)
    {
        // Prioridade: variável de ambiente > configuração > hash do hostname
        var envMachineId = Environment.GetEnvironmentVariable("SNOWFLAKE_MACHINE_ID");
        if (!string.IsNullOrEmpty(envMachineId) && long.TryParse(envMachineId, out var envId))
        {
            return envId;
        }

        var configMachineId = configuration.GetValue<long?>("Snowflake:MachineId");
        if (configMachineId.HasValue)
        {
            return configMachineId.Value;
        }

        // Fallback: usa hash do hostname (cuidado com colisões em produção!)
        var hostname = Environment.MachineName;
        return Math.Abs(hostname.GetHashCode()) % 1024;
    }
}

public interface IIdGenerator
{
    long NextId();
    string NextIdAsString();
}

public class SnowflakeIdGeneratorAdapter : IIdGenerator
{
    private readonly SnowflakeIdGenerator _generator;

    public SnowflakeIdGeneratorAdapter(SnowflakeIdGenerator generator)
    {
        _generator = generator;
    }

    public long NextId() => _generator.NextId();
    public string NextIdAsString() => _generator.NextId().ToString();
}

Configuração no Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSnowflakeIdGenerator(builder.Configuration);

var app = builder.Build();

Com appsettings.json:

{
  "Snowflake": {
    "MachineId": 1
  }
}

Ou via variável de ambiente no Kubernetes:

env:
  - name: SNOWFLAKE_MACHINE_ID
    valueFrom:
      fieldRef:
        fieldPath: metadata.annotations['snowflake-machine-id']

Uso em entidades

public class Order
{
    public long Id { get; private set; }
    public string CustomerName { get; set; } = string.Empty;
    public decimal Total { get; set; }
    public DateTimeOffset CreatedAt { get; set; }

    public static Order Create(IIdGenerator idGenerator, string customerName, decimal total)
    {
        return new Order
        {
            Id = idGenerator.NextId(),
            CustomerName = customerName,
            Total = total,
            CreatedAt = DateTimeOffset.UtcNow
        };
    }
}

// No controller ou service
public class OrderService
{
    private readonly IIdGenerator _idGenerator;
    private readonly AppDbContext _context;

    public OrderService(IIdGenerator idGenerator, AppDbContext context)
    {
        _idGenerator = idGenerator;
        _context = context;
    }

    public async Task<Order> CreateOrderAsync(CreateOrderRequest request)
    {
        var order = Order.Create(_idGenerator, request.CustomerName, request.Total);

        _context.Orders.Add(order);
        await _context.SaveChangesAsync();

        return order;
    }
}

Implementação de alta performance

Para cenários de altíssima throughput, podemos eliminar o lock usando operações atômicas:

public sealed class LockFreeSnowflakeGenerator
{
    private static readonly DateTimeOffset CustomEpoch = 
        new(2024, 1, 1, 0, 0, 0, TimeSpan.Zero);

    private const int SequenceBits = 12;
    private const int MachineIdBits = 10;
    private const int MachineIdShift = SequenceBits;
    private const int TimestampShift = SequenceBits + MachineIdBits;
    private const long MaxSequence = (1L << SequenceBits) - 1;

    private readonly long _machineId;

    // Combina timestamp e sequence em um único valor atômico
    // [timestamp: 41 bits][sequence: 12 bits] = 53 bits, cabe em long
    private long _state;

    public LockFreeSnowflakeGenerator(long machineId)
    {
        if (machineId < 0 || machineId > 1023)
            throw new ArgumentOutOfRangeException(nameof(machineId));

        _machineId = machineId;
        _state = GetCurrentTimestamp() << SequenceBits;
    }

    public long NextId()
    {
        long oldState, newState, timestamp, sequence;

        do
        {
            oldState = Interlocked.Read(ref _state);
            var currentTimestamp = GetCurrentTimestamp();
            var oldTimestamp = oldState >> SequenceBits;
            var oldSequence = oldState & MaxSequence;

            if (currentTimestamp > oldTimestamp)
            {
                // Novo milissegundo
                timestamp = currentTimestamp;
                sequence = 0;
            }
            else if (currentTimestamp == oldTimestamp)
            {
                // Mesmo milissegundo
                sequence = oldSequence + 1;

                if (sequence > MaxSequence)
                {
                    // Overflow: força espera pelo próximo ms via spin
                    Thread.SpinWait(10);
                    continue;
                }

                timestamp = currentTimestamp;
            }
            else
            {
                // Clock regression: usa timestamp antigo + sequence
                timestamp = oldTimestamp;
                sequence = oldSequence + 1;

                if (sequence > MaxSequence)
                {
                    timestamp++;
                    sequence = 0;
                }
            }

            newState = (timestamp << SequenceBits) | sequence;

        } while (Interlocked.CompareExchange(ref _state, newState, oldState) != oldState);

        return (timestamp << TimestampShift) | (_machineId << MachineIdShift) | sequence;
    }

    private static long GetCurrentTimestamp()
    {
        return (long)(DateTimeOffset.UtcNow - CustomEpoch).TotalMilliseconds;
    }
}

Benchmark Comparativo

[MemoryDiagnoser]
public class SnowflakeBenchmarks
{
    private readonly SnowflakeIdGenerator _locked = new(1);
    private readonly LockFreeSnowflakeGenerator _lockFree = new(1);
    private readonly Guid _guid = Guid.NewGuid();

    [Benchmark(Baseline = true)]
    public long SnowflakeLocked() => _locked.NextId();

    [Benchmark]
    public long SnowflakeLockFree() => _lockFree.NextId();

    [Benchmark]
    public Guid GuidNewGuid() => Guid.NewGuid();
}

Resultados típicos (depende do hardware):

Método	Média	Alocação
SnowflakeLocked	~50 ns	0 B
SnowflakeLockFree	~25 ns	0 B
Guid.NewGuid	~35 ns	0 B

Atribuição de Machine ID em Kubernetes

O maior desafio do Snowflake em ambientes containerizados é garantir que cada pod tenha um Machine ID único. Existem várias estratégias:

1. StatefulSet com Ordinal Index

public static long GetMachineIdFromPodName()
{
    // Pod name em StatefulSet: myapp-0, myapp-1, myapp-2...
    var podName = Environment.GetEnvironmentVariable("POD_NAME") ?? "pod-0";
    var parts = podName.Split('-');

    if (parts.Length > 0 && int.TryParse(parts[^1], out var ordinal))
    {
        return ordinal % 1024;
    }

    return 0;
}

Kubernetes manifest:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: myapp
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: app
          env:
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name

2. Registro Dinâmico com Redis

Para Deployments (não StatefulSet), pods podem "alugar" um Machine ID:

public class RedisMachineIdProvider
{
    private readonly IDatabase _redis;
    private readonly string _serviceName;
    private readonly TimeSpan _leaseDuration;
    private readonly string _instanceId;

    private long _machineId = -1;
    private Timer? _renewalTimer;

    public RedisMachineIdProvider(
        IConnectionMultiplexer connection,
        string serviceName,
        TimeSpan? leaseDuration = null)
    {
        _redis = connection.GetDatabase();
        _serviceName = serviceName;
        _leaseDuration = leaseDuration ?? TimeSpan.FromMinutes(5);
        _instanceId = Guid.NewGuid().ToString("N");
    }

    public async Task<long> AcquireMachineIdAsync()
    {
        for (long candidateId = 0; candidateId < 1024; candidateId++)
        {
            var key = $"snowflake:{_serviceName}:machine:{candidateId}";

            var acquired = await _redis.StringSetAsync(
                key,
                _instanceId,
                _leaseDuration,
                When.NotExists);

            if (acquired)
            {
                _machineId = candidateId;
                StartLeaseRenewal();
                return candidateId;
            }

            // Verifica se o lease expirou (cleanup de instância morta)
            var currentHolder = await _redis.StringGetAsync(key);
            if (!currentHolder.HasValue)
            {
                continue; // Tenta novamente
            }
        }

        throw new InvalidOperationException(
            "No available machine ID. All 1024 slots are in use.");
    }

    private void StartLeaseRenewal()
    {
        var renewalInterval = _leaseDuration / 2;

        _renewalTimer = new Timer(async _ =>
        {
            var key = $"snowflake:{_serviceName}:machine:{_machineId}";
            await _redis.KeyExpireAsync(key, _leaseDuration);
        }, null, renewalInterval, renewalInterval);
    }

    public async Task ReleaseMachineIdAsync()
    {
        _renewalTimer?.Dispose();

        if (_machineId >= 0)
        {
            var key = $"snowflake:{_serviceName}:machine:{_machineId}";
            await _redis.KeyDeleteAsync(key);
        }
    }
}

// Uso com IHostedService para lifecycle management
public class SnowflakeInitializerService : IHostedService
{
    private readonly RedisMachineIdProvider _machineIdProvider;
    private readonly SnowflakeIdGeneratorHolder _holder;

    public SnowflakeInitializerService(
        RedisMachineIdProvider machineIdProvider,
        SnowflakeIdGeneratorHolder holder)
    {
        _machineIdProvider = machineIdProvider;
        _holder = holder;
    }

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        var machineId = await _machineIdProvider.AcquireMachineIdAsync();
        _holder.Generator = new SnowflakeIdGenerator(machineId);
    }

    public async Task StopAsync(CancellationToken cancellationToken)
    {
        await _machineIdProvider.ReleaseMachineIdAsync();
    }
}

// Holder para permitir inicialização tardia
public class SnowflakeIdGeneratorHolder
{
    public SnowflakeIdGenerator? Generator { get; set; }

    public long NextId() => Generator?.NextId() 
        ?? throw new InvalidOperationException("Generator not initialized");
}

3. Baseado em IP do Pod

Uma abordagem simples que funciona bem para clusters pequenos:

public static long GetMachineIdFromPodIp()
{
    var podIp = Environment.GetEnvironmentVariable("POD_IP");

    if (string.IsNullOrEmpty(podIp))
    {
        // Fallback: obtém IP da interface de rede
        podIp = Dns.GetHostAddresses(Dns.GetHostName())
            .FirstOrDefault(ip => ip.AddressFamily == AddressFamily.InterNetwork)?
            .ToString() ?? "127.0.0.1";
    }

    // Usa os últimos 10 bits do IP (último octeto + parte do penúltimo)
    var parts = podIp.Split('.');
    if (parts.Length == 4)
    {
        var lastOctet = int.Parse(parts[3]);
        var secondLastOctet = int.Parse(parts[2]);

        // Combina para formar um ID de 10 bits
        return ((secondLastOctet & 0x03) << 8) | lastOctet;
    }

    return 0;
}

Variações do Snowflake

Diferentes empresas adaptaram o Snowflake para suas necessidades:

Discord (Epoch: 2015)

public class DiscordSnowflake
{
    // Discord usa epoch de 1 de Janeiro de 2015
    private static readonly DateTimeOffset DiscordEpoch = 
        new(2015, 1, 1, 0, 0, 0, TimeSpan.Zero);

    // Estrutura: timestamp(42) + worker(5) + process(5) + sequence(12)
    private const int WorkerIdBits = 5;
    private const int ProcessIdBits = 5;
    private const int SequenceBits = 12;

    // ... implementação similar
}

Instagram (Sharded)

public class InstagramSnowflake
{
    // Instagram: timestamp(41) + shard_id(13) + sequence(10)
    // Mais shards, menos IDs por milissegundo por shard
    private const int ShardIdBits = 13;    // 8192 shards
    private const int SequenceBits = 10;   // 1024 IDs/ms/shard

    private readonly long _shardId;

    public InstagramSnowflake(long shardId)
    {
        // Shard ID tipicamente derivado do user_id % num_shards
        _shardId = shardId & ((1L << ShardIdBits) - 1);
    }
}

Sony (Sonyflake)

public class Sonyflake
{
    // Sonyflake: timestamp em unidades de 10ms para durar mais tempo
    // timestamp(39) + sequence(8) + machine_id(16)
    // Dura ~174 anos, mas apenas 256 IDs por 10ms por máquina

    private static readonly DateTimeOffset SonyEpoch = 
        new(2014, 9, 1, 0, 0, 0, TimeSpan.Zero);

    private const int SequenceBits = 8;
    private const int MachineIdBits = 16;

    private static long GetCurrentTimestamp()
    {
        // Unidades de 10ms ao invés de 1ms
        return (long)(DateTimeOffset.UtcNow - SonyEpoch).TotalMilliseconds / 10;
    }
}

UUID v7: O Padrão Moderno

Em 2024, a RFC 9562 formalizou o UUID v7, uma alternativa padronizada que resolve os mesmos problemas do Snowflake. Se você está começando um projeto novo, vale considerar essa opção.

Anatomia do UUID v7

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
├───────────────────────────────────────────────────────────────┤
│                          unix_ts_ms                           │
├───────────────────────────────────────────────────────────────┤
│           unix_ts_ms          │  ver  │       rand_a          │
├───────────────────────────────────────────────────────────────┤
│var│                        rand_b                             │
├───────────────────────────────────────────────────────────────┤
│                            rand_b                             │
└───────────────────────────────────────────────────────────────┘

Segmento	Bits	Descrição
unix_ts_ms	48	Timestamp Unix em milissegundos
ver	4	Versão (sempre 7)
rand_a	12	Dados aleatórios ou sub-milissegundo
var	2	Variante (sempre 10)
rand_b	62	Dados aleatórios ou contador

Total: 128 bits (vs 64 do Snowflake)

Implementação em C

A partir do .NET 9, UUID v7 está disponível nativamente:

// .NET 9+
var id = Guid.CreateVersion7();
var idWithTimestamp = Guid.CreateVersion7(DateTimeOffset.UtcNow);

Para versões anteriores do .NET, uma implementação manual:

public static class UuidV7
{
    private static long _lastTimestamp;
    private static int _counter;
    private static readonly object _lock = new();
    private static readonly Random _random = Random.Shared;

    public static Guid NewUuid()
    {
        Span<byte> bytes = stackalloc byte[16];

        lock (_lock)
        {
            var timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();

            // Monotonic counter para mesmo milissegundo
            if (timestamp == _lastTimestamp)
            {
                _counter++;
            }
            else
            {
                _lastTimestamp = timestamp;
                _counter = _random.Next(0, 0xFFF); // Randomiza início do counter
            }

            // Bytes 0-5: timestamp (48 bits, big-endian)
            bytes[0] = (byte)(timestamp >> 40);
            bytes[1] = (byte)(timestamp >> 32);
            bytes[2] = (byte)(timestamp >> 24);
            bytes[3] = (byte)(timestamp >> 16);
            bytes[4] = (byte)(timestamp >> 8);
            bytes[5] = (byte)timestamp;

            // Bytes 6-7: version (4 bits) + rand_a/counter (12 bits)
            var randA = (ushort)((_counter & 0xFFF) | 0x7000); // Version 7
            bytes[6] = (byte)(randA >> 8);
            bytes[7] = (byte)randA;

            // Bytes 8-15: variant (2 bits) + rand_b (62 bits)
            _random.NextBytes(bytes.Slice(8, 8));
            bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80); // Variant 10
        }

        return new Guid(bytes, bigEndian: true);
    }

    public static DateTimeOffset ExtractTimestamp(Guid uuid)
    {
        Span<byte> bytes = stackalloc byte[16];
        uuid.TryWriteBytes(bytes, bigEndian: true, out _);

        long timestamp = ((long)bytes[0] << 40) |
                         ((long)bytes[1] << 32) |
                         ((long)bytes[2] << 24) |
                         ((long)bytes[3] << 16) |
                         ((long)bytes[4] << 8) |
                         bytes[5];

        return DateTimeOffset.FromUnixTimeMilliseconds(timestamp);
    }

    public static bool IsVersion7(Guid uuid)
    {
        Span<byte> bytes = stackalloc byte[16];
        uuid.TryWriteBytes(bytes, bigEndian: true, out _);

        var version = (bytes[6] >> 4) & 0x0F;
        var variant = (bytes[8] >> 6) & 0x03;

        return version == 7 && variant == 2;
    }
}

Implementação de Alta Performance

Para cenários que exigem máxima performance, eliminando alocações:

public sealed class UuidV7Generator
{
    private long _lastTimestamp;
    private long _counter;

    public Guid NewUuid()
    {
        var timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
        long counter;

        // Operação atômica para timestamp + counter
        while (true)
        {
            var oldTimestamp = Interlocked.Read(ref _lastTimestamp);
            var oldCounter = Interlocked.Read(ref _counter);

            if (timestamp > oldTimestamp)
            {
                if (Interlocked.CompareExchange(ref _lastTimestamp, timestamp, oldTimestamp) == oldTimestamp)
                {
                    counter = Random.Shared.NextInt64(0, 0xFFF);
                    Interlocked.Exchange(ref _counter, counter);
                    break;
                }
            }
            else
            {
                counter = Interlocked.Increment(ref _counter) & 0xFFF;
                if (counter != 0)
                {
                    timestamp = oldTimestamp;
                    break;
                }
                // Counter overflow: aguarda próximo ms
                Thread.SpinWait(100);
                timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
            }
        }

        return CreateUuid(timestamp, counter);
    }

    private static Guid CreateUuid(long timestamp, long counter)
    {
        Span<byte> bytes = stackalloc byte[16];

        // Timestamp (48 bits)
        bytes[0] = (byte)(timestamp >> 40);
        bytes[1] = (byte)(timestamp >> 32);
        bytes[2] = (byte)(timestamp >> 24);
        bytes[3] = (byte)(timestamp >> 16);
        bytes[4] = (byte)(timestamp >> 8);
        bytes[5] = (byte)timestamp;

        // Version 7 + counter
        bytes[6] = (byte)(0x70 | ((counter >> 8) & 0x0F));
        bytes[7] = (byte)counter;

        // Variant + random
        Span<byte> randomBytes = bytes.Slice(8, 8);
        Random.Shared.NextBytes(randomBytes);
        bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80);

        return new Guid(bytes, bigEndian: true);
    }
}

Uso Prático

// Geração simples
var id1 = UuidV7.NewUuid();
var id2 = UuidV7.NewUuid();

Console.WriteLine(id1); // 018f5e4c-7b2a-7123-8456-789abcdef012
Console.WriteLine(id2); // 018f5e4c-7b2a-7124-8def-123456789abc

// IDs são ordenáveis!
Console.WriteLine(id1 < id2); // True (na maioria dos casos)

// Extrair timestamp
var created = UuidV7.ExtractTimestamp(id1);
Console.WriteLine(created); // 2024-06-15T14:30:00.000+00:00

// Validar versão
Console.WriteLine(UuidV7.IsVersion7(id1)); // True
Console.WriteLine(UuidV7.IsVersion7(Guid.NewGuid())); // False (v4)

Entity Framework Core com UUID v7

public class Order
{
    public Guid Id { get; private set; }
    public string CustomerName { get; set; } = string.Empty;
    public decimal Total { get; set; }

    private Order() { }

    public static Order Create(string customerName, decimal total)
    {
        return new Order
        {
            Id = UuidV7.NewUuid(),
            CustomerName = customerName,
            Total = total
        };
    }
}

// DbContext configuration
public class AppDbContext : DbContext
{
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>(entity =>
        {
            entity.HasKey(e => e.Id);

            // UUID v7 é ordenável, então funciona bem como clustered index
            entity.HasIndex(e => e.Id).IsClustered();
        });
    }
}

Snowflake vs UUID v7: Comparação Detalhada

Aspecto	Snowflake (64 bits)	UUID v7 (128 bits)
Tamanho	8 bytes	16 bytes
Ordenação	Perfeita (timestamp nos bits altos)	Quase perfeita (mesmo ms pode variar)
Unicidade	Requer Machine ID único	Aleatoriedade garante unicidade
Coordenação	Precisa distribuir Machine IDs	Nenhuma
Timestamp	Epoch customizado (69 anos)	Unix epoch (até ano 10889)
Extração de metadata	Timestamp + Machine + Sequence	Apenas timestamp
Padrão	Proprietário (Twitter)	RFC 9562
Suporte nativo	Não	.NET 9+
Performance índice DB	Excelente	Bom (2x tamanho)
JavaScript safe	Não (>53 bits)	Sim (string nativa)

Quando Escolher Cada Um

Escolha Snowflake quando:

Tamanho do ID é crítico (8 vs 16 bytes faz diferença em bilhões de registros)
Precisa identificar a origem do ID (Machine ID)
Quer garantia absoluta de ordenação monotônica
Já tem infraestrutura para distribuir Machine IDs

Escolha UUID v7 quando:

Não quer gerenciar Machine IDs
Prefere usar padrões estabelecidos (RFC)
Interoperabilidade com sistemas que esperam UUIDs
Está no .NET 9+ e quer solução nativa
Precisa de compatibilidade com JavaScript sem conversão

Migração: Snowflake para UUID v7

Se você tem um sistema com Snowflake e quer migrar:

public static class SnowflakeToUuidV7Converter
{
    public static Guid ConvertToUuidV7(long snowflakeId, DateTimeOffset snowflakeEpoch)
    {
        // Extrai timestamp do Snowflake
        var timestampMs = snowflakeId >> 22; // Assumindo 22 bits para machine+sequence
        var unixTimestampMs = (long)(snowflakeEpoch.ToUnixTimeMilliseconds() + timestampMs);

        // Extrai sequence para usar como parte do UUID
        var sequence = snowflakeId & 0xFFF;

        Span<byte> bytes = stackalloc byte[16];

        // Timestamp
        bytes[0] = (byte)(unixTimestampMs >> 40);
        bytes[1] = (byte)(unixTimestampMs >> 32);
        bytes[2] = (byte)(unixTimestampMs >> 24);
        bytes[3] = (byte)(unixTimestampMs >> 16);
        bytes[4] = (byte)(unixTimestampMs >> 8);
        bytes[5] = (byte)unixTimestampMs;

        // Version 7 + sequence original
        bytes[6] = (byte)(0x70 | ((sequence >> 8) & 0x0F));
        bytes[7] = (byte)sequence;

        // Variant + Machine ID nos bytes restantes (preserva rastreabilidade)
        var machineId = (snowflakeId >> 12) & 0x3FF;
        bytes[8] = (byte)(0x80 | ((machineId >> 4) & 0x3F));
        bytes[9] = (byte)((machineId << 4) & 0xF0);

        // Preenche resto com zeros (ou hash determinístico)
        bytes[10] = bytes[11] = bytes[12] = bytes[13] = bytes[14] = bytes[15] = 0;

        return new Guid(bytes, bigEndian: true);
    }
}

Benchmark: Snowflake vs UUID v7 vs UUID v4

[MemoryDiagnoser]
public class IdGeneratorBenchmarks
{
    private readonly SnowflakeIdGenerator _snowflake = new(1);
    private readonly UuidV7Generator _uuidV7 = new();

    [Benchmark(Baseline = true)]
    public long Snowflake() => _snowflake.NextId();

    [Benchmark]
    public Guid UuidV7() => _uuidV7.NewUuid();

    [Benchmark]
    public Guid UuidV4() => Guid.NewGuid();

    // .NET 9+ apenas
    // [Benchmark]
    // public Guid UuidV7Native() => Guid.CreateVersion7();
}

Resultados típicos:

Método	Média	Alocação
Snowflake	~25 ns	0 B
UuidV7 (custom)	~45 ns	0 B
UuidV4	~35 ns	0 B
UuidV7 (.NET 9)	~30 ns	0 B

O Snowflake é mais rápido, mas UUID v7 tem a vantagem de não precisar de coordenação.

Considerações e Limitações

Clock Drift

O maior inimigo do Snowflake é o clock do sistema voltar no tempo (NTP sync, VM migration, etc.):

// Estratégias para lidar com clock regression:

// 1. Lançar exceção (implementação padrão)
if (timestamp < _lastTimestamp)
{
    throw new InvalidOperationException("Clock moved backwards");
}

// 2. Aguardar o tempo "alcançar" (pode bloquear por muito tempo)
while (timestamp < _lastTimestamp)
{
    Thread.Sleep(1);
    timestamp = GetCurrentTimestamp();
}

// 3. Usar timestamp antigo e incrementar sequence (nossa implementação lock-free)
if (currentTimestamp < oldTimestamp)
{
    timestamp = oldTimestamp;
    sequence = oldSequence + 1;
}

Limite de 69 Anos

Com epoch em 2024, os IDs funcionam até ~2093. Para sistemas que precisam durar mais:

// Opção 1: Usar epoch mais recente
private static readonly DateTimeOffset CustomEpoch = 
    new(2024, 1, 1, 0, 0, 0, TimeSpan.Zero); // Válido até ~2093

// Opção 2: Reduzir bits de sequence/machine para mais timestamp
// timestamp(43) + machine(8) + sequence(12) = ~278 anos

IDs em URLs

Snowflake IDs são números grandes que podem ser problemáticos em JavaScript (limite de 53 bits para inteiros seguros):

// Solução 1: Retornar como string na API
[JsonConverter(typeof(LongToStringConverter))]
public long Id { get; set; }

// Solução 2: Usar Base62 encoding
public static class Base62
{
    private const string Alphabet = 
        "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";

    public static string Encode(long value)
    {
        if (value == 0) return "0";

        var result = new StringBuilder();

        while (value > 0)
        {
            result.Insert(0, Alphabet[(int)(value % 62)]);
            value /= 62;
        }

        return result.ToString();
    }

    public static long Decode(string encoded)
    {
        return encoded.Aggregate(0L, (current, c) => 
            current * 62 + Alphabet.IndexOf(c));
    }
}

// 123456789012345678 -> "2aZrWMN8Hy" (11 chars vs 18 dígitos)

Quando Usar Cada Abordagem

Use Snowflake quando:

Tamanho do ID é crítico (8 vs 16 bytes importa em bilhões de registros)
Precisa identificar a origem do ID (Machine ID embutido)
Quer garantia absoluta de ordenação monotônica
Já tem infraestrutura para distribuir Machine IDs
Performance de geração é o fator mais crítico

Use UUID v7 quando:

Não quer gerenciar Machine IDs
Prefere usar padrões estabelecidos (RFC 9562)
Interoperabilidade com sistemas que esperam UUIDs
Está no .NET 9+ e quer solução nativa
Precisa de compatibilidade com JavaScript sem conversão
Simplicidade de implementação é prioridade

Use UUID v4 quando:

Não precisa de ordenação temporal
Quer IDs completamente aleatórios
Segurança é prioridade (IDs não revelam timestamp)

Use auto-increment quando:

Sistema é simples com um único banco de dados
Não precisa gerar IDs fora do banco
Sequencialidade absoluta é necessária

Conclusão

O Snowflake é uma solução elegante para um problema complexo. Sua estrutura simples de 64 bits resolve simultaneamente unicidade, ordenação e performance, sem necessidade de coordenação central.

A implementação não é difícil, mas os detalhes importam: tratamento de clock drift, atribuição de Machine ID em containers, e configuração do epoch. Com esses cuidados, você terá um sistema de geração de IDs que escala para bilhões de registros.

O UUID v7, padronizado em 2024, oferece uma alternativa interessante. Troca o tamanho compacto do Snowflake pela simplicidade de não precisar gerenciar Machine IDs. Para novos projetos, especialmente no .NET 9+, é uma opção a considerar seriamente.

A escolha entre Snowflake e UUID v7 depende do contexto: se você precisa de IDs menores e pode gerenciar a infraestrutura de Machine IDs, Snowflake é imbatível. Se prefere simplicidade e padronização, UUID v7 entrega praticamente os mesmos benefícios com menos complexidade operacional.

Ambos os algoritmos têm mais de uma década de validação em produção (Snowflake no Twitter, UUID v7 baseado em implementações similares) e continuam relevantes porque acertaram nos trade-offs fundamentais. Às vezes, as melhores soluções são as mais simples.

Redis INCR: O comando atômico que você deveria conhecer

Cristiano Rodrigues — Thu, 26 Mar 2026 14:21:33 +0000

Em sistemas distribuídos, contar algo corretamente é mais difícil do que parece. Dois processos lendo e atualizando o mesmo valor podem facilmente gerar race conditions e inconsistências.

É exatamente aqui que o comando INCR do Redis brilha.

O INCR resolve 3 problemas clássicos:

contadores distribuídos
rate limiting
geração de IDs

Vamos entender por que esse comando aparentemente simples é tão poderoso.

O que é o comando INCR?

O INCR incrementa o valor numérico armazenado em uma chave por 1. Se a chave não existir, ela é criada com valor 0 antes do incremento, resultando em 1.

> SET contador 10
OK
> INCR contador
(integer) 11
> INCR contador
(integer) 12

Se a chave não existe:

> INCR novo_contador
(integer) 1

A família completa de comandos de incremento inclui:

Comando	Descrição
`INCR`	Incrementa por 1
`INCRBY`	Incrementa por um valor inteiro específico
`INCRBYFLOAT`	Incrementa por um valor decimal
`DECR`	Decrementa por 1
`DECRBY`	Decrementa por um valor inteiro específico

Por que o INCR é especial?

A característica mais importante do INCR é sua atomicidade. Em sistemas distribuídos, onde múltiplas instâncias da aplicação podem tentar modificar o mesmo valor simultaneamente, a atomicidade garante que cada operação seja executada de forma isolada.

A atomicidade do INCR é possível porque o Redis executa comandos de forma sequencial em um único thread. Isso significa que não existe concorrência interna entre comandos: cada operação é processada por completo antes da próxima iniciar. Essa característica de single-thread para execução de comandos é o que torna operações como INCR naturalmente seguras em ambientes concorrentes.

Considere o cenário clássico de race condition:

Tempo    Processo A          Processo B          Valor Real
─────────────────────────────────────────────────────────────
T1       Lê valor: 10                            10
T2                           Lê valor: 10        10
T3       Calcula: 10 + 1                         10
T4                           Calcula: 10 + 1     10
T5       Escreve: 11                             11
T6                           Escreve: 11         11  ← Perdemos um incremento!

Com INCR, o Redis garante que isso não acontece. A operação de leitura-incremento-escrita é executada como uma única unidade atômica.

Casos de Uso Práticos

1. Contadores de visualização

Um dos casos mais comuns é contar visualizações de páginas ou recursos:

public class ViewCounterService
{
    private readonly IDatabase _redis;
    private readonly TimeSpan _cacheExpiry = TimeSpan.FromHours(24);

    public ViewCounterService(IConnectionMultiplexer connection)
    {
        _redis = connection.GetDatabase();
    }

    public async Task<long> IncrementViewCountAsync(string resourceId)
    {
        var key = $"views:{resourceId}";
        var count = await _redis.StringIncrementAsync(key);

        // Define TTL apenas na primeira visualização
        if (count == 1)
        {
            await _redis.KeyExpireAsync(key, _cacheExpiry);
        }

        return count;
    }

    public async Task<long> GetViewCountAsync(string resourceId)
    {
        var key = $"views:{resourceId}";
        var value = await _redis.StringGetAsync(key);
        return value.HasValue ? (long)value : 0;
    }
}

2. Rate Limiting com Fixed Window

O rate limiting é essencial para proteger APIs contra abusos. O INCR combinado com TTL cria um rate limiter baseado em fixed window, simples e eficiente:

public class RateLimiter
{
    private readonly IDatabase _redis;

    public RateLimiter(IConnectionMultiplexer connection)
    {
        _redis = connection.GetDatabase();
    }

    public async Task<RateLimitResult> CheckRateLimitAsync(
        string clientId, 
        int maxRequests, 
        TimeSpan window)
    {
        var key = $"ratelimit:{clientId}:{DateTime.UtcNow.Ticks / window.Ticks}";

        var count = await _redis.StringIncrementAsync(key);

        if (count == 1)
        {
            await _redis.KeyExpireAsync(key, window);
        }

        return new RateLimitResult
        {
            IsAllowed = count <= maxRequests,
            CurrentCount = count,
            Limit = maxRequests,
            RetryAfter = count > maxRequests 
                ? await _redis.KeyTimeToLiveAsync(key) 
                : null
        };
    }
}

public record RateLimitResult
{
    public bool IsAllowed { get; init; }
    public long CurrentCount { get; init; }
    public int Limit { get; init; }
    public TimeSpan? RetryAfter { get; init; }
}

Nota: Essa abordagem usa fixed window counter, onde cada janela de tempo tem seu próprio contador. Para cenários que exigem sliding window real, considere usar Sorted Sets com ZADD/ZRANGEBYSCORE ou um algoritmo de token bucket. Além disso, vale observar que o padrão INCR seguido de EXPIRE pode sofrer uma race condition sutil: outro processo pode incrementar a chave entre o INCR e o EXPIRE. Para maior robustez, você pode encapsular ambos em um script Lua, garantindo a execução atômica de INCR + EXPIRE.

Uso em um middleware ASP.NET Core:

public class RateLimitingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly RateLimiter _rateLimiter;

    public RateLimitingMiddleware(RequestDelegate next, RateLimiter rateLimiter)
    {
        _next = next;
        _rateLimiter = rateLimiter;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var clientId = context.Connection.RemoteIpAddress?.ToString() ?? "unknown";
        var result = await _rateLimiter.CheckRateLimitAsync(
            clientId, 
            maxRequests: 100, 
            window: TimeSpan.FromMinutes(1));

        context.Response.Headers["X-RateLimit-Limit"] = result.Limit.ToString();
        context.Response.Headers["X-RateLimit-Remaining"] = 
            Math.Max(0, result.Limit - result.CurrentCount).ToString();

        if (!result.IsAllowed)
        {
            context.Response.StatusCode = StatusCodes.Status429TooManyRequests;
            if (result.RetryAfter.HasValue)
            {
                context.Response.Headers["Retry-After"] = 
                    ((int)result.RetryAfter.Value.TotalSeconds).ToString();
            }
            return;
        }

        await _next(context);
    }
}

3. Geração de IDs sequenciais

Quando você precisa de IDs sequenciais em um sistema distribuído:

public class SequentialIdGenerator
{
    private readonly IDatabase _redis;
    private readonly string _prefix;

    public SequentialIdGenerator(IConnectionMultiplexer connection, string prefix = "id")
    {
        _redis = connection.GetDatabase();
        _prefix = prefix;
    }

    public async Task<long> GenerateIdAsync(string entity)
    {
        var key = $"{_prefix}:{entity}:sequence";
        return await _redis.StringIncrementAsync(key);
    }

    public async Task<string> GenerateFormattedIdAsync(string entity, string format = "{0}-{1:D8}")
    {
        var id = await GenerateIdAsync(entity);
        return string.Format(format, entity.ToUpper(), id);
    }
}

// Uso
var generator = new SequentialIdGenerator(connection);
var orderId = await generator.GenerateFormattedIdAsync("order"); 
// Resultado: "ORDER-00000001"

4. Contadores de sessões ativas

Monitorar quantos usuários estão ativos em tempo real:

public class ActiveSessionTracker
{
    private readonly IDatabase _redis;
    private const string ActiveSessionsKey = "sessions:active:count";
    private const string SessionPrefix = "session:";

    public ActiveSessionTracker(IConnectionMultiplexer connection)
    {
        _redis = connection.GetDatabase();
    }

    public async Task<string> StartSessionAsync(string userId)
    {
        var sessionId = Guid.NewGuid().ToString("N");
        var sessionKey = $"{SessionPrefix}{sessionId}";

        var transaction = _redis.CreateTransaction();

        _ = transaction.StringSetAsync(sessionKey, userId, TimeSpan.FromMinutes(30));
        _ = transaction.StringIncrementAsync(ActiveSessionsKey);

        await transaction.ExecuteAsync();

        return sessionId;
    }

    public async Task EndSessionAsync(string sessionId)
    {
        var sessionKey = $"{SessionPrefix}{sessionId}";

        var existed = await _redis.KeyDeleteAsync(sessionKey);

        if (existed)
        {
            await _redis.StringDecrementAsync(ActiveSessionsKey);
        }
    }

    public async Task<long> GetActiveSessionCountAsync()
    {
        var value = await _redis.StringGetAsync(ActiveSessionsKey);
        return value.HasValue ? (long)value : 0;
    }
}

Nota: Nessa abordagem, se uma sessão expirar automaticamente pelo TTL, o contador ActiveSessionsKey não será decrementado, o que pode gerar drift ao longo do tempo. Para maior robustez em produção, considere usar um Sorted Set (ZSET) com timestamps para rastrear sessões ativas, permitindo que você calcule o total real a qualquer momento com ZRANGEBYSCORE, ou implemente um processo periódico de reconciliação do contador.

5. Métricas por intervalo de tempo

Coletar métricas agregadas por minuto/hora/dia:

public class MetricsCollector
{
    private readonly IDatabase _redis;

    public MetricsCollector(IConnectionMultiplexer connection)
    {
        _redis = connection.GetDatabase();
    }

    public async Task RecordMetricAsync(string metricName, long value = 1)
    {
        var now = DateTime.UtcNow;

        var keys = new[]
        {
            $"metrics:{metricName}:minute:{now:yyyyMMddHHmm}",
            $"metrics:{metricName}:hour:{now:yyyyMMddHH}",
            $"metrics:{metricName}:day:{now:yyyyMMdd}"
        };

        var expiries = new[]
        {
            TimeSpan.FromHours(2),
            TimeSpan.FromDays(2),
            TimeSpan.FromDays(60)
        };

        var batch = _redis.CreateBatch();

        for (int i = 0; i < keys.Length; i++)
        {
            var key = keys[i];
            var expiry = expiries[i];

            _ = batch.StringIncrementAsync(key, value);
            _ = batch.KeyExpireAsync(key, expiry, ExpireWhen.HasNoExpiry);
        }

        batch.Execute();
    }

    public async Task<Dictionary<string, long>> GetHourlyMetricsAsync(
        string metricName, 
        DateTime date)
    {
        var results = new Dictionary<string, long>();

        for (int hour = 0; hour < 24; hour++)
        {
            var key = $"metrics:{metricName}:hour:{date:yyyyMMdd}{hour:D2}";
            var value = await _redis.StringGetAsync(key);
            results[$"{hour:D2}:00"] = value.HasValue ? (long)value : 0;
        }

        return results;
    }
}

Sistemas Distribuídos com múltiplos pods

Em ambientes Kubernetes ou qualquer arquitetura com múltiplas instâncias, o Redis INCR se torna ainda mais valioso. Cada pod opera de forma independente, sem conhecimento dos outros, mas todos precisam coordenar acesso a recursos compartilhados.

O Problema do estado compartilhado

Imagine 5 pods processando requisições simultaneamente. Sem coordenação central, cada pod manteria seu próprio contador local:

Pod 1: contador local = 47
Pod 2: contador local = 52
Pod 3: contador local = 38
Pod 4: contador local = 61
Pod 5: contador local = 44
                         ───────
Total real de requisições: 242
Mas cada pod "acha" que processou apenas seu número local

Com Redis como ponto central de coordenação, todos os pods compartilham a mesma visão do estado.

E em Redis Cluster?

Em arquiteturas maiores que utilizam Redis Cluster, o INCR funciona normalmente desde que as chaves relacionadas estejam no mesmo hash slot. O Redis Cluster distribui chaves entre nós usando CRC16, então se você precisa que múltiplas chaves sejam processadas no mesmo nó, utilize hash tags. Por exemplo, {rate}:user:123 e {rate}:user:456 serão direcionadas para o mesmo slot por compartilharem a tag {rate}. Isso é especialmente relevante quando você usa transactions ou scripts Lua que operam sobre múltiplas chaves.

Considerações de Performance

O INCR é extremamente rápido, com complexidade O(1). No entanto, existem algumas práticas para otimizar ainda mais:

Batch de operações: Quando você precisa incrementar múltiplos contadores, use batching:

public async Task IncrementMultipleAsync(Dictionary<string, long> counters)
{
    var batch = _redis.CreateBatch();
    var tasks = new List<Task<long>>();

    foreach (var (key, increment) in counters)
    {
        tasks.Add(batch.StringIncrementAsync(key, increment));
    }

    batch.Execute();
    await Task.WhenAll(tasks);
}

Pipeline: Para operações que não dependem do resultado imediato:

public void RecordEventsFireAndForget(IEnumerable<string> eventKeys)
{
    foreach (var key in eventKeys)
    {
        _redis.StringIncrement(key, flags: CommandFlags.FireAndForget);
    }
}

Armadilhas Comuns

1. Não definir TTL: Contadores sem expiração podem acumular indefinidamente. Sempre considere se o contador precisa de um TTL.

2. Usar GET seguido de SET: Nunca faça isso para incrementar valores. Use sempre INCR:

// ERRADO: Race condition!
var value = await _redis.StringGetAsync(key);
await _redis.StringSetAsync(key, (long)value + 1);

// CORRETO: Atômico
await _redis.StringIncrementAsync(key);

3. Ignorar overflow: O Redis armazena inteiros como strings de até 64 bits signed. Em cenários extremos, considere verificar limites.

4. Não tratar valores não numéricos: Se uma chave contiver um valor não numérico, INCR retornará erro. Valide ou use chaves dedicadas.

Conclusão

O INCR do Redis é uma ferramenta fundamental para construir sistemas distribuídos robustos. Sua atomicidade elimina race conditions, sua velocidade permite uso em cenários de alta performance, e sua simplicidade torna a implementação direta.

Os casos de uso vão desde contadores simples até rate limiters sofisticados e sistemas de métricas em tempo real. O segredo está em entender que operações atômicas simples, quando combinadas corretamente, resolvem problemas complexos de concorrência.

O poder do Redis muitas vezes não está em comandos complexos, mas em operações simples que são atômicas, rápidas e distribuídas.

Na próxima vez que você precisar de um contador distribuído, pense no INCR antes de partir para soluções mais complexas. Frequentemente, a resposta mais simples é também a mais elegante.

25 Dicas de performance com .NET 10

Cristiano Rodrigues — Tue, 24 Mar 2026 16:53:37 +0000

O .NET 10 traz melhorias significativas de performance, mas conhecer as técnicas certas faz toda a diferença. Este artigo reúne 25 dicas práticas para extrair o máximo de suas aplicações.

1. Prefira Span para manipulação de dados em memória

Span<T> permite trabalhar com fatias de memória sem alocações adicionais. Ideal para parsing e manipulação de strings ou arrays.

// Evite: cria substring (alocação)
string texto = "nome:valor";
string valor = texto.Substring(5);

// Prefira: zero alocações
ReadOnlySpan<char> span = texto.AsSpan();
ReadOnlySpan<char> valorSpan = span.Slice(5);

O ganho é especialmente relevante em loops ou operações de alto throughput, onde cada alocação evitada reduz a pressão sobre o Garbage Collector.

2. Use FrozenDictionary e FrozenSet para dados imutáveis

Introduzidas no .NET 8 e otimizadas no .NET 10, as coleções "frozen" são ideais para dados que não mudam após a inicialização.

using System.Collections.Frozen;

// Dados de configuração que nunca mudam
var statusCodes = new Dictionary<int, string>
{
    [200] = "OK",
    [404] = "Not Found",
    [500] = "Internal Server Error"
}.ToFrozenDictionary();

// Lookup significativamente mais rápido que Dictionary regular
var descricao = statusCodes[200];

O custo de criação é maior, mas as leituras subsequentes são significativamente mais rápidas devido às otimizações internas de hash (hashing otimizado para lookup). Os ganhos variam conforme o dataset, então sempre meça no seu cenário.

3. Evite Closures em Hot Paths

Closures podem gerar alocações, especialmente quando capturam variáveis externas. Em código executado frequentemente, isso impacta a performance.

// Evite: closure captura 'multiplicador'
int multiplicador = 10;
var resultado = lista.Select(x => x * multiplicador).ToList();

// Prefira: use um loop simples para evitar a captura
var resultado = new List<int>(lista.Count);
foreach (var item in lista)
{
    resultado.Add(item * multiplicador);
}

4. Configure o Garbage Collector para seu cenário

O .NET 10 permite ajuste fino do GC. Para aplicações de alta performance, considere o Server GC com regiões habilitadas.

<!-- No .csproj ou runtimeconfig.json -->
<PropertyGroup>
    <ServerGarbageCollection>true</ServerGarbageCollection>
    <GarbageCollectionAdaptationMode>1</GarbageCollectionAdaptationMode>
</PropertyGroup>

// Ou via código para cenários específicos
GCSettings.LatencyMode = GCLatencyMode.SustainedLowLatency;

Para aplicações com picos de alocação conhecidos, GC.TryStartNoGCRegion() pode evitar pausas em momentos críticos.

5. Use SearchValues para buscas repetitivas em strings

SearchValues<T> pré-computa estruturas de busca, tornando operações como IndexOfAny muito mais eficientes.

// Pré-compute uma vez
private static readonly SearchValues<char> Separadores = 
    SearchValues.Create([' ', ',', ';', '\t', '\n']);

// Use múltiplas vezes
public int ContarPalavras(ReadOnlySpan<char> texto)
{
    int count = 1;
    int index;
    while ((index = texto.IndexOfAny(Separadores)) >= 0)
    {
        count++;
        texto = texto.Slice(index + 1);
    }
    return count;
}

6. Prefira ValueTask para operações que frequentemente completam sincronamente

Quando um método async frequentemente retorna de forma síncrona (cache hit, por exemplo), ValueTask evita a alocação de Task.

private readonly ConcurrentDictionary<string, Produto> _cache = new();

// ValueTask evita alocação quando há cache hit
public ValueTask<Produto?> ObterProdutoAsync(string id)
{
    if (_cache.TryGetValue(id, out var produto))
    {
        return ValueTask.FromResult<Produto?>(produto);
    }

    return ObterProdutoDoBancoAsync(id);
}

private async ValueTask<Produto?> ObterProdutoDoBancoAsync(string id)
{
    var produto = await _repository.GetByIdAsync(id);
    if (produto is not null)
    {
        _cache.TryAdd(id, produto);
    }
    return produto;
}

ValueTask não deve ser usado indiscriminadamente. Ele não pode ser awaited múltiplas vezes e pode causar boxing se convertido para Task. Use apenas quando a maioria das chamadas (>90%) completa de forma síncrona.

7. Utilize ArrayPool e MemoryPool para arrays temporários

Reutilizar arrays através de pools reduz drasticamente as alocações em operações de I/O ou processamento de buffers.

public async Task ProcessarArquivoAsync(Stream stream)
{
    byte[] buffer = ArrayPool<byte>.Shared.Rent(8192);
    try
    {
        int bytesRead;
        while ((bytesRead = await stream.ReadAsync(buffer)) > 0)
        {
            ProcessarBloco(buffer.AsSpan(0, bytesRead));
        }
    }
    finally
    {
        // clearArray: true evita vazamento de dados entre usos
        ArrayPool<byte>.Shared.Return(buffer, clearArray: true);
    }
}

Os Arrays retornados pelo pool não são zerados por padrão. Se o buffer contiver dados sensíveis, sempre use clearArray: true no Return para evitar vazamento de informações entre usos.

Para cenários mais complexos, considere MemoryPool<T> que trabalha com Memory<T> e permite maior flexibilidade.

8. Implemente ISpanParsable para tipos customizados

O .NET 10 favorece parsing baseado em Span. Implemente ISpanParsable<T> para seus tipos de domínio.

public readonly record struct Cpf : ISpanParsable<Cpf>
{
    private readonly long _valor;

    public static Cpf Parse(ReadOnlySpan<char> s, IFormatProvider? provider)
    {
        // Remove pontuação sem alocar
        Span<char> digitos = stackalloc char[11];
        int pos = 0;

        foreach (char c in s)
        {
            if (char.IsDigit(c) && pos < 11)
                digitos[pos++] = c;
        }

        if (pos != 11)
            throw new FormatException("CPF deve ter 11 dígitos");

        return new Cpf(long.Parse(digitos));
    }

    public static bool TryParse(ReadOnlySpan<char> s, IFormatProvider? provider, out Cpf result)
    {
        // Implementação similar com tratamento de erro
    }
}

9. Use StringComparison explícito

Comparações de string sem especificar o tipo usam cultura corrente, que é mais lento e pode causar bugs sutis.

// Evite: usa CurrentCulture implicitamente
bool igual = str1.Equals(str2);
bool contem = texto.Contains("busca");

// Prefira: significativamente mais rápido para comparações ordinárias
bool igual = str1.Equals(str2, StringComparison.Ordinal);
bool contem = texto.Contains("busca", StringComparison.OrdinalIgnoreCase);

// Para dicionários
var dict = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);

10. Configure Connection Pooling adequadamente

Conexões de banco de dados são recursos caros. Configure o pool de acordo com sua carga.

// Para SQL Server / PostgreSQL
var connectionString = new NpgsqlConnectionStringBuilder
{
    Host = "localhost",
    Database = "mydb",
    Username = "user",
    Password = "pass",

    // Pool settings
    MinPoolSize = 10,
    MaxPoolSize = 100,
    ConnectionIdleLifetime = 300,
    ConnectionPruningInterval = 10
}.ToString();

// Para Entity Framework Core
services.AddDbContextPool<AppDbContext>(options =>
{
    options.UseNpgsql(connectionString);
}, poolSize: 128);

11. Prefira CompositeFormat para Strings formatadas repetidamente

CompositeFormat pré-compila o formato, evitando parsing repetido em logs ou mensagens frequentes.

// Pré-compile uma vez
private static readonly CompositeFormat LogFormat = 
    CompositeFormat.Parse("[{0:HH:mm:ss}] {1}: {2}");

// Use múltiplas vezes sem parsing repetido
public void Log(string nivel, string mensagem)
{
    var linha = string.Format(null, LogFormat, DateTime.Now, nivel, mensagem);
    Console.WriteLine(linha);
}

12. Use Source Generators para serialização JSON

System.Text.Json com source generators elimina reflection em runtime, melhorando performance.

[JsonSerializable(typeof(Produto))]
[JsonSerializable(typeof(List<Produto>))]
[JsonSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]
public partial class AppJsonContext : JsonSerializerContext { }

// Uso
var json = JsonSerializer.Serialize(produto, AppJsonContext.Default.Produto);
var produto = JsonSerializer.Deserialize(json, AppJsonContext.Default.Produto);

13. Evite Async em Métodos que não precisam

O overhead de async/await inclui a criação da máquina de estados. Se o resultado já está disponível, retorne diretamente.

// Evite: async desnecessário
public async Task<int> ObterValorAsync()
{
    return await Task.FromResult(42);
}

// Prefira: retorno direto
public Task<int> ObterValorAsync()
{
    return Task.FromResult(42);
}

// Para validações antes de operações async
public Task<Resultado> ProcessarAsync(Dados dados)
{
    if (dados is null)
        return Task.FromResult(Resultado.Invalido);

    return ProcessarInternoAsync(dados);
}

14. Utilize Parallel.ForEachAsync para I/O concorrente controlado

Para processamento paralelo de I/O, Parallel.ForEachAsync oferece controle fino sobre concorrência.

public async Task ProcessarUrlsAsync(IEnumerable<string> urls)
{
    var options = new ParallelOptions
    {
        MaxDegreeOfParallelism = 10 // Limite de requisições simultâneas
    };

    await Parallel.ForEachAsync(urls, options, async (url, ct) =>
    {
        var conteudo = await _httpClient.GetStringAsync(url, ct);
        await ProcessarConteudoAsync(conteudo);
    });
}

15. Configure HttpClient corretamente

HttpClient deve ser reutilizado. Use IHttpClientFactory para gerenciamento adequado de conexões.

// Configuração
services.AddHttpClient("api", client =>
{
    client.BaseAddress = new Uri("https://api.exemplo.com");
    client.DefaultRequestHeaders.Add("Accept", "application/json");
})
.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(2),
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(1),
    MaxConnectionsPerServer = 100,
    EnableMultipleHttp2Connections = true
});

// Uso
public class MeuServico(IHttpClientFactory factory)
{
    private readonly HttpClient _client = factory.CreateClient("api");
}

16. Use stackalloc para Buffers Pequenos

Para buffers pequenos e de vida curta, stackalloc evita completamente o uso do heap.

public string FormatarCpf(long cpf)
{
    Span<char> buffer = stackalloc char[14]; // XXX.XXX.XXX-XX

    cpf.TryFormat(buffer.Slice(0, 3), out _);
    buffer[3] = '.';
    // ... resto da formatação

    return new string(buffer);
}

// Com limite de segurança para tamanhos variáveis
public void ProcessarDados(int tamanho)
{
    Span<byte> buffer = tamanho <= 256
        ? stackalloc byte[tamanho]
        : new byte[tamanho];

    // Processar...
}

17. Prefira Struct Records para DTOs pequenos

Para objetos de transferência pequenos e imutáveis, record struct frequentemente evita alocações no heap.

// Alocado na stack, sem pressão no GC
public readonly record struct Coordenada(double Latitude, double Longitude);

public readonly record struct ResultadoPaginado<T>(
    T[] Items,
    int Total,
    int Pagina,
    int TamanhoPagina
);

Evite structs grandes (mais de 16-24 bytes) ou com muitos campos, pois o custo de cópia pode superar o benefício.

18. Use Regex Source Generators

Regex compilado via source generator é mais rápido e compatível com Native AOT.

public partial class Validadores
{
    [GeneratedRegex(@"^[\w\.-]+@[\w\.-]+\.\w{2,}$", RegexOptions.IgnoreCase)]
    private static partial Regex EmailRegex();

    [GeneratedRegex(@"^\d{5}-?\d{3}$")]
    private static partial Regex CepRegex();

    public static bool ValidarEmail(string email) => EmailRegex().IsMatch(email);
    public static bool ValidarCep(string cep) => CepRegex().IsMatch(cep);
}

19. Minimize Boxing com Generics Constraints

Boxing de value types cria objetos no heap. Use constraints genéricos para evitar.

// Evite: boxing implícito
public void Processar(IComparable valor) { }

// Prefira: sem boxing
public void Processar<T>(T valor) where T : IComparable<T> { }

// Para interfaces numéricas (.NET 7+)
public T Somar<T>(T a, T b) where T : INumber<T>
{
    return a + b;
}

20. Configure Output Caching em Minimal APIs

O .NET 10 traz melhorias significativas no Output Caching para Minimal APIs.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => builder.Expire(TimeSpan.FromMinutes(5)));

    options.AddPolicy("PorUsuario", builder => builder
        .SetVaryByHeader("Authorization")
        .Expire(TimeSpan.FromMinutes(1)));
});

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

app.MapGet("/produtos", async (AppDbContext db) =>
    await db.Produtos.ToListAsync())
    .CacheOutput(x => x.Expire(TimeSpan.FromMinutes(10)));

app.MapGet("/perfil", async (HttpContext ctx, AppDbContext db) =>
    await db.Usuarios.FindAsync(ctx.User.GetId()))
    .CacheOutput("PorUsuario");

21. Use Channels para Produtor-Consumidor

Channel<T> é mais eficiente que BlockingCollection para cenários async de produtor-consumidor.

public class FilaDeProcessamento
{
    private readonly Channel<Trabalho> _channel = Channel.CreateBounded<Trabalho>(
        new BoundedChannelOptions(1000)
        {
            FullMode = BoundedChannelFullMode.Wait,
            SingleReader = true,
            SingleWriter = false
        });

    public async ValueTask EnfileirarAsync(Trabalho trabalho, CancellationToken ct = default)
    {
        await _channel.Writer.WriteAsync(trabalho, ct);
    }

    public async Task ProcessarAsync(CancellationToken ct)
    {
        await foreach (var trabalho in _channel.Reader.ReadAllAsync(ct))
        {
            await ProcessarTrabalhoAsync(trabalho);
        }
    }
}

22. Prefira AsNoTracking para Queries somente leitura

O Entity Framework mantém tracking de entidades por padrão, o que consome memória e CPU.

// Para queries de leitura
var produtos = await _context.Produtos
    .AsNoTracking()
    .Where(p => p.Ativo)
    .ToListAsync();

// Configure globalmente para contextos de leitura
services.AddDbContext<ReadOnlyDbContext>(options =>
{
    options.UseNpgsql(connectionString)
           .UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking);
});

23. Utilize StringBuilder com capacidade inicial

Para concatenação de strings em loops, StringBuilder com capacidade pré-definida evita realocações.

public string GerarRelatorio(IReadOnlyList<Venda> vendas)
{
    // Estime a capacidade: ~50 chars por linha
    var sb = new StringBuilder(vendas.Count * 50);

    foreach (var venda in vendas)
    {
        sb.Append(venda.Data.ToString("dd/MM/yyyy"));
        sb.Append(" - ");
        sb.Append(venda.Cliente);
        sb.Append(": R$ ");
        sb.AppendLine(venda.Valor.ToString("N2"));
    }

    return sb.ToString();
}

24. Habilite Dynamic PGO

Profile-Guided Optimization dinâmica permite que o JIT otimize baseado no comportamento real da aplicação.

<PropertyGroup>
    <TieredPGO>true</TieredPGO>
</PropertyGroup>

Ou via variável de ambiente:

DOTNET_TieredPGO=1
DOTNET_TC_QuickJitForLoops=1
DOTNET_ReadyToRun=0

O Dynamic PGO pode trazer ganhos de 10-30% em aplicações de longa execução após o warm-up.

25. Meça ANTES DE OTIMIZAR

A dica mais importante: use ferramentas de profiling para identificar gargalos reais.

// BenchmarkDotNet para microbenchmarks
[MemoryDiagnoser]
[SimpleJob(RuntimeMoniker.Net100)]
public class MeusBenchmarks
{
    [Benchmark(Baseline = true)]
    public void AbordagemOriginal() { }

    [Benchmark]
    public void AbordagemOtimizada() { }
}

Ferramentas essenciais para profiling:

dotnet-counters: Métricas em tempo real de GC, threadpool, exceções
dotnet-trace: Coleta traces para análise detalhada
dotnet-dump: Análise de memória e diagnóstico de leaks
PerfView: Análise profunda de CPU e alocações
Visual Studio Profiler: Integração completa com debugging

# Monitorar métricas básicas
dotnet-counters monitor --process-id <PID> --counters System.Runtime

# Coletar trace de 30 segundos
dotnet-trace collect --process-id <PID> --duration 00:00:30

Conclusão

Performance em .NET 10 é resultado de escolhas conscientes em cada camada da aplicação. Desde a escolha de estruturas de dados apropriadas até a configuração adequada de infraestrutura, cada decisão impacta o resultado final.

Lembre-se: otimização prematura é a raiz de todo mal. Meça primeiro, identifique os gargalos reais, e então aplique as técnicas apropriadas. As dicas apresentadas aqui são ferramentas no seu arsenal, ou como eu costumo chamar... seu cinto de utilidades, use-as quando os dados indicarem necessidade.

Organizando Projetos .NET com o Central Package Management, Directory.Build e EditorConfig

Cristiano Rodrigues — Thu, 19 Mar 2026 10:36:00 +0000

Quando trabalhamos com soluções .NET que possuem múltiplos projetos, a manutenção pode se tornar um pesadelo. Imagine ter que atualizar a versão do Newtonsoft.Json em 15 projetos diferentes, ou garantir que todos os projetos usem as mesmas configurações de compilação. É exatamente para resolver esses problemas que existem recursos como Central Package Management, Directory.Build.props/targets e .editorconfig.

Neste artigo, vamos explorar cada um desses recursos e entender como eles podem transformar a organização do seu projeto.

O Problema: Caos em soluções Multi-Projeto

Antes de mergulharmos nas soluções, vamos entender o problema. Em uma solução típica com vários projetos, você provavelmente já enfrentou situações como:

Versões diferentes do mesmo pacote NuGet em projetos distintos, causando conflitos em runtime. Configurações de compilação repetidas em cada arquivo .csproj, tornando mudanças globais trabalhosas. Estilos de código inconsistentes entre desenvolvedores da equipe, gerando commits desnecessários apenas para formatação.

Esses problemas não apenas consomem tempo, mas também introduzem bugs sutis e dificultam a manutenção do código a longo prazo.

Central Package Management: Uma única fonte de verdade para versões

O Central Package Management (CPM) foi introduzido no NuGet 6.2 e permite centralizar todas as versões de pacotes em um único arquivo. Em vez de especificar versões em cada projeto, você define todas elas em um arquivo Directory.Packages.props na raiz da solução.

Habilitando o Central Package Management

Primeiro, crie um arquivo Directory.Packages.props na raiz da sua solução:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />
    <PackageVersion Include="Serilog" Version="3.1.1" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
    <PackageVersion Include="FluentValidation" Version="11.9.0" />
    <PackageVersion Include="Polly" Version="8.2.0" />
  </ItemGroup>
</Project>

Referenciando Pacotes nos Projetos

Com o CPM habilitado, seus arquivos .csproj ficam mais limpos. Note que você não especifica mais a versão:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore" />
    <PackageReference Include="Serilog" />
  </ItemGroup>
</Project>

Sobrescrevendo versões quando necessário

Em casos excepcionais onde um projeto específico precisa de uma versão diferente, você pode usar o atributo VersionOverride:

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" VersionOverride="12.0.3" />
</ItemGroup>

Isso é útil durante migrações graduais ou quando existe uma incompatibilidade específica em um projeto legado.

Organizando pacotes com rótulos

Para soluções grandes, você pode organizar os pacotes usando comentários ou até mesmo arquivos separados que são importados:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <!-- Frameworks e Runtime -->
  <ItemGroup Label="Microsoft">
    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />
    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="8.0.0" />
  </ItemGroup>

  <!-- Logging e Observabilidade -->
  <ItemGroup Label="Observability">
    <PackageVersion Include="Serilog" Version="3.1.1" />
    <PackageVersion Include="Serilog.Sinks.Console" Version="5.0.1" />
    <PackageVersion Include="OpenTelemetry" Version="1.7.0" />
  </ItemGroup>

  <!-- Testes -->
  <ItemGroup Label="Testing">
    <PackageVersion Include="xunit" Version="2.6.6" />
    <PackageVersion Include="Moq" Version="4.20.70" />
    <PackageVersion Include="FluentAssertions" Version="6.12.0" />
  </ItemGroup>
</Project>

Directory.Build.props: Configurações compartilhadas

O arquivo Directory.Build.props é automaticamente importado por todos os projetos no diretório onde ele está localizado (e em subdiretórios). Ele é processado no início do build, antes das configurações do projeto.

Criando o Directory.Build.props

Coloque este arquivo na raiz da solução:

<Project>
  <!-- Configurações gerais de compilação -->
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
  </PropertyGroup>

  <!-- Informações do assembly -->
  <PropertyGroup>
    <Company>MinhaEmpresa</Company>
    <Authors>Time de Desenvolvimento</Authors>
    <Copyright>Copyright © MinhaEmpresa 2026</Copyright>
    <RepositoryUrl>https://github.com/minhaempresa/meu-projeto</RepositoryUrl>
  </PropertyGroup>

  <!-- Configurações de output -->
  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>
</Project>

Configurações Condicionais

Você pode aplicar configurações diferentes baseadas em condições:

<Project>
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <!-- Configurações apenas para projetos de teste -->
  <PropertyGroup Condition="$(MSBuildProjectName.EndsWith('.Tests'))">
    <IsPackable>false</IsPackable>
    <IsTestProject>true</IsTestProject>
  </PropertyGroup>

  <!-- Configurações apenas para builds de Release -->
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <DebugType>none</DebugType>
    <DebugSymbols>false</DebugSymbols>
    <Optimize>true</Optimize>
  </PropertyGroup>

  <!-- Analisadores apenas em Debug -->
  <ItemGroup Condition="'$(Configuration)' == 'Debug'">
    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="8.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

Hierarquia de Directory.Build.props

O MSBuild procura por arquivos Directory.Build.props subindo na árvore de diretórios, mas por padrão para no primeiro que encontrar. Se você precisa de configurações em múltiplos níveis, use a importação explícita:

/solution
├── Directory.Build.props          (configurações globais)
├── src/
│   ├── Directory.Build.props      (configurações específicas de src)
│   ├── Api/
│   │   └── Api.csproj
│   └── Domain/
│       └── Domain.csproj
└── tests/
    ├── Directory.Build.props      (configurações específicas de testes)
    └── Api.Tests/
        └── Api.Tests.csproj

No src/Directory.Build.props, importe o arquivo pai:

<Project>
  <!-- Importa as configurações globais primeiro -->
  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />

  <!-- Configurações específicas para projetos em src/ -->
  <PropertyGroup>
    <IsPackable>true</IsPackable>
  </PropertyGroup>
</Project>

Directory.Build.targets: Ações Pós-Processamento

Enquanto o Directory.Build.props é importado no início do build, o Directory.Build.targets é importado no final, depois que todas as propriedades e itens do projeto foram definidos. Isso o torna ideal para tarefas que dependem de valores computados ou para adicionar targets customizados.

Casos de Uso Típicos

<Project>
  <!-- Target que roda após o build -->
  <Target Name="PrintBuildInfo" AfterTargets="Build">
    <Message Importance="High" Text="Build concluído: $(MSBuildProjectName) - $(Configuration)" />
  </Target>

  <!-- Copiar arquivos de configuração -->
  <Target Name="CopyConfigFiles" AfterTargets="Build" 
          Condition="Exists('$(ProjectDir)appsettings.local.json')">
    <Copy SourceFiles="$(ProjectDir)appsettings.local.json" 
          DestinationFolder="$(OutputPath)" 
          SkipUnchangedFiles="true" />
  </Target>

  <!-- Gerar arquivo de versão -->
  <Target Name="GenerateVersionFile" BeforeTargets="Build">
    <PropertyGroup>
      <BuildTimestamp>$([System.DateTime]::UtcNow.ToString("yyyy-MM-dd HH:mm:ss"))</BuildTimestamp>
    </PropertyGroup>
    <WriteLinesToFile File="$(OutputPath)version.txt"
                      Lines="Version: $(Version);Built: $(BuildTimestamp)"
                      Overwrite="true" />
  </Target>

  <!-- Validação de estrutura do projeto -->
  <Target Name="ValidateProjectStructure" BeforeTargets="Build">
    <Error Condition="!Exists('$(ProjectDir)README.md')" 
           Text="Cada projeto deve ter um README.md" />
  </Target>
</Project>

Diferença entre Props e Targets

A distinção é importante para evitar comportamentos inesperados:

O Directory.Build.props é processado antes do arquivo .csproj. Use-o para definir valores padrão que o projeto pode sobrescrever.

O Directory.Build.targets é processado depois do arquivo .csproj. Use-o para ações que dependem de valores finais ou para adicionar targets que referenciam propriedades do projeto.

Por exemplo, se você quer definir uma propriedade baseada no nome do projeto:

<!-- Directory.Build.targets (CORRETO) -->
<Project>
  <PropertyGroup>
    <PackageId Condition="'$(PackageId)' == ''">MinhaEmpresa.$(MSBuildProjectName)</PackageId>
  </PropertyGroup>
</Project>

Se isso estivesse em Directory.Build.props, o $(MSBuildProjectName) poderia não estar disponível ainda.

EditorConfig: Consistência de estilo de código

O arquivo .editorconfig define regras de formatação e estilo de código que são respeitadas pela maioria das IDEs modernas, incluindo Visual Studio, VS Code e Rider. Isso garante que todos os desenvolvedores do time sigam as mesmas convenções.

Estrutura Básica do EditorConfig

Crie um arquivo .editorconfig na raiz da solução:

# Arquivo raiz do EditorConfig
root = true

# Configurações para todos os arquivos
[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

# Configurações específicas para C#
[*.cs]
# Organização de usings
dotnet_sort_system_directives_first = true
dotnet_separate_import_directive_groups = false

# Preferências de this.
dotnet_style_qualification_for_field = false:suggestion
dotnet_style_qualification_for_property = false:suggestion
dotnet_style_qualification_for_method = false:suggestion
dotnet_style_qualification_for_event = false:suggestion

# Preferências de tipos
dotnet_style_predefined_type_for_locals_parameters_members = true:warning
dotnet_style_predefined_type_for_member_access = true:warning

# Preferências de modificadores
dotnet_style_require_accessibility_modifiers = for_non_interface_members:warning
csharp_preferred_modifier_order = public,private,protected,internal,static,extern,new,virtual,abstract,sealed,override,readonly,unsafe,volatile,async:warning

# Preferências de expressão
dotnet_style_object_initializer = true:suggestion
dotnet_style_collection_initializer = true:suggestion
dotnet_style_explicit_tuple_names = true:warning
dotnet_style_prefer_inferred_tuple_names = true:suggestion
dotnet_style_prefer_inferred_anonymous_type_member_names = true:suggestion

# Preferências de null checking
dotnet_style_coalesce_expression = true:warning
dotnet_style_null_propagation = true:warning
dotnet_style_prefer_is_null_check_over_reference_equality_method = true:warning

# Configurações de formatação C#
csharp_new_line_before_open_brace = all
csharp_new_line_before_else = true
csharp_new_line_before_catch = true
csharp_new_line_before_finally = true
csharp_new_line_before_members_in_object_initializers = true
csharp_new_line_before_members_in_anonymous_types = true

# Indentação
csharp_indent_case_contents = true
csharp_indent_switch_labels = true
csharp_indent_block_contents = true
csharp_indent_braces = false

# Espaçamento
csharp_space_after_cast = false
csharp_space_after_keywords_in_control_flow_statements = true
csharp_space_between_method_declaration_parameter_list_parentheses = false
csharp_space_between_method_call_parameter_list_parentheses = false

# Wrapping
csharp_preserve_single_line_statements = false
csharp_preserve_single_line_blocks = true

# Estilos de código
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_style_var_elsewhere = true:suggestion

# Expression-bodied members
csharp_style_expression_bodied_methods = when_on_single_line:suggestion
csharp_style_expression_bodied_constructors = false:suggestion
csharp_style_expression_bodied_operators = when_on_single_line:suggestion
csharp_style_expression_bodied_properties = true:suggestion
csharp_style_expression_bodied_indexers = true:suggestion
csharp_style_expression_bodied_accessors = true:suggestion
csharp_style_expression_bodied_lambdas = true:suggestion
csharp_style_expression_bodied_local_functions = when_on_single_line:suggestion

# Pattern matching
csharp_style_pattern_matching_over_is_with_cast_check = true:warning
csharp_style_pattern_matching_over_as_with_null_check = true:warning
csharp_style_prefer_switch_expression = true:suggestion
csharp_style_prefer_pattern_matching = true:suggestion
csharp_style_prefer_not_pattern = true:suggestion

# Null checking
csharp_style_throw_expression = true:suggestion
csharp_style_conditional_delegate_call = true:warning

# Preferências de código
csharp_prefer_simple_default_expression = true:suggestion
csharp_style_prefer_local_over_anonymous_function = true:suggestion
csharp_style_prefer_tuple_swap = true:suggestion
csharp_style_implicit_object_creation_when_type_is_apparent = true:suggestion
csharp_style_prefer_utf8_string_literals = true:suggestion
csharp_style_namespace_declarations = file_scoped:warning
csharp_style_prefer_primary_constructors = true:suggestion

# Using directives
csharp_using_directive_placement = outside_namespace:warning

# Configurações de XML/XAML
[*.{xml,csproj,props,targets}]
indent_size = 2

# Configurações de JSON
[*.json]
indent_size = 2

# Configurações de YAML
[*.{yml,yaml}]
indent_size = 2

# Markdown
[*.md]
trim_trailing_whitespace = false

Níveis de severidade

O EditorConfig permite definir diferentes níveis de severidade para cada regra:

none desabilita a regra completamente. silent ou refactoring aplica a regra apenas para refatorações, sem mostrar no editor. suggestion mostra como sugestão (pontos verdes no Visual Studio). warning mostra como aviso durante o build. error mostra como erro e falha o build.

Convenções de Nomenclatura

O EditorConfig também suporta regras de nomenclatura, essenciais para manter consistência:

[*.cs]
# Definição de símbolos
dotnet_naming_symbols.public_symbols.applicable_kinds = property,method,field,event,delegate
dotnet_naming_symbols.public_symbols.applicable_accessibilities = public,internal,protected,protected_internal

dotnet_naming_symbols.private_fields.applicable_kinds = field
dotnet_naming_symbols.private_fields.applicable_accessibilities = private

dotnet_naming_symbols.const_fields.applicable_kinds = field
dotnet_naming_symbols.const_fields.required_modifiers = const

dotnet_naming_symbols.interfaces.applicable_kinds = interface

dotnet_naming_symbols.async_methods.applicable_kinds = method
dotnet_naming_symbols.async_methods.required_modifiers = async

# Estilos de nomenclatura
dotnet_naming_style.pascal_case.capitalization = pascal_case

dotnet_naming_style.camel_case_with_underscore.capitalization = camel_case
dotnet_naming_style.camel_case_with_underscore.required_prefix = _

dotnet_naming_style.interface_style.capitalization = pascal_case
dotnet_naming_style.interface_style.required_prefix = I

dotnet_naming_style.async_suffix.capitalization = pascal_case
dotnet_naming_style.async_suffix.required_suffix = Async

# Regras
dotnet_naming_rule.public_members_pascal_case.symbols = public_symbols
dotnet_naming_rule.public_members_pascal_case.style = pascal_case
dotnet_naming_rule.public_members_pascal_case.severity = warning

dotnet_naming_rule.private_fields_camel_case.symbols = private_fields
dotnet_naming_rule.private_fields_camel_case.style = camel_case_with_underscore
dotnet_naming_rule.private_fields_camel_case.severity = warning

dotnet_naming_rule.const_fields_pascal_case.symbols = const_fields
dotnet_naming_rule.const_fields_pascal_case.style = pascal_case
dotnet_naming_rule.const_fields_pascal_case.severity = warning

dotnet_naming_rule.interfaces_begin_with_i.symbols = interfaces
dotnet_naming_rule.interfaces_begin_with_i.style = interface_style
dotnet_naming_rule.interfaces_begin_with_i.severity = error

dotnet_naming_rule.async_methods_end_with_async.symbols = async_methods
dotnet_naming_rule.async_methods_end_with_async.style = async_suffix
dotnet_naming_rule.async_methods_end_with_async.severity = suggestion

Estrutura final recomendada

Combinando tudo, essa seria uma estrutura de diretórios recomendada:

/MinhaSolucao
├── .editorconfig
├── Directory.Build.props
├── Directory.Build.targets
├── Directory.Packages.props
├── MinhaSolucao.sln
├── src/
│   ├── Directory.Build.props      (opcional, para configs específicas)
│   ├── MinhaSolucao.Api/
│   │   └── MinhaSolucao.Api.csproj
│   ├── MinhaSolucao.Domain/
│   │   └── MinhaSolucao.Domain.csproj
│   └── MinhaSolucao.Infrastructure/
│       └── MinhaSolucao.Infrastructure.csproj
└── tests/
    ├── Directory.Build.props      (opcional, para configs de teste)
    ├── MinhaSolucao.Api.Tests/
    │   └── MinhaSolucao.Api.Tests.csproj
    └── MinhaSolucao.Domain.Tests/
        └── MinhaSolucao.Domain.Tests.csproj

Dicas práticas

Comece pelo Central Package Management se você tem problemas frequentes com versões conflitantes de pacotes. É a mudança com maior impacto imediato.

O TreatWarningsAsErrors no Directory.Build.props força a equipe a manter o código limpo. Combine com NoWarn para ignorar conscientemente warnings específicos.

Use o EditorConfig com a severidade warning para regras importantes, mas não críticas, e error apenas para convenções que realmente não podem ser violadas (como o prefixo I em interfaces).

Versione esses arquivos no Git. Eles fazem parte da infraestrutura do projeto tanto quanto o código.

Ao migrar um projeto existente, faça incrementalmente. Comece com configurações menos restritivas e aumente a severidade conforme a equipe se adapta.

Conclusão

Investir tempo na configuração adequada da estrutura do projeto traz retornos significativos ao longo do ciclo de vida do software. Central Package Management elimina conflitos de versão e simplifica atualizações. Directory.Build.props/targets centraliza configurações e automatiza tarefas repetitivas. EditorConfig garante a consistência do código, independentemente da IDE ou do desenvolvedor.

Juntos, esses recursos transformam uma coleção de projetos em uma solução coesa. O esforço inicial de configuração se paga rapidamente em produtividade, menos bugs e código mais fácil de manter.

Gostou do artigo? Tem alguma configuração adicional que você usa em seus projetos? Compartilhe nos comentários!

Closures no .NET: As Alocações Invisíveis que Estão Matando sua Performance

Cristiano Rodrigues — Wed, 18 Mar 2026 18:06:02 +0000

Você já parou para pensar no que realmente acontece quando usa uma lambda que captura uma variável externa? Aquele código aparentemente inocente pode estar gerando alocações no heap sem você perceber, criando pressão no Garbage Collector e degradando a performance da sua aplicação.

Neste artigo, vamos dissecar o mecanismo de closures no .NET, entender exatamente o que o compilador gera por trás dos panos, e aprender técnicas práticas para evitar essas alocações quando performance é crítica.

O Que são Closures?

Uma closure ocorre quando uma função (lambda, delegate, ou método local) "captura" variáveis do escopo externo. O termo vem do conceito de "fechar" sobre o ambiente léxico onde a função foi definida.

public void ExemploSimples()
{
    int multiplicador = 10; // variável do escopo externo

    Func<int, int> multiplicar = x => x * multiplicador; // closure!

    Console.WriteLine(multiplicar(5)); // 50
}

Parece simples e elegante, certo? O problema é que essa elegância tem um custo oculto.

O que o compilador realmente gera

Quando você escreve uma closure, o compilador C# não faz mágica. Ele gera uma classe oculta para armazenar as variáveis capturadas. Vamos ver o que acontece com o exemplo anterior:

// O que você escreveu:
public void ExemploSimples()
{
    int multiplicador = 10;
    Func<int, int> multiplicar = x => x * multiplicador;
    Console.WriteLine(multiplicar(5));
}

// O que o compilador gera (simplificado):
public void ExemploSimples()
{
    var displayClass = new <>c__DisplayClass0_0(); // ALOCAÇÃO NO HEAP!
    displayClass.multiplicador = 10;

    Func<int, int> multiplicar = new Func<int, int>(displayClass.<ExemploSimples>b__0); // OUTRA ALOCAÇÃO!
    Console.WriteLine(multiplicar(5));
}

[CompilerGenerated]
private sealed class <>c__DisplayClass0_0
{
    public int multiplicador;

    internal int <ExemploSimples>b__0(int x)
    {
        return x * this.multiplicador;
    }
}

Percebeu? Duas alocações no heap onde você achava que não tinha nenhuma:

Uma instância da classe DisplayClass para armazenar as variáveis capturadas
Uma instância do delegate Func<int, int>

O impacto real: Benchmark

Vamos medir o impacto real dessas alocações:

using BenchmarkDotNet.Attributes;

[MemoryDiagnoser]
public class ClosureBenchmarks
{
    private const int Iterations = 1000;

    [Benchmark(Baseline = true)]
    public int SemClosure()
    {
        int soma = 0;
        for (int i = 0; i < Iterations; i++)
        {
            soma += MultiplicarSemClosure(i, 10);
        }
        return soma;
    }

    [Benchmark]
    public int ComClosure()
    {
        int multiplicador = 10;
        int soma = 0;
        for (int i = 0; i < Iterations; i++)
        {
            // Closure criada a cada iteração? Não!
            // Mas se estivesse dentro do loop...
            soma += MultiplicarComClosure(i, x => x * multiplicador);
        }
        return soma;
    }

    [Benchmark]
    public int ComClosureDentroDoLoop()
    {
        int soma = 0;
        for (int i = 0; i < Iterations; i++)
        {
            int multiplicador = 10; // variável declarada dentro do loop
            Func<int, int> func = x => x * multiplicador; // closure recriada!
            soma += func(i);
        }
        return soma;
    }

    private static int MultiplicarSemClosure(int x, int multiplicador) => x * multiplicador;

    private static int MultiplicarComClosure(int x, Func<int, int> func) => func(x);
}

Resultado típico:

Método	Mean	Allocated
SemClosure	1.2 μs	0 B
ComClosure	2.8 μs	64 B
ComClosureDentroDoLoop	45.3 μs	64,000 B

O cenário ComClosureDentroDoLoop aloca 64KB em apenas 1000 iterações! Em um hot path executado milhões de vezes, isso se traduz em pressão massiva no GC.

Cenários Comuns de Closures Problemáticas

1. LINQ em Hot Paths

// PROBLEMÁTICO: closure em cada chamada
public IEnumerable<Produto> FiltrarPorCategoria(int categoriaId)
{
    return _produtos.Where(p => p.CategoriaId == categoriaId);
}

// MELHOR: evitar closure quando possível
public IEnumerable<Produto> FiltrarPorCategoria(int categoriaId)
{
    // Se performance for crítica, considere um loop tradicional
    foreach (var produto in _produtos)
    {
        if (produto.CategoriaId == categoriaId)
            yield return produto;
    }
}

2. Event Handlers com Captura

// PROBLEMÁTICO: cada subscription cria uma closure
public void Registrar(string userId)
{
    _eventBus.Subscribe<PedidoCriado>(evento => 
        ProcessarPedido(evento, userId)); // closure captura userId
}

// MELHOR: usar objeto de estado explícito
public void Registrar(string userId)
{
    var handler = new PedidoHandler(userId);
    _eventBus.Subscribe<PedidoCriado>(handler.Processar);
}

3. Timers e Callbacks Assíncronos

// PROBLEMÁTICO: closure de longa duração
public void IniciarMonitoramento(string recurso)
{
    _timer = new Timer(_ => 
        VerificarStatus(recurso), // closure mantém referência
        null, 
        TimeSpan.Zero, 
        TimeSpan.FromSeconds(30));
}

// MELHOR: passar estado explicitamente
public void IniciarMonitoramento(string recurso)
{
    _timer = new Timer(
        state => VerificarStatus((string)state!),
        recurso, // estado passado explicitamente
        TimeSpan.Zero, 
        TimeSpan.FromSeconds(30));
}

4. Parallel.For e closures

// PROBLEMÁTICO: closure compartilhada entre threads
public void ProcessarEmParalelo(int[] dados)
{
    int total = 0;
    Parallel.For(0, dados.Length, i =>
    {
        Interlocked.Add(ref total, dados[i]); // closure + contention
    });
}

// MELHOR: usar overload com estado local
public void ProcessarEmParalelo(int[] dados)
{
    int total = 0;
    Parallel.For(
        0, 
        dados.Length,
        () => 0, // inicializador de estado local
        (i, state, subtotal) => subtotal + dados[i], // sem closure
        subtotal => Interlocked.Add(ref total, subtotal) // agregação final
    );
}

Técnicas para evitar Closures

1. Static Lambdas (C# 9+)

// Com static, o compilador IMPEDE a captura de variáveis
// Erro de compilação se tentar capturar algo
_lista.Where(static x => x.Ativo); // sem alocação de delegate

// Útil para lambdas que não precisam de estado externo
Func<int, int> dobrar = static x => x * 2;

2. Passar estado explicitamente

Muitos métodos do .NET aceitam um parâmetro state justamente para evitar closures:

// Closure
Task.Run(() => ProcessarItem(item));

// Estado explícito
Task.Factory.StartNew(
    state => ProcessarItem((Item)state!),
    item);

// Closure com Timer
new Timer(_ => Executar(config));

// Estado explícito com Timer
new Timer(
    state => Executar((Config)state!),
    config,
    dueTime,
    period);

3. Structs e ref struct para evitar Heap

// Usando Span<T> e stackalloc para evitar heap completamente
public int SomarPares(int[] numeros)
{
    Span<int> pares = stackalloc int[numeros.Length];
    int count = 0;

    foreach (var n in numeros)
    {
        if (n % 2 == 0)
            pares[count++] = n;
    }

    int soma = 0;
    foreach (var p in pares[..count])
        soma += p;

    return soma;
}

4. Object Pooling para Delegates reutilizáveis

public class ProcessadorPool
{
    private readonly ObjectPool<Action<Item>> _pool;

    public ProcessadorPool()
    {
        _pool = new DefaultObjectPool<Action<Item>>(
            new DefaultPooledObjectPolicy<Action<Item>>());
    }

    public void Processar(Item item)
    {
        var action = _pool.Get();
        try
        {
            // usar action
        }
        finally
        {
            _pool.Return(action);
        }
    }
}

5. Cached Delegates

public class Processador
{
    // Delegate cacheado como campo estático
    private static readonly Func<Produto, bool> _filtroAtivo = 
        static p => p.Ativo;

    // Reutilizado em todas as chamadas, zero alocações adicionais
    public IEnumerable<Produto> ObterAtivos(IEnumerable<Produto> produtos)
    {
        return produtos.Where(_filtroAtivo);
    }
}

Identificando Closures no seu código

1. JetBrains Rider / ReSharper

Configura para exibir hints de "Implicitly captured closure":

Settings → Editor → Inspection Severity → 
  "Implicitly captured closure" → Warning

2. Visual Studio com Roslyn Analyzers

Instale o pacote Microsoft.CodeAnalysis.NetAnalyzers e habilite:

CA1859: Use concrete types when possible for improved performance
CA1822: Mark members as static

3. BenchmarkDotNet com MemoryDiagnoser

[MemoryDiagnoser]
[DisassemblyDiagnoser]
public class MeusBenchmarks
{
    // O DisassemblyDiagnoser mostra o IL/ASM gerado
}

4. dotnet-counters para Monitoramento em Runtime

dotnet-counters monitor --process-id <PID> \
    --counters System.Runtime[gc-heap-size,alloc-rate]

Quando Closures são aceitáveis

Nem toda closure é problemática. Use closures livremente quando:

Código executado raramente: Setup de aplicação, configuração inicial
Código não crítico para performance: UI handlers em aplicações desktop
Clareza supera performance: Código de domínio onde legibilidade é prioridade
Lambdas estáticas são suficientes: Sem captura de variáveis

// Perfeitamente aceitável em startup
services.AddSingleton(sp => 
{
    var config = sp.GetRequiredService<IConfiguration>();
    return new MinhaClasse(config["Setting"]);
});

// Perfeitamente aceitável em código de domínio
var pedidosPendentes = pedidos
    .Where(p => p.Status == StatusPedido.Pendente)
    .OrderBy(p => p.DataCriacao)
    .ToList();

Resumo das Melhores Práticas

Cenário	Recomendação
Hot paths (loops apertados, alta frequência)	Evite closures completamente
LINQ em coleções grandes	Considere loops tradicionais
Callbacks de longa duração	Use estado explícito
Event handlers frequentes	Use métodos de instância
Lambdas sem captura	Use `static` keyword
Delegates reutilizáveis	Cache como campo estático
Parallel processing	Use overloads com estado local

Conclusão

Closures são uma ferramenta poderosa que torna o código C# mais expressivo e legível. No entanto, em cenários de alta performance, as alocações invisíveis que elas geram podem se tornar um gargalo significativo.

A chave não é eliminar todas as closures do seu código, mas sim:

Entender o que o compilador gera
Medir o impacto real com benchmarks
Otimizar apenas onde necessário

Use ferramentas como BenchmarkDotNet e analyzers do Roslyn para identificar hot paths problemáticos, e aplique as técnicas apresentadas de forma cirúrgica onde o impacto é mensurável.

Lembre-se: otimização prematura é a raiz de todo mal, mas ignorância sobre o que seu código realmente faz é ainda pior.

Gostou do conteúdo? Compartilhe com outros devs .NET que precisam entender o que acontece por trás das lambdas!

Async/Await no .NET 10: Eliminando o Overhead da State Machine

Cristiano Rodrigues — Wed, 04 Mar 2026 20:19:47 +0000

O .NET 10 trouxe melhorias significativas na programação assíncrona. Algumas são diretamente relacionadas ao async/await, enquanto outras otimizam o runtime de maneiras que beneficiam especialmente o código assíncrono. Vamos conhecer as principais.

Runtime-Async (Experimental)

Uma das melhorias mais interessantes do .NET 10 é o runtime-async. A ideia é implementar async/await diretamente no runtime/JIT, em vez de depender apenas da transformação do compilador C#.

Como funciona hoje

Quando você escreve um método async, o compilador do C# gera uma máquina de estados. Essa classe contém campos para todas as variáveis locais, o estado atual e o awaiter. A cada await, o método pode "pausar", salvando o estado, e "continuar", restaurando-o.

public async Task<string> BuscarDadosAsync(string url)
{
    var cliente = new HttpClient();
    var resposta = await cliente.GetStringAsync(url);
    return resposta.ToUpper();
}
// máquina de estado
private sealed class <BuscarDadosAsync>d__1 : IAsyncStateMachine
{
        public int <>1__state;

        public AsyncTaskMethodBuilder<string> <>t__builder;

        public string url;

        public C <>4__this;

        private HttpClient <cliente>5__1;

        private string <resposta>5__2;

        private string <>s__3;

        [Nullable(new byte[] { 0, 1 })]
        private TaskAwaiter<string> <>u__1;

        private void MoveNext()
        {
            int num = <>1__state;
            string result;
            try
            {
                if (num != 0)
                {
                    <cliente>5__1 = new HttpClient();
                }
                try
                {
                    TaskAwaiter<string> awaiter;
                    if (num != 0)
                    {
                        awaiter = <cliente>5__1.GetStringAsync(url).GetAwaiter();
                        if (!awaiter.IsCompleted)
                        {
                            num = (<>1__state = 0);
                            <>u__1 = awaiter;
                            <BuscarDadosAsync>d__1 stateMachine = this;
                            <>t__builder.AwaitUnsafeOnCompleted(ref awaiter, ref stateMachine);
                            return;
                        }
                    }
                    else
                    {
                        awaiter = <>u__1;
                        <>u__1 = default(TaskAwaiter<string>);
                        num = (<>1__state = -1);
                    }
                    <>s__3 = awaiter.GetResult();
                    <resposta>5__2 = <>s__3;
                    <>s__3 = null;
                    result = <resposta>5__2.ToUpper();
                }
                finally
                {
                    if (num < 0 && <cliente>5__1 != null)
                    {
                        ((IDisposable)<cliente>5__1).Dispose();
                    }
                }
            }
            catch (Exception exception)
            {
                <>1__state = -2;
                <cliente>5__1 = null;
                <resposta>5__2 = null;
                <>t__builder.SetException(exception);
                return;
            }
            <>1__state = -2;
            <cliente>5__1 = null;
            <resposta>5__2 = null;
            <>t__builder.SetResult(result);
        }

        void IAsyncStateMachine.MoveNext()
        {
            //ILSpy generated this explicit interface implementation from .override directive in MoveNext
            this.MoveNext();
        }

        [DebuggerHidden]
        private void SetStateMachine([Nullable(1)] IAsyncStateMachine stateMachine)
        {
        }

        void IAsyncStateMachine.SetStateMachine([Nullable(1)] IAsyncStateMachine stateMachine)
        {
            //ILSpy generated this explicit interface implementation from .override directive in SetStateMachine
            this.SetStateMachine(stateMachine);
        }
    }

O compilador transforma isso em uma classe com campos, um método MoveNext(), e toda a infraestrutura para gerenciar estados. Funciona bem, mas tem overhead.

O que muda com Runtime-Async

Com runtime-async, o JIT entende nativamente o conceito de "suspender" e "retomar" execução. Em vez de gerar state machines complexas, o código pode ser mais direto, com o runtime gerenciando a suspensão.

Benefícios esperados do Runtime-Async:

Redução significativa no tempo de execução para chamadas async encadeadas (multi-tier)
Redução nas alocações de memória por eliminar objetos de state machine
Melhor performance em cenários com muitas camadas async (Controller → Service → Repository)
Suspensão e retomada gerenciadas nativamente pelo runtime/JIT

Imagine uma requisição típica de API:

// Controller
public async Task<IActionResult> Get(int id)
{
    var dados = await _service.BuscarAsync(id);
    return Ok(dados);
}

// Service
public async Task<Dados> BuscarAsync(int id)
{
    var entidade = await _repository.GetByIdAsync(id);
    return MapearParaDados(entidade);
}

// Repository
public async Task<Entidade> GetByIdAsync(int id)
{
    return await _context.Entidades.FindAsync(id);
}

Hoje, cada camada gera sua própria state machine. Com runtime-async, o JIT pode otimizar toda a cadeia, reduzindo o overhead de cada "salto" entre métodos async.

Como habilitar

Para habilitar (ainda experimental), você precisa:

<!-- No .csproj -->
<PropertyGroup>
    <EnablePreviewFeatures>true</EnablePreviewFeatures>
    <Features>runtime-async=on</Features>
</PropertyGroup>

E a variável de ambiente: DOTNET_RuntimeAsync=1

Limitação atual: As bibliotecas do framework ainda não foram recompiladas com essa feature. Os ganhos são visíveis principalmente em código de aplicação.

ThreadPool Mais Inteligente

O .NET 10 traz melhorias no ThreadPool para prevenir deadlocks em cenários de sync-over-async.

O problema que resolve

Considere este cenário problemático:

public void MetodoSincrono()
{
    // Thread A pega um work item da fila local
    var resultado = MetodoAsync().Result; // Bloqueia Thread A
    // A continuação do MetodoAsync está na fila local de Thread A
    // Mas Thread A está bloqueada esperando...
    // Deadlock potencial!
}

Quando uma thread bloqueia esperando uma Task, ela pode estar segurando work items na sua fila local que são justamente as continuações necessárias para completar essa Task.

A solução do .NET 10

Antes de uma thread bloquear esperando uma Task, ela agora move work items da sua fila local para a fila global. Isso permite que outras threads processem esses work items, incluindo as continuações que vão desbloquear a Task.

// Internamente, algo como:
void BloquearEsperandoTask(Task task)
{
    // NOVO: Move work items locais para fila global
    MoverWorkItemsParaFilaGlobal();

    // Agora outras threads podem processar as continuações
    task.Wait();
}

Como isso ajuda no async

Mesmo que você siga todas as boas práticas e evite .Result e .Wait(), bibliotecas de terceiros ou código legado podem fazer isso. O ThreadPool mais inteligente reduz as chances de deadlock nesses cenários, tornando as aplicações async mais robustas.

Além disso, em cenários de alta carga onde o ThreadPool está saturado, essa melhoria ajuda a evitar situações em que threads ficam bloqueadas esperando trabalho que está "preso" em filas locais de outras threads.

Stack Allocation para Arrays Pequenos

O JIT do .NET 10 pode alocar arrays pequenos diretamente na stack quando detecta que não escapam do método.

O problema que resolve

Em código async, frequentemente criamos arrays temporários:

public async Task ProcessarAsync(Stream stream)
{
    byte[] buffer = new byte[4096]; // Alocação na heap
    int bytesLidos = await stream.ReadAsync(buffer);
    // Processar buffer...
}
// buffer vai para o GC

Cada chamada a esse método aloca um array na heap. Em um servidor processando milhares de requisições por segundo, isso gera pressão significativa no GC.

A solução do .NET 10

O JIT analisa se o array "escapa" do método (é passado para outro lugar, retornado ou armazenado em um campo). Se não escapa, pode alocar na stack:

void ProcessarIds()
{
    int[] ids = { 1, 2, 3, 4, 5 }; // Stack allocation!
    foreach (var id in ids)
        ProcessarId(id);
    // Array destruído automaticamente ao sair do método
}

Como isso ajuda no async

Nos métodos async, a situação é mais complexa. A state machine captura variáveis locais, como campos e arrays que cruzam um await, então arrays que cruzam um await geralmente não podem ser stack-allocated. Porém, arrays usados apenas antes do primeiro await ou apenas depois do último podem se beneficiar:

public async Task<int> CalcularAsync()
{
    // Este array pode ser stack-allocated (antes do await)
    int[] pesos = { 1, 2, 3, 4, 5 };
    int soma = pesos.Sum();

    var dados = await BuscarDadosAsync();

    // Este array também pode ser stack-allocated (depois do await, não escapa)
    int[] resultados = { dados.A, dados.B, dados.C };
    return resultados.Max() * soma;
}

A redução da pressão do GC significa menos pausas de coleta, o que melhora a latência das operações async, especialmente em cenários de alta throughput.

Escape Analysis para Delegates

Closures e delegates que não escapam do método também podem ser alocados na stack.

O problema que resolve

Closures são extremamente comuns em código async:

public async Task ProcessarListaAsync(List<int> numeros, int limite)
{
    // Esta closure captura 'limite' e aloca na heap
    var filtrados = numeros.Where(n => n > limite).ToList();

    await ProcessarFiltradosAsync(filtrados);
}

Cada invocação cria um objeto closure na heap para capturar a variável limite. Em código frequentemente chamado, isso acumula.

A solução do .NET 10

O JIT agora pode detectar quando uma closure não escapa e alocá-la na stack:

void Filtrar(List<int> numeros)
{
    int limite = 10;
    // Esta closure pode ser stack-allocated
    var grandes = numeros.Where(n => n > limite).ToList();
    // Closure destruída ao sair do método
}

Como isso ajuda no async

Código async frequentemente usa lambdas para continuações, transformações e callbacks:

public async Task<List<ProdutoDto>> BuscarProdutosAsync(string categoria)
{
    var produtos = await _repository.GetByCategoriaAsync(categoria);

    // Estas closures são candidatas a stack allocation
    var ativos = produtos.Where(p => p.Ativo).ToList();
    var dtos = ativos.Select(p => new ProdutoDto 
    { 
        Nome = p.Nome, 
        Preco = p.Preco 
    }).ToList();

    return dtos;
}

Combinado com a melhoria de arrays, código async que faz transformações de dados se beneficia duplamente: menos alocações de closures e menos alocações de arrays intermediários.

Impacto em Task.Run e continuações

Lambdas passadas para Task.Run ou ContinueWith geralmente escapam (são passados para o ThreadPool), então não se beneficiam diretamente. Porém, lambdas usadas localmente em operações LINQ antes ou depois de awaits podem ser otimizadas.

Juntando Tudo: O Impacto Combinado

Vejamos um exemplo que se beneficia de todas essas melhorias:

public async Task<RelatorioDto> GerarRelatorioAsync(int clienteId)
{
    // 1. Stack allocation para array de IDs
    int[] meses = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 };

    // 2. Runtime-async otimiza esta cadeia
    var vendas = await _vendasService.BuscarPorClienteAsync(clienteId);
    var pagamentos = await _pagamentosService.BuscarPorClienteAsync(clienteId);

    // 3. Closures podem ser stack-allocated
    var vendasPorMes = meses.Select(m => new
    {
        Mes = m,
        Total = vendas.Where(v => v.Data.Month == m).Sum(v => v.Valor)
    }).ToList();

    // 4. ThreadPool inteligente previne deadlocks se alguém chamar .Result
    return new RelatorioDto
    {
        ClienteId = clienteId,
        VendasPorMes = vendasPorMes,
        TotalPagamentos = pagamentos.Sum(p => p.Valor)
    };
}

Em versões anteriores do .NET, este método geraria:

State machine alocada na heap
Array meses na heap
Múltiplas closures para os lambdas
Possível risco de deadlock se chamado com .Result

No .NET 10:

Runtime-async pode otimizar a cadeia de awaits
Array meses pode ir para a stack
Closures podem ir para a stack
ThreadPool protege contra deadlocks

Diagnóstico: Verificando as Otimizações

Para verificar se as otimizações estão sendo aplicadas, você pode usar o BenchmarkDotNet:

[MemoryDiagnoser]
public class AsyncBenchmarks
{
    [Benchmark]
    public async Task<int> ProcessarComArrayAsync()
    {
        int[] valores = { 1, 2, 3, 4, 5 };
        await Task.Delay(1);
        return valores.Sum();
    }

    [Benchmark]
    public async Task<int> ProcessarComClosureAsync()
    {
        int limite = 3;
        var lista = new List<int> { 1, 2, 3, 4, 5 };
        await Task.Delay(1);
        return lista.Where(x => x > limite).Sum();
    }
}

Compare os resultados entre .NET 9 e .NET 10 para ver a redução em alocações.

Conclusão

O .NET 10 trouxe um conjunto de otimizações que, combinadas, melhoram significativamente a performance de código async:

Runtime-async reduz o overhead das state machines
ThreadPool inteligente previne deadlocks em cenários de sync-over-async
Stack allocation para arrays reduz pressão no GC
Escape analysis para delegates elimina alocações de closures temporárias

Essas melhorias são especialmente impactantes em aplicações de alto throughput, como APIs web, onde código async é executado milhares de vezes por segundo.

Convido você a realizar seus próprios benchmarks comparando .NET 9 e .NET 10 e compartilhar suas descobertas. Aproveite e leia sobre escape analysis e pare de alocar lixo na heap sem perceber.

Até a próxima!

Referências

Async/Await por Debaixo do Capô: Entendendo I/O Assíncrono no .NET

Cristiano Rodrigues — Mon, 09 Feb 2026 23:43:12 +0000

Windows (IOCP) | Linux (epoll/io_uring) | macOS (kqueue)

Introdução

Cada vez mais utilizamos async/await em nossas aplicações .NET, seja em APIs, processamento de arquivos ou comunicação com bancos de dados. Mas você já parou para pensar no que realmente acontece quando escrevemos await httpClient.GetAsync(url)?

Parece mágica: a thread é liberada enquanto esperamos a resposta do servidor, e quando os dados chegam, o código continua de onde parou. Porém, por trás dessa sintaxe elegante existe uma colaboração sofisticada entre o compilador C#, o runtime do .NET e o sistema operacional.

E aqui está um detalhe que muitos desenvolvedores desconhecem: cada plataforma oferece seu próprio mecanismo de I/O assíncrono. O Windows usa IOCP (I/O Completion Ports), o Linux usa epoll ou o mais moderno io_uring, e o macOS usa kqueue. O .NET abstrai essas diferenças, permitindo que o mesmo código rode eficientemente em qualquer plataforma.

Neste artigo vamos explorar em profundidade como todas essas peças se encaixam, desde o nível do hardware até a sintaxe do C#.

O Problema: Por Que I/O é Diferente

Para entender a necessidade do async, precisamos primeiro entender a natureza fundamental do I/O. Quando seu programa precisa ler dados do disco ou da rede, acontece algo muito diferente de uma operação de CPU.

CPU vs I/O: Escalas de Tempo

Uma CPU moderna executa bilhões de instruções por segundo. Um acesso à memória RAM leva cerca de 100 nanosegundos. Mas um acesso ao disco SSD leva cerca de 100 microssegundos (1000x mais lento), e uma chamada de rede pode levar 100 milissegundos (1.000.000x mais lento que a RAM).

Operação	Latência Típica	Ciclos CPU desperdiçados
Acesso à RAM	~100 ns	~300 ciclos
SSD (NVMe)	~100 μs	~300.000 ciclos
HDD	~10 ms	~30.000.000 ciclos
Rede local	~1 ms	~3.000.000 ciclos
Rede intercontinental	~100 ms	~300.000.000 ciclos

Vejam os números da tabela acima. Se uma thread fica bloqueada esperando I/O, ela está desperdiçando tempo que poderia ser usado para processar outras requisições. Imagine um servidor web com 10.000 conexões simultâneas: criar 10.000 threads bloqueadas consumiria cerca de 10GB de RAM apenas em stacks de thread. Isso não escala.

O Modelo Síncrono e Suas Limitações

No modelo síncrono tradicional, quando você chama File.ReadAllBytes(path), a thread fica bloqueada até o I/O completar. O kernel coloca a thread em estado de espera, o hardware trabalha, e quando termina, a thread é acordada. Durante todo esse tempo, a thread está ocupando recursos sem fazer nada útil.

Então qual é a solução? I/O assíncrono: iniciar a operação, liberar a thread imediatamente, e ser notificado quando completar. Cada sistema operacional implementa isso de forma diferente, e é isso que vamos explorar agora.

Windows: I/O Completion Ports (IOCP)

O Windows oferece o mecanismo mais maduro para I/O assíncrono: I/O Completion Ports (IOCP). Introduzido no Windows NT 3.5 em 1993, foi refinado ao longo de décadas e é a base de servidores de alta performance como IIS e SQL Server.

Arquitetura do IOCP

Mas como o IOCP funciona na prática? Ele opera como uma fila de notificações gerenciada pelo kernel. Quando uma operação de I/O completa, o kernel coloca uma notificação nessa fila. Um pequeno pool de threads fica esperando por notificações e as processa conforme chegam.

A beleza desse modelo é que você pode ter 10.000 operações de I/O pendentes sendo atendidas por apenas 20-50 threads. Cada thread processa uma notificação, executa o callback apropriado, e volta a esperar a próxima notificação.

As APIs do Windows

Para entender como isso funciona no nível do sistema, vejamos as principais APIs envolvidas:

// Criar uma porta de completion
HANDLE hPort = CreateIoCompletionPort(
    INVALID_HANDLE_VALUE, NULL, 0, 0);

// Associar um handle de arquivo à porta
CreateIoCompletionPort(hFile, hPort, completionKey, 0);

// Iniciar leitura assíncrona
ReadFile(hFile, buffer, size, NULL, &overlapped);

// Esperar por completions
GetQueuedCompletionStatus(hPort, &bytes, &key, &ov, INFINITE);

Quando você chama ReadFile() em modo assíncrono com uma estrutura OVERLAPPED, a função retorna imediatamente com ERROR_IO_PENDING. Isso indica que a operação foi iniciada e você será notificado quando completar.

O Fluxo Completo no Windows

Vamos acompanhar passo a passo o que acontece quando executamos await File.ReadAllBytesAsync(path) no Windows:

1. Thread 5 (sua thread): Chama ReadAllBytesAsync → FileStream abre arquivo com FILE_FLAG_OVERLAPPED → Chama ReadFile nativo → Retorna ERROR_IO_PENDING → await suspende o método → Thread 5 retorna ao ThreadPool e fica livre para outras tarefas

2. Hardware (durante 50ms): Controlador do disco recebe comando via DMA → Lê setores do SSD → Transfere bytes para buffer na RAM via DMA → Dispara interrupção para CPU

3. Kernel: Processa interrupção → Encontra a estrutura OVERLAPPED associada → Posta notificação na porta IOCP

4. Thread 8 (IOCP): GetQueuedCompletionStatus retorna → Task é completada com SetResult(bytes) → Continuação é agendada → MoveNext() é chamado → Seu código continua após o await

O ponto crucial aqui é que a Thread 5 nunca ficou esperando. Durante os 50ms de I/O, ela processou outras requisições.

Linux: epoll e io_uring

O Linux oferece duas abordagens principais para I/O assíncrono. O epoll, introduzido em 2002, é amplamente utilizado e otimizado para sockets e pipes. Já o io_uring, introduzido em 2019, representa uma revolução na forma como o Linux lida com I/O assíncrono.

epoll: O Mecanismo Clássico

O epoll usa um modelo readiness-based (baseado em prontidão), diferente do modelo completion-based do IOCP. Isso significa que o epoll avisa quando um file descriptor está pronto para leitura/escrita, não quando a operação completou.

// Criar instância epoll
int epfd = epoll_create1(0);

// Registrar interesse em um socket
struct epoll_event ev;
ev.events = EPOLLIN | EPOLLET;  // Edge-triggered
ev.data.fd = sockfd;
epoll_ctl(epfd, EPOLL_CTL_ADD, sockfd, &ev);

// Esperar eventos
struct epoll_event events[MAX_EVENTS];
int n = epoll_wait(epfd, events, MAX_EVENTS, -1);

// Processar eventos
for (int i = 0; i < n; i++) {
    if (events[i].events & EPOLLIN) {
        read(events[i].data.fd, buf, sizeof(buf));
    }
}

Uma limitação importante do epoll é que ele não funciona bem com arquivos regulares. Arquivos em disco sempre reportam "pronto" porque o kernel não pode prever se a leitura vai bloquear. Por isso, para I/O de arquivo, o .NET usa threads de trabalho que fazem a operação bloqueante em background.

io_uring: A Nova Era

Introduzido no Linux 5.1 (2019), o io_uring representa uma mudança de paradigma. Ele usa um par de ring buffers em memória compartilhada entre user space e kernel space, permitindo submeter e receber completions sem fazer syscalls para cada operação.

A arquitetura do io_uring consiste em duas filas circulares: Submission Queue (SQ), onde a aplicação coloca requisições de I/O, e Completion Queue (CQ), onde o kernel coloca os resultados. Ambas ficam em memória mapeada, evitando cópias e syscalls.

// Inicializar io_uring
struct io_uring ring;
io_uring_queue_init(256, &ring, 0);

// Preparar requisição de leitura
struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_read(sqe, fd, buf, size, offset);
sqe->user_data = (uint64_t)callback_context;

// Submeter
io_uring_submit(&ring);

// Coletar completion
struct io_uring_cqe *cqe;
io_uring_wait_cqe(&ring, &cqe);
int bytes_read = cqe->res;
void *ctx = (void*)cqe->user_data;
io_uring_cqe_seen(&ring, cqe);

O io_uring traz várias vantagens significativas: funciona com arquivos, sockets, e praticamente qualquer operação de I/O; suporta operações encadeadas (linked operations); permite batching de múltiplas operações em uma única syscall; e pode operar em modo "polled" para latência ultra-baixa.

O .NET 6+ pode usar io_uring através de bibliotecas como IoUring.Transport para Kestrel. A integração nativa ainda está em desenvolvimento, mas já demonstra ganhos significativos de performance.

macOS/BSD: kqueue

O kqueue, introduzido no FreeBSD 4.1 em 2000 e adotado pelo macOS, é um mecanismo elegante e versátil. Assim como o epoll, ele usa um modelo readiness-based, mas com uma interface mais flexível que pode monitorar muito mais do que apenas file descriptors.

Arquitetura e Versatilidade

O kqueue pode monitorar: sockets e pipes (via EVFILT_READ/WRITE), mudanças no filesystem (via EVFILT_VNODE), processos filhos (via EVFILT_PROC), sinais (via EVFILT_SIGNAL), e timers de alta resolução (via EVFILT_TIMER).

// Criar kqueue
int kq = kqueue();

// Registrar interesse em um socket
struct kevent ev;
EV_SET(&ev, sockfd, EVFILT_READ, EV_ADD | EV_ENABLE, 0, 0, NULL);
kevent(kq, &ev, 1, NULL, 0, NULL);

// Esperar eventos
struct kevent events[MAX_EVENTS];
int n = kevent(kq, NULL, 0, events, MAX_EVENTS, NULL);

// Processar eventos
for (int i = 0; i < n; i++) {
    int fd = events[i].ident;
    int bytes_available = events[i].data;  // Quantos bytes prontos!
    // ...
}

Uma vantagem interessante do kqueue é que o campo data do evento indica quantos bytes estão disponíveis para leitura. Isso permite alocar buffers do tamanho exato necessário.

Assim como o epoll, o kqueue não oferece I/O assíncrono verdadeiro para arquivos regulares. O .NET usa a mesma estratégia de threads de trabalho para compensar essa limitação.

Comparação entre Plataformas

Agora que entendemos cada mecanismo, vamos comparar suas características:

Aspecto	Windows IOCP	Linux epoll	macOS kqueue
Introduzido	1993 (NT 3.5)	2002 (Linux 2.5)	2000 (FreeBSD 4.1)
Modelo	Completion-based	Readiness-based	Readiness-based
Sockets	Excelente	Excelente	Excelente
Arquivos	Excelente	Limitado*	Limitado*
Timers	Via threadpool	Via timerfd	Nativo
Sinais	N/A	Via signalfd	Nativo

Nota: Para I/O de arquivo verdadeiramente assíncrono no Linux, use io_uring (Linux 5.1+). No macOS, I/O de arquivo usa threads de trabalho em background.

Juntando Todas as Peças

Agora que entendemos os mecanismos de cada plataforma, vamos ver como um simples await File.ReadAllBytesAsync() funciona em cada uma delas.

No Windows (IOCP)

1. Thread 5: ReadAllBytesAsync → FileStream com FILE_FLAG_OVERLAPPED → ReadFile → ERROR_IO_PENDING → await suspende → Thread 5 volta ao pool

2. Hardware: DMA transfere bytes → interrupção

3. Kernel: Processa interrupção → posta no IOCP

4. Thread 8 (IOCP): GetQueuedCompletionStatus retorna → completa Task → MoveNext() → código continua

No Linux (io_uring)

1. Thread 5: Prepara SQE → io_uring_submit → await suspende → Thread 5 volta ao pool

2. Hardware: DMA transfere → interrupção

3. Kernel: Posta CQE no io_uring

4. Thread do pool: io_uring_wait_cqe retorna → completa Task → continuação executa

No macOS (kqueue para sockets)

1. Thread 5: Registra kevent com EVFILT_READ → await suspende → Thread 5 volta ao pool

2. Kernel: Detecta dados chegaram → marca kevent como pronto

3. Thread do pool: kevent() retorna → lê dados → completa Task → continuação executa

O ponto crucial em todos os casos: A Thread 5 nunca ficou esperando. Ela processou outras requisições enquanto o I/O acontecia.

Como o .NET Abstrai as Diferenças

O .NET precisa fornecer uma API unificada que funcione em todas as plataformas. Internamente, ele detecta o sistema operacional e usa a implementação apropriada.

No Windows: O ThreadPool é integrado nativamente com IOCP. Threads do pool podem alternar entre executar work items e processar I/O completions.

No Linux: O .NET usa uma classe interna chamada SocketAsyncEngine que gerencia um epoll por processo. Para sockets, é assíncrono de verdade. Para arquivos, usa threads de trabalho.

No macOS: Similar ao Linux, usa kqueue para sockets e threads de trabalho para arquivos.

O ThreadPool no .NET mantém dois tipos de threads: Worker Threads (para Task.Run, continuations, etc.) e I/O Threads (para callbacks de IOCP no Windows, ou equivalentes em outras plataformas).

O Compilador e as State Machines

Quando você escreve um método async, o compilador C# faz uma transformação complexa. Ele converte seu método em uma classe que implementa IAsyncStateMachine. Esse é o recurso que permite "pausar" e "continuar" a execução.

O Que o Compilador Gera

Considere este código simples:

public async Task<string> BuscarDadosAsync(string url)
{
    var cliente = new HttpClient();
    var resposta = await cliente.GetStringAsync(url);
    return resposta.ToUpper();
}

O compilador transforma isso em algo parecido com:

private struct BuscarDadosAsyncStateMachine : IAsyncStateMachine
{
    public int state;
    public AsyncTaskMethodBuilder<string> builder;
    public string url;
    private HttpClient cliente;
    private string resposta;
    private TaskAwaiter<string> awaiter;

    public void MoveNext()
    {
        switch (state)
        {
            case -1: // Início
                cliente = new HttpClient();
                awaiter = cliente.GetStringAsync(url).GetAwaiter();
                if (!awaiter.IsCompleted)
                {
                    state = 0;
                    builder.AwaitUnsafeOnCompleted(ref awaiter, ref this);
                    return; // Libera a thread
                }
                goto case 0;
            case 0:
                resposta = awaiter.GetResult();
                builder.SetResult(resposta.ToUpper());
                return;
        }
    }
}

Vejam o que acontece: as variáveis locais viraram campos da struct. O método foi quebrado em estados (switch). Cada await é um ponto onde o método pode "pausar".

Quando o awaiter não está completo, a state machine registra o callback (via AwaitUnsafeOnCompleted) e faz return. Esse return é o que libera a thread. Quando o I/O completa, MoveNext() é chamado novamente, o switch vai para o estado correto, e a execução continua.

Boas Práticas: O Que Fazer e O Que Evitar

Agora que entendemos como async funciona internamente, podemos apreciar melhor por que certas práticas são recomendadas.

1. Nunca use .Result ou .Wait()

❌ EVITE:

var dados = httpClient.GetStringAsync(url).Result; // Deadlock!

✅ CORRETO:

var dados = await httpClient.GetStringAsync(url);

Chamar .Result ou .Wait() bloqueia a thread atual esperando a Task completar. Se você está em um contexto com SynchronizationContext (como ASP.NET clássico ou WPF), a continuação precisa rodar nessa mesma thread, mas ela está bloqueada esperando. Deadlock.

2. Evite async-over-sync

❌ EVITE:

await Task.Run(() => File.ReadAllBytes(path)); // Thread bloqueada

✅ CORRETO:

await File.ReadAllBytesAsync(path); // Async de verdade

Task.Run com código síncrono apenas move o bloqueio para outra thread. Você não ganha nada, só desloca o problema.

3. Use ConfigureAwait(false) em bibliotecas

❌ EVITE:

// Biblioteca capturando contexto desnecessariamente
public async Task<T> GetAsync<T>(string url)
{
    var response = await _httpClient.GetAsync(url);
    // ...
}

✅ CORRETO:

public async Task<T> GetAsync<T>(string url)
{
    var response = await _httpClient.GetAsync(url)
        .ConfigureAwait(false);
    // ...
}

Em bibliotecas, você não precisa voltar ao contexto original. ConfigureAwait(false) permite que a continuação rode em qualquer thread, evitando overhead e possíveis deadlocks.

4. Evite async void (exceto event handlers)

❌ EVITE:

public async void ProcessarEmBackground() // Exceções perdidas!
{
    await Task.Delay(1000);
    throw new Exception("Ninguém vai ver isso");
}

✅ CORRETO:

public async Task ProcessarEmBackgroundAsync()
{
    await Task.Delay(1000);
    throw new Exception("Vai propagar corretamente");
}

EXCEÇÃO (event handlers):

private async void btnSalvar_Click(object sender, EventArgs e)
{
    await SalvarAsync(); // OK, é um event handler
}

async void é "fire and forget": exceções não podem ser capturadas e vão derrubar o processo. Use apenas em event handlers, onde a assinatura exige void.

5. Sempre suporte CancellationToken

❌ EVITE:

public async Task<List<Produto>> BuscarProdutosAsync()
{
    // Operação que não pode ser cancelada
}

✅ CORRETO:

public async Task<List<Produto>> BuscarProdutosAsync(
    CancellationToken ct = default)
{
    var response = await _httpClient.GetAsync(url, ct);
    ct.ThrowIfCancellationRequested();
    // ...
}

CancellationToken permite cancelar operações quando não são mais necessárias. Isso é essencial para timeout de requisições HTTP, shutdown gracioso da aplicação, e cancelamento por parte do usuário.

6. Use Task.WhenAll para operações paralelas

❌ EVITE (sequencial: ~530ms):

var vendas = await BuscarVendasAsync();      // 200ms
var clientes = await BuscarClientesAsync();  // 150ms
var estoque = await BuscarEstoqueAsync();    // 180ms

✅ CORRETO (paralelo: ~200ms):

var vendasTask = BuscarVendasAsync();
var clientesTask = BuscarClientesAsync();
var estoqueTask = BuscarEstoqueAsync();

await Task.WhenAll(vendasTask, clientesTask, estoqueTask);

var vendas = vendasTask.Result;    // Já completou
var clientes = clientesTask.Result;
var estoque = estoqueTask.Result;

Quando você tem múltiplas operações independentes, inicie todas antes de aguardar qualquer uma. Task.WhenAll permite que executem em paralelo.

Diagnóstico e Troubleshooting

Entender async é importante também para diagnosticar problemas. Vejamos algumas técnicas úteis.

Monitorando o ThreadPool

ThreadPool.GetAvailableThreads(out int workerAvail, out int ioAvail);
ThreadPool.GetMaxThreads(out int workerMax, out int ioMax);

var workerBusy = workerMax - workerAvail;
var ioBusy = ioMax - ioAvail;

Console.WriteLine($"Workers ocupados: {workerBusy}");
Console.WriteLine($"I/O threads ocupadas: {ioBusy}");

Se você vê muitos workers ocupados durante operações de I/O, provavelmente há código bloqueante onde deveria ser async.

Sinais de Problemas

Wall Time alto com CPU baixo: Indica I/O síncrono bloqueando threads. O tempo total é alto, mas a CPU fica ociosa esperando I/O.

ThreadPool starvation: Threads esgotadas, novas tarefas ficam na fila. Sintoma comum de sync-over-async.

Thread count crescente: O runtime cria threads para compensar as bloqueadas. Consumo de memória aumenta progressivamente.

Deadlocks com .Result/.Wait(): Aplicação trava completamente em certos cenários. Comum em código legado misturado com async.

Conclusão

O async/await no .NET abstrai elegantemente as complexidades do I/O assíncrono em cada plataforma. O Windows com IOCP, o Linux com epoll/io_uring, e o macOS com kqueue oferecem diferentes abordagens, mas o .NET nos permite escrever código que funciona em todas elas.

Entender como esses mecanismos funcionam por baixo do capô nos ajuda a escrever código mais eficiente, diagnosticar problemas de performance, escolher as APIs corretas para cada situação, e aproveitar ao máximo o I/O assíncrono verdadeiro.

O exemplo foi extenso, mas importante para demonstrar a profundidade do assunto. Convido você a realizar seus próprios testes, explorar o código do .NET no GitHub, e compartilhar suas descobertas.

Até a próxima!

Referências

.NET 10: O GC que reduz a memória, mas exige uma escolha dura – Você aceita diminuir o Throughput?

Cristiano Rodrigues — Wed, 29 Oct 2025 15:17:26 +0000

Recentemente, a Maoni publicou um post explicando em detalhes como o DATAS afeta o comportamento das aplicações. Este texto traz um resumo dos principais pontos abordados por ela.
Para quem quiser ler o post original completo, acesse aqui o link.

A transição para o .NET 10 introduz uma alteração significativa no mecanismo de Coleta de Lixo (GC), com a ativação padrão do DATAS (Dynamic Adaptation to Application Size — Adaptação Dinâmica ao Tamanho da Aplicação) para o Server GC. Embora o .NET 9 já contasse com o DATAS habilitado por padrão, a migração para a versão LTS (.NET 10) representa o primeiro contato de muitos usuários com este recurso.

Diferentemente da maioria das otimizações do GC, que são transparentes e automáticas, o DATAS exige atenção do usuário, o que justifica a necessidade de uma fase de preparação e análise. As mudanças no perfil de desempenho da aplicação podem ser notáveis, principalmente na utilização da memória, que tende a ser significativamente reduzida.

É importante que os usuários avaliem as métricas de desempenho de suas aplicações para determinar se esta compensação se alinha aos seus objetivos de otimização.

1. O Paradigma do DATAS em Comparação ao Server GC Tradicional

A principal distinção do DATAS reside na sua política fundamental: a adaptação ao tamanho da aplicação. O Server GC tradicional nunca teve como objetivo adaptar-se ao tamanho da aplicação, baseando suas decisões primariamente na taxa de sobrevivência das gerações e no número de cores (núcleos) que o processo pode utilizar. Em consequência, o tamanho do heap em um Server GC não adaptativo pode variar drasticamente dependendo da máquina em que é executado.

O DATAS resolve essa variabilidade ao adaptar-se ao LDS (Live Data Size - Tamanho dos Dados Vivos), resultando em tamanhos de heap similares, mesmo que o número de cores varie substancialmente.

1.1 Objetivos Primários do DATAS

O DATAS foi concebido para atender a dois tipos específicos de cenários:

Cargas de Trabalho Intermitentes (Bursty Workloads) em Ambientes com Restrição de Memória: Aplicativos que processam um volume variável de requisições, com picos e vales de demanda. O DATAS retrai o tamanho do heap quando a carga de trabalho diminui e o expande quando a demanda aumenta. Este comportamento é particularmente valioso em contêineres com limites de memória estabelecidos. Em ambientes orquestrados (como k8s), o DATAS aumenta a robustez do gerenciamento, auxiliando na definição de limites de memória mais previsíveis, o que potencializa o uso de HPA (Horizontal Pod Autoscaler).
Cargas de Trabalho de Pequeno Porte Utilizando Server GC: Para aplicações menores, como um pequeno serviço asp.net core, o DATAS garante que o tamanho do heap esteja mais alinhado com as necessidades reais de memória da aplicação.

1.2 O Mecanismo de Adaptação

A adaptabilidade é alcançada através de dois componentes-chave:

Budget Computed via DATAS (BCD): Este conceito introduz um limite superior para o orçamento da Geração 0 (Gen0), calculado em função do tamanho da aplicação (LDS).
Manutenção do Throughput: Dentro desse limite superior, a memória é reduzida, desde que seja mantido um nível de desempenho aceitável, definido pelo Target Throughput Cost Percentage (TCP). O TCP padrão é de 2%. Se a carga de trabalho diminuir (e, consequentemente, o custo de throughput cair abaixo do TCP), o DATAS reduzirá o orçamento da Gen0, o que resulta em GCs mais frequentes, mas em um tamanho de heap geral menor, adaptando-se à demanda.

Em termos simples, o TCP indica quanto tempo o GC fica em pausa quando o sistema está em estado estável.

1.3 Implicações para o Workstation GC

Para aqueles desenvolvedores que utilizavam o Workstation GC unicamente para restringir o consumo de memória, devido ao uso excessivo pelo Server GC, podem considerar o DATAS uma alternativa superior. O DATAS possibilita tanto a limitação do uso de memória quanto a redução das pausas do GC, aproveitando múltiplas threads para a coleta (característica do Server GC).

2. Cenários em que o recurso não se aplica e pode causar perda de desempenho

Embora o DATAS otimize a utilização de memória, ele geralmente implica uma ligeira regressão no *throughput* em comparação com o Server GC não adaptativo. É crucial analisar métricas de desempenho para validar a implementação.

O DATAS não é recomendado nos seguintes cenários, a menos que haja tuning específico:

Sem Benefício no Uso de Memória Liberada: Em aplicações executadas em máquinas dedicadas, onde a memória liberada pelo DATAS não será reutilizada, a mudança de comportamento pode não trazer vantagens reais.
Impacto no Desempenho de Inicialização (Startup Performance): O DATAS sempre começa com apenas um heap. Como o ajuste inicial prioriza a otimização de tamanho, o crescimento para múltiplos heaps ocorre gradualmente — o que pode causar regressão no desempenho de inicialização.
Cenários com Alta Exigência de *Throughput*: Em ambientes dedicados que precisam maximizar o throughput nos horários de pico e não toleram quedas de desempenho, o DATAS pode não ser ideal. Nesses casos, pode ser necessário desativá-lo ou ajustar seu tuning de forma mais agressiva.
Aplicações com Muitas Coletas de Geração 2 (Gen2): Quando a aplicação realiza majoritariamente GCs de Gen2 — geralmente devido à criação excessiva de objetos temporários grandes — e o DATAS apresenta resultados insatisfatórios, recomenda-se desativá-lo.

3. Soluções e Estratégias de Tuning para o DATAS

Se for observada uma diminuição no throughput após a migração, existem configurações específicas para otimizar o DATAS ou desativá-lo.

3.1 Desativação Simples

Para desativar o mecanismo de adaptação dinâmica, utilize a configuração GCDynamicAdaptationMode.

3.2 Otimização Fina (Tuning)

A otimização geralmente envolve ajustar o orçamento da Geração 0 (BCD) para permitir um uso maior de memória entre as coletas, melhorando o throughput.

A análise de desempenho deve focar em traços do GC, comparando o "Gen0 Alloc MB" (orçamento Gen0) e a "% Pause Time" (aproximação do TCP) entre as execuções. Em um caso de cliente, por exemplo, o orçamento de Gen0 sem DATAS era 2.6 vezes maior do que com DATAS, pois este último estava estritamente aderente ao TCP padrão de 2%.

Para ajustar o BCD e aumentar o throughput:

Ajuste do Target TCP: Se o throughput for mais importante, o alvo de custo de throughput pode ser reduzido, por exemplo, para 1%, utilizando a configuração GCDTargetTCP.
Aumento do Orçamento Gen0: Para que o DATAS utilize um orçamento de Gen0 maior, deve-se aumentar o multiplicador usado no cálculo do BCD:
- Use GCDGen0GrowthPercent para aumentar a constante na fórmula do BCD.
- Se for necessário um aumento muito grande (para garantir que o orçamento não seja limitado pelo valor mínimo), ajuste GCDGen0GrowthMinFactor.

3.3 Gerenciamento Dinâmico de Heaps

Anteriormente, alguns desenvolvedores configuravam manualmente o número de heaps (GCHeapCount) no Server GC para restringir o uso de memória. Contudo, especificar GCHeapCount desabilita o DATAS, pois interfere na sua capacidade de adaptar o número de heaps.

A recomendação é remover a configuração GCHeapCount. Ao permitir que o DATAS gerencie a contagem de heaps, a aplicação se beneficia de maior flexibilidade. Em cenários de alta carga, o uso de mais threads de GC resulta em pausas individuais de coleta significativamente menores, e o tamanho total do heap ainda é reduzido quando a carga diminui.

Conclusão

O DATAS é uma evolução robusta do Server GC, tornando-o mais adequado para ambientes modernos de infraestrutura baseada em contêineres e multitenancy. Contudo, a natureza fundamentalmente diferente de sua política de alocação exige validação.

O sucesso da implementação do DATAS no .NET 10 depende da análise cuidadosa dos objetivos de otimização da aplicação. Se a redução de memória é prioridade, o DATAS deve ser mantido. Se a maximização do throughput é o foco absoluto, o tuning fino (via GCDTargetTCP ou GCDGen0GrowthPercent) ou a desativação completa pode ser a solução mais adequada. A execução de testes de desempenho comparativos é essencial para determinar a configuração ideal.

DEV Community: Unhacked

Singleton em C# e .NET 10: o padrão que todo mundo conhece e quase todo mundo usa errado

O que o Singleton resolve

Por que a solução óbvia falha

Anatomia do padrão

Implementação: da trava ao Lazy

Trava em toda leitura

Double-checked locking

Inicialização estática

Lazy<T>: a forma idiomática

Performance: por que o benchmark ingênuo mente

Exemplo da vida real

Integração com ASP.NET Core: o Singleton que você deveria usar

Quando não usar: o lado escuro do padrão

Conclusão

Backpressure sem drama: pipelines in-process com System.Threading.Channels

O problema em detalhe: por que as soluções óbvias falham

Anatomia de um Channel

Por que funciona

O que acontece por baixo dos panos

Implementação: do básico ao pipeline

Integração real: fila de trabalho em ASP.NET Core

Alta performance: as opções que a maioria ignora

Benchmark 1: o pipeline completo

Benchmark 2: isolando a estrutura de dados

Outras variantes: o canal com prioridade

Quando escolher cada um

Erros comuns

Considerações e limitações

Conclusão

Referências

Gerenciando Feature Flags no Azure App Configuration com Minimal APIs em .NET

Como o WithFeatureGate funciona por dentro

FeatureGate e autorização: quem decide primeiro

A avaliação assíncrona das flags

O "tempo real" do refresh, sem a ilusão

Segurança: a role que todo mundo esquece

Targeting na prática

Do interruptor binário às variants

Quando NÃO usar Feature Flags

Conclusão

Streaming de JSON no ASP.NET Core: o endpoint de ingestão que para de estourar a memória

O cenário concreto

O que realmente acontece com [FromBody]

Por que o streaming funciona

O detalhe que quase ninguém comenta: backpressure

A implementação em streaming

O streaming só vale se o processamento também for streaming

Validação passa a ser sua responsabilidade

Medindo o ganho

Estimando o pico, que é o que importa

O teste que mais convence: carga real

Quando escolher cada abordagem

Não é só para payloads gigantes

Limitações que você precisa conhecer antes de produção

Conclusão

Snowflake e UUID v7: Gerando identificadores únicos em sistemas distribuídos

O problema dos IDs distribuídos

Anatomia de um Snowflake ID

O que cada parte significa

Como o ID é montado na prática

Por que essa estrutura é genial

Implementação em "C#"

Uso básico

Integração com ASP.NET Core

Registro como Serviço Singleton

Configuração no Program.cs

Uso em entidades

Implementação de alta performance

Benchmark Comparativo

Atribuição de Machine ID em Kubernetes

1. StatefulSet com Ordinal Index

2. Registro Dinâmico com Redis

3. Baseado em IP do Pod

Variações do Snowflake

Discord (Epoch: 2015)

Instagram (Sharded)

Sony (Sonyflake)

UUID v7: O Padrão Moderno

Anatomia do UUID v7

Como o `WithFeatureGate` funciona por dentro

O que realmente acontece com `[FromBody]`