Provedor de Cache de Saída ASP.NET para o Cache Redis do Azure

O Provedor de Cache de Saída Redis é um mecanismo de armazenamento fora do processo para dados do cache de saída. Esses dados são usados especificamente para respostas HTTP completas (cache de saída de página). O provedor se conecta ao novo ponto de extensibilidade do provedor de cache de saída que foi apresentado no ASP.NET 4.

Para aplicativos ASP.NET Core, consulte Cache de saída em ASP.NET Core usando o Redis no .NET 8.

Para usar o Provedor de Cache de Saída Redis, primeiro configure seu cache e, em seguida, configure seu aplicativo ASP.NET usando o pacote NuGet do Provedor de Cache de Saída do Redis. Este artigo fornece diretrizes sobre como configurar seu aplicativo para usar o Provedor de Cache de Saída Redis.

Armazenar a saída da página ASP.NET Core no Redis

Para obter uma especificação completa de recursos, veja Cache de saída principal do ASP.NET.

Para um exemplo de aplicativo demonstrando o uso, consulte Aplicativo Web .NET 8 com Cache de Saída Redis e OpenAI do Azure.

Armazenar a saída da página ASP.NET no Redis

Para configurar um aplicativo cliente no Visual Studio usando o pacote NuGet de Estado de Sessão do Cache do Azure para Redis, selecione Gerenciador de Pacotes NuGet e Console do Gerenciador de Pacotes no menu Ferramentas.

Execute o comando a seguir na janela Package Manager Console:

Install-Package Microsoft.Web.RedisOutputCacheProvider

O pacote NuGet do Provedor de Cache de Saída Redis tem uma dependência no pacote StackExchange.Redis. Se o pacote StackExchange.Redis não estiver presente em seu projeto, ele será instalado. Para obter mais informações sobre o pacote NuGet do Provedor de Cache de Saída Redis, consulte a página do NuGet RedisOutputCacheProvider.

O pacote do NuGet baixa e adiciona as referências de assembly necessárias e adiciona a seção a seguir ao seu arquivo web.config. Essa seção contém a configuração necessária para que seu aplicativo ASP.NET use o Provedor de Cache de Saída Redis.

<caching>
  <outputCache defaultProvider="MyRedisOutputCache">
    <providers>
      <add name="MyRedisOutputCache" type="Microsoft.Web.Redis.RedisOutputCacheProvider"
           host=""
           accessKey=""
           ssl="true" />
    </providers>
  </outputCache>
</caching>

Configure os atributos na primeira coluna com os valores do cache no portal do Microsoft Azure. Além disso, configure os outros valores que você deseja. Para obter instruções sobre como acessar as propriedades do cache, consulte Definir configurações do Cache Redis do Azure.

Atributo	Type	Padrão	Descrição
_host*	string	"localhost"	O nome do host ou o endereço IP do servidor Redis
port	número inteiro positivo	6379 (não TLS/SSL) 6380 (TLS/SSL) 10000 para Redis Enterprise e Azure Managed Redis (versão prévia)	Porta do servidor Redis
accessKey	string	""	Senha do servidor Redis quando a autorização do Redis está habilitada. O valor é uma cadeia de caracteres vazia por padrão, o que significa que o provedor de estado de sessão não usa nenhuma senha quando se conecta ao servidor Redis. Se o servidor Redis estiver em uma rede publicamente acessível, como o Cache do Azure para Redis, lembre-se de habilitar a autorização do Redis para aprimorar a segurança e de fornecer uma senha segura.
ssl	booleano	false	Indica se a conexão ao servidor Redis será feita via TLS. Esse valor é false por padrão porque o Redis não dá suporte ao TLS por padrão. Se você estiver usando o Cache do Azure para Redis, que dá suporte ao SSL por padrão, lembre-se de definir esse valor como true para aprimorar a segurança. A porta não TLS é desabilitada por padrão para novos caches. Especifique true para que essa configuração use a porta não TLS. Para obter mais informações sobre como habilitar a porta não TLS, confira a seção Portas de Acesso no artigo  Configurar um cache.
databaseIdNumber	número inteiro positivo	0	Esse atributo só pode ser especificado por meio de web.config ou AppSettings. Especifique o banco de dados Redis a ser usado.
connectionTimeoutInMilliseconds	número inteiro positivo	Fornecido por StackExchange.Redis	Usado para definir ConnectTimeout ao criar StackExchange.Redis.ConnectionMultiplexer.
operationTimeoutInMilliseconds	número inteiro positivo	Fornecido por StackExchange.Redis	Usado para definir SyncTimeout ao criar StackExchange.Redis.ConnectionMultiplexer.
connectionString (cadeia de conexão StackExchange.Redis válida)	string	n/a	Uma referência de parâmetro a AppSettings ou web.config ou uma cadeia de conexão StackExchange.Redis válida. Esse atributo pode fornecer valores para host, port, accessKey, ssl e outros atributos de StackExchange.Redis. Para obter uma análise mais detalhada de connectionString, confira Como definir connectionString na seção Observações sobre o atributo.
settingsClassName settingsMethodName	string string	n/a	Esses atributos só podem ser especificados por meio de web.config ou AppSettings. Use-os para fornecer uma cadeia de conexão. _settingsClassName* deve ser um nome de classe qualificado do assembly que contém o método especificado por settingsMethodName. O método especificado por settingsMethodName deve ser público, estático e nulo (não aceitar parâmetros), com o tipo de retorno string. Esse método retorna a cadeia de conexão real.
loggingClassName loggingMethodName	string string	n/a	Esses atributos só podem ser especificados por meio de web.config ou AppSettings. Use esses atributos para depurar seu aplicativo fornecendo logs do Cache de Saída/Estado de Sessão com os logs de StackExchange.Redis. loggingClassName deve ser um nome de classe de assembly qualificado que contenha o método especificado por loggingMethodName. O método especificado por loggingMethodName deve ser público, estático e nulo (não aceitar parâmetros), com o tipo de retorno System.IO.TextWriter.
applicationName	string	O nome do módulo do processo atual ou "/"	Somente SessionStateProvider Esse atributo só pode ser especificado por meio de web.config ou AppSettings. O prefixo do nome do aplicativo a ser usado no Cache Redis. O cliente pode usar o mesmo cache Redis para fins diferentes. Para garantir que as chaves de sessão não colidam, elas podem ser prefixadas com o nome do aplicativo.
throwOnError	booleano	true	Somente SessionStateProvider Esse atributo só pode ser especificado por meio de web.config ou AppSettings. Indica se uma exceção será gerada em caso de erro. Para obter mais informações sobre throwOnError, confira Observações sobre throwOnError na seção Observações sobre o atributo.
retryTimeoutInMilliseconds	número inteiro positivo	5.000	Somente SessionStateProvider Esse atributo só pode ser especificado por meio de web.config ou AppSettings. A duração de novas tentativas em caso de falha de uma operação. Se esse valor for menor que operationTimeoutInMilliseconds, o provedor não tentará novamente. Para obter mais informações sobre retryTimeoutInMilliseconds, confira Observações sobre retryTimeoutInMilliseconds na seção Observações sobre o atributo.
redisSerializerType	string	n/a	Especifica o nome de tipo de assembly qualificado de uma classe que implementa Microsoft.Web.Redis. Serializer que contém a lógica personalizada usada para serializar e desserializar os valores. Para obter mais informações, confira Sobre redisSerializerType na seção Observações sobre o atributo.

Observações sobre o atributo

Como definir connectionString

O valor de connectionString é usado como chave para buscar a cadeia de conexão real em AppSettings, caso essa cadeia de caracteres exista nele. Se não for encontrado dentro do AppSettings, o valor de connectionString será usado como chave para buscar a cadeia de conexão real da seção ConnectionString web.config, se essa seção existir. Se a cadeia de conexão não existir no AppSettings ou na seção ConnectionString web.config, o valor literal de connectionString será usado como a cadeia de conexão ao criar StackExchange.Redis.ConnectionMultiplexer.

Os exemplos a seguir ilustram como connectionString é usada.

Exemplo 1

<connectionStrings>
    <add name="MyRedisConnectionString" connectionString="mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False" />
</connectionStrings>

Em web.config, use a chave como valor de parâmetro em vez de valor real.

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             connectionString = "MyRedisConnectionString"/>
    </providers>
</sessionState>

Exemplo 2

<appSettings>
    <add key="MyRedisConnectionString" value="mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False" />
</appSettings>

Em web.config, use a chave como valor de parâmetro em vez de valor real.

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             connectionString = "MyRedisConnectionString"/>
    </providers>
</sessionState>

Exemplo 3

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             connectionString = "mycache.redis.cache.windows.net:6380,password=actual access key,ssl=True,abortConnect=False"/>
    </providers>
</sessionState>

Observações sobre throwOnError

Atualmente, se ocorre um erro durante uma operação de sessão, o provedor de estado de sessão gera uma exceção. A aplicação da exceção desliga o aplicativo.

Esse comportamento foi modificado de uma forma que dá suporte às expectativas dos usuários existentes do provedor de estado de sessão ASP.NET, permitindo também que você atue sobre exceções. O comportamento padrão ainda gera uma exceção quando ocorre um erro, de maneira consistente com outros provedores de estado de sessão ASP.NET. O código existente deve funcionar da mesma forma que antes.

Se você definir throwOnError como false, em vez de gerar uma exceção quando ocorrer um erro, ele falhará silenciosamente. Para ver se houve um erro e, em caso afirmativo, descobrir qual foi a exceção, verifique a propriedade estática Microsoft.Web.Redis.RedisSessionStateProvider.LastException.

Observações sobre retryTimeoutInMilliseconds

A configuração retryTimeoutInMilliseconds fornece alguma lógica para simplificar o caso em que uma operação de sessão deve tentar novamente em caso de falha devido a uma falha de rede ou outro motivo. A configuração retryTimeoutInMilliseconds também permite que você controle o tempo de repetir ou escolha não repetir.

Se você definir retryTimeoutInMilliseconds para um número, por exemplo, 2000, quando uma operação de sessão falhar, ela tentará novamente por 2.000 milissegundos antes de tratá-la como um erro. Para que o provedor de estado de sessão aplique essa lógica de repetir, basta configurar o tempo limite. A primeira repetição ocorrerá após 20 milissegundos, o que é suficiente na maioria dos casos em que ocorre uma falha de rede. Depois disso, ele repetirá a operação a cada segundo até atingir o tempo limite. Logo após o tempo limite, ele repetirá a operação mais uma vez para garantir que não cortará o tempo limite por (no máximo) um segundo.

Se você não achar que precisa tentar novamente ou se quiser lidar com a lógica de repetir por conta própria, defina retryTimeoutInMilliseconds como 0. Por exemplo, talvez você não queira tentar novamente quando estiver executando o servidor Redis no mesmo computador que seu aplicativo.

Sobre redisSerializerType

A serialização usada para armazenar os valores no Redis é feita em um formato binário por padrão, que é fornecido pela classe BinaryFormatter. Use redisSerializerType para especificar o nome de tipo de assembly qualificado de uma classe que implemente Microsoft.Web.Redis.ISerializer e tenha a lógica personalizada para serializar e desserializar os valores. Por exemplo, esta é uma classe de serializador Json usando JSON.NET:

namespace MyCompany.Redis
{
    public class JsonSerializer : ISerializer
    {
        private static JsonSerializerSettings _settings = new JsonSerializerSettings() { TypeNameHandling = TypeNameHandling.All };

        public byte[] Serialize(object data)
        {
            return Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(data, _settings));
        }

        public object Deserialize(byte[] data)
        {
            if (data == null)
            {
                return null;
            }
            return JsonConvert.DeserializeObject(Encoding.UTF8.GetString(data), _settings);
        }
    }
}

Supondo que essa classe seja definida em um assembly com o nome MyCompanyDll, você pode definir o parâmetro redisSerializerType para usá-lo:

<sessionState mode="Custom" customProvider="MySessionStateStore">
    <providers>
        <add type = "Microsoft.Web.Redis.RedisSessionStateProvider"
             name = "MySessionStateStore"
             redisSerializerType = "MyCompany.Redis.JsonSerializer,MyCompanyDll"
             ... />
    </providers>
</sessionState>

Diretiva de cache de saída

Adicione uma diretiva OutputCache a cada página da qual você deseja armazenar a saída em cache.

<%@ OutputCache Duration="60" VaryByParam="*" %>

No exemplo anterior, os dados da página em cache permaneceram no cache por 60 segundos, e outra versão da página foi armazenada em cache para cada combinação de parâmetros. Para saber mais sobre a diretiva OutputCache, consulte @OutputCache.

Após a conclusão dessas etapas, seu aplicativo será configurado para usar o Provedor de Cache de Saída Redis.

Provedores de cache de saída de terceiros

• NCache
• Apache Ignite

Conteúdo relacionado

Consulte Provedor de Estado de Sessão ASP.NET para o Cache Redis do Azure.