This documentation is archived and is not being maintained.

Migrate from AppFabric Caching to Azure Managed Cache Service

Updated: August 25, 2015

ImportantImportant
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?

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.

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.

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.

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

noteNote
Each offering differs in terms of pricing and features. For more information see Cache Service Pricing FAQ. Additional details are also provided in the following Configure the Cache section in this migration guide.

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.

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

WarningWarning
It is not supported to install both AppFabric and the Azure SDK on the same development machine. These steps assume that you are using separate machines or that you completely uninstall AppFabric before installating the Azure SDK.

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

ImportantImportant
Once a Managed Cache Service instance is created using the PowerShell cmdlets it can be viewed and configured in the Azure Management Portal.

  1. Open an Azure PowerShell command window.

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

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

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.

Named Caches in Windows Azure Cache Service

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

 

Get-CacheConfig setting Managed Cache Service setting

CacheName

Name

TimeToLive

Time (min)

Secondaries (0, 1)

High Availability (0 = Disabled, 1 = Enabled)

IsExpirable (True, False)

Expiry Policy (True = Absolute, False = Never)

Managed Cache Service has a third expiration policy called Sliding, where the timeout interval for an item resets each time the item is accessed.

EvictionType (None, LRU)

Expiry Policy (None = Disabled, LRU = Enabled)

NotificationsEnabled (True, False)

Notifications (True = Enabled, False = Disabled)

noteNote
Any AppFabric caching settings that are not listed here are not supported in Microsoft Azure Cache.

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.

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

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

ImportantImportant
Before configuring the cache client using the Managed Cache Service NuGet package, ensure that the Microsoft AppFabric 1.1 for Windows Server configuration is completely removed from the web.config or app.config of the client project, as described in the previous section.

ImportantImportant
These steps require the latest 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.

noteNote
If Azure Caching does not appear in the list, type WindowsAzure.Caching into the Search Online text box.

Windows Azure Cache NuGet Package

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.

    Endpoint URL for Windows Azure Cache Service
    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.

    Manage Access Keys for Windows Azure Cache Service 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.

    WarningWarning
    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>
noteNote
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

noteNote
Managed Cache Service and Microsoft AppFabric 1.1 for Windows Server 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 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.

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.

Show: