DEV Community: Cristiano Rodrigues

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.

Managing Features in Minimal APIs with Microsoft.FeatureManagement: An Introduction to Feature Flag Support.

Cristiano Rodrigues — Sat, 08 Mar 2025 22:54:18 +0000

Recently, I had the honor of contributing to the open-source project Microsoft/FeatureManagement-Dotnet, a well-established library that simplifies the use of feature flags within the .NET ecosystem. My implementation added native support for Minimal APIs in ASP.NET Core, providing a practical way to integrate dynamic feature control. In this article, I’ll explore this new functionality I developed, covering everything from basic concepts to advanced scenarios, with practical examples and suggestions on how to apply it in real-world projects.

The Role of Feature Flags in Modern Development

Feature flags, or functionality toggles, are a cornerstone of contemporary software development. They allow enabling or disabling features at runtime without requiring code changes or a new deployment. This is particularly valuable in cases such as:

Progressive Rollouts: Gradually introducing new features to subsets of users, minimizing risks.
A/B Testing: Comparing different versions of a feature to optimize outcomes.
Access Control: Restricting features to specific users or groups based on dynamic rules.
Experiment Management: Testing new ideas without compromising system stability.

The Microsoft.FeatureManagement library already provided robust support for feature flags in traditional ASP.NET Core controllers. With the introduction of Minimal APIs in .NET 6 — a lightweight and efficient model for building APIs — the need arose to adapt this capability. My contribution addresses this demand by integrating feature flags directly into the routing pipeline of Minimal APIs.

Introducing WithFeatureGate

The foundation of my implementation is the WithFeatureGate extension, a method designed to be simple and intuitive. It conditions endpoint execution on the state of feature flags. If the conditions aren’t met, the endpoint automatically returns an HTTP 404 (Not Found) status without executing the associated code.

A Basic Example

Here’s how it works in practice:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFeatureManagement();

var app = builder.Build();

app.MapGet("/test", () => "Feature Enabled")
   .WithFeatureGate("TestFeature");

app.Run();

In this case, the /test endpoint is only accessible if the TestFeature feature flag is enabled. The configuration can be defined in appsettings.json like this:

{
  "FeatureManagement": {
    "TestFeature": true
  }
}

If TestFeature is false, a GET request to /test returns a 404 without further processing. This integration reflects the simplicity of Minimal APIs while offering significant flexibility.

Advanced Features of the Implementation

The WithFeatureGate method goes beyond basic scenarios. It’s designed to support more complex use cases, providing detailed control over endpoint behavior. Below, I outline some of the key possibilities:

1. Control with Multiple Features

To require multiple feature flags to be active simultaneously, list their names:

app.MapGet("/test-multiple", () => "Multiple Features Enabled")
   .WithFeatureGate("Feature1", "Feature2");

The /test-multiple endpoint only returns a 200 OK if both Feature1 and Feature2 are enabled. If either is disabled, the result is a 404. This is useful for features dependent on multiple components.

2. "Any" Requirement: Flexibility with Options

When the goal is to enable the endpoint with at least one active feature, use RequirementType.Any:

app.MapGet("/test-any", () => "Any Feature Enabled")
   .WithFeatureGate(RequirementType.Any, "Feature1", "Feature2");

Here, the endpoint responds successfully if either Feature1 or Feature2 (or both) is active. This option is ideal for scenarios with alternative activation paths.

3. Negation: Inverted Logic

It’s possible to configure an endpoint to be accessible only when a feature is disabled:

app.MapGet("/test-negated", () => "Feature Denied")
   .WithFeatureGate(true, "TestFeature");

In this example, /test-negated only works if TestFeature is false. This functionality enables inverted logic or alternative experiences.

4. Endpoint Groups with MapGroup

To apply a feature flag to a set of endpoints, the MapGroup method offers a practical solution:

var group = app.MapGroup("/api")
               .WithFeatureGate("GroupFeature");

group.MapGet("/endpoint1", () => "Endpoint 1");
group.MapGet("/endpoint2", () => "Endpoint 2");

If GroupFeature is disabled, all endpoints under /api — such as /api/endpoint1 and /api/endpoint2 — return a 404. This approach simplifies managing entire API sections.

5. Targeting: Audience Control

The Microsoft.FeatureManagement library supports the TargetingFilter, which directs functionalities to specific users or groups based on detailed configurations. This is especially useful for personalization or segmented rollouts. Here’s how I implemented a practical example:

First, register the filter and configure an ITargetingContextAccessor in the service container. Below is an implementation that identifies the user and groups from the HTTP context:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFeatureManagement()
               .AddFeatureFilter<TargetingFilter>();
builder.Services.AddSingleton<ITargetingContextAccessor, CustomTargetingContextAccessor>();

