Migrate from In-Role Cache to 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?

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

Migration Steps

The following sections describe the steps required to migrate an In-Role Cache application to use Managed Cache Service.

  • Choose a Cache Offering

  • Create a Cache

  • Configure the Cache

  • Decommission the In-Role Cache Cluster

  • Configure the Cache Clients

    • Uninstall the In-Role Cache NuGet Package

    • Configure a Cache Client using the Caching NuGet Package

  • Migrate ASP.NET Session and Page Output Caching

Choose a Cache Offering

Managed Cache Service is available in the following three offerings.

  • Basic - Cache in sizes from 128MB to 1GB in 128MB increments, with one default named cache

  • Standard - Cache in sizes from 1GB to 10GB in 1GB increments, with support for notifications, high availability, and up to ten named caches

  • Premium - Cache in sizes from 5GB to 150GB in 5GB increments, with support for notifications, high availability, and up to ten named caches

Note

Each offering differs in terms of pricing and features. For more information see Cache Service Pricing FAQ and Cache Offerings for Azure Managed Cache Service. Additional details are also provided in the following Configure the Cache section in this migration guide.

All of the cache features of In-Role Cache are available in the different cache offerings for Managed Cache Service. If your application uses notifications then you should chose the either the Standard or Basic cache offering. If your cache has high availability enabled then you should choose the Premium cache offering. A starting point for migration is to pick the Managed Cache Service cache offering that has the cache features your application requires, and matches the capacity needs of your In-Role Cache application.

After you deploy the application, you can monitor the performance of your cache and scale up or down depending on the requirements of your application. For more information about monitoring performance and scaling, see Monitor Azure Managed Cache Service and Scale a Cache for Azure Managed Cache Service.

Create a Cache

Cache instances in Managed Cache Service are created using PowerShell scripts.

Important

Once a Managed Cache Service instance is created using the PowerShell cmdlets it can be viewed and configured in the Azure Management Portal.

To create a Managed Cache Service instance

  1. Open an Azure PowerShell command window.

    Note

    For instructions on installing and using Azure PowerShell, see How to install and configure Azure PowerShell.

  2. Invoke the Add-AzureAccount cmdlet, and enter the email address and password associated with your account.

    Note

    If you have configured Azure PowerShell with a certificate for your account then you can skip this step. For more information about connecting Azure PowerShell with your Azure account, see How to install and configure Azure PowerShell.

  3. Invoke the New-AzureManagedCache cmdlet and specify the name, region, cache offering, and size for the cache. If the following example, a Basic 128MB cache is created with name contosocache, in the South Central US geographic region.

    New-AzureManagedCache -Name contosocache -Location "South Central US" -Sku Basic -Memory 128MB

    Note

    For a complete list of parameters and values that can be used when creating a cache, see the New-AzureManagedCache cmdlet documentation.

  4. Once the PowerShell cmdlet is invoked, it can take a few minutes for the cache to be created. After the cache has been created, your new cache has a Running status and is ready for use with default settings, and can be viewed and configure in the Azure Management Portal.

    You can monitor the creation progress in the Azure PowerShell window. Once the cache is ready for use, the New-AzureManagedCache cmdlet will display the cache information, as shown in the following example.

    PS C:\> Add-AzureAccount
VERBOSE: Account "user@domain.com" has been added.
VERBOSE: Subscription "MySubscription" is selected as the default subscription.
VERBOSE: To view all the subscriptions, please use Get-AzureSubscription.
VERBOSE: To switch to a different subscription, please use Select-AzureSubscription.
PS C:\> New-AzureManagedCache -Name contosocache -Location "South Central US" -Sku Basic -Memory 128MB
VERBOSE: Intializing parameters...
VERBOSE: Creating prerequisites...
VERBOSE: Verify cache service name...
VERBOSE: Creating cache service...
VERBOSE: Waiting for cache service to be in ready state...


Name     : contosocache
Location : South Central US
State    : Active
Sku      : Basic
Memory   : 128MB



PS C:\>

Configure the Cache

Both In-Role Cache and Managed Cache Service support named caches, which provide you the flexibility to configure different cache options for different sets of data. Every Managed Cache Service cache has a default named cache, and in the Standard and Premium cache offerings, up to nine additional named caches can be configured. Each named cache has its own individual settings, such as high availability, notifications, and custom eviction and expiration policies. Named cache settings are configured in the Management Portal on the Configure tab for Cache.

Named Caches in Windows Azure Cache Service

While In-Role Cache and Managed Cache Service have the same cache features, there are slight differences which are listed in the following table.

Feature Managed Cache Service Support In-Role Cache Support

Name

A default cache is configured, and in the Standard and Premium cache offerings, up to nine additional named caches can be configured if desired.

A default cache is configured, and additional named caches can be configured.

High Availability

High availability is available in the Standard and Premium cache offerings, and is not available in the Basic cache offering. For more information, see Cache Offerings for Azure Managed Cache Service.

High availability can be enabled for all In-Role Cache topologies.

Notifications

Notifications are available in the Standard and Premium cache offerings, and are not available in the Basic cache offering. For more information, see Cache Offerings for Azure Managed Cache Service.

Notifications can be enabled for all In-Role Cache topologies.

Eviction Policy

Choices are Enabled, which uses a LRU (last recently used) algorithm to determine which items to evict, or Disabled. The default is Enabled.

Choices are LRU (last recently used), or None. The default is LRU.

Time (min)

In Managed Cache Service, the setting is named Time (min).

In In-Role Cache, the setting is named Time to live (min).

Expiry Policy

This setting is named Expiry Policy and it has three possible values: Never, Absolute, and Sliding that correspond to the Expiration Policy settings from In-Role Cache.

