Migrate from Shared Caching to Azure Managed Cache Service

Article
11/09/2015

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 applications that use Microsoft Azure Shared Caching to Managed Cache Service can be accomplished with minimal changes to your application. Because Managed Cache Service uses most of the same API as Shared Caching, existing code that uses Shared Caching 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 Shared Caching applications to use Managed Cache Service.

Note

Azure Shared Cache was retired in September of 2014. We recommend moving to Azure Redis Cache but if you want to move your application with no code changes you can move to Managed Cache Service. This topic covers migrating to Managed Cache Service; for guidance on migrating to Azure Redis Cache, see Migrate from Shared Caching to Azure Redis Cache (Preview).

Migration Steps

The following sections describe the steps required to migrate a Microsoft Azure Shared Caching application to use Managed Cache Service.

Choose a Cache Offering
Create a Cache
Configure the Cache
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

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 Shared Caching are available in all three Managed Cache Service offerings, so a starting point for migration is to pick the Managed Cache Service cache offering that matches the size of your Shared Caching account. 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

Open an Azure PowerShell command window.

Note

For instructions on installing and using Azure PowerShell, see How to install and configure Azure PowerShell.
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.
Invoke the New-AzureManagedCache cmdlet and specify the name, region, cache offering, and size for the cache. In 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.

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

Managed Cache Service supports named caches, which provide you the flexibility to configure different cache options for different sets of data. Every 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

The following table lists the differences in the cache settings between Managed Cache Service and Shared Caching.

Feature	Managed Cache Service Support	Shared Caching 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.	Default cache only.
High Availability	Provides high availability for items in the cache. If items are lost due to a failure, backup copies of the items in the cache are still available. 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 and High Availability for Azure Managed Cache Service.	No high availability.
Notifications	Notifications allow your application to receive asynchronous notifications when various cache operations occur in the cache. 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 and Notifications for Azure Managed Cache Service.	Not supported.
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.	LRU only.
Time (min)	The default expiration for items in the cache is 10 minutes, but it is configurable. The expiration time for individual items added to the cache can also be specified using overloads of Add and Put when items are added to the cache. Tim (min) works in conjunction with Expiry Policy to determine when items expire.	The default expiration is 24 hours, and it is not configurable. The expiration time for individual items added to the cache can be configured using overloads of Add and Put when items are added to the cache.
Expiry Policy	There are three types of Expiry Policy: Never, Absolute, and Sliding. When Absolute is specified, the expiration interval specified by Time (min) begins when items are added to the cache. When Sliding is specified, the interval is reset each time an item is accessed in the cache. When None is specified, Time (min) must be set to 0, and items will not expire. The default is Absolute. For more information, see Expiration and Eviction for Azure Managed Cache Service.	The expiration policy is absolute. The expiration interval begins when items are added to the cache.

To configure Managed Cache Service settings to most closely match the default Shared Caching settings, use the following settings.

Expiry Policy set to Absolute
Time (min) set to 1440
Notifications set to Disabled (Configurable for the Standard and Premium cache offerings, always disabled for the Basic cache offering)
High Availability set to Disabled (Configurable for the Standard and Premium cache offerings, always disabled for the Basic cache offering)
Eviction set to Enabled

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

To configure the cache clients, perform the following steps for each cache client.

Remove the Shared Caching Configuration
Configure a Cache Client using the Caching NuGet Package

Remove the Shared Caching Configuration

Before the client applications can be configured for Managed Cache Service, 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 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 Azure Shared Caching, click Uninstall, and then click Close.

Uninstall Shared Caching NuGet Package

Note

If there is no Microsoft Azure Shared Caching NuGet package in the list, then click Close and follow the steps in Manually Remove the Shared Caching Configuration.

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 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">
    <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 cache client project 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 is a web project, 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 cache client project 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

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 Shared Caching configuration is completely removed from the web.config or app.config of the client project, as described in the previous section.

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.

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>

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

Note

Managed Cache Service and Shared Caching 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 Shared Caching 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\Azure\.NET SDK[SDK Version]\ref\Caching folder.

Migrate ASP.NET Session and Page Output Caching

Once your ASP.NET web projects are migrated from Microsoft Azure Shared Caching 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.

Migrate from Shared Caching to Azure Managed Cache Service

Migration Steps

Choose a Cache Offering

Create a Cache

To create a Managed Cache Service instance

Configure the Cache

Configure the Cache Clients

Remove the Shared Caching Configuration

Uninstall the Shared Caching NuGet Package

Manually Remove the Shared Caching Configuration

Configure a Cache Client using the Caching NuGet Package

Migrate ASP.NET Session and Page Output Caching

See Also

Concepts

Other Resources

Additional resources