var app = builder.Build();

app.MapGet("/premium-feature", () => "Welcome to the Premium Feature!")
   .WithFeatureGate("PremiumFeature");

app.Run();

// Implementation of ITargetingContextAccessor
public class CustomTargetingContextAccessor : ITargetingContextAccessor
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public CustomTargetingContextAccessor(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public ValueTask<TargetingContext> GetContextAsync()
    {
        var context = _httpContextAccessor.HttpContext;
        var userId = context?.User?.Identity?.Name ?? "anonymous";
        var groups = context?.User?.Claims
            .Where(c => c.Type == "group")
            .Select(c => c.Value)
            .ToArray() ?? Array.Empty<string>();

        return new ValueTask<TargetingContext>(new TargetingContext
        {
            UserId = userId,
            Groups = groups
        });
    }
}

In this example, the CustomTargetingContextAccessor uses the IHttpContextAccessor to extract the authenticated user’s name (via Identity.Name) and associated groups (via custom "group" claims). This assumes that authentication is configured, such as with JWT or cookies, and that the token includes groups as claims.

The configuration in appsettings.json defines who has access to the feature:

{
  "FeatureManagement": {
    "PremiumFeature": {
      "EnabledFor": [
        {
          "Name": "Targeting",
          "Parameters": {
            "Audience": {
              "Users": ["thaise.medeiros"],
              "Groups": [
                {
                  "Name": "PremiumUsers",
                  "RolloutPercentage": 100
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Here, the /premium-feature endpoint is only available to the user "thaise.medeiros" or members of the "PremiumUsers" group. The RolloutPercentage field specifies that 100% of the group members have access, but this value can be adjusted for gradual rollouts — for example, 50% to reach half the group.

The ITargetingContextAccessor is key to connecting the configuration to actual requests. It provides the current user’s context, allowing the TargetingFilter to evaluate whether access should be granted. Combined with authentication (like JWT), this creates a robust and flexible way to tailor features for specific audiences.

Why Feature Flags make sense in Minimal APIs

Minimal APIs were designed for simplicity and performance, eliminating the complexity of controllers and unnecessary metadata. Integrating feature flags into the routing maintains this lean approach while adding essential dynamic control for modern applications. This shines in:

Microservices: Managing distributed features becomes simpler.
Continuous Delivery: Enables deploying code safely and activating features on demand.
User Experience: Facilitates customizing the API for different profiles or tests.

Combining Minimal APIs with WithFeatureGate offers a straightforward development model paired with a powerful tool for software evolution.

How the functionality was implemented

Developing feature flag support for Minimal APIs required aligning the flexibility of FeatureManagement with the simplicity of Minimal APIs. The solution needed to fit naturally into the routing pipeline, leveraging ASP.NET Core’s endpoint filters to evaluate feature flags at runtime.

The implementation revolves around a filter that checks the state of flags before allowing or blocking access to endpoints. This filter is integrated into the Minimal APIs’ endpoint-building system through extensions that make its use seamless and intuitive. One challenge was ensuring it supported various configurations — such as multiple flags, "all active" or "at least one active" logic, and even negation.

Another critical aspect was integrating the filter with advanced features like targeting, which relies on a mechanism to identify the current user’s context. This was addressed using FeatureManagement’s existing infrastructure, ensuring compatibility with filters like TargetingFilter.

The result is a solution that extends FeatureManagement’s capabilities to Minimal APIs, balancing power and simplicity so developers can quickly adopt it in their projects.

Conclusion

Adding feature flag support to Minimal APIs with Microsoft.FeatureManagement was a significant contribution to the .NET community. With WithFeatureGate, it’s possible to implement everything from basic controls to advanced configurations like targeting and grouping, all practically and efficiently. Whether launching a new feature, conducting tests, or personalizing experiences, this implementation delivers the necessary tools elegantly.

The functionality is already available in the Microsoft/FeatureManagement-Dotnet repository, though it hasn’t yet been included in an official release. You can explore it in your projects now and see how feature flags can enhance software development and delivery — but it’ll be officially released soon!

DragonflyDB com C#: Uma Alternativa Moderna ao Redis

Cristiano Rodrigues — Thu, 27 Feb 2025 18:00:00 +0000

No universo das bases de dados em memória, o Redis há muito tempo reina como uma escolha confiável para desenvolvedores que buscam desempenho e simplicidade. No entanto, com o avanço das aplicações modernas e a crescente demanda por escalabilidade e eficiência, uma nova opção tem chamado a atenção: o DragonflyDB. Neste artigo, vamos explorar por que o DragonflyDB pode ser uma escolha estratégica para substituir o Redis, especialmente em projetos C#, e demonstrar sua compatibilidade com a API do Redis por meio de exemplos práticos. Prepare-se para uma análise técnica com um toque de leveza — afinal, código bom é aquele que funciona e ainda traz um sorriso ao rosto!

Por que trocar o Redis pelo DragonflyDB?

Antes de mergulharmos no código, vale a pena entender o que torna o DragonflyDB uma alternativa atraente. O Redis, embora excelente, foi projetado há mais de uma década com uma arquitetura single-threaded que, apesar de eficiente em muitos cenários, pode se tornar um gargalo em workloads intensos ou em hardware multi-core moderno. O DragonflyDB, por outro lado, chega com uma abordagem renovada: uma arquitetura multi-threaded baseada em um design shared-nothing, que aproveita ao máximo os recursos de hardware atuais.

Aqui estão alguns motivos técnicos para considerar a troca:

Desempenho Superior: Benchmarks mostram que o DragonflyDB pode alcançar até 25 vezes mais throughput que o Redis em uma única instância, chegando a milhões de operações por segundo (QPS). Isso é ideal para aplicações C# que exigem baixa latência e alta escalabilidade.
Escalabilidade Vertical: Enquanto o Redis muitas vezes exige clustering complexo para escalar, o DragonflyDB escala verticalmente, utilizando múltiplos núcleos de forma eficiente. Isso reduz a complexidade operacional — e quem não gosta de menos dor de cabeça?
Eficiência de Recursos: O DragonflyDB consome menos memória para o mesmo volume de dados e evita picos de uso durante operações como snapshotting, um problema comum no Redis.
Compatibilidade Total com a API do Redis: Aqui está o pulo do gato: você pode migrar para o DragonflyDB sem alterar uma linha sequer do seu código C# que usa bibliotecas como StackExchange.Redis. É praticamente um "troque e siga em frente".
Custo-Benefício: Com maior eficiência, você pode rodar workloads maiores em instâncias menores, reduzindo custos de infraestrutura — uma notícia que qualquer equipe de DevOps vai adorar.

Em resumo, o DragonflyDB oferece um upgrade em desempenho e simplicidade, mantendo a familiaridade do Redis. Vamos agora ao que interessa: o código!

Configurando o DragonflyDB com C

Para começar, vamos assumir que você já tem o DragonflyDB rodando (seja localmente via Docker ou em um ambiente cloud). O processo é simples:

docker run -p 6379:6379 --ulimit memlock=-1 docker.dragonflydb.io/dragonflydb/dragonfly

Isso inicia o DragonflyDB na porta padrão do Redis (6379), permitindo que ele funcione como um drop-in replacement. Agora, vamos integrar isso ao C# usando a biblioteca StackExchange.Redis, amplamente adotada para interagir com o Redis.

Exemplo 1: Operações Básicas de chave-valor

Vamos criar um exemplo simples que armazena e recupera um valor. O código abaixo é idêntico ao que você usaria com o Redis:

using StackExchange.Redis;
using System;

class Program
{
    static async Task Main(string[] args)
    {
        // Conectando ao DragonflyDB (ou Redis) na porta padrão
        var connection = await ConnectionMultiplexer.ConnectAsync("localhost:6379");
        var db = connection.GetDatabase();

        // Definindo uma chave
        await db.StringSetAsync("user:1:name", "João Silva");
        Console.WriteLine("Nome definido com sucesso!");

        // Recuperando o valor
        string name = await db.StringGetAsync("user:1:name");
        Console.WriteLine($"Nome recuperado: {name}");

        connection.Close();
    }
}

Por que isso funciona? O DragonflyDB suporta os comandos básicos do Redis, como SET e GET, sem nenhuma alteração. A biblioteca StackExchange.Redis envia os comandos via protocolo RESP (Redis Serialization Protocol), que o DragonflyDB entende perfeitamente. Resultado? Você migra para o DragonflyDB e seu código continua rodando como se nada tivesse mudado.

Exemplo 2: Trabalhando com Hashes

Hashes são ótimos para armazenar objetos estruturados. Vamos adicionar informações de um usuário:

using StackExchange.Redis;
using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var connection = await ConnectionMultiplexer.ConnectAsync("localhost:6379");
        var db = connection.GetDatabase();

        // Adicionando um hash
        await db.HashSetAsync("user:2", new HashEntry[]
        {
            new HashEntry("name", "Maria Oliveira"),
            new HashEntry("age", 28),
            new HashEntry("role", "Desenvolvedora")
        });

        // Recuperando valores do hash
        var userData = await db.HashGetAllAsync("user:2");
        foreach (var entry in userData)
        {
            Console.WriteLine($"{entry.Name}: {entry.Value}");
        }

        connection.Close();
    }
}

Aqui, usamos HSET e HGETALL para manipular um hash. O DragonflyDB suporta cerca de 185 comandos do Redis (equivalente à API do Redis 5.0), incluindo operações avançadas com hashes, listas e sets. Isso significa que sua lógica de negócios em C# não precisa de ajustes.

Exemplo 3: Listas e Filas Simples

Listas são perfeitas para implementar filas ou pilhas. Veja como adicionar e remover itens:

using StackExchange.Redis;
using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var connection = await ConnectionMultiplexer.ConnectAsync("localhost:6379");
        var db = connection.GetDatabase();

        // Adicionando itens a uma lista (fila)
        await db.ListRightPushAsync("tasks", "Tarefa 1");
        await db.ListRightPushAsync("tasks", "Tarefa 2");
        Console.WriteLine("Tarefas adicionadas!");

        // Removendo e exibindo o primeiro item (LIFO)
        string task = await db.ListLeftPopAsync("tasks");
        Console.WriteLine($"Tarefa removida: {task}");

        connection.Close();
    }
}

Com RPUSH e LPOP, criamos uma fila simples. O DragonflyDB lida com essas operações de forma eficiente, aproveitando sua arquitetura multi-threaded para processar múltiplas requisições em paralelo — algo que o Redis single-threaded não consegue igualar em cargas altas.

Compatibilidade e Limitações

Embora o DragonflyDB seja altamente compatível com a API do Redis, vale notar que ele ainda está em evolução. Atualmente, cobre a maioria dos comandos (~185 comandos) do Redis 5.0, mas alguns recursos avançados podem não estar totalmente implementados. Antes de migrar, verifique a documentação oficial para garantir que seus casos de uso são suportados.

Outro ponto positivo é o suporte à replicação no estilo Redis (REPLICAOF), o que facilita a migração sem downtime. Você pode configurar o DragonflyDB como réplica de um Redis existente, sincronizar os dados e promovê-lo a primário. Atualmente é oferecido o suporte às estruturas de dados e ao protocolo de replicação do Redis OSS até a versão 6.2.

Conclusão

O DragonflyDB é mais do que uma alternativa ao Redis; é uma evolução pensada para as demandas atuais. Com desempenho superior, escalabilidade simplificada e compatibilidade quase total com a API do Redis, ele permite que desenvolvedores C# melhorem suas aplicações sem reinventar a roda. Os exemplos acima mostram como é fácil integrá-lo usando ferramentas familiares como o StackExchange.Redis.

Se sua aplicação está sofrendo com gargalos de desempenho no Redis ou você quer reduzir custos sem sacrificar potência, o DragonflyDB é uma escolha que vale a pena explorar. Então, que tal dar uma chance a ele? Instale, teste e veja como esse "libélula" pode fazer sua aplicação voar mais alto!

Como o .NET Gerencia sua Memória (e por que você não deve interferir).

Cristiano Rodrigues — Wed, 26 Feb 2025 13:10:59 +0000

A gestão de memória no .NET é um tema fascinante que frequentemente surpreende até mesmo desenvolvedores experientes. Vamos mergulhar fundo em como o .NET lida com variáveis locais, explorando o papel do JIT (Just-In-Time Compiler) e do Garbage Collector (GC).

Fundamentos: Variáveis Locais

Antes de entrarmos em detalhes mais complexos, é essencial entender como o .NET trata variáveis locais e argumentos de método. Para tipos por valor (value types), como int ou struct, os dados são armazenados diretamente na pilha ou até em registradores da CPU. O GC não se preocupa com eles, a menos que sejam "boxed" — ou seja, encapsulados em um objeto no heap, como ao passar um int para um método que espera um object. Se quiser saber mais dá uma lida neste post: A verdadeira natureza dos tipos de valor e referência em .net

Já para tipos por referência (reference types), como classes, a pilha armazena apenas uma referência que aponta para o objeto no heap gerenciado. O JIT gera uma tabela de alocação que o GC consulta para determinar quais referências ainda estão "vivas" em cada ponto de coleta. É aí que a mágica e a complexidade começa.

Debug vs Release: Comportamentos diferentes

Modo Debug: Foco na Depuração

Considere este exemplo prático:

static void MethodA()
{
    var logger = new Logger();
    DoingStuff(logger);
    DoingOtherStuff();
    return CalculateResult();
}

No modo Debug, o JIT prioriza a conveniência da depuração, desativando otimizações como a eliminação de variáveis não utilizadas. Todas as variáveis locais permanecem vivas durante toda a execução do método. Se o GC rodar durante DoingStuff, DoingOtherStuff ou CalculateResult, a instância de Logger continuará enraizada pela variável logger. É como um assistente zeloso mantendo todas as ferramentas à mão, mesmo após você terminar de usá-las, para facilitar o uso de breakpoints e inspeções no IDE.

Modo Release: Eficiência em Primeiro Lugar

Agora, veja o mesmo código no modo Release:

static void MethodA()
{
    var logger = new Logger();
    DoingStuff(logger);
    DoingOtherStuff();
    return CalculateResult();
}

Aqui, o JIT se torna mais eficiente. Ele analisa o código e determina o tempo de vida mínimo necessário para cada variável. Durante DoingStuff, o logger permanece enraizado, pois está em uso. Mas, após essa chamada, o JIT sabe que ele não é mais necessário. Se o GC rodar durante DoingOtherStuff ou CalculateResult, a instância de Logger poderá ser coletada, liberando memória mais cedo.

O Impacto do Tiered JIT em Cenários do Mundo Real

Vamos explorar um exemplo mais realista:

static void Main(string[] args)
{
    var repository = new CustomerRepository("some-connection-string");
    var data = repository.GetByStatus(CustomerStatus.Active);
    var result = DoProcess(data); // Imagine que isso leve 1 hora
    Console.WriteLine(result);
}

O comportamento varia conforme o ambiente:

Modo Debug: O CustomerRepository fica na memória durante toda a hora de processamento, mesmo após GetByStatus. Isso facilita a depuração, mas pode desperdiçar memória.
Modo Release com Tier 1: Disponível como padrão em versões mais antigas do .NET (antes do Tiered Compilation), o JIT detecta que o repository não é mais necessário após GetByStatus e permite sua coleta pelo GC. É o mais eficiente possível.
Modo Release com Tier 0: Introduzido no .NET Core 2.1 e padrão em versões recentes, o Tier 0 prioriza compilação rápida e pode manter o repository vivo por mais tempo, semelhante ao modo Debug. O Tier 1 só é ativado dinamicamente em métodos chamados com frequência, o que pode surpreender desenvolvedores esperando otimizações imediatas.

Erros Comuns ao Tentar Otimizar o GC (E por que não funcionam)

Desenvolvedores frequentemente tentam "ajudar" o GC com técnicas que parecem lógicas, mas não funcionam como esperado.

A Tentativa do Null

static void Main(string[] args)
{
    var repository = new CustomerRepository("some-connection-string");
    var data = repository.GetByStatus(CustomerStatus.Active);
    repository = null; // Tentativa de "liberar" a referência
    var result = DoProcess(data);
    Console.WriteLine(result);
}

Essa abordagem é inútil no modo Release: o JIT ignora a atribuição de null no IL gerado, e editores modernos até marcam essa linha como "Assignment is not used".

A Tentativa do Escopo

static void Main(string[] args)
{
    Customer[] data;
    {
        var repository = new CustomerRepository("some-connection-string");
        data = repository.GetByStatus(CustomerStatus.Active);
    }
    var result = DoProcess(data);
    Console.WriteLine(result);
}

Usar escopos locais também não funciona. O compilador Roslyn ignora esses limites no IL, mantendo o mesmo comportamento.

A Tentativa do Using

Se CustomerRepository implementar IDisposable, uma ideia comum é usar um bloco using para tentar liberar recursos mais cedo. Veja este exemplo:

static void Main(string[] args)
{
    Customer[] data;
    using (var repository = new CustomerRepository("some-connection-string"))
    {
        data = repository.GetByStatus(CustomerStatus.Active);
    }
    var result = DoProcess(data);
    Console.WriteLine(result);
}

À primeira vista, parece que o repository seria descartado imediatamente após GetByStatus, liberando memória. Afinal, o using garante que o método Dispose() seja chamado ao sair do bloco, certo? Sim, mas isso não significa que o objeto será coletado pelo GC mais cedo. O Dispose() apenas libera recursos não gerenciados (como conexões de banco de dados ou arquivos abertos), se houver, mas o objeto em si permanece no heap até que o GC decida coletá-lo. No modo Release, o JIT ainda pode considerar a referência viva até o fim do método Main, dependendo de como o código é otimizado. Ou seja, o using não reduz o tempo de vida da referência como esperado.

Ou pior ainda:

static void Main(string[] args)
{
    using (var repository = new CustomerRepository("some-connection-string"))
    {
        var data = repository.GetByStatus(CustomerStatus.Active);
        var result = DoProcess(data);
        Console.WriteLine(result);
    } // repository.Dispose() só acontece aqui!
}

Nesse caso, o repository permanece vivo durante toda a execução de DoProcess, porque o bloco using só termina no fim do método. Isso significa que, mesmo que você ache que está "controlando" os recursos, o objeto não será elegível para coleta até depois do processamento longo — o oposto do que se pretendia! Comparado à versão sem using, onde o JIT poderia liberar o repository após GetByStatus no modo Release, essa abordagem pode até aumentar o uso de memória desnecessariamente.

A Tentativa do GC.Collect

Outra prática comum é forçar a coleta manualmente:

static void Main(string[] args)
{
    var repository = new CustomerRepository("some-connection-string");
    var data = repository.GetByStatus(CustomerStatus.Active);
    GC.Collect(); // Tentativa de "limpar" a memória
    var result = DoProcess(data);
    Console.WriteLine(result);
}

Parece uma solução direta, mas na prática é uma armadilha. Chamar GC.Collect() raramente resolve problemas reais de memória e pode até prejudicar a performance, forçando coletas prematuras que interrompem o fluxo natural do GC. O .NET foi projetado para gerenciar a memória de forma eficiente por conta própria — interferir manualmente quase sempre é contraproducente.

Uma Solução Real (Quando Realmente Necessária)

Se você realmente precisa controlar o tempo de vida dos objetos (e isso deve ser uma decisão baseada em medições, não em suposições), aqui está uma abordagem que funciona:

static void Main(string[] args)
{
    var data = PrepareData("some-connection-string");
    var result = DoProcess(data);
    Console.WriteLine(result);
}

[MethodImpl(MethodImplOptions.NoInlining)]
static Customer[] PrepareData(string connection)
{
    var repository = new CustomerRepository(connection);
    return repository.GetByStatus(CustomerStatus.Active);
}

A separação em métodos menores, combinada com o atributo NoInlining, impede que o JIT combine o código e garante que o repository seja elegível para coleta após PrepareData. Use isso apenas em casos extremos, como aplicações de servidor com milhares de requisições por segundo, onde picos de memória são um problema medido.

O Caso Especial dos Métodos Assíncronos

Os métodos assíncronos apresentam um comportamento interessante e geralmente mais favorável quando se trata de gerenciamento de memória:

static async Task Main(string[] args)
{
    var repository = new CustomerRepository("some-connection-string");
    var data = await repository.GetByStatus(CustomerStatus.Active);
    var result = await DoProcess(data);
    Console.WriteLine(result);
}

O compilador transforma métodos async em máquinas de estado, onde variáveis locais são encapsuladas em campos de uma classe gerada. Após cada await, o escopo efetivo dessas variáveis pode ser reduzido, permitindo que o GC as libere mais cedo. É um caso onde a memória funciona de forma mais intuitiva.

Considerações Finais

O gerenciamento de memória no .NET é um sistema sofisticado projetado para equilibrar performance e facilidade de uso. Na maioria dos casos, você não precisa interferir — o framework faz um excelente trabalho sozinho.

Quando enfrentar problemas reais de memória:

Use ferramentas como Visual Studio Diagnostic Tools, dotMemory (JetBrains) ou BenchmarkDotNet para identificar gargalos.
Não confie em intuições sobre como o código "deveria" funcionar.
Teste otimizações em condições realistas, em Debug e Release.
Considere o impacto do Tiered JIT.

Em vez de lutar contra o GC, invista em profiling e testes. Código bem estruturado não só é mais fácil de manter, mas também tende a ter um comportamento mais previsível em termos de memória.

Gerenciando funcionalidades em Minimal APIs com Microsoft.FeatureManagement: Introdução ao suporte a Feature Flags.

Cristiano Rodrigues — Mon, 24 Feb 2025 13:55:49 +0000

Recentemente, tive a honra de contribuir com o projeto open-source Microsoft/FeatureManagement-Dotnet, uma biblioteca consolidada que facilita o uso de feature flags no ecossistema .NET. Minha implementação adicionou suporte nativo para Minimal APIs no ASP.NET Core, oferecendo uma maneira prática de integrar controle dinâmico de funcionalidades. Neste artigo, vou explorar essa nova funcionalidade que desenvolvi, abordando desde os conceitos básicos até cenários avançados, com exemplos práticos e sugestões de como aplicá-la em projetos reais.

O Papel das Feature Flags no desenvolvimento moderno

Feature flags, ou bandeiras de funcionalidade, são um recurso fundamental no desenvolvimento de software atual. Elas permitem ativar ou desativar funcionalidades em tempo de execução, sem necessidade de alterar o código ou realizar um novo deploy. Isso é especialmente útil em casos como:

Lançamentos Progressivos (Rollouts): Implementar novidades gradualmente para subgrupos de usuários, reduzindo riscos.
Testes A/B: Comparar diferentes versões de uma funcionalidade para otimizar resultados.
Controle de Acesso: Restringir funcionalidades a usuários ou grupos específicos com base em regras dinâmicas.
Gerenciamento de Experimentos: Testar novas ideias sem impactar a estabilidade do sistema.

O Microsoft.FeatureManagement já oferecia suporte robusto para feature flags em controladores tradicionais do ASP.NET Core. Com a introdução das Minimal APIs no .NET 6 — um modelo leve e eficiente para construção de APIs —, surgiu a necessidade de adaptar essa capacidade. Minha contribuição resolve essa demanda, integrando feature flags diretamente ao pipeline de roteamento das Minimal APIs.

Introduzindo o WithFeatureGate

A base da minha implementação é a extensão WithFeatureGate, um método projetado para ser simples e intuitivo, condicionando a execução de endpoints ao estado de feature flags. Se as condições não forem atendidas, o endpoint retorna um status HTTP 404 (Not Found) automaticamente, sem executar o código associado.

Um exemplo básico

Veja como funciona na prática:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFeatureManagement();

var app = builder.Build();

app.MapGet("/test", () => "Funcionalidade Habilitada")
   .WithFeatureGate("TestFeature");

app.Run();

Nesse caso, o endpoint /test só é acessível se a feature flag TestFeature estiver ativada. A configuração pode ser definida no appsettings.json, como:

{
  "FeatureManagement": {
    "TestFeature": true
  }
}

Se TestFeature estiver como false, uma requisição GET para /test retorna 404, sem processamento adicional. Essa integração reflete a simplicidade das Minimal APIs, ao mesmo tempo que oferece flexibilidade significativa.

Recursos avançados da implementação

O WithFeatureGate vai além de cenários básicos. Ele foi projetado para suportar casos de uso mais complexos, proporcionando controle detalhado sobre o comportamento dos endpoints. A seguir, apresento algumas das principais possibilidades:

1. Controle com múltiplas features

Para exigir que várias feature flags estejam ativas simultaneamente, basta listar os nomes:

app.MapGet("/test-multiple", () => "Múltiplas Funcionalidades Habilitadas")
   .WithFeatureGate("Feature1", "Feature2");

O endpoint /test-multiple só retorna 200 OK se tanto Feature1 quanto Feature2 estiverem ativadas. Caso uma delas esteja desativada, o resultado é 404. Isso é útil para funcionalidades que dependem de múltiplos componentes.

2. Requisito "Any": Flexibilidade com opções

Quando o objetivo é liberar o endpoint com pelo menos uma feature ativa, usa-se o RequirementType.Any:

app.MapGet("/test-any", () => "Qualquer Funcionalidade Habilitada")
   .WithFeatureGate(RequirementType.Any, "Feature1", "Feature2");

Aqui, o endpoint responde com sucesso se Feature1 ou Feature2 (ou ambas) estiverem ativas. Essa opção é ideal para cenários com caminhos alternativos de ativação.

3. Negação: Lógica invertida

É possível configurar o endpoint para ser acessível apenas quando uma feature está desativada:

app.MapGet("/test-negated", () => "Funcionalidade Negada")
   .WithFeatureGate(true, "TestFeature");

Nesse exemplo, /test-negated só funciona se TestFeature for false. Essa funcionalidade permite criar lógicas invertidas ou experiências alternativas.

4. Grupos de Endpoints com MapGroup

Para aplicar uma feature flag a um conjunto de endpoints, o método MapGroup é uma solução prática:

var group = app.MapGroup("/api")
               .WithFeatureGate("GroupFeature");

group.MapGet("/endpoint1", () => "Endpoint 1");
group.MapGet("/endpoint2", () => "Endpoint 2");

Se GroupFeature estiver desativada, todos os endpoints sob /api — como /api/endpoint1 e /api/endpoint2 — retornam 404. Essa abordagem facilita o gerenciamento de seções completas de uma API.

5. Targeting: Controle por audiência

O Microsoft.FeatureManagement oferece suporte ao TargetingFilter, um recurso que permite direcionar funcionalidades a usuários ou grupos específicos com base em configurações detalhadas. Isso é especialmente útil para cenários de personalização ou lançamentos segmentados. Veja como implementei um exemplo prático:

Primeiro, é necessário registrar o filtro e configurar um ITargetingContextAccessor no contêiner de serviços. Aqui está uma implementação que identifica o usuário e os grupos a partir do contexto HTTP:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFeatureManagement()
               .AddFeatureFilter<TargetingFilter>();
builder.Services.AddSingleton<ITargetingContextAccessor, CustomTargetingContextAccessor>();

var app = builder.Build();

app.MapGet("/premium-feature", () => "Bem-vindo à funcionalidade Premium!")
   .WithFeatureGate("PremiumFeature");

app.Run();

// Implementação do ITargetingContextAccessor
public class CustomTargetingContextAccessor : ITargetingContextAccessor
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public CustomTargetingContextAccessor(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public ValueTask<TargetingContext> GetContextAsync()
    {
        var context = _httpContextAccessor.HttpContext;
        var userId = context?.User?.Identity?.Name ?? "anonymous";
        var groups = context?.User?.Claims
            .Where(c => c.Type == "group")
            .Select(c => c.Value)
            .ToArray() ?? Array.Empty<string>();

        return new ValueTask<TargetingContext>(new TargetingContext
        {
            UserId = userId,
            Groups = groups
        });
    }
}

Nesse exemplo, o CustomTargetingContextAccessor usa o IHttpContextAccessor para extrair o nome do usuário autenticado (via Identity.Name) e os grupos associados (via claims personalizados do tipo "group"). Isso assume que a autenticação está configurada, como com JWT ou cookies, e que os grupos são incluídos como claims no token.

A configuração no appsettings.json define quem tem acesso à funcionalidade:

{
  "FeatureManagement": {
    "PremiumFeature": {
      "EnabledFor": [
        {
          "Name": "Targeting",
          "Parameters": {
            "Audience": {
              "Users": ["thaise.medeiros"],
              "Groups": [
                {
                  "Name": "PremiumUsers",
                  "RolloutPercentage": 100
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Aqui, o endpoint /premium-feature só estará disponível para a usuária "thaise.medeiros" ou para membros do grupo "PremiumUsers". O campo RolloutPercentage define que 100% dos membros do grupo têm acesso, mas esse valor pode ser ajustado para lançamentos graduais — por exemplo, 50% para atingir metade do grupo.

O ITargetingContextAccessor é a chave para conectar a configuração às requisições reais. Ele fornece o contexto do usuário atual, permitindo que o TargetingFilter avalie se o acesso deve ser concedido. Combinado com autenticação (como JWT), isso cria uma forma robusta e flexível de personalizar funcionalidades para audiências específicas.

Por que Feature Flags fazem sentido em Minimal APIs

As Minimal APIs foram criadas para simplicidade e desempenho, eliminando a complexidade de controladores e metadados desnecessários. Integrar feature flags ao roteamento mantém essa abordagem enxuta, adicionando controle dinâmico essencial para aplicações modernas. Isso se destaca em:

Microsserviços: Gerenciar funcionalidades distribuídas fica mais simples.
Entrega Contínua: Permite implantar código com segurança e ativar recursos sob demanda.
Experiência do Usuário: Facilita personalizar a API para diferentes perfis ou testes.

A combinação de Minimal APIs com WithFeatureGate oferece um modelo direto de desenvolvimento aliado a uma ferramenta robusta para evolução de software.

Como a funcionalidade foi implementada

Desenvolver o suporte a feature flags para Minimal APIs foi um processo que exigiu alinhar a flexibilidade do FeatureManagement com a simplicidade das Minimal APIs. A solução que se encaixasse naturalmente no pipeline de roteamento, aproveitando os filtros de endpoint do ASP.NET Core para avaliar as feature flags em tempo de execução.

A implementação gira em torno de um filtro que verifica o estado das flags antes de liberar ou bloquear o acesso aos endpoints. Esse filtro é integrado ao sistema de construção de endpoints das Minimal APIs por meio de extensões que tornam seu uso fluido e intuitivo. Um dos desafios foi garantir que ele suportasse diferentes configurações — como múltiplas flags, lógica de "todas ativas" ou "pelo menos uma ativa", e até negação

Outro ponto importante foi integrar o filtro com recursos avançados, como o targeting, que depende de um mecanismo para identificar o contexto do usuário atual. Isso foi resolvido usando a infraestrutura existente do FeatureManagement, garantindo compatibilidade com filtros como o TargetingFilter.

O resultado é uma solução que estende as capacidades do FeatureManagement às Minimal APIs, equilibrando potência e simplicidade de forma que os desenvolvedores possam adotá-la facilmente em seus projetos.

Conclusão

Adicionar suporte a feature flags em Minimal APIs com o Microsoft.FeatureManagement foi uma contribuição significativa para a comunidade .NET. Com o WithFeatureGate, é possível implementar desde controles básicos até configurações avançadas como targeting e agrupamento, tudo de forma prática e eficiente. Seja para lançar uma nova funcionalidade, conduzir testes ou personalizar experiências, essa implementação entrega as ferramentas necessárias de maneira elegante.

A funcionalidade já está disponível no repositório Microsoft/FeatureManagement-Dotnet, embora ainda não tenha sido incluída em uma release oficial. Você pode explorá-la agora mesmo em seus projetos e conferir como feature flags podem aprimorar o desenvolvimento e a entrega de software — mas em breve ela será lançada!