Migrate from Azure Shared Caching to In-Role Cache

Migrating your applications that use Microsoft Azure Shared Caching to In-Role Cache caching can be accomplished with minimal changes to your application. Because In-Role Cache uses the same API as Shared Caching, existing code that uses Shared Caching to access a cache can be reused to access a In-Role Cache in-role cache. This topic shows how to make the necessary configuration and application changes to migrate your Shared Caching application to use In-Role Cache.

Migration Steps

The following sections describe the steps required to migrate a Microsoft Azure Shared Caching application to use In-Role Cache.

• Determine the Cache Cluster Deployment Topology

  • Configure a Dedicated Role Cache Cluster

  • Configure a Co-located Role Cache Cluster

• Configure the Cache Cluster Storage Account

• Configure the Named Cache Settings

• Configure the Cache Clients

  • Remove the Shared Caching Configuration

  • Configure a Cache Client using the Caching NuGet Package

• Migrate ASP.NET Session and Page Output Caching

Determine the Cache Cluster Deployment Topology

In-Role Cache provides the ability to host caching services on Azure roles. In this model, the cache is part of your Cloud Service. One role within the Cloud Service is selected to host In-Role Cache. The running instances of that role join memory resources to form a cache cluster. This private cache cluster is available only to the roles within the same deployment. There are two deployment topologies for In-Role Cache: dedicated and co-located.

If your application has unutilized memory in its existing roles, then you can configure a co-located role cache cluster on those roles, and utilize that extra memory for caching. If there is not sufficient extra memory in the roles to support a cache cluster, you can scale the roles out, or you can add a cache worker role and configure a dedicated role cache cluster.Azure

• Configure a Dedicated Role Cache Cluster

• Configure a Co-located Role Cache Cluster

Configure a Dedicated Role Cache Cluster

To configure a dedicated role cache cluster, add a cache worker role to your project. To add a cache worker role, expand the Azure in Solution Explorer if it is not already expanded.

Right-click the Roles folder in the Azure project, and choose Add, New Worker Role Project, and choose Cache Worker Role. Type the desired name of the role into the Name box, and click Add.

A cache worker role is preconfigured for dedicated role caching. To view the settings, right-click the newly added role in the Azure Roles folder, and choose Properties.

Switch to the Caching tab to see the caching properties of the cache worker role.

Because this role is a cache worker role, the Enable Caching checkbox is already checked and Dedicated Role caching is selected. The settings for the cache are configured in the Named Cache Settings section. There are some differences in the cache settings between In-Role Cache and Microsoft Azure Shared Caching. These settings are described in the following sections Configure the Cache Cluster Storage Account and Configure the Named Cache Settings.

Switch to the Configuration tab.

The default Instance count is 1 and the default VM size is Small. Modify these settings to match your desired configuration. The Capacity Planning Considerations for Azure In-Role Cache guide can provide guidance on which settings to choose to meet the caching requirements of your application.

Once the cache worker role is added and the virtual machine size and instance count are configured, you can configure the cache as described in the following Configure the Named Cache Settings section.

Configure a Co-located Role Cache Cluster

To configure a co-located role cache cluster, right-click the desired role in the Azure Roles folder, and choose Properties.

Switch to the Caching tab, check the Enable Caching checkbox, and specify the desired caching options. The default configuration allocates 30% of the memory in the role instance for caching. Adjust the Cache Size (%) slider to configure the desired cache size.

A very basic approximation of the formula used to determine the cache size is to multiply the number of role instances by the amount of memory based on the virtual machine size, and then take the specified percentage. Note that this formula is a very basic approximation, and for more information on the settings required to provision a cache of the desired size, see Capacity Planning Considerations for Azure In-Role Cache. If additional role instances or a larger virtual machine size are required to host the cache cluster successfully, they can be configured on the Configuration tab.

Configure the Cache Cluster Storage Account

In-Role Cache requires a Azure storage account. This storage account is used to hold configuration data about the cache cluster that is accessed from all virtual machines that make up the cache cluster. This storage account is specified on the Caching tab of the cache cluster role property page, just above the Named Cache Settings.

Configure the Named Cache Settings

Cache settings are configured in the Named Cache Settings section.

There are some differences in the cache settings between In-Role Cache and Microsoft Azure Shared Caching.

Configure the Cache Clients

Once the cache cluster is configured, the next step is to add the necessary configuration and references so that cache clients can access the cache. In In-Role Cache, the clients can be any roles in the same deployment as the cache cluster. When accessing a co-located role cache cluster, the client can be the role itself that hosts the cache cluster. To configure the cache clients, perform the following steps for each role that accesses the cache.

• Remove the Shared Caching Configuration

• Configure a Cache Client using the Caching NuGet Package

Remove the Shared Caching Configuration

Before the client roles are configured for In-Role Cache, the existing Shared Caching configuration and assembly references must be removed. If Shared Caching was configured using the Shared Caching NuGet package, then the configuration can be removed by uninstalling the Shared Caching NuGet package, otherwise it must be manually removed.

• Uninstall the Shared Caching NuGet Package

• Manually Remove the Shared Caching Configuration

Uninstall the Shared Caching NuGet Package

To uninstall the Shared Caching NuGet package, right-click the desired client role in Solution Explorer and choose Manage NuGet Packages. Select the Installed packages node, and type Caching into the Search installed packages box. Select Azure Shared Caching, click Uninstall, and then click Close.

Uninstalling the Shared Caching NuGet package removes the Shared Caching assemblies and the Shared Caching entries in the app.config or web.config of the client role. Because some customized settings may not be removed when uninstalling the NuGet package, open web.config or app.config and ensure that the following elements are completely removed.

• Ensure that the dataCacheClients entry is removed from the configSections element. Do not remove the entire configSections element; just remove the dataCacheClients entry, if it is present.

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

