Migrate from AppFabric Caching to Azure Managed Cache Service
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?
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.
On the AppFabric cache cluster, open a Caching Administration Windows PowerShell command prompt.
Run the Get-Cache command without any parameters. This lists the named caches.
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 : {}
Run the Get-CacheHost command to see a list of cache hosts in the cache cluster.
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.Add the
Size
values for all cache hosts to determine the overall size of the cache cluster. ThisSize
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
Note
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.
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
Warning
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.
Create a Cache
Cache instances in Managed Cache Service are created using PowerShell scripts.
Important
Once a Managed Cache Service instance is created using the PowerShell cmdlets it can be viewed and configured in the Azure Management Portal.
To create a Managed Cache Service instance
Open an Azure PowerShell command window.
Note
For instructions on installing and using Azure PowerShell, see How to install and configure Azure PowerShell.
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.
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 namecontosocache
, in theSouth 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.
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.
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) |
Note
Any AppFabric caching settings that are not listed here are not supported in Microsoft Azure Cache.
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 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 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.
Important
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.
Important
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.
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.
Two sections are added to
configSections
, nameddataCacheClients
andcacheDiagnostics
.<!-- 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>
A
dataCacheClients
section is added to theconfiguration
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 thesslEnabled
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>
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 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.
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.