Migrate from Azure Shared Caching to In-Role Cache
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 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.
Note
For more information about the benefits of using In-Role Cache, see About In-Role Cache for Azure 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.
Cache Cluster Deployment Topology | Description |
---|---|
Dedicated Role caching |
Worker role instances are used exclusively for caching. |
Co-located Role caching |
The cache shares the VM resources (bandwidth, CPU, and memory) with the primary application hosted by the role. |
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.
Note
Dedicated role caching is only supported on worker roles and cannot be configured on web roles.
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.
Important
If this storage account is not configured the roles will fail to start.
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.
Feature | In-Role Cache Support | Microsoft Azure Shared Caching Support |
---|---|---|
Name |
A default cache is configured, and additional named caches can be configured if desired. |
Default cache only. |
High Availability |
Provides high availability for items in the cache. If one role goes down, a backup copy of the items in the cache are still available. |
No high availability. |
Notifications |
Notifications allow your application to receive asynchronous notifications when various cache operations occur on the cache cluster. For more information, see Notifications in Azure In-Role Cache |
Not supported. |
Eviction Policy |
Choices are LRU (last recently used), or None. The default is LRU. |
LRU only. |
Time to live (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. |
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. |
Expiration Type |
There are three types of Expiration Type: None, Absolute, and Sliding Window. When Absolute is specified, the expiration interval specified by Time to Live (min) begins when items are added to the cache. When Sliding Window is specified, the interval is reset each time an item is accessed in the cache. When None is specified, Time To Live (min) must be set to 0, and items will not expire. The default is Absolute. For more information, see Expiration and Eviction in Azure In-Role Cache. |
The expiration policy is absolute. The expiration interval begins when items are added to the cache. |
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.
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 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 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"> <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 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>
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.
Important
Before configuring the cache client using the In-Role Cache NuGet package, ensure that the Shared Caching configuration is completely removed from the web.config
or app.config
of the client role, as described in the previous section.
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.
Note
If Azure Caching does not appear in the list, type WindowsAzure.Caching into the Search Online text box.
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.
Two sections are added to
configSections
, nameddataCacheClients
andcacheDiagnostics
.<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>
A
dataCacheClients
section is added to theconfiguration
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 withCacheWorkerRole1
.<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
.A
cacheDiagnostics
section is also added to theconfiguration
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>
Note
For more information about cache diagnostic levels, see Azure In-Role Cache Troubleshooting and Diagnostics.
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
Note
In-Role Cache and Microsoft Azure 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 In-Role Cache NuGet package will remove the Shared Caching assembly references and add the correct In-Role Cache assembly references. The In-Role Cache assemblies are located in the C:\Program Files\Microsoft SDKs\Azure\.NET SDK\2012-10\ref\Caching
folder.
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
.
Note
If your ASP.NET web role was already configured to use the Session State Provider for Microsoft Azure Cache then this section is already present.
<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
.
Note
If your ASP.NET web role was already configured to use the Output Cache Provider for Microsoft Azure Cache then this section is already present.
<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.