Cache no .NET: FusionCache, Output Cache e qual escolher

Configurando o cache no .NET com FusionCache e Redis

Para começar, adicione os pacotes do núcleo, do serializador, do backplane e do cache distribuído do Redis:

dotnet add package ZiggyCreatures.FusionCache
dotnet add package ZiggyCreatures.FusionCache.Serialization.SystemTextJson
dotnet add package ZiggyCreatures.FusionCache.Backplane.StackExchangeRedis
dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis

Em seguida, registre o FusionCache no container de injeção de dependência do Program.cs:

var redisConnection = builder.Configuration.GetConnectionString("Redis")!;

builder.Services.AddFusionCache()
    .WithDefaultEntryOptions(new FusionCacheEntryOptions
    {
        Duration = TimeSpan.FromMinutes(10),
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(1),
        FactorySoftTimeout = TimeSpan.FromMilliseconds(300)
    })
    .WithSerializer(new FusionCacheSystemTextJsonSerializer())
    .WithDistributedCache(new RedisCache(new RedisCacheOptions
    {
        Configuration = redisConnection
    }))
    .WithBackplane(new RedisBackplane(new RedisBackplaneOptions
    {
        Configuration = redisConnection
    }));

Esse registro monta três blocos. Primeiro, o serializador, que converte o valor para o L2 com System.Text.Json.

Depois vem o cache distribuído, que é o mesmo RedisCache usado pela interface IDistributedCache. Por fim, o backplane avisa as outras instâncias sobre mudanças usando o pub/sub do Redis.

Com isso pronto, o handler recebe a interface IFusionCache e usa o método GetOrSetAsync:

internal sealed class GetShipmentByNumberHandler(
    ShipmentsDbContext dbContext,
    IFusionCache cache)
{
    public async Task<ShipmentResponse?> HandleAsync(
        string shipmentNumber,
        CancellationToken cancellationToken)
    {
        // Busca no L1, depois no L2 e só então no banco
        return await cache.GetOrSetAsync<ShipmentResponse?>(
            $"shipment:{shipmentNumber}",
            async (_, ct) => await dbContext.Shipments
                .Where(s => s.Number == shipmentNumber)
                .Select(s => s.MapToResponse())
                .FirstOrDefaultAsync(ct),
            tags: ["shipments"],
            token: cancellationToken);
    }
}

Para remover um item, você usa a chave ou uma tag, exatamente como no HybridCache:

await cache.RemoveAsync($"shipment:{shipmentNumber}", token: cancellationToken);

Como o backplane sincroniza as instâncias

A diferença real aparece no que acontece depois dessa remoção nas outras instâncias da aplicação. Para entender, considere uma API com duas instâncias, A e B, atrás de um balanceador.

Primeiro, um cliente envia um PUT para atualizar o status de um envio, e a instância A processa a requisição. Em seguida, A remove a entrada do L2 no Redis e publica uma mensagem no backplane.

Então, o Redis entrega essa mensagem para a instância B, que descarta a cópia que guardava no L1. Assim, a próxima leitura em B não encontra nada na memória, consulta o L2 e, sem resultado, executa a factory no banco.

Vale notar que a mensagem do backplane carrega apenas a chave e a ação, sem o valor. Por isso, o tráfego entre as instâncias continua pequeno.

Esse mecanismo resolve a maior armadilha do HybridCache no .NET quando há várias instâncias com cache. Segundo a documentação oficial do HybridCache, invalidar uma chave ou tag afeta o servidor atual e o L2, mas não toca no L1 dos outros servidores.

Usando o FusionCache como HybridCache

Se os seus handlers já injetam HybridCache, você não precisa reescrevê-los. O FusionCache pode se registrar como a implementação da abstração da Microsoft com o método AsHybridCache:

builder.Services.AddFusionCache()
    .WithSerializer(new FusionCacheSystemTextJsonSerializer())
    .WithDistributedCache(new RedisCache(new RedisCacheOptions { Configuration = redisConnection }))
    .WithBackplane(new RedisBackplane(new RedisBackplaneOptions { Configuration = redisConnection }))
    // Expõe o FusionCache por trás da abstração HybridCache
    .AsHybridCache();

Dessa forma, as suas classes continuam dependendo de HybridCache, mas o motor de cache por baixo no .NET passa a ser o FusionCache. Além disso, a mesma instância continua disponível como IFusionCache para quem quiser a API completa.

