In-Role Cache Role Configuration Settings (ServiceConfiguration.cscfg)


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 the available Microsoft Azure Cache settings in the ServiceConfiguration.cscfg file. These settings specify the configuration of caching on the target role. The role properties dialog in Visual Studio automatically configures these settings when you enable caching. The reference information in this topic is most useful for non-Visual Studio cloud service deployments that want to take advantage of caching.


The following example shows a basic ServiceConfiguration.cscfg file that has caching configured. This example has two named caches, default and NamedCache1. This can serve as an example of the reference sections that follow.

<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="WindowsAzure1" xmlns="" osFamily="3" osVersion="*" schemaVersion="2012-10.1.8">
  <Role name="WebRole1">
    <Instances count="2" />
      <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="UseDevelopmentStorage=true" />
      <Setting name="Microsoft.WindowsAzure.Plugins.Caching.NamedCaches" value="{&quot;caches&quot;:[{&quot;name&quot;:&quot;default&quot;,&quot;policy&quot;:{&quot;eviction&quot;:{&quot;type&quot;:0},&quot;expiration&quot;:{&quot;defaultTTL&quot;:10,&quot;isExpirable&quot;:true,&quot;type&quot;:1},&quot;serverNotification&quot;:{&quot;isEnabled&quot;:false}},&quot;secondaries&quot;:0},{&quot;name&quot;:&quot;NamedCache1&quot;,&quot;policy&quot;:{&quot;eviction&quot;:{&quot;type&quot;:-1},&quot;expiration&quot;:{&quot;defaultTTL&quot;:20,&quot;isExpirable&quot;:true,&quot;type&quot;:2},&quot;serverNotification&quot;:{&quot;isEnabled&quot;:true}},&quot;secondaries&quot;:1}]}" />
      <Setting name="Microsoft.WindowsAzure.Plugins.Caching.ClientDiagnosticLevel" value="1" />
      <Setting name="Microsoft.WindowsAzure.Plugins.Caching.DiagnosticLevel" value="1" />
      <Setting name="Microsoft.WindowsAzure.Plugins.Caching.CacheSizePercentage" value="30" />
      <Setting name="Microsoft.WindowsAzure.Plugins.Caching.ConfigStoreConnectionString" value="UseDevelopmentStorage=true" />


The Microsoft.WindowsAzure.Plugins.Caching.NamedCaches setting specifies all of the caches and their configuration settings. This information is organized using the JSON syntax. The double quotes in the syntax are escaped using the &quot; character entity reference. The following NamedCaches value is taken from the full ServiceConfiguration.cscfg file above.


The following example shows the same setting from the previous example, but the output is formatted, and the &quot; symbols are replaced with double-quotes. This is shown to better understand the syntax and should not be used in the ServiceConfiguration.cscfg file.

    "caches": [
            "name": "default",
            "policy": {
                "eviction": {"type": 0},
                "expiration": {"defaultTTL": 10, "isExpirable": true, "type": 1},
                "serverNotification": {"isEnabled": false}
            "secondaries": 0
            "name": "NamedCache1",
            "policy": {
                "eviction": {"type": -1},
                "expiration": {"defaultTTL": 20, "isExpirable": true, "type": 2},
                "serverNotification": {"isEnabled": true}
           "secondaries": 1

All named caches are defined within a top-level caches field. Each named cache is defined by the following three fields.

Caches Field Description


Specifies the name of the cache.


A policy for eviction, expiration, and notification settings.


Defines the number of backup copies to maintain for high availability. At this time the value must be 0 or 1. A value of 0 disables high availability.

The policy field consists of the following properties.

Policy Field Description


Contains a single field, type, that specifies the type of eviction. Possible values are 0 (LRU) and -1 (None). A value of 0 enables eviction for least recently used items. A value of -1 disables eviction.


Contains three fields that describe the expiration policy.

  1. defaultTTL: The number of minutes that items remain in the cache before expiring.

  2. isExpirable: A value of true enables expiration and a value of false disables expiration.

  3. type: The type of expiration. A value of 0 disables expiration. A value of 1 specifies absolute expiration. A value of 2 specifies sliding expiration. With sliding expiration, every touch of the item in the cache resets the expiration time.


In type is set to 0 (disabled), isExpirable must be set to fasle, and defaultTTL must be set to 0.


Contains a single field, isEnabled, that specifies whether notifications are enabled for this cache.


Specifies the initial level of diagnostic collection for caching. This setting is specific to diagnostic information for roles that are clients of a cache. This provides diagnostics information about the use of the cache from the client perspective. Note that in the collocated typology, it is possible to use both ClientDiagnosticLevel and DiagnosticLevel in the same role configuration.

<Setting name="Microsoft.WindowsAzure.Plugins.Caching.ClientDiagnosticLevel" value="1" />


Specifies the initial level of diagnostic collection for caching. This setting is specific to diagnostic information on the roles that host caching.

<Setting name="Microsoft.WindowsAzure.Plugins.Caching.DiagnosticLevel" value="1" />


The percentage of available memory to use for caching. For co-located topologies, this should be a whole number without a percent sign, such as 30.

<Setting name="Microsoft.WindowsAzure.Plugins.Caching.CacheSizePercentage" value="30" />

For dedicated topologies, this should be an empty string.

<Setting name="Microsoft.WindowsAzure.Plugins.Caching.CacheSizePercentage" value="" />


The Azure storage account to use for caching. This is storage is used to hold configuration data about the cache cluster and is accessible from all virtual machines that make up the cache cluster. Note that the following example uses the developer storage for local debugging. Before deploying to the cloud, you should change this to an actual storage account.

<Setting name="Microsoft.WindowsAzure.Plugins.Caching.ConfigStoreConnectionString" value="UseDevelopmentStorage=true" />