Dedicated topology

In the dedicated topology, you define a worker role that is dedicated to Caching. This means that all of the worker role's available memory is used for the Caching and operating overhead.

The following diagram shows Caching in a dedicated topology. The cloud service shown has three roles: Web1, Worker1, and Cache1. There are two running instances of each role. In this example, the cache is distributed across all instances of the dedicated Cache1 role.

A dedicated topology has the advantage of scaling the caching tier independently of any other role in the cloud service.^[5] For the best Caching performance, a dedicated topology is recommended because the role instances do not share their resources with other application code and services.^[3]

Co-located topology

In a co-located topology, you use a percentage of available memory on existing web or worker roles for Caching.^[4]

The following diagram shows Caching in a co-located topology. The cloud service has two roles: Web1 and Worker1. There are two running instances of each role. In this example, the cache is distributed across all instances of the Web1 role. Because this role also hosts the web front-end for the cloud service, the cache is configured to use only a percentage of the physical memory on each instance of the Web1 role.

A co-located cache is a cost-effective way to make use of existing memory on a role within a cloud service.^[4]

Configuration example

In Visual Studio, Caching is configured in the Caching tab of the properties of the role that hosts Caching.^[6] This makes underlying changes to the ServiceConfiguration.cscfg file.^[7] These settings determine the topology used (dedicated or co-located) and the number of named caches^[8] and their settings.

Other roles must be configured to use Caching.^[9] One way to do this is with a NuGet package. This includes modifying the web.config to contain a properly configured dataCacheClients^[10] section. The following example dataCacheClients section specifies that the role that hosts Caching is named “CacheWorker1”.

<dataCacheClients>
  <dataCacheClient name="default">
    <autoDiscover isEnabled="true" identifier="CacheWorkerRole1" />
  </dataCacheClient>
</dataCacheClients>

Code examples

Note that the code samples in this section are shown in C#.

When hosting Caching on roles, the DataCache class constructor can be used to specify both the named cache and the dataCacheClient section for the cache client settings. The following code shows how to create a named cache, NamedCache2, using the settings from a dataCacheClient section named customClient.

var cache = new DataCache("NamedCache2", "customClient");

The following method shows how to use the Cache object to retrieve data from the cache. In this example, a user identifier (userid) is the key for the associated user information object. The code first attempts to get this user information from the cache using the userid key. If that does not succeed, the code retrieves the information with a database query and then stores the returned user data in the cache. The next time the same code is run, the user information will be returned from the cache rather than the database. This assumes that the cached data has not been expired or evicted.

dataType GetUserData(string userId) 
{
    dataType data = null;

    // Attempt to retrieve the user data from the cache:
    object dataObject = Cache.Get(userId);

    if (dataObject != null)
       data = (dataType)dataObject;
    else
    {
       // If it doesn't exist in the cache, retrieve it from the database:
       data = GetUserDataFromDatabase("SELECT * FROM users WHERE userId = @userId", userId);

       // Put the returned data in the cache for future requests:
       Cache.Add(userId, data);
    }

    return data;
}

The following method shows how to update data that is already in the cache.

void UpdateUserData(string userId, dataType data) 
{
    // Update the user information in the database:
    result = UpdateUserDataInDatabase(userId, data);
    
    if (result) 
    {
       // If successfully updated, update the cache:
       Cache.Put(userId, data);
    }
}

The following call removes the item from the cache.

Cache.Remove(userId);