How to: Configure a Cache Client for Azure Managed Cache Service

  • Article

Important

Microsoft recommends all new developments use Azure Redis Cache. For current documentation and guidance on choosing an Azure Cache offering, see Which Azure Cache offering is right for me?

Managed Cache Service makes it easy to configure cache clients by providing a NuGet package to add the necessary assembly references and configuration. The Cache NuGet package also provides commented out sections in web.config for web projects to enable the Cache Session State and Page Output Cache providers. This topic provides a walkthrough of configuring cache clients using the Cache NuGet package.

In this topic

  • Configure a Cache Client using the Caching NuGet Package

  • Use the Session State provider in an ASP.NET project

  • Use the Output Cache provider to an ASP.NET project

Configure a Cache Client using the Caching NuGet Package

Configuring Managed Cache Service client applications is easy. Managed Cache Service provides a NuGet package to add the necessary configuration and assembly references to allow cache clients to access a cache.

Note

Managed Cache Service supports Azure Web Sites, Cloud Services, and Virtual Machines client applications. The configuration steps for these different client application types are very similar, with only minor differences. The Cache NuGet package which is provided handles most of these differences automatically, and these differences are described at various points in this topic. For a summary of the differences, see Cache Service Client Application Types.

If you are creating a cloud services application, then download nsure you are using the Azure SDK version 2.1 or higher. If you are creating Azure Web Sites or Virtual Machines client applications, then the Cache NuGet Package installs everything you need to get started.

Important

These steps require NuGet Package Manager version 2.6.40627.9000 or higher. To install the latest NuGet Package Manager, see NuGet Package Manager.

To use the Managed Cache Service NuGet package, right-click the client project in Solution Explorer and choose Manage NuGet Packages.

Select Azure Caching, click Install, and then click I Accept. Once the package is installed to the client project, click Close to close the Manage NuGet Packages window.

Note

If Azure Caching does not appear in the list, type WindowsAzure.Caching into the Search Online text box.

Windows Azure Cache NuGet Package

When the Managed Cache Service NuGet package is installed to a client project, it adds the required configuration and assembly references so the client application can access the cache.

In the web.config or app.config for the client project, several items are added.

  1. Two sections are added to configSections, named dataCacheClients and cacheDiagnostics.

    <!-- Non-cache sections omitted for space -->
  <configSections>
    <section name="dataCacheClients" 
        type="Microsoft.ApplicationServer.Caching.DataCacheClientsSection, Microsoft.ApplicationServer.Caching.Core" 
        allowLocation="true" 
        allowDefinition="Everywhere" />

    <section name="cacheDiagnostics" 
        type="Microsoft.ApplicationServer.Caching.AzureCommon.DiagnosticsConfigurationSection, Microsoft.ApplicationServer.Caching.AzureCommon" 
        allowLocation="true" 
        allowDefinition="Everywhere" />
  </configSections>

  2. A dataCacheClients section is added to the configuration section.

    <!-- Non-cache sections omitted for space -->
  <dataCacheClients>
    <dataCacheClient name="default">
      <!--To use the in-role flavor of Azure Caching, set identifier to be the cache cluster role name -->
      <!--To use the Azure Caching Service, set identifier to be the endpoint of the cache cluster -->
      <autoDiscover
        isEnabled="true" 
        identifier="[Cache role name or Service Endpoint]" />
      <!--<localCache isEnabled="true" sync="TimeoutBased" objectCount="100000" ttlValue="300" />-->
      <!--Use this section to specify security settings for connecting to your cache. 
          This section is not required if your cache is hosted on a role that is a part 
          of your cloud service. -->
      <!--<securityProperties mode="Message" sslEnabled="false">
        <messageSecurity authorizationInfo="[Authentication Key]" />
      </securityProperties>-->
    </dataCacheClient>
  </dataCacheClients>

    Replace [Cache role name or Service Endpoint] with the endpoint URL which is displayed on the Cache Dashboard in the Management Portal.

    Endpoint URL for Windows Azure Cache Service
    In this example, the cache is named applicationcache, and the endpoint URL is applicationcache.cache.windows.net.

    <autoDiscover isEnabled="true" identifier="applicationcache.cache.windows.net" />

    Uncomment the securityProperties section, and replace [Authentication Key] with the authentication key.

    <!--Use this section to specify security settings for connecting to your cache. 
    This section is not required if your cache is hosted on a role that is a part 
    of your cloud service. -->
<!--<securityProperties mode="Message" sslEnabled="false">
  <messageSecurity authorizationInfo="[Authentication Key]" />
</securityProperties>-->

    The authentication key can be found in the Management Portal by clicking Access Keys from the cache dashboard.

    Manage Access Keys for Windows Azure Cache Service

    Warning

    These settings must be configured properly or clients will not be able to access the cache.

For cloud services projects, the Managed Cache Service NuGet package also adds a ClientDiagnosticLevel setting to the ConfigurationSettings of the cache client role in ServiceConfiguration.cscfg. The following example is the WebRole1 section from a ServiceConfiguration.cscfg file with a ClientDiagnosticLevel of 1, which is the default ClientDiagnosticLevel.

<Role name="WebRole1">
  <Instances count="1" />
  <ConfigurationSettings>
    <!-- Other settings omitted for space... -->
    <Setting name="Microsoft.WindowsAzure.Plugins.Caching.ClientDiagnosticLevel" value="1" />
  </ConfigurationSettings>
</Role>

Note

For more information about cache diagnostic levels, see About ClientDiagnosticLevel for Azure Managed Cache Service.

In addition to adding the required configuration, the Managed Cache Service NuGet package also adds the following assembly references.

  • Microsoft.ApplicationServer.Caching.Client.dll

  • Microsoft.ApplicationServer.Caching.Core.dll

  • Microsoft.ApplicationServer.Caching.AzureCommon.dll

  • Microsoft.ApplicationServer.Caching.AzureClientHelper.dll

  • Microsoft.WindowsFabric.Common.dll

  • Microsoft.WindowsFabric.Data.Common.dll

If the project is a web project, the following assembly reference is also added.

  • Microsoft.Web.DistributedCache.dll

Use the Session State provider in an ASP.NET project

The Microsoft Azure Cache session state provider is an out-of-process storage mechanism for ASP.NET applications. This provider enables you to store your session state in a cache rather than in-memory or in a SQL Server database. When you use the Caching NuGet package to enabled caching, it adds a commented out section to enable the Cache Session State provider.

  1. First, configure a cache to use with the ASP.NET provider, as described in the previous Configure a Cache Client using the Caching NuGet Package section.

  2. Remove any existing sessionState element that configures session state caching. Do not remove the commented sessionState section that was added by the NuGet package.

  3. In the web.config file, uncomment the sessionState section.

    <!-- Azure Caching session state provider -->
<!--<sessionState mode="Custom" customProvider="AFCacheSessionStateProvider">
  <providers>
    <add name="AFCacheSessionStateProvider" type="Microsoft.Web.DistributedCache.DistributedCacheSessionStateStoreProvider, Microsoft.Web.DistributedCache" cacheName="default" dataCacheClientName="default" applicationName="AFCacheSessionState"/>
  </providers>
</sessionState>-->

The following list provides optional configuration changes that affect the session state provider.

  • Change the targeted named cache with the cacheName attribute of the add element.

  • Change the source of the cache client settings with the dataCacheClientName attribute of the add element. Set this attribute to the name of an existing dataCacheClient section in the web.config file.

  • Modify the behavior of the cache client by changing the settings in the associated dataCacheClient section. For example, enable compression with the isCompressionEnabled attribute.

    <dataCacheClient name="default" isCompressionEnabled="true">
  <!-- Other cache settings omitted -->
</dataCacheClient>

    For a list of available configuration options, see Cache Client Configuration Settings for Azure Managed Cache Service. Note that the ASP.NET providers for caching do not support binary or custom serialization types. If these serializers are used for session state, the following exception occurs: "Type 'Microsoft.Web.DistributedCache.SerializableSessionStateStoreData' in Assembly 'Microsoft.Web.DistributedCache, Version=101.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' is not marked as serializable"

  • Change the settings for the session state provider. For a list of available configuration options, see ASP.NET Session State Provider Configuration Settings for Azure Managed Cache Service.

Use the Output Cache provider to an ASP.NET project

The Microsoft Azure Cache 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. When you use the Caching NuGet package to enabled caching, it adds a commented out section to enable the Cache Page Output provider.

  1. First, configure a cache to use with the ASP.NET provider, as described in the previous Configure a Cache Client using the Caching NuGet Package section.

  2. Use NuGet to add caching support to your ASP.NET project in Visual Studio.

    Important

    These steps require the latest NuGet Package Manager (version 2.6.40627.9000 or higher). To install the latest NuGet Package Manager, see NuGet Package Manager.

  3. Remove any existing caching element that configures output caching. Do not remove the commented caching section that was added by the NuGet package.

  4. In the web.config file, uncomment the caching section.

        <!-- Azure Caching output caching provider -->
    <!--Uncomment this section to use Azure Caching for output caching-->
    <!--<caching>
      <outputCache defaultProvider="AFCacheOutputCacheProvider">
        <providers>
          <add name="AFCacheOutputCacheProvider" 
            type="Microsoft.Web.DistributedCache.DistributedCacheOutputCacheProvider, Microsoft.Web.DistributedCache"
            cacheName="default"
            dataCacheClientName="default"
            applicationName="AFCacheOutputCache" />
        </providers>
      </outputCache>
    </caching>-->

The following list provides optional configuration changes that affect the output cache provider.

  • Change the targeted named cache with the cacheName attribute of the add element.

  • Change the source of the cache client settings with the dataCacheClientName attribute of the add element. Set this attribute to the name of an existing dataCacheClient section in the web.config file.

  • Modify the behavior of the cache client by changing the settings in the associated dataCacheClient section. For example, enable compression with the isCompressionEnabled attribute.

    <dataCacheClient name="default" isCompressionEnabled="true">

    For a list of available configuration options, see Cache Client Configuration Settings for Azure Managed Cache Service. Note that the ASP.NET providers for caching do not support binary or custom serialization types.

  • Change the settings for the output cache provider. For a list of available configuration options, see ASP.NET Page Output Cache Provider Configuration Settings for Azure Managed Cache Service.