This setting is named Expiration Policy and it has three possible values: None, Absolute, and Sliding Window.

To migrate from In-Role Cache to Managed Cache Service, re-create all of the named caches from your In-Role Cache cache cluster in your new Managed Cache Service cache.

Decommission the In-Role Cache Cluster

After configuring the new Managed Cache Service cache, the next step is to remove caching from the role that hosted In-Role Cache. These steps are different depending on the cache cluster topology for the In-Role Cache.

  • Dedicated Role Cache Cluster

  • Co-located Role Cache Cluster

Dedicated Role Cache Cluster

To remove a dedicated role cache cluster, you must remove the cache worker role project from the Visual Studio solution and from the Roles folder in the cloud services project.

  1. Right-click the cache worker role in the Roles folder in the cloud services project in Solution Explorer and choose Remove.

    Remove Cache Worker Role

  2. Right-click the worker role project in Solution Explorer and choose Remove.

Co-located Role Cache Cluster

To disable co-located role caching in a web or worker role, you must uncheck the Caching setting on the Caching tab in the role properties.

  1. Right-click the role in the cloud services project in Solution Explorer and choose Properties.

    Cache Role Properties Menu Item

  2. Switch to the Caching tab, uncheck the Enable Caching checkbox, and press CTRL+S to save.

    Disable Colocated Role Cache Setting

Configure the Cache Clients

Once the cache is created and configured, the next step is to add the necessary configuration and references so that cache clients can access the cache. Managed Cache Service supports the following clients.

  • Azure Web Sites

  • Azure Cloud Services web role and worker role

  • Azure Virtual Machines

Note

If the In-Role Cache project is already using the latest Azure SDK, then all you need to do is update the cache client configuration by skipping the steps below and following the procedure described in Update the Cache Client Configuration to use Cache Service.

If the In-Role Cache project is using Azure SDK 1.8 - 2.0, then you need to remove the Caching NuGet package, remove any remaining cache client configuration, and then install the latest Azure SDK (currently 2.1). After you upgrade the SDK, install and configure the latest Caching NuGet package. To configure the cache clients, perform the following steps for each cache client.

  • Uninstall the In-Role Cache NuGet Package

  • Configure a Cache Client using the Caching NuGet Package

Uninstall the In-Role Cache NuGet Package

Before the client applications can be configured for Managed Cache Service, the existing In-Role Cache configuration and assembly references must be removed. This can be accomplished by uninstalling the caching NuGet package.

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

Note

In the following screenshot, the NuGet package version is 2.1.0.0. If you have this version or higher you can skip this step. You only need to perform this step if the NuGet package version is 1.8. or 2.0..

Uninstall In-Role Cache NuGet Package

Uninstalling the In-Role Cache NuGet package removes the In-Role Cache assemblies and the In-Role Cache entries in the app.config or web.config of the client application. 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" channelOpenTimeout="0">
    <autoDiscover isEnabled="true" identifier="CacheWorker" />
  </dataCacheClient>
</dataCacheClients>

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

Configure a Cache Client using the Caching NuGet Package

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

Important

Before configuring the cache client using the Managed Cache Service NuGet package, ensure that the In-Role Cache configuration is completely removed from the web.config or app.config of the client role, as described in the previous section.

Important

These steps require the latest NuGet Package Manager (version 2.2.* 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 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 primary 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 Manage Keys from the cache dashboard. For more information about access keys and securing cache communications with the sslEnabled attribute, see Security Model for Azure Managed Cache Service.

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

Note

Managed Cache Service and In-Role Cache share the same API, and although the assembly names are the same, the assemblies themselves are different and are in different locations. The Managed Cache Service NuGet package will remove the In-Role Cache assembly references and add the correct Managed Cache Service assembly references. The Managed Cache Service assemblies are located in the C:\Program Files\Microsoft SDKs\Windows Azure\.NET SDK\v2.1\ref\Caching folder.

Update the Cache Client Configuration to use Cache Service

If the In-Role Cache project is already using the latest Azure SDK, then all you need to do is update the cache client configuration to point to the new Managed Cache Service cache.

  1. Open the web.config or app.config of the cache client project and find the dataCacheClients section.

    <!-- Non-cache sections omitted for space -->
  <dataCacheClients>
    <dataCacheClient name="default">
      <!--To use the in-role flavor of Windows Azure Caching, set identifier to be the cache cluster role name -->
      <!--To use the Windows Azure Caching Service, set identifier to be the endpoint of the cache cluster -->
      <autoDiscover
        isEnabled="true" 
        identifier="MyCacheWorkerRole" />
      <!--<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>

  2. In the autoDiscover section, replace the role name of the In-Role Cache cluster with the name of the endpoint URL for the Managed Cache Service cache in the identifier attribute. The endpoint URL 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" />

  3. 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

Migrate ASP.NET Session and Page Output Caching

Once your ASP.NET web projects are migrated from In-Role Cache to Managed Cache Service as described in Configure the Cache Clients, only minimal changes are required to enable storing ASP.NET Session State or Page Output Caching in the 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>

Note

If your ASP.NET web role was already configured to use the Session State Provider for caching then this section is already present, and no changes are required.

Update cacheName to specify the cache 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>

Note

If your ASP.NET web role was already configured to use the Output Cache Provider for caching then this section is already present, and no changes are required.

Update cacheName to specify the cache 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.

See Also

Concepts

Cache Offerings for Azure Managed Cache Service
Capacity Planning for Azure Managed Cache Service
Session State Provider for Azure Managed Cache Service
Page Output Cache Provider for Azure Managed Cache Service

Other Resources

Azure Managed Cache Service