Cache no .NET: IMemoryCache, Redis ou HybridCache?

Por que o cache no .NET exige cuidado

Considere uma API de rastreamento de remessas com latência p95 de 120 ms. Depois de adicionar o IMemoryCache, a latência cai para 5 ms e todo mundo comemora.

Em seguida, o time escala a API para duas instâncias. Então um cliente atualiza o endereço de entrega, recarrega a página e vê o endereço antigo.

Ele recarrega de novo e vê o endereço novo. Na terceira vez, o endereço antigo volta.

Nada está quebrado, de fato. Cada instância tem a própria memória, e apenas uma delas sabe que o endereço mudou.

Esse comportamento resume o problema central do cache no .NET. Por isso, escolher o tipo certo depende de entender onde cada camada guarda os dados e quem enxerga cada cópia.

Onde cada camada de cache no .NET fica

Todo cache no .NET fica em algum ponto do caminho entre a requisição HTTP e o banco de dados. Alguns ficam na frente do seu código e guardam respostas HTTP inteiras.

Outros ficam dentro dos handlers e guardam objetos .NET. Nesse caso, eles usam a memória de um único processo ou um armazenamento externo compartilhado por todas as instâncias.

Três termos aparecem em todo o restante do artigo, por isso vale defini-los agora:

• Cache L1: a memória do processo atual. Ele oferece a leitura mais rápida possível, porque não envolve rede nem desserialização.
• Cache L2: um armazenamento externo, como o Redis, compartilhado por todas as instâncias. Ele responde mais devagar que o L1, mas muito mais rápido que o banco.
• Cache stampede: acontece quando muitas requisições perdem o cache ao mesmo tempo e todas consultam o banco pela mesma chave.

Além disso, o .NET oferece seis formas de cache: IMemoryCache, IDistributedCache, Redis, HybridCache, FusionCache e Output Cache. Este artigo cobre as quatro primeiras, que atuam dentro do handler.

O cenário de exemplo: uma API de remessas

Os exemplos usam um domínio de remessas com Minimal APIs e EF Core no .NET 10, a versão LTS atual. O endpoint chama um handler, e o handler consulta o banco diretamente:

app.MapGet("/api/shipments/{shipmentNumber}", async (
    string shipmentNumber,
    GetShipmentByNumberHandler handler,
    CancellationToken cancellationToken) =>
{
    var shipment = await handler.HandleAsync(shipmentNumber, cancellationToken);
    return shipment is null ? Results.NotFound() : Results.Ok(shipment);
});

internal sealed class GetShipmentByNumberHandler(ShipmentsDbContext dbContext)
{
    public async Task<ShipmentResponse?> HandleAsync(
        string shipmentNumber,
        CancellationToken cancellationToken)
    {
        return await dbContext.Shipments
            .Where(s => s.Number == shipmentNumber)
            .Select(s => s.MapToResponse())
            .FirstOrDefaultAsync(cancellationToken);
    }
}

Essa consulta já responde bem, porque o campo Number tem índice e a projeção traz apenas as colunas necessárias. A partir dela, cada seção adiciona um tipo diferente de cache.

IMemoryCache: o cache no .NET mais rápido

O IMemoryCache é um armazenamento chave-valor que vive na memória do processo da aplicação. Você guarda qualquer objeto .NET e recebe de volta a mesma referência.

Por isso, uma leitura dele não exige serialização nem chamada de rede. O registro no container de injeção de dependência ocupa uma linha:

builder.Services.AddMemoryCache();

Se o conceito de container ainda não estiver claro, o artigo sobre injeção de dependência no balta.io explica o padrão em detalhes.

No handler, o padrão cache-aside envolve a consulta ao banco:

internal sealed class GetShipmentByNumberHandler(
    ShipmentsDbContext dbContext,
    IMemoryCache cache)
{
    public async Task<ShipmentResponse?> HandleAsync(
        string shipmentNumber,
        CancellationToken cancellationToken)
    {
        return await cache.GetOrCreateAsync($"shipment:{shipmentNumber}", async entry =>
        {
            // A entrada expira 10 minutos depois de gravada
            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(10);
            entry.SetSize(1);

            return await dbContext.Shipments
                .Where(s => s.Number == shipmentNumber)
                .Select(s => s.MapToResponse())
                .FirstOrDefaultAsync(cancellationToken);
        });
    }
}

O GetOrCreateAsync primeiro procura a chave. Quando não a encontra, ele executa a factory, consulta o banco e guarda o resultado.

Na prática, um acerto equivale a uma busca em dicionário que devolve uma referência. Não há nada para desserializar.

builder.Services.AddMemoryCache(options =>
{
    // Cada remessa conta como 1, então o cache guarda no máximo 10.000 remessas
    options.SizeLimit = 10_000;
});

var response = await cache.GetOrCreateAsync(key, ...);
response.Items.Clear(); // todas as próximas requisições recebem a remessa sem itens

IDistributedCache com Redis: cache distribuído no .NET

Quando a API escala para várias instâncias, ela precisa de um armazenamento que todas compartilhem. O IDistributedCache é a abstração do .NET para esse armazenamento externo, e o Redis é a implementação mais comum.

Primeiro, instale o pacote e registre o Redis:

dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
    // Prefixo aplicado a todas as chaves desta aplicação
    options.InstanceName = "shipments:";
});

O InstanceName adiciona um prefixo a cada chave. Dessa forma, várias aplicações dividem o mesmo Redis sem colisão de chaves.

A interface trabalha apenas com byte[] e strings, então a serialização fica por sua conta:

internal sealed class GetShipmentByNumberHandler(
    ShipmentsDbContext dbContext,
    IDistributedCache cache)
{
    public async Task<ShipmentResponse?> HandleAsync(
        string shipmentNumber,
        CancellationToken cancellationToken)
    {
        var key = $"shipment:{shipmentNumber}";

        var cached = await cache.GetStringAsync(key, cancellationToken);
        if (cached is not null)
        {
            return JsonSerializer.Deserialize<ShipmentResponse>(cached);
        }

        var shipment = await dbContext.Shipments
            .Where(s => s.Number == shipmentNumber)
            .Select(s => s.MapToResponse())
            .FirstOrDefaultAsync(cancellationToken);

        if (shipment is not null)
        {
            await cache.SetStringAsync(key, JsonSerializer.Serialize(shipment),
                new DistributedCacheEntryOptions
                {
                    AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(10)
                },
                cancellationToken);
        }

        return shipment;
    }
}

Todas as instâncias leem e gravam as mesmas chaves no Redis. Quando a instância A guarda uma remessa, a instância B a encontra no Redis.

Do mesmo modo, quando a instância A remove a chave, a instância B percebe na próxima leitura. Com isso, o cache no .NET deixa de divergir entre instâncias.

string? cached = null;
try
{
    cached = await cache.GetStringAsync(key, cancellationToken);
}
catch (RedisConnectionException ex)
{
    // O cache falhou, mas a requisição segue para o banco
    logger.LogWarning(ex, "Redis unavailable, falling back to database");
}

HybridCache: L1 e L2 em uma única API de cache no .NET

O HybridCache chegou com o .NET 9 para substituir o uso direto de IMemoryCache e IDistributedCache. Ele combina um L1 em memória, para velocidade, com um L2 opcional, para compartilhamento.

Além disso, ele resolve o stampede, porque requisições concorrentes pela mesma chave dividem uma única chamada da factory. A configuração começa pelo pacote e pelo registro:

dotnet add package Microsoft.Extensions.Caching.Hybrid

builder.Services.AddHybridCache(options =>
{
    options.MaximumPayloadBytes = 1024 * 1024;
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(10),
        LocalCacheExpiration = TimeSpan.FromMinutes(10)
    };
});

Sem nenhum outro registro, o HybridCache roda apenas com o L1. Porém, assim que você registra um IDistributedCache, ele passa a usá-lo como L2 automaticamente:

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
});

Com isso, você começa o cache no .NET só com memória e adiciona o Redis depois, sem mudar o código que chama o cache. O handler fica assim:

internal sealed class GetShipmentByNumberHandler(
    ShipmentsDbContext dbContext,
    HybridCache cache)
{
    public async Task<ShipmentResponse?> HandleAsync(
        string shipmentNumber,
        CancellationToken cancellationToken)
    {
        return await cache.GetOrCreateAsync(
            $"shipment:{shipmentNumber}",
            (dbContext, shipmentNumber),
            // Lambda static: evita capturar variáveis e alocar uma closure por chamada
            static async (state, ct) => await state.dbContext.Shipments
                .Where(s => s.Number == state.shipmentNumber)
                .Select(s => s.MapToResponse())
                .FirstOrDefaultAsync(ct),
            tags: ["shipments"],
            cancellationToken: cancellationToken);
    }
}

Em uma leitura, o HybridCache verifica primeiro o L1, depois o L2 e só então executa a factory. Quando a factory consulta o banco, o resultado vai para o L2 e para o L1.

