This documentation is archived and is not being maintained.

Regions and Tagging in Azure In-Role Cache

Updated: August 25, 2015

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?

In-Role Cache supports the creation and use of user-defined regions. This feature is available to caches that reside on role-based In-Role Cache. A region is a subgroup for cached items. Regions also support the annotation of cached items with additional descriptive strings called tags. Regions support the ability to perform search operations on any tagged items in that region.

Regions are optional; if you want to use them, explicitly create them in code with the CreateRegion method. After a region is created, you can add tags to objects that are inserted into the region. There are overloads on the Add and Put methods which accept a region name. To search a region for objects with a given tag, use the methods GetObjectsByTag, GetObjectsByAnyTag, and GetObjectsByAllTags.

Because of architectural requirements of the search functionality, objects in a region are limited to a single cache server. In a Azure deployment, this means that the entire region resides on a single server. If high availability is enabled, a backup of the region exists on a different server. In Azure these servers are virtual machines instances of the role that hosts In-Role Cache. This behavior differs from the scenario where regions are not used. In that scenario, new items in distributed in-memory cache are placed on any of the available cache servers.

A region must exist as a single entity on one of the cache servers. Therefore, the amount of caching memory available on any single role instance must be greater than the largest anticipated region. Potentially use multiple smaller regions to realize the benefits of regions and tagging as well as the advantages of the distributed cache.

The following example shows how to create a region named Test.

DataCache cache = new DataCache("default");

The following example shows how to add three objects to the Test region with tags.

List<DataCacheTag> tagList1 = new List<DataCacheTag>()
    new DataCacheTag("Tag1"),
    new DataCacheTag("Tag2")
List<DataCacheTag> tagList2 = new List<DataCacheTag>()
    new DataCacheTag("Tag3")
cache.Put("Key1", "Value1", tagList1, "Test");
cache.Put("Key2", "Value2", tagList1, "Test");
cache.Put("Key3", "Value3", tagList2, "Test");

The following example shows how to search the Test region for all objects that have the Tag1 tag.

foreach (KeyValuePair<string, object> result in 
    cache.GetObjectsByTag(new DataCacheTag("Tag1"), "Test"))
    string keyValue = result.Key;
    string objectValue = result.Value.ToString();

See Also