• Ensure that the dataCacheClients section is removed. The dataCacheClients section will be similar to the following example.

  <dataCacheClients>
    <dataCacheClient name="default">
      <hosts>
        <host name="MyCacheNamespace.cache.windows.net" cachePort="22233" />
      </hosts>
  
      <securityProperties mode="Message">
        <messageSecurity 
          authorizationInfo="Your authorization token will be here.">
        </messageSecurity>
      </securityProperties>
    </dataCacheClient>
  </dataCacheClients>
  

Once the Shared Caching configuration is removed, you can configure the cache client as described in the following Configure a Cache Client using the Caching NuGet Package section.

Manually Remove the Shared Caching Configuration

To manually remove the Shared Caching configuration you must remove the Shared Caching assembly references and the Shared Caching configuration from app.config or web.config.

To remove the Shared Caching assembly references, select the desired client role in Solution Explorer and expand the References folder. For each of the assemblies in the following list, right-click the assembly in the References folder in Solution Explorer and choose Remove. If the client role is a web role, also remove Microsoft.Web.DistributedCache.

• Microsoft.ApplicationServer.Caching.Client

• Microsoft.ApplicationServer.Caching.Core

• Microsoft.WindowsFabric.Common

• Microsoft.WindowsFabric.Data.Common

To remove the Shared Caching configuration, open the web.config or app.config of the client role and remove the following two items.

• Remove the dataCacheClients entry from the configSections element. Do not remove the entire configSections element; just remove the dataCacheClients entry, if it is present.

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

• Remove the dataCacheClients section, which will be similar to the following example.

  <dataCacheClients>
    <dataCacheClient name="default">
      <hosts>
        <host name="MyCacheNamespace.cache.windows.net" cachePort="22233" />
      </hosts>
  
      <securityProperties mode="Message">
        <messageSecurity 
          authorizationInfo="Your authorization token will be here.">
        </messageSecurity>
      </securityProperties>
    </dataCacheClient>
  </dataCacheClients>
  

Once these items are removed, you can follow the steps in the next section to configure your cache client.

Configure a Cache Client using the Caching NuGet Package

In-Role Cache provides a NuGet package to add the necessary configuration and assembly references to allow client roles to access a cache cluster.

To use the In-Role Cache NuGet package, right-click on the desired client role 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 role, click Close to close the Manage NuGet Packages window.

When the In-Role Cache NuGet package is installed to a client role, it adds the required configuration and assembly references so the client role can access the desired cache cluster.

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

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

   <configSections>
     <!-- Existing sections omitted for clarity. -->
     <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.

   <dataCacheClients>
     <dataCacheClient name="default">
       <autoDiscover isEnabled="true" identifier="[cache cluster role name]" />
       <!--<localCache isEnabled="true" sync="TimeoutBased" objectCount="100000" ttlValue="300" />-->
     </dataCacheClient>
   </dataCacheClients>
   

   Replace [cache cluster role name] with the name of the role that hosts the cache cluster. In the following example, [cache cluster role name] has been replaced with CacheWorkerRole1.

   <autoDiscover isEnabled="true" identifier="CacheWorkerRole1" />
   

   Warning

   This setting must be configured properly or clients will not be able to access the cache. If the identifier does not map to a role, a TargetInvocationException will be thrown when the cache is accessed with an inner DataCacheException containing a message similar to the following: The role [cache cluster role name] was not found in the current deployment. If the identifier maps to a role in the deployment that does not host a cache cluster, an InvalidOperationException is thrown with the following message: No Endpoints found.

3. A cacheDiagnostics section is also added to the configuration section.

   <cacheDiagnostics>
     <crashDump dumpLevel="Off" dumpStorageQuotaInMB="100" />
   </cacheDiagnostics>
   

   Note

   Crash dumps for cache clients are disabled by default and are controlled by this section. For more information about caching diagnostics, see Azure In-Role Cache Troubleshooting and Diagnostics.

The In-Role Cache 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 clarity... -->
    <Setting name="Microsoft.WindowsAzure.Plugins.Caching.ClientDiagnosticLevel" value="1" />
  </ConfigurationSettings>
</Role>

In addition to adding the required configuration, the In-Role Cache 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 role is a web role, the following assembly reference is also added.

• Microsoft.Web.DistributedCache.dll

Migrate ASP.NET Session and Page Output Caching

Once your ASP.NET web role clients are migrated from Microsoft Azure Shared Caching to In-Role Cache as described in Configure the Cache Clients, only minimal changes are required to store ASP.NET Session State or Page Output Caching in an in-role cache. To enable storing ASP.NET Session State in the cache, add the following section to system.web in web.config.

<sessionState mode="Custom" customProvider="AppFabricCacheSessionStoreProvider">
  <providers>
    <add name="AppFabricCacheSessionStoreProvider" type="Microsoft.Web.DistributedCache.DistributedCacheSessionStateStoreProvider, Microsoft.Web.DistributedCache" cacheName="default" useBlobMode="true" dataCacheClientName="default" />
  </providers>
</sessionState>

Update cacheName to specify the cache in the cache cluster that holds the session state. Use default to specify the default cache.

To enable storing Page Output Caching in the cache, add the following section to system.web.

<caching>
  <outputCache defaultProvider="DistributedCache">
    <providers>
      <add name="DistributedCache" type="Microsoft.Web.DistributedCache.DistributedCacheOutputCacheProvider, Microsoft.Web.DistributedCache" cacheName="default" dataCacheClientName="default" />
    </providers>
  </outputCache>
</caching>

Update cacheName to specify the cache in the cache cluster that holds the session state. Use default to specify the default cache.

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

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

In this 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 available options, see OutputCache Directive.