Enquanto isso, as requisições concorrentes pela mesma chave aguardam a factory que já está rodando. A documentação oficial do HybridCache detalha esse fluxo e todas as opções disponíveis.

Armadilhas do HybridCache em produção

As quatro armadilhas a seguir aparecem com frequência quando o HybridCache sai do ambiente local e roda em produção.

O L1 não sincroniza entre instâncias no cache no .NET

Registre o Redis como L2, rode duas instâncias e observe o fluxo. A instância A recebe um PUT que altera o status da remessa e chama RemoveAsync para a chave.

Esse comando limpa o L1 da instância A e o L2 compartilhado. Contudo, a instância B ainda tem o valor antigo no próprio L1.

Assim, a instância B continua servindo o status antigo até o LocalCacheExpiration vencer. Afinal, o HybridCache não tem backplane, ou seja, nenhuma mensagem avisa as outras instâncias para descartar a chave.

A única defesa disponível é um LocalCacheExpiration curto:

options.DefaultEntryOptions = new HybridCacheEntryOptions
{
    // O L2 guarda a entrada por 30 minutos
    Expiration = TimeSpan.FromMinutes(30),
    // Cada instância volta ao Redis a cada 30 segundos
    LocalCacheExpiration = TimeSpan.FromSeconds(30)
};

Nesse caso, a defasagem fica limitada a 30 segundos por instância. Mesmo assim, ela não desaparece, e o tempo escolhido define quanto dado antigo o negócio tolera.

var shipment = await cache.GetOrCreateAsync(key, state, factory, cancellationToken: cancellationToken);

if (shipment is null)
{
    // Não deixa o "não encontrado" ocupar o cache pelo TTL inteiro
    await cache.RemoveAsync(key, cancellationToken);
}

return shipment;

await cache.SetAsync(key, value, new HybridCacheEntryOptions
{
    Expiration = TimeSpan.FromHours(1)
});

public static class HybridCacheEntry
{
    // Garante que L1 e L2 recebam o mesmo tempo de vida
    public static HybridCacheEntryOptions Ttl(TimeSpan ttl) => new()
    {
        Expiration = ttl,
        LocalCacheExpiration = ttl
    };
}

Como escolher o cache no .NET para o seu cenário

A escolha do cache no .NET depende de quantas instâncias rodam e de quanta defasagem o negócio aceita. A tabela abaixo resume os critérios vistos até aqui:

Em resumo, o IMemoryCache serve bem a uma única instância com dados que não serializam. Já o IDistributedCache atende várias instâncias que precisam enxergar exatamente o mesmo dado.

Para código novo, o HybridCache costuma ser o melhor ponto de partida, porque entrega L1, L2, tags e proteção contra stampede em uma API. Mesmo assim, ajuste o LocalCacheExpiration à tolerância de defasagem do negócio.

Conclusão

O cache no .NET reduz a latência de forma drástica, mas cada tipo resolve um problema e cria outro. Enquanto o IMemoryCache é imbatível em velocidade, ele fica preso a um processo.

Já o IDistributedCache com Redis garante consistência entre instâncias, só que paga rede e desserialização em cada leitura. Por fim, o HybridCache combina os dois e protege contra stampede, embora não sincronize o L1 entre instâncias.

Portanto, corrija as consultas primeiro, escolha a camada pelo número de instâncias e conheça as armadilhas antes de ir para produção. Com isso, o cache no .NET entrega o ganho prometido sem devolver dados antigos aos seus usuários.

FAQ

O HybridCache substitui o IMemoryCache?

Para código novo, na maioria dos casos, sim. Ainda assim, o IMemoryCache continua útil para objetos não serializáveis e para quem depende de expiração deslizante.

Preciso de Redis para usar o HybridCache?

Não. Sem um IDistributedCache registrado, o HybridCache funciona apenas com o L1 em memória e mantém a proteção contra stampede.

O HybridCache sincroniza o L1 entre instâncias?

Não, porque ele não tem backplane. A defasagem entre instâncias fica limitada pelo valor de LocalCacheExpiration.

Por que o SetSize não limita o meu IMemoryCache?

Porque o SetSize só tem efeito quando você define SizeLimit no registro do cache. Depois disso, toda entrada precisa informar o tamanho.

Como evitar que um null fique em cache no HybridCache?

Verifique o resultado do GetOrCreateAsync e chame RemoveAsync quando ele vier nulo. Assim, a próxima requisição consulta o banco de novo.