Contudo, existe um limite importante nesse adaptador. Pela abstração, cada chamada aceita apenas HybridCacheEntryOptions, então fail-safe, timeouts e eager refresh ficam configurados uma vez, nas opções padrão do registro.

Por outro lado, o adaptador supera limitações da implementação da Microsoft. Por exemplo, ele permite registrar vários caches nomeados e expô-los como keyed services com AsKeyedHybridCache.

Recursos de resiliência do FusionCache

O primeiro recurso de resiliência do cache no .NET com FusionCache é o fail-safe. Quando o banco cai e a factory lança uma exceção, o FusionCache devolve o último valor conhecido em vez de um erro.

O segundo são os timeouts soft e hard. Se a factory demora mais que o timeout soft e existe um valor antigo, a biblioteca devolve esse valor e continua a factory em segundo plano.

Já o timeout hard define um limite absoluto. Assim, mesmo sem valor antigo, a requisição não fica esperando indefinidamente.

O terceiro é o eager refresh, que atualiza uma entrada em segundo plano antes que ela expire. Com isso, as chaves mais acessadas praticamente nunca sofrem um miss.

Por fim, o adaptive caching permite que a factory defina o tempo de vida de cada entrada com base no que carregou. Esses recursos tornam o cache no .NET uma camada de resiliência, e não apenas de desempenho.

Vantagens e desvantagens do FusionCache

Entre as vantagens, o backplane mantém o L1 sincronizado entre as instâncias. Também pesam a favor os recursos de resiliência, o adaptador para HybridCache e a maturidade do projeto, que tem documentação extensa e um mantenedor ativo.

Por outro lado, há três desvantagens claras. A primeira é a dependência de terceiros, que exige acompanhar atualizações e mudanças de versão.

Em segundo lugar, a superfície de configuração é maior, porque mais opções significam mais formas de configurar errado. Por último, o backplane depende do pub/sub do Redis, e alguns planos gerenciados não oferecem esse recurso.

Configurando políticas e tags

Durante o registro, você define políticas nomeadas e depois habilita o middleware no pipeline:

builder.Services.AddOutputCache(options =>
{
    // Uma entrada por número de envio, expirando em 5 minutos
    options.AddPolicy("shipment-by-number", policy => policy
        .Expire(TimeSpan.FromMinutes(5))
        .SetVaryByRouteValue("shipmentNumber")
        .Tag("shipments"));
});

var app = builder.Build();

app.UseOutputCache();

Em seguida, o endpoint usa a política pelo nome com o método CacheOutput:

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);
})
.CacheOutput("shipment-by-number");

O método SetVaryByRouteValue transforma cada número de envio em uma entrada própria. Para endpoints de listagem, SetVaryByQuery("carrier", "status") faz o mesmo com os parâmetros da query string.

Já o método Tag agrupa as entradas para remoção rápida. Então, basta injetar IOutputCacheStore no fluxo de escrita e remover pela tag:

internal sealed class UpdateShipmentStatusHandler(
    ShipmentsDbContext dbContext,
    IOutputCacheStore outputCache)
{
    public async Task HandleAsync(
        string shipmentNumber,
        ShipmentStatus status,
        CancellationToken cancellationToken)
    {
        var shipment = await dbContext.Shipments
            .FirstAsync(s => s.Number == shipmentNumber, cancellationToken);

        shipment.UpdateStatus(status);
        await dbContext.SaveChangesAsync(cancellationToken);

        // Remove todas as respostas marcadas com a tag
        await outputCache.EvictByTagAsync("shipments", cancellationToken);
    }
}

Atenção à ordem do pipeline. Segundo a documentação do Output Cache, UseOutputCache deve vir depois de UseCors, UseAuthentication e UseAuthorization.

Output cache no .NET com Redis

Por padrão, o Output Cache no .NET guarda as respostas em memória, o que traz de volta o problema das duas instâncias. Nesse caso, cada servidor tem o próprio cache, e ele se perde quando o processo reinicia.

A saída é usar o armazenamento em Redis com o pacote oficial:

dotnet add package Microsoft.AspNetCore.OutputCaching.StackExchangeRedis

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

Assim, todas as instâncias servem as mesmas respostas, e EvictByTagAsync em uma delas remove a entrada para todas. Repare que o método é AddStackExchangeRedisOutputCache, e não AddStackExchangeRedisCache.

