Cache de resposta no ASP.NET Core

Por Rick Anderson e Kirk Larkin

Exibir ou baixar código de exemplo (como baixar)

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 respeitar os cabeçalhos para armazenar respostas em cache em RFC 9111: cache HTTP.

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

O middleware de cache de resposta:

• Habilita o cache de respostas do servidor com base em cabeçalhos de cache HTTP. Implementa a semântica de cache HTTP padrão. Os caches baseados em cabeçalhos de cache HTTP, assim como fazem os proxies.
• Normalmente, não é benéfico para aplicativos de interface do usuário, como o Razor Pages, porque os navegadores geralmente definem cabeçalhos de solicitação que impedem o cache. O cache de saída, que está disponível no ASP.NET Core 7.0 e 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 solicitações públicas de API GET ou HEAD de clientes, desde que as Condições em cache para o armazenamento sejam atendidas.

Para testar o cache de resposta, use Fiddler ou outra ferramenta que possa definir explicitamente os cabeçalhos de solicitação. A configuração explícita de cabeçalhos é preferida para testar o armazenamento em cache. Para saber mais, consulte a Solução de problemas.

Cache de resposta baseado em HTTP

RFC 9111: O cache HTTP descreve como os caches de Internet devem se comportar. O cabeçalho HTTP principal 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, à medida que as respostas fazem o caminho dos servidores de volta para os clientes. Solicitações e respostas são movidas por meio de 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úblico	Um cache pode armazenar a resposta.
private	A resposta não deve ser armazenada por um cache compartilhado. Um cache privado pode armazenar e reutilizar a resposta.
max-age	O cliente não aceita uma resposta cuja idade é maior que o número especificado de segundos. Exemplos: max-age=60 (60 segundos), max-age=2592000 (1 mês)
no-cache	Em solicitações: um cache não deve usar uma resposta armazenada para atender à solicitação. O servidor de origem regenera a resposta para o cliente e o middleware atualiza a resposta armazenada em seu cache. Em respostas: a resposta não deve ser usada para uma solicitação subsequente sem validação no servidor de origem.
no-store	Em solicitações: um cache não deve armazenar a solicitação. Em respostas: um cache não deve armazenar nenhuma parte da resposta.

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

parâmetro	Função
Age	Uma estimativa da quantidade de tempo em segundos desde que a resposta foi gerada ou validada com êxito no servidor de origem.
Expira em	O tempo após o qual a resposta é considerada obsoleta.
Pragma	Existe para compatibilidade com versões anteriores com caches HTTP/1.0 para definir o comportamento no-cache. Se o cabeçalho Cache-Control estiver presente, o cabeçalho Pragma será ignorado.
Vary	Especifica que uma resposta armazenada em cache não deve ser enviada, a menos que todos os campos do cabeçalho Vary correspondam tanto na solicitação original da resposta armazenada em cache quanto na nova solicitação.

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

RFC 9111: Cache HTTP (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 respeitar cabeçalhos Cache-Control de solicitação de cliente faz sentido se você considerar a meta de cache HTTP. De acordo com a especificação oficial, o cache destina-se a reduzir a latência e a sobrecarga de rede de atender 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 Middleware de Cache de Resposta porque o middleware segue a especificação oficial de cache. O suporte para cache de saída para controlar melhor a carga do servidor foi adicionado ao .NET 7. Para obter mais informações, confira Cache de Saída.

Atributo ResponseCache

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

Aviso

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

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

O Middleware de Cache de Resposta deve ser habilitado para definir a propriedade VaryByQueryKeys. Caso contrário, uma exceção de runtime será gerada. 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 atenda a uma resposta armazenada 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:

Solicitação	Retornado 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 (por meio de IFilterFactory) um Microsoft.AspNetCore.Mvc.Internal.ResponseCacheFilter. O ResponseCacheFilter executa o trabalho de atualização dos cabeçalhos e recursos HTTP apropriados da resposta. O filtro:

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

Vary

Esse cabeçalho só é gravado quando a propriedade VaryByHeader é definida. A propriedade definida como 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());

Visualizar 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 AddResponseCaching do Middleware de Cache de Resposta à 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 a propriedade é definida como true, o cabeçalho Cache-Control é definido como no-store. Se Location for definido como None:

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

Se NoStore for false e Location for None, Cache-Control e Pragma estiverem 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 do aplicar ou a respostas de página do Razor Pages, adicione-o com um filtro MVC ou flitro Razor Pages.

Em um aplicativo MVC:

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

Para obter uma abordagem que se aplica ao Razor Pages do aplicativo, consulte Adicionar ResponseCacheAttribute à lista de filtros globais do MVC não se aplica ao Razor Pages (dotnet/aspnetcore #18890). O exemplo fornecido no comentário do problema foi escrito para aplicativos direcionados ASP.NET Core antes do lançamento de APIs mínimas em 6.0. Para aplicativos 6.0 ou posteriores, altere o registro de serviço no exemplo para builder.Services.AddSingleton... para Program.cs.

Local 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 como o valor do local seguido pelo max-age da resposta.

LocationAs opções de Any e Client traduzem em valores de cabeçalho Cache-Control de public e private, respectivamente. Conforme observado na seção NoStore e Location.None, a configuração Location para 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 em cache o valor, incluindo Middleware de Cache de Resposta.

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

Os cabeçalhos de controle de cache fornecem diretrizes para clientes e proxies intermediários quando e como armazenar respostas em cache. Não há garantia de que clientes e proxies respeitarão o RFC 9111: cache HTTP. O Middleware de Cache de Resposta sempre segue as regras de cache estabelecidas pela especificação.

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

[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 configurações de cache de resposta em muitos atributos de ação do controlador, os perfis de cache podem ser configurados como opções ao configurar o MVC/Razor Pages. Os valores encontrados em um perfil de cache referenciado são usados como padrões pelo ResponseCacheAttribute e são substituídos por quaisquer propriedades especificadas no 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:

• Páginas Razor: atributos não podem ser aplicados a métodos de manipulador. Navegadores usados com aplicativos de interface do usuário impedem o cache de resposta.
• Controladores MVC.
• Métodos de ação MVC: os atributos no nível do 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
• Cache-Control
• 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
• Auxiliar de Marca de Cache no ASP.NET Core MVC
• Auxiliar de Marca de Cache Distribuído no ASP.NET Core