Migrate from AppFabric Caching to Azure Managed Cache Service

This topic describes how to migrate from Microsoft AppFabric 1.1 for Windows Server to Azure Managed Cache Service. This type of caching migration might take place when you move an on-premises application to Azure.

AppFabric supports on-premises cache clusters the use your own servers and network infrastructure. The move to Azure is facilitated by the fact that most of the features and programming model of AppFabric are shared with Managed Cache Service.

• Plan for Migration

  • Analyze the AppFabric Cache Cluster

  • Choose a Cache Offering

• Recreate the Cache Cluster using Cache Service

  • Create a Cache

  • Configure the Cache

• Configure the Cache Clients

  • Install the Caching NuGet Package

  • Migrate Application Code

Plan for Migration

Before you migrate your cache-enabled application to the cloud, first review the differences between AppFabric and Microsoft Azure Cache. If you require a feature, such as read-through or write-behind, that is not available in Microsoft Azure Cache, you must redesign that part of your solution in order to successfully move to Azure.

• Analyze the AppFabric Cache Cluster

• Choose a Cache Offering

Analyze the AppFabric Cache Cluster

All of the caches and their relevant settings must be recreated on in Managed Cache Service. The first step is to analyze the AppFabric cache cluster to understand the current on-premises configuration.

1. On the AppFabric cache cluster, open a Caching Administration Windows PowerShell command prompt.

2. Run the Get-Cache command without any parameters. This lists the named caches.

3. For each cache listed, run the Get-CacheConfig command. Pass the cache name as an argument to this command. Record the configuration settings for each cache. The following shows an example of this output.

   PS C:\Windows\system32> Get-CacheConfig TestCache
   
   CacheName                : TestCache
   TimeToLive               : 20 mins
   CacheType                : Partitioned
   Secondaries              : 0
   MinSecondaries           : 0
   IsExpirable              : True
   EvictionType             : None
   NotificationsEnabled     : True
   WriteBehindEnabled       : False
   WriteBehindInterval      : 300
   WriteBehindRetryInterval : 60
   WriteBehindRetryCount    : -1
   ReadThroughEnabled       : False
   ProviderType             :
   ProviderSettings         : {}
   

4. Run the Get-CacheHost command to see a list of cache hosts in the cache cluster.

5. For each cache host, run the Get-CacheHostConfig command. Pass the required arguments, the name of the cache host and the caching port (typically 22233). Record the Size parameter for each cache host.

6. Add the Size values for all cache hosts to determine the overall size of the cache cluster. This Size can be used as a starting point when determining the cache offering and capacity when creating a new cache in Managed Cache Service.

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

Most of the cache features of Microsoft AppFabric 1.1 for Windows Server are available in Managed Cache Service (with the exception of read-through and write-behind), but not all Managed Cache Service features are available in all Managed Cache Service cache offerings. If your application uses notifications or high availability you should chose the either the Standard or 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 of your Microsoft AppFabric 1.1 for Windows Server caches, as described in Analyze the AppFabric Cache Cluster. 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.

Recreate the Cache Cluster using Cache Service

To recreate the Microsoft AppFabric 1.1 for Windows Server cache cluster using Managed Cache Service, perform the following steps.

• Create a Cache

• Configure the Cache

Create a Cache

Cache instances in Managed Cache Service are created using PowerShell scripts.

To create a Managed Cache Service instance

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.

   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.

   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 Microsoft AppFabric 1.1 for Windows Server 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.

The following table correlates the output from Get-CacheConfig to the settings in the caching window.

Remove the AppFabric Caching Configuration

Before the client applications can be configured for Managed Cache Service, the existing Microsoft AppFabric 1.1 for Windows Server configuration and assembly references must be removed.

To manually remove the Microsoft AppFabric 1.1 for Windows Server configuration you must remove the Microsoft AppFabric 1.1 for Windows Server assembly references and the Microsoft AppFabric 1.1 for Windows Server configuration from app.config or web.config.

To remove the Microsoft AppFabric 1.1 for Windows Server 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 Microsoft AppFabric 1.1 for Windows Server 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 the Cache Clients

Once the new cache is created and configured, the cache clients can be configured to use the cache.

• Install the Caching NuGet Package

• Migrate Application Code

Install the Caching NuGet Package

Microsoft Azure Cache provides a NuGet package to add the necessary configuration and assembly references to allow cache clients to access a cache.

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.

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.

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

   <!-- 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 which is displayed on the Cache Dashboard in the Management Portal.

   
   In this example, the cache is named applicationcache, and the endpoint 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.

   The sslEnabled attribute configures whether communication between the cache client and the cache is encrypted using SSL. For more information about using the sslEnabled attribute, see Securing Communications between Cache Clients and the Cache.

   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>

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

Migrate Application Code

The final step is to move any application code to use Managed Cache Service. Note that the namespace and many of the APIs remain the same and minimal changes should be required. For more information, see Differences between On-Premises AppFabric 1.1 Caching and Azure Managed Cache Service.