How to: Prepare Visual Studio to Use Azure In-Role Cache

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 explains how to prepare a Visual Studio project to use Microsoft Azure Cache. This includes the following tasks:

  • Verify that the correct version of the .NET Framework is targeted.

  • Reference the caching assemblies.

After these tasks, you can configure your cache client in the dataCacheClient section of the application or web.config files. This enables you to use the caching methods in the Microsoft.ApplicationServer.Caching namespace.

Warning

You should not install Microsoft AppFabric 1.1 for Windows Server and Microsoft Azure Cache on the same machine. This includes both the product and the SDK. It is possible to mistakenly reference some of the Microsoft AppFabric 1.1 for Windows Server assemblies in the Global Assembly Cache. This could lead to incorrect or unexpected behavior.

To target the correct version of the .NET Framework

  1. Open your Visual Studio project.

  2. In Solution Explorer, right-click the project name and then select Properties.

  3. For a Visual C# project, use the following steps:

    1. Select the Application tab of the Project Properties dialog.

    2. Verify that the target framework version is .NET Framework 2.0 or higher (non-client profile).

  4. For a Visual Basic project, use the following steps:

    1. Select the Compile section of the Project Properties page.

    2. At the bottom of the Compile page, click the Advanced Compile Options button.

    3. Verify that the target framework version is .NET Framework 2.0 or higher (non-client profile).

Important

Do not use the client profile for the target framework version. In Visual Studio, select .NET Framework versions that do not specify "Client Profile".

Configure a Project for Caching on Roles

To add the assembly references, you must have the Azure SDK installed on your machine. For instructions, see Azure SDK Download.

The following steps use a NuGet package to add the necessary assembly references and configuration changes. These steps are specific to using In-Role Cache that is hosted on a Azure role in the same deployment.

  1. In Solution Explorer, right-click on the project name, and then select Add Library Package Reference (NuGet 1.2) or Manage NuGet Packages (NuGet 2.0 or higher).

  2. In the left pane, select the Online category.

  3. Search for WindowsAzure.Caching.

  4. Install the In-Role Cache package named Microsoft.WindowsAzure.Caching (NuGet 1.2) or Azure Caching (NuGet 2.0 or higher).

    Screenshot of Caching Preview Package (NuGet 1.2)

    Screenshot of Caching Preview Package (NuGet 2.0)

In addition to adding the appropriate assembly references, this package also modifies the configuration file (app.config or web.config) for the targeted project. It adds a boilerplate dataCacheClient section similar to the following.

<dataCacheClients>
  <dataCacheClient name="default">
    <autoDiscover isEnabled="true" identifier="[cache cluster role name]" />
    <!--<localCache isEnabled="true" sync="TimeoutBased" objectCount="100000" ttlValue="300" />-->
  </dataCacheClient>
</dataCacheClients>

The final step is to change the identifier attribute from "[cache cluster role name]" to the actual name of the role that has In-Role Cache enabled. In a co-located topology, this could be the same role, such as "WebRole1". In a dedicated topology, this could be a different role, such as "CacheWorkerRole1". For samples of both topologies, see Azure In-Role Cache Samples.

Note

Uninstalling the NuGet package does not remove the dataCacheClients section if that section has been customized. It must be removed manually.

The NuGet package adds references to the following assemblies:

  • Microsoft.ApplicationServer.Caching.AzureClientHelper

  • Microsoft.ApplicationServer.Caching.AzureCommon

  • Microsoft.ApplicationServer.Caching.Client

  • Microsoft.ApplicationServer.Caching.Core

  • Microsoft.Web.DistributedCache

  • Microsoft.WindowsFabric.Common

  • Microsoft.WindowsFabric.Data.Common

Note

It is possible to manually reference these assemblies without the NuGet package. By default, they are installed to C:\Program Files\Microsoft SDKs\Azure\.NET SDK&lt;current version>\ref\Caching.

See Also

Concepts

Develop for Azure In-Role Cache
ASP.NET 4 Cache Providers for Azure In-Role Cache