ASP.NET Output Cache Provider for Azure Cache for Redis

The Redis Output Cache Provider is an out-of-process storage mechanism for output cache data. This data is specifically for full HTTP responses (page output caching). The provider plugs into the new output cache provider extensibility point that was introduced in ASP.NET 4.

For ASP.NET Core applications, see Output Caching in ASP.NET core using Redis in .NET 8.

To use the Redis Output Cache Provider, first configure your cache, and then configure your ASP.NET application using the Redis Output Cache Provider NuGet package. This article provides guidance on configuring your application to use the Redis Output Cache Provider. For more information about creating and configuring an Azure Cache for Redis instance, see Create a cache.

Store ASP.NET core page output in Redis

For a full feature specification, see ASP.NET core output caching.

For sample application demonstrating the usage, see .NET 8 Web Application with Redis Output Caching and Azure Open AI.

Store ASP.NET page output in Redis

To configure a client application in Visual Studio using the Azure Cache for Redis Session State NuGet package, select NuGet Package Manager, Package Manager Console from the Tools menu.

Run the following command from the Package Manager Console window:

Install-Package Microsoft.Web.RedisOutputCacheProvider

The Redis Output Cache Provider NuGet package has a dependency on the StackExchange.Redis package. If the StackExchange.Redis package isn't present in your project, it gets installed. For more information about the Redis Output Cache Provider NuGet package, see the RedisOutputCacheProvider NuGet page.

The NuGet package downloads and adds the required assembly references and adds the following section into your web.config file. This section contains the required configuration for your ASP.NET application to use the Redis Output Cache Provider.

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

Configure the attributes in the first column with the values from your cache in the Microsoft Azure portal. Also, configure the other values you want. For instructions on accessing your cache properties, see Configure Azure Cache for Redis settings.

Attribute notes

Setting connectionString

The value of connectionString is used as key to fetch the actual connection string from AppSettings, if such a string exists in AppSettings. If not found inside AppSettings, the value of connectionString is used as key to fetch actual connection string from the web.config ConnectionString section, if that section exists. If the connection string doesn't exist in AppSettings or the web.config ConnectionString section, the literal value of connectionString is used as the connection string when creating StackExchange.Redis.ConnectionMultiplexer.

The following examples illustrate how connectionString is used.

Example 1

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

In web.config, use the key as parameter value instead of actual value.

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

Example 2

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

In web.config, use the key as parameter value instead of actual value.

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

Example 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>

Notes on throwOnError

Currently, if an error occurs during a session operation, the session state provider throws an exception. Throwing the exception shuts down the application.

This behavior was modified in a way that supports the expectations of existing ASP.NET session state provider users while also allowing you to act on exceptions. The default behavior still throws an exception when an error occurs, consistent with other ASP.NET session state providers. Existing code should work the same as before.

If you set throwOnError to false, then instead of throwing an exception when an error occurs, it fails silently. To see if there was an error and, if so, discover what the exception was, check the static property Microsoft.Web.Redis.RedisSessionStateProvider.LastException.

Notes on retryTimeoutInMilliseconds

The retryTimeoutInMilliseconds setting provides some logic to simplify the case where a session operation should retry on failure because of a network glitch or something else. The retryTimeoutInMilliseconds setting also allows you to control the retry timeout or to completely opt out of retry.

If you set retryTimeoutInMilliseconds to a number, for example 2000, when a session operation fails, it retries for 2,000 milliseconds before treating it as an error. To have the session state provider apply this retry logic, just configure the timeout. The first retry will happen after 20 milliseconds, which is sufficient in most cases when a network glitch happens. After that, it will retry every second until it times out. Right after the time-out, it will retry one more time to make sure that it won’t cut off the timeout by (at most) one second.

If you don’t think you need retry or if you want to handle the retry logic yourself, set retryTimeoutInMilliseconds to 0. For example, you might not want retry when you're running the Redis server on the same machine as your application.

About redisSerializerType

The serialization to store the values on Redis is done in a binary format by default, which is provided by the BinaryFormatter class. Use redisSerializerType to specify the assembly qualified type name of a class that implements Microsoft.Web.Redis.ISerializer and has the custom logic to serialize and deserialize the values. For example, here's a Json serializer class using 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);
        }
    }
}

Assuming this class is defined in an assembly with name MyCompanyDll, you can set the parameter redisSerializerType to use it:

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

Output cache directive

Add an OutputCache directive to each page for which you wish to cache the output.

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

In the previous example, the cached page data remains in the cache for 60 seconds, and a different version of the page is cached for each parameter combination. For more information about the OutputCache directive, see @OutputCache.

After you do these steps, your application is configured to use the Redis Output Cache Provider.

Third-party output cache providers

• NCache
• Apache Ignite

Related content

Check out the ASP.NET Session State Provider for Azure Cache for Redis.