Middleware de cache de resposta no ASP.NET Core

Por John Luo e Rick Anderson

Este artigo explica como configurar o middleware de cache de resposta em um aplicativo ASP.NET Core. O middleware determina quando as respostas podem ser armazenadas em cache, armazena respostas e serve respostas do cache. Para obter uma introdução ao cache HTTP e ao [ResponseCache] atributo, consulte Cache de resposta.

O middleware de cache para resposta:

• Permite armazenar em cache respostas do servidor com base em cabeçalhos de cache HTTP. Implementa a semântica de cache HTTP padrão. Caches baseados em cabeçalhos de cache HTTP, como fazem os proxies.
• Normalmente, não é benéfico para aplicativos de interface do usuário, como Razor Pages, porque os navegadores geralmente definem cabeçalhos de solicitação que impedem o armazenamento em cache. O cache de saída, que está disponível no .NET 7 ou posterior, beneficia os aplicativos de interface do usuário. Com o cache de saída, a configuração decide o que deve ser armazenado em cache independentemente dos cabeçalhos HTTP.
• Pode ser benéfico para pedidos públicos de API GET ou HEAD de clientes onde as condições para o cache de e são cumpridas.

Para testar o cache de respostas, use Fiddlerou outra ferramenta que possa definir explicitamente cabeçalhos de solicitação. A configuração de cabeçalhos explicitamente é preferível para testar o cache. Para mais informações, consulte Resolução de Problemas.

Configuration

No Program.cs, adicione os serviços de cache de resposta de middleware AddResponseCaching à coleção de serviços e configure a aplicação para usar o middleware com o método de extensão UseResponseCaching. UseResponseCaching Adiciona o middleware ao pipeline de processamento de solicitações:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching();

var app = builder.Build();

app.UseHttpsRedirection();

// UseCors must be called before UseResponseCaching
//app.UseCors();

app.UseResponseCaching();

Warning

UseCors deve ser chamado antes UseResponseCaching ao usar middleware CORS.

O aplicativo de exemplo adiciona cabeçalhos para controlar o cache em solicitações subsequentes:

• Cache-Control: armazena em cache respostas que podem ser armazenadas em cache por até 10 segundos.
• Variar: configura o middleware para servir uma resposta em cache somente se o cabeçalho Accept-Encoding das solicitações subsequentes corresponder ao da solicitação original.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching();

var app = builder.Build();

app.UseHttpsRedirection();

// UseCors must be called before UseResponseCaching
//app.UseCors();

app.UseResponseCaching();

app.Use(async (context, next) =>
{
    context.Response.GetTypedHeaders().CacheControl =
        new Microsoft.Net.Http.Headers.CacheControlHeaderValue()
        {
            Public = true,
            MaxAge = TimeSpan.FromSeconds(10)
        };
    context.Response.Headers[Microsoft.Net.Http.Headers.HeaderNames.Vary] =
        new string[] { "Accept-Encoding" };

    await next();
});

app.MapGet("/", () => DateTime.Now.Millisecond);

app.Run();

Os cabeçalhos anteriores não são gravados na resposta e são substituídos quando um controlador, ação ou Razor Página:

• Tem um atributo [ResponseCache]. Isso se aplica mesmo se uma propriedade não estiver definida. Por exemplo, omitir a propriedade VaryByHeader fará com que o cabeçalho correspondente seja removido da resposta.

O Middleware de Cache de Resposta armazena em cache apenas as respostas do servidor que resultam em um código de status 200 (OK). Quaisquer outras respostas, incluindo páginas de erro, são ignoradas pelo middleware.

Warning

As respostas que contêm conteúdo para clientes autenticados devem ser marcadas como não armazenáveis em cache para impedir que o middleware armazene e sirva essas respostas. Consulte Condições para armazenamento em cache para obter detalhes sobre como o middleware determina se uma resposta pode ser armazenada em cache.

O código anterior normalmente não retorna um valor armazenado em cache para um navegador. Use o Fiddler ou outra ferramenta que possa definir explicitamente cabeçalhos de solicitação e seja preferida para testar o cache. Para obter mais informações, consulte Solução de problemas neste artigo.

Opções

As opções de cache de resposta são mostradas na tabela a seguir.

Option	Description
MaximumBodySize	O maior tamanho do corpo da resposta que pode ser armazenado em cache em bytes. O valor padrão é 64 * 1024 * 1024 (64 MB).
SizeLimit	O limite de tamanho para o middleware de cache de resposta em bytes. O valor padrão é 100 * 1024 * 1024 (100 MB).
UseCaseSensitivePaths	Determina se as respostas são armazenadas em cache em caminhos sensíveis a maiúsculas e minúsculas. O valor predefinido é false.

O exemplo a seguir configura o middleware para:

• Respostas de cache com um tamanho de corpo menor ou igual a 1.024 bytes.
• Armazene as respostas por caminhos sensíveis a maiúsculas e minúsculas. Por exemplo, /page1 e /Page1 são armazenados separadamente.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching(options =>
{
    options.MaximumBodySize = 1024;
    options.UseCaseSensitivePaths = true;
});

var app = builder.Build();

app.UseHttpsRedirection();

// UseCors must be called before UseResponseCaching
//app.UseCors();

app.UseResponseCaching();

app.Use(async (context, next) =>
{
    context.Response.GetTypedHeaders().CacheControl =
        new Microsoft.Net.Http.Headers.CacheControlHeaderValue()
        {
            Public = true,
            MaxAge = TimeSpan.FromSeconds(10)
        };
    context.Response.Headers[Microsoft.Net.Http.Headers.HeaderNames.Vary] =
        new string[] { "Accept-Encoding" };

    await next(context);
});

app.MapGet("/", () => DateTime.Now.Millisecond);

app.Run();

VaryByQueryKeys

Ao usar MVC, controladores de API da Web ou Razor modelos de página Pages, o [ResponseCache] atributo especifica os parâmetros necessários para definir cabeçalhos apropriados para cache de resposta. O único parâmetro do [ResponseCache] atributo que requer estritamente o middleware é VaryByQueryKeys, que não corresponde a um cabeçalho HTTP real. Para obter mais informações, consulte Cache de resposta no ASP.NET Core.

Quando não estiver a usar o atributo [ResponseCache], pode variar o cache de resposta com VaryByQueryKeys. Use o ResponseCachingFeature diretamente do HttpContext.Features:

var responseCachingFeature = context.HttpContext.Features.Get<IResponseCachingFeature>();

if (responseCachingFeature != null)
{
    responseCachingFeature.VaryByQueryKeys = new[] { "MyKey" };
}

O uso de um único valor igual a * em VaryByQueryKeys varia o cache por todos os parâmetros de consulta de solicitação.

Os cabeçalhos HTTP usados pelo middleware de cache de resposta

A tabela a seguir fornece informações sobre cabeçalhos HTTP que afetam o cache de resposta.

Header	Details
Authorization	A resposta não será armazenada em cache se o cabeçalho existir.
Cache-Control	O middleware considera apenas respostas de cache marcadas com a public diretiva de cache. Controle o cache com os seguintes parâmetros: max-age max-stale† min-fresh must-revalidate no-cache no-store only-if-cached privado public s-maxage proxy-revalidate‡ †Se nenhum limite for especificado para max-stale, o middleware não tomará nenhuma ação. proxy-revalidate‡ tem o mesmo efeito que must-revalidate. Para obter mais informações, consulte RFC 9111: Diretivas de solicitação.
Pragma	Um Pragma: no-cache cabeçalho na solicitação produz o mesmo efeito que Cache-Control: no-cache. Este cabeçalho é substituído pelas diretivas relevantes no cabeçalho Cache-Control, se houver. Considerado para compatibilidade retroativa com HTTP/1.0.
Set-Cookie	A resposta não será armazenada em cache se o cabeçalho existir. Qualquer middleware no pipeline de processamento de solicitações que defina um ou mais cookies impede que o Middleware de Cache de Resposta armazene em cache a resposta (por exemplo, o provedor baseado em TempData).
Vary	O Vary cabeçalho é usado para modificar a resposta em cache por outro cabeçalho. Por exemplo, armazene respostas em cache codificando incluindo o Vary: Accept-Encoding cabeçalho, que armazena em cache respostas para solicitações com cabeçalhos Accept-Encoding: gzip e Accept-Encoding: text/plain separadamente. Uma resposta com um valor de cabeçalho de * nunca é armazenada.
Expires	Uma resposta considerada obsoleta por esse cabeçalho não é armazenada ou recuperada, a menos que seja substituída por outros Cache-Control cabeçalhos.
If-None-Match	A resposta completa é servida a partir do cache se o valor não for * e se o ETag da resposta não corresponder a nenhum dos valores fornecidos. Caso contrário, uma resposta 304 (Não Modificada) é enviada.
If-Modified-Since	Se o If-None-Match cabeçalho não estiver presente, uma resposta completa será servida do cache se a data de resposta em cache for mais recente do que o valor fornecido. Caso contrário, uma resposta 304 - Não Modificado será apresentada.
Date	Quando se serve a partir do cache, o cabeçalho Date é definido pelo middleware se não tiver sido fornecido na resposta original.
Content-Length	Quando se serve a partir do cache, o cabeçalho Content-Length é definido pelo middleware se não tiver sido fornecido na resposta original.
Age	O Age cabeçalho enviado na resposta original é ignorado. O middleware calcula um novo valor ao servir uma resposta em cache.

O cache respeita as diretivas de solicitação Cache-Control

O middleware respeita as regras do RFC 9111: HTTP Caching (Seção 5.2. Cache-Control). As regras exigem um cache para honrar um cabeçalho válido Cache-Control enviado pelo cliente. Sob a especificação, um cliente pode fazer solicitações com um no-cache valor de cabeçalho e forçar o servidor a gerar uma nova resposta para cada solicitação. Atualmente, não há controle do desenvolvedor sobre esse comportamento de cache ao usar o middleware porque o middleware adere à especificação oficial de cache.

Para obter mais controle sobre o comportamento de cache, explore outros recursos de cache do ASP.NET Core. Consulte os seguintes tópicos:

• Cache na memória no ASP.NET Core
• Cache distribuído no ASP.NET Core
• Tag Helper de Cache em ASP.NET Core MVC
• auxiliar de tag de cache distribuído no ASP.NET Core

Troubleshooting

O middleware de cache de resposta usa IMemoryCache, que tem uma capacidade limitada. Quando a capacidade é excedida, o cache de memória é compactado (TriggerOvercapacityCompaction).

Note

Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, use a lista suspensa Alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Se o comportamento de cache não for o esperado, confirme se as respostas podem ser armazenadas em cache e podem ser servidas a partir do cache. Examine os cabeçalhos de entrada da solicitação e os cabeçalhos de saída da resposta. Habilite o registro em log para ajudar na depuração.

Ao testar e solucionar problemas de comportamento de cache, um navegador normalmente define cabeçalhos de solicitação que impedem o cache. Por exemplo, um navegador pode definir o Cache-Control cabeçalho para no-cache ou max-age=0 ao atualizar uma página. O Fiddler e outras ferramentas podem definir explicitamente cabeçalhos de solicitação e são preferidos para testar o cache.

Condições para armazenamento em cache

• A solicitação deve resultar em uma resposta do servidor com um código de status 200 (OK).
• O método de solicitação deve ser GET ou HEAD.
• O middleware de cache de resposta deve ser colocado antes do middleware que requer cache. Para obter mais informações, consulte ASP.NET Core Middleware.
• O Authorization cabeçalho não deve estar presente.
• Cache-Control Os parâmetros de cabeçalho devem ser válidos e a resposta deve ser marcada public e não marcada private.
• O cabeçalho Pragma: no-cache não deve estar presente se o cabeçalho Cache-Control não estiver presente, pois o cabeçalho Cache-Control substitui o cabeçalho Pragma quando está presente.
• O Set-Cookie cabeçalho não deve estar presente.
• Vary Os parâmetros do cabeçalho devem ser válidos e não iguais a *.
• O Content-Length valor do cabeçalho (se definido) deve corresponder ao tamanho do corpo da resposta.
• O IHttpSendFileFeature não é usado.
• A resposta não deve estar desatualizada, conforme especificado pelo cabeçalho Expires e pelas diretivas de cache max-age e s-maxage.
• O buffer de resposta deve ser bem-sucedido. O tamanho da resposta deve ser menor do que o configurado ou o valor predefinido SizeLimit. O tamanho do corpo da resposta deve ser menor do que o configurado ou padrão MaximumBodySize.
• A resposta deve ser armazenável em cache de acordo com RFC 9111: HTTP Caching. Por exemplo, a no-store diretiva não deve existir nos campos de cabeçalho de solicitação ou resposta. Consulte RFC 9111: HTTP Caching (Seção 3: Armazenando respostas em caches para obter detalhes.

Note

O sistema Antifalsificação para gerar tokens seguros e evitar ataques de falsificação de solicitação entre sites (CSRF) define os cabeçalhos Cache-Control e Pragma para no-cache, de modo que as respostas não sejam armazenadas em cache. Para obter informações sobre como desabilitar tokens antifalsificação para elementos de formulário HTML, consulte Impedir ataques de falsificação de solicitação entre sites (XSRF/CSRF) no ASP.NET Core.

Recursos adicionais

• Visualizar ou descarregar amostra de código (como descarregar)
• Fonte do GitHub para IResponseCachingPolicyProvider
• Fonte do GitHub para IResponseCachingPolicyProvider
• Inicialização do aplicativo no ASP.NET Core
• ASP.NET Middleware principal
• Cache na memória no ASP.NET Core
• Cache distribuído no ASP.NET Core
• Detectar alterações com tokens de alteração no ASP.NET Core
• Cache de Resposta no ASP.NET Core
• Tag Helper de Cache em ASP.NET Core MVC
• auxiliar de tag de cache distribuído no ASP.NET Core