Cache de resposta no ASP.NET Core

Por Rick Anderson e Kirk Larkin

Ver ou transferir o código de exemplo (como transferir)

O cache de resposta reduz o número de solicitações que um cliente ou proxy faz a um servidor Web. O cache de resposta também reduz a quantidade de trabalho que o servidor Web executa para gerar uma resposta. O cache de resposta é definido em cabeçalhos.

O atributo ResponseCache define cabeçalhos de cache de resposta. Clientes e proxies intermediários devem honrar os cabeçalhos para respostas de cache em RFC 9111: HTTP Caching.

Para o cacheamento do lado do servidor que segue a especificação de caching HTTP 1.1, use Response Caching Middleware. O middleware pode usar as propriedades ResponseCacheAttribute para influenciar o comportamento de cache do lado do servidor.

O middleware de cache de 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. cache de saída, que está disponível no ASP.NET Core 7.0 e posterior, beneficia os aplicativos da 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 solicitações públicas de API GET ou HEAD de clientes onde as condições de para de cache são atendidas.

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 obter mais informações, consulte Solução de problemas.

Cache de resposta baseado em HTTP

RFC 9111: HTTP Caching descreve como os caches da Internet devem se comportar. O cabeçalho HTTP primário usado para cache é Cache-Control, que é usado para especificar diretivas de cache. As diretivas controlam o comportamento de cache à medida que as solicitações passam de clientes para servidores e as respostas passam de servidores de volta para clientes. As solicitações e respostas são movidas por servidores proxy e os servidores proxy também devem estar em conformidade com a especificação de cache HTTP 1.1.

As diretivas Cache-Control comuns são mostradas na tabela a seguir.

Diretiva	Ação
pública	Um cache pode armazenar a resposta.
privada	A resposta não deve ser armazenada por um cache compartilhado. Um cache privado pode armazenar e reutilizar a resposta.
idade máxima	O cliente não aceita uma resposta cuja idade seja maior do que o número de segundos especificado. Exemplos: max-age=60 (60 segundos), max-age=2592000 (1 mês)
sem cache	Em solicitações: Um cache não deve usar uma resposta armazenada para satisfazer a solicitação. O servidor de origem regenera a resposta para o cliente e o middleware atualiza a resposta armazenada em seu cache. Sobre as respostas: A resposta não deve ser usada para uma solicitação subsequente sem validação no servidor de origem.
sem loja	Em solicitações: Um cache não deve armazenar a solicitação. Sobre as respostas: Um cache não deve armazenar nenhuma parte da resposta.

Outros cabeçalhos de cache que desempenham um papel no cache são mostrados na tabela a seguir.

Cabeçalho	Função
Idade	Uma estimativa do tempo, em segundos, desde que a resposta foi gerada ou validada com êxito no servidor de origem.
Expira	O tempo após o qual a resposta é considerada obsoleta.
Pragma	Existe para garantir a compatibilidade retroativa com caches HTTP/1.0 no que diz respeito à definição do comportamento no-cache. Se o cabeçalho Cache-Control estiver presente, o cabeçalho Pragma será ignorado.
variam	Especifica que uma resposta em cache não deve ser enviada, a menos que todos os campos de cabeçalho Vary correspondam na solicitação original da resposta em cache e na nova solicitação.

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

RFC 9111: HTTP Caching (Seção 5.2. Cache-Control) requer um cache para honrar um cabeçalho Cache-Control válido enviado pelo cliente. Um cliente pode fazer solicitações com um valor de cabeçalho no-cache e forçar o servidor a gerar uma nova resposta para cada solicitação.

Sempre honrar os cabeçalhos de solicitação do cliente Cache-Control faz sentido se considerarmos o objetivo do cache HTTP. De acordo com a especificação oficial, o cache destina-se a reduzir a latência e a sobrecarga de rede de satisfazer solicitações em uma rede de clientes, proxies e servidores. Não é necessariamente uma maneira de controlar a carga em um servidor de origem.

Não há controle do desenvolvedor sobre esse comportamento de cache ao usar o Response Caching Middleware porque o middleware adere à especificação oficial de cache. O suporte para cache de saída para controlar melhor a carga do servidor foi adicionado no .NET 7. Para obter mais informações, consulte Caché de saída.

Atributo ResponseCache

O ResponseCacheAttribute especifica os parâmetros necessários para definir cabeçalhos apropriados no cache de resposta.

Advertência

Desative o cache para conteúdo que contenha informações para clientes autenticados. O cache só deve ser habilitado para conteúdo que não é alterado com base na identidade de um usuário ou se um usuário está conectado.