A Microsoft também não recomenda usar IDistributedCache como armazenamento do Output Cache. O motivo é que essa interface não tem operações atômicas, que as tags exigem.

Vale um alerta sobre o middleware antigo de Response Caching, ativado com UseResponseCaching. Ele depende dos cabeçalhos Cache-Control enviados pelo cliente, que pode simplesmente ignorá-lo, além de não remover por tag nem suportar Redis.

Armadilhas do output cache no .NET

Antes das armadilhas, vale conhecer a política padrão. Ela só guarda respostas 200 de requisições GET ou HEAD, ignora respostas que definem cookies e não guarda requisições autenticadas.

Além disso, a granularidade é a resposta inteira. Ou seja, um único campo alterado invalida todo o payload.

A primeira armadilha é guardar dados por usuário sem variar pelo usuário. Se você sobrescrever o padrão e cachear respostas autenticadas, o usuário A pode receber os envios do usuário B.

Nesse caso, varie a política pelo cabeçalho Authorization:

options.AddPolicy("my-shipments", policy => policy
    .Expire(TimeSpan.FromMinutes(1))
    .SetVaryByHeader("Authorization")
    .Tag("shipments"));

Isso funciona, mas cada token vira uma entrada própria no cache do .NET. Portanto, a taxa de acerto cai conforme a base de usuários cresce.

A segunda armadilha é que a remoção mora no fluxo de escrita. Se algum handler esquecer de remover a tag, respostas antigas ficam disponíveis até expirar.

Por isso, centralize a remoção em um único lugar, como um handler de evento de domínio. Dessa forma, nenhum fluxo novo de escrita esquece a invalidação.

Quando usar IMemoryCache

O IMemoryCache é a opção de cache mais rápida no .NET, com leituras em nanossegundos e sem serialização. Ele serve bem para objetos que não podem ser serializados e para dados imutáveis muito grandes, lidos milhares de vezes.

Também atende ferramentas pequenas e aplicações de instância única. O artigo sobre ASP.NET Memory Cache mostra o uso básico dessa interface.

Escolha essa opção quando desserializar o objeto custaria mais que a consulta evitada. Além disso, limite a quantidade de chaves com SizeLimit e aceite que cada instância tenha a própria cópia.

Quando usar IDistributedCache

Use o IDistributedCache diretamente como cache no .NET apenas em casos específicos. Por exemplo, quando você precisa de controle total sobre os bytes gravados no Redis.

Ele também faz sentido para compartilhar valores pequenos entre aplicações diferentes pelo mesmo Redis. Outro cenário é um projeto preso ao .NET 8 ou anterior que não pode adicionar o HybridCache.

Quando usar HybridCache

O HybridCache é o padrão para novas aplicações a partir do .NET 9, e continua sendo no .NET 10, a versão LTS atual. Ele combina L1 e L2, protege contra stampede, suporta tags e adiciona Redis com uma linha.

Escolha essa opção quando quiser uma biblioteca oficial, sem dependência de terceiros. Ela também funciona bem quando você pretende começar sem Redis e adicioná-lo depois.

No entanto, conheça as armadilhas citadas pelo autor: o L1 não sincroniza entre instâncias, um null cacheado conta como acerto e as opções se mesclam de formas pouco óbvias. Portanto, alguns segundos de L1 desatualizado precisam ser aceitáveis para os seus dados.

Quando usar FusionCache

O FusionCache é a escolha de cache no .NET para várias instâncias que precisam de consistência quase imediata após uma escrita. Também atende APIs que precisam continuar respondendo quando o banco está lento ou fora do ar.

Ele serve ainda para times que superaram o HybridCache e querem manter os handlers como estão. Nesse cenário, o AsHybridCache faz a troca sem reescrever código.

Escolha essa opção quando um LocalCacheExpiration curto não bastar, quando precisar de fail-safe, timeouts ou eager refresh, e quando o seu Redis suportar pub/sub.

Quando usar output cache no .NET

O Output Cache é o cache no .NET ideal para endpoints públicos de leitura, com respostas idênticas para todos os usuários. Também combina com respostas que mudam pouco e podem ser removidas por tag.

Além disso, ele funciona como uma segunda camada sobre um cache de objetos. Escolha essa opção quando pular o handler inteiro for um ganho real e a resposta mudar como um todo.