In-Role Cache Role Configuration Settings (ServiceConfiguration.cscfg)
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 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.
ServiceConfiguration.cscfg
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="https://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration" osFamily="3" osVersion="*" schemaVersion="2012-10.1.8">
<Role name="WebRole1">
<Instances count="2" />
<ConfigurationSettings>
<Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="UseDevelopmentStorage=true" />
<Setting name="Microsoft.WindowsAzure.Plugins.Caching.NamedCaches" value="{"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}]}" />
<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" />
</ConfigurationSettings>
</Role>
</ServiceConfiguration>
NamedCaches
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 " character entity reference. The following NamedCaches value is taken from the full ServiceConfiguration.cscfg file above.
{"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}]}
The following example shows the same setting from the previous example, but the output is formatted, and the " 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 |
|---|---|
name |
Specifies the name of the cache. |
policy |
A policy for eviction, expiration, and notification settings. |
secondaries |
Defines the number of backup copies to maintain for high availability. At this time the value must be |
The policy field consists of the following properties.
| Policy Field | Description |
|---|---|
eviction |
Contains a single field, type, that specifies the type of eviction. Possible values are |
expiration |
Contains three fields that describe the expiration policy.
Important In type is set to |
serverNotification |
Contains a single field, isEnabled, that specifies whether notifications are enabled for this cache. |
ClientDiagnosticLevel
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" />
DiagnosticLevel
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" />
CacheSizePercentage
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="" />
ConfigStoreConnectionString
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" />