Migrate from Shared Caching to Azure Managed Cache Service

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. In the following example, a Basic 128MB cache is created with name contosocache, in the South Central US geographic region.
   
   
   Windows PowerShell

   Copy

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

   Copy

   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:\>
   

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.

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

  Copy

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

  Copy

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

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.

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.

1. Two sections are added to configSections, named dataCacheClients and cacheDiagnostics.
   
   
   XML

   Copy

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

   Copy

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

   Copy

   <autoDiscover isEnabled="true" identifier="applicationcache.cache.windows.net" />
   

   Uncomment the securityProperties section, and replace [Authentication Key] with the authentication key.
   
   
   XML

   Copy

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

   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.