Cache de resposta no ASP.NET Core

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.

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

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.

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:

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

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 é controlado por cabeçalhos que especificam como você deseja que o cliente, o proxy e o middleware armazenem respostas em cache.

O [ResponseCache] participa da configuração de 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 [ResponseCache] para definir cabeçalhos de cache do lado do servidor.

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.

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

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 o cache de saída para controlar melhor a carga do servidor é uma proposta de design para uma versão futura do ASP.NET Core. Para obter mais informações, consulte Adicionar suporte para cache de saída (dotnet/aspnetcore #27387).

Outra tecnologia de cache no ASP.NET Core

cache na memória

O cache na memória usa a memória do servidor para armazenar dados em cache. Esse tipo de armazenamento em cache é adequado para um único servidor ou vários servidores que usam afinidade de sessão. A afinidade de sessão também é conhecida como sessões permanentes. A afinidade de sessão significa que as solicitações de um cliente são sempre roteadas para o mesmo servidor para processamento.

Para obter mais informações, confira Cache na memória no ASP.NET Core e Solucionar problemas de afinidade de sessão do Gateway de Aplicativo do Azure.

Cache distribuído

Use um cache distribuído para armazenar dados em memória quando o aplicativo está hospedado em uma nuvem ou no farm de servidores. O cache é compartilhado entre os servidores que processam as solicitações. Um cliente pode enviar uma solicitação tratada por qualquer servidor do grupo se os dados armazenados em cache para o cliente estiverem disponíveis. O ASP.NET Core funciona com caches distribuídos de SQL Server, Redis e NCache.

Para obter mais informações, confira Cache distribuído no ASP.NET Core.

Auxiliar de Marcação de cache

Armazene em cache o conteúdo de uma exibição MVC ou Página Razor com o Auxiliar de Marca de Cache. O Auxiliar de Marca de Cache usa o cache na memória para armazenar dados.

Para obter mais informações, confira Auxiliar de Marca de Cache no ASP.NET Core MVC.

Auxiliar de Marca de Cache Distribuído

Armazene em cache o conteúdo de uma exibição MVC ou Página Razor em cenários de Web farm ou nuvem distribuída com o Auxiliar de Marca de Cache Distribuído. O Auxiliar de Marca de Cache Distribuído usa SQL Server, Redis ou NCache para armazenar dados.

Para obter mais informações, confira Auxiliar de Marca de Cache Distribuído no ASP.NET Core.

Atributo ResponseCache

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

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.

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:

[ResponseCache(VaryByHeader = "User-Agent", Duration = 30)]
public class Cache1Model : PageModel
{

Usando o aplicativo de exemplo, visualize os cabeçalhos de resposta com as ferramentas de rede do navegador. Os seguintes cabeçalhos de resposta são enviados com a resposta da página Cache1:

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

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. A página Cache2 no aplicativo de exemplo produz cabeçalhos de resposta que instruem o cliente a não armazenar a resposta.

[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
public class Cache2Model : PageModel
{

O aplicativo de exemplo retorna a página Cache2 com os seguintes cabeçalhos:

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:

services.AddMvc().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).

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.

Cabeçalhos de controle de cache apenas 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 o modelo de página Cache3 do aplicativo de exemplo e os cabeçalhos produzidos pela configuração Duration e deixando o valor padrão Location :

[ResponseCache(Duration = 10, Location = ResponseCacheLocation.Any, NoStore = false)]
public class Cache3Model : PageModel
{

O aplicativo de exemplo retorna a página Cache3 com o seguinte cabeçalho:

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 em Startup.ConfigureServices. 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 .

Configurar um perfil de cache. O exemplo a seguir mostra um perfil de cache de 30 segundos no aplicativo de exemplo Startup.ConfigureServices:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();
    services.AddMvc(options =>
    {
        options.CacheProfiles.Add("Default30",
            new CacheProfile()
            {
                Duration = 30
            });
    });
}

O modelo de página Cache4 do aplicativo de exemplo faz referência ao perfil de Default30 cache:

[ResponseCache(CacheProfileName = "Default30")]
public class Cache4Model : PageModel
{

O ResponseCacheAttribute pode ser aplicado em:

• Páginas Razor: atributos não podem ser aplicados a métodos de manipulador.
• 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 cabeçalho resultante aplicado à resposta da página Cache4 pelo perfil de cache Default30:

Cache-Control: public,max-age=30

Recursos adicionais

• Armazenando respostas em caches
• RFC 9111: Cache HTTP (Seção 5.2. 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
• Auxiliar de Marca de Cache no ASP.NET Core MVC
• Auxiliar de Marca de Cache Distribuído no ASP.NET Core