VERKOOP: 1-800-867-1389
EN
Deze inhoud is niet beschikbaar in uw taal, maar wel in het Engels.

# Migrate from Azure Shared Caching to In-Role Cache

Updated: July 17, 2010

Note
For guidance on choosing the right Azure Cache offering for your application, 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

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

In-Role Cache provides the ability to host caching services on 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

To configure a dedicated role cache cluster, add a cache worker role to your project. To add a cache worker role, expand the 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 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  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 In-Role Cache (Azure 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  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 In-Role Cache (Azure 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 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.

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-Role Cache for Azure 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

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

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

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.

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 In-Role Cache Troubleshooting and Diagnostics (Azure Cache).

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

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.

Vindt u dit nuttig?
(1500 tekens resterend)
Bedankt voor uw feedback

Toevoegen
Weergeven: