Migrate from In-Role Cache to Azure Managed Cache Service
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
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. If the following example, a Basic 128MB cache is created with namecontosocache
, in theSouth 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
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.
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.
Right-click the cache worker role in the Roles folder in the cloud services project in Solution Explorer and choose Remove.
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.
Right-click the role in the cloud services project in Solution Explorer and choose Properties.
Switch to the Caching tab, uncheck the Enable Caching checkbox, and press CTRL+S to save.
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..
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 theconfigSections
element. Do not remove the entireconfigSections
element; just remove thedataCacheClients
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. ThedataCacheClients
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.
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.
Two sections are added to
configSections
, nameddataCacheClients
andcacheDiagnostics
.<!-- 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 theconfiguration
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.
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.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.
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>
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 theidentifier
attribute. The endpoint URL is displayed on the Cache Dashboard in the Management Portal.
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.
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