VaryByQueryKeys varia a resposta armazenada pelos valores da lista fornecida de chaves de consulta. Quando um único valor de * é fornecido, o middleware varia as respostas por todos os parâmetros da string de consulta da solicitação.

Middleware de Cache de Resposta deve estar ativado para definir a propriedade VaryByQueryKeys. Caso contrário, uma exceção de tempo de execução será lançada. Não há um cabeçalho HTTP correspondente para a propriedade VaryByQueryKeys. A propriedade é um recurso HTTP manipulado pelo Middleware de Cache de Resposta. Para que o middleware sirva uma resposta em cache, a cadeia de caracteres de consulta e o valor da cadeia de caracteres de consulta devem corresponder a uma solicitação anterior. Por exemplo, considere a sequência de solicitações e resultados mostrados na tabela a seguir:

Pedido	Devolvido de
http://example.com?key1=value1	Servidor
http://example.com?key1=value1	Middleware
http://example.com?key1=NewValue	Servidor

A primeira solicitação é retornada pelo servidor e armazenada em cache no middleware. A segunda solicitação é retornada pelo middleware porque a cadeia de caracteres de consulta corresponde à solicitação anterior. A terceira solicitação não está no cache do middleware porque o valor da cadeia de caracteres de consulta não corresponde a uma solicitação anterior.

O ResponseCacheAttribute é usado para configurar e criar (via IFilterFactory) um Microsoft.AspNetCore.Mvc.Internal.ResponseCacheFilter. O ResponseCacheFilter executa o trabalho de atualizar os cabeçalhos HTTP apropriados e os recursos da resposta. O filtro:

• Remove todos os cabeçalhos existentes para Vary, Cache-Controle Pragma.
• Escreve os cabeçalhos apropriados com base nas propriedades definidas no ResponseCacheAttribute.
• Atualiza o recurso HTTP de cache de resposta se VaryByQueryKeys estiver definido.

Variar

Esse cabeçalho só é gravado quando a propriedade VaryByHeader é definida. A propriedade é definida para o valor da propriedade Vary. O exemplo a seguir usa a propriedade VaryByHeader:

[ApiController]
public class TimeController : ControllerBase
{
    [Route("api/[controller]")]
    [HttpGet]
    [ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]
    public ContentResult GetTime() => Content(
                      DateTime.Now.Millisecond.ToString());

Exiba os cabeçalhos de resposta com o Fiddler ou outra ferramenta. Os cabeçalhos de resposta incluem:

Cache-Control: public,max-age=30
Vary: User-Agent

O código anterior requer a adição dos serviços de middleware de cache de resposta AddResponseCaching à coleção de serviços e configura o aplicativo para usar o middleware com o método de extensão UseResponseCaching.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddResponseCaching();

var app = builder.Build();

app.UseHttpsRedirection();

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

app.UseResponseCaching();

app.UseAuthorization();

app.MapControllers();

app.Run();

NoStore e Location.None

NoStore substitui a maioria das outras propriedades. Quando esta propriedade é definida como true, o cabeçalho Cache-Control é definido como no-store. Se Location estiver definido como None:

• Cache-Control é configurado como no-store,no-cache.
• Pragma é definido como no-cache.

Se NoStore é false e Location é None, Cache-Controle Pragma são definidos como no-cache.

NoStore normalmente é definido como true para páginas de erro. O seguinte produz cabeçalhos de resposta que instruem o cliente a não armazenar a resposta.

[Route("api/[controller]/ticks")]
[HttpGet]
[ResponseCache(Location = ResponseCacheLocation.None, NoStore = true)]
public ContentResult GetTimeTicks() => Content(
                  DateTime.Now.Ticks.ToString());

O código anterior inclui os seguintes cabeçalhos na resposta:

Cache-Control: no-store,no-cache
Pragma: no-cache

Para aplicar o ResponseCacheAttribute a todas as respostas do controlador MVC ou das páginas Razor Pages do aplicativo, adicione-o com um filtro MVC ou um filtro Páginas Razor.

Em um aplicativo MVC:

builder.Services.AddControllersWithViews().AddMvcOptions(options => 
    options.Filters.Add(
        new ResponseCacheAttribute
        {
            NoStore = true, 
            Location = ResponseCacheLocation.None
        }));

Para ver uma abordagem aplicável às aplicações de páginas Razor, consulte Adicionar ResponseCacheAttribute à lista de filtros globais do MVC não se aplica a páginas Razor (dotnet/aspnetcore #18890). O exemplo fornecido no comentário do problema foi escrito para aplicativos direcionados ao ASP.NET Core antes do lançamento do Minimal APIs na versão 6.0. Para aplicações 6.0 ou posteriores, altere o registo de serviço no exemplo de Program.cspara builder.Services.AddSingleton....

Localização e Duração

Para habilitar o cache, Duration deve ser definido como um valor positivo e Location deve ser Any (o padrão) ou Client. A estrutura define o cabeçalho Cache-Control para o valor do local seguido pelo max-age da resposta.

As opções de Locationde Any e Client correspondem a valores de cabeçalho Cache-Control de public e private, respectivamente. Conforme observado na seção NoStore e Location.None, definir Location como None define os cabeçalhos Cache-Control e Pragma como no-cache.

Location.Any (Cache-Control definido como public) indica que o cliente ou qualquer proxy intermediário pode armazenar o valor em cache, incluindo Response Caching Middleware.

Location.Client (Cache-Control definido como private) indica que apenas o cliente pode armazenar o valor em cache. Nenhum cache intermediário deve armazenar o valor em cache, incluindo Middleware de Cache de Resposta.

Os cabeçalhos de controle de cache fornecem orientação para clientes e proxies intermediários quando e como armazenar respostas em cache. Não há garantia de que os clientes e proxies honrarão RFC 9111: HTTP Caching. O Middleware de cache de resposta observa sempre as regras de cache estabelecidas pela especificação.

O exemplo a seguir mostra os cabeçalhos produzidos definindo Duration e deixando o valor de Location padrão:

[Route("api/[controller]/ms")]
[HttpGet]
[ResponseCache(Duration = 10, Location = ResponseCacheLocation.Any, NoStore = false)]
public ContentResult GetTimeMS() => Content(
                  DateTime.Now.Millisecond.ToString());

O código anterior inclui os seguintes cabeçalhos na resposta:

Cache-Control: public,max-age=10

Perfis de cache

Em vez de duplicar as definições de cache de resposta em vários atributos de ação dos controladores, podem configurar-se perfis de cache como opções ao instalar as páginas MVC/Razor. Os valores encontrados num perfil de cache referenciado são usados como valores predefinidos pelo ResponseCacheAttribute e podem ser substituídos por quaisquer propriedades especificadas pelo atributo.

O exemplo a seguir mostra um perfil de cache de 30 segundos:

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCaching();
builder.Services.AddControllers(options =>
{
    options.CacheProfiles.Add("Default30",
        new CacheProfile()
        {
            Duration = 30
        });
});

var app = builder.Build();

app.UseHttpsRedirection();

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

app.UseResponseCaching();

app.UseAuthorization();

app.MapControllers();

app.Run();

O código a seguir faz referência ao perfil de cache Default30:

[ApiController]
[ResponseCache(CacheProfileName = "Default30")]
public class Time2Controller : ControllerBase
{
    [Route("api/[controller]")]
    [HttpGet]
    public ContentResult GetTime() => Content(
                      DateTime.Now.Millisecond.ToString());

    [Route("api/[controller]/ticks")]
    [HttpGet]
    public ContentResult GetTimeTicks() => Content(
                      DateTime.Now.Ticks.ToString());
}

A resposta de cabeçalho resultante pelo perfil de cache Default30 inclui:

Cache-Control: public,max-age=30

O atributo [ResponseCache] pode ser aplicado a:

• Razor Pages: Os atributos não podem ser aplicados a métodos manipuladores. Os navegadores usados com aplicativos de interface do usuário impedem o cache de respostas.
• Controladores MVC.
• Métodos de ação MVC: os atributos de nível de método substituem as configurações especificadas em atributos de nível de classe.

O código a seguir aplica o atributo [ResponseCache] no nível do controlador e no nível do método:

[ApiController]
[ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]
public class Time4Controller : ControllerBase
{
    [Route("api/[controller]")]
    [HttpGet]
    public ContentResult GetTime() => Content(
                      DateTime.Now.Millisecond.ToString());

    [Route("api/[controller]/ticks")]
    [HttpGet]
    public ContentResult GetTimeTicks() => Content(
                  DateTime.Now.Ticks.ToString());

    [Route("api/[controller]/ms")]
    [HttpGet]
    [ResponseCache(Duration = 10, Location = ResponseCacheLocation.Any, NoStore = false)]
    public ContentResult GetTimeMS() => Content(
                      DateTime.Now.Millisecond.ToString());
}

Recursos adicionais

• Armazenando respostas em caches
• de controle de cache
• 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
• Middleware de 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