In-Role Cache Client Configuration Settings (Web.config)

This topic describes the requirements for supporting In-Role Cache in a .NET Framework web.config or app.config configuration file. It also describes the available configuration options for cache clients. The settings described in this topic are required only by cache clients; they are not necessary for roles that host In-Role Cache.

The following sections are covered in this topic.

• <configSections>

• <dataCacheClients>

  • <dataCacheClient>

    • <autoDiscover>

    • <localCache>

    • <clientNotification>

    • <serializationProperties>

• <cacheDiagnostics>

  • <crashDump>

Cache Client Configuration Example

The following example shows the sections of a web.config or app.config file that are relevant to In-Role Cache. In this example, the default cache client is accessing the caches hosted by the CacheWorkerRole1 role, and local cache is enabled.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="dataCacheClients" type="Microsoft.ApplicationServer.Caching.DataCacheClientsSection, Microsoft.ApplicationServer.Caching.Core" allowLocation="true" allowDefinition="Everywhere" />
    <section name="cacheDiagnostics" type="Microsoft.ApplicationServer.Caching.AzureCommon.DiagnosticsConfigurationSection, Microsoft.ApplicationServer.Caching.AzureCommon" allowLocation="true" allowDefinition="Everywhere" />
  </configSections>
  <dataCacheClients>
    <dataCacheClient name="default">
      <autoDiscover isEnabled="true" identifier="CacheWorkerRole1" />
      <localCache isEnabled="true" sync="TimeoutBased" objectCount="100000" ttlValue="300" />
    </dataCacheClient>
  </dataCacheClients>
  <cacheDiagnostics>
    <crashDump dumpLevel="Off" dumpStorageQuotaInMB="100" />
  </cacheDiagnostics>
</configuration>

configSections

The following two named section elements should be added to the list of sections in the configSections element.

The following example shows how to define these sections.

    <section name="dataCacheClients" type="Microsoft.ApplicationServer.Caching.DataCacheClientsSection, Microsoft.ApplicationServer.Caching.Core" allowLocation="true" allowDefinition="Everywhere" />
    <section name="cacheDiagnostics" type="Microsoft.ApplicationServer.Caching.AzureCommon.DiagnosticsConfigurationSection, Microsoft.ApplicationServer.Caching.AzureCommon" allowLocation="true" allowDefinition="Everywhere" />

dataCacheClients

Each dataCacheClients element contains one or more named dataCacheClient elements. The dataCacheClients element does not have any attributes. The ability to have multiple cache client configuration sections enables applications to use different settings with different kinds of cached data.

dataCacheClient

Each dataCacheClients element contains one or more named dataCacheClient elements. Application code loads the settings for a cache client by referencing the name of the associated dataCacheClient section.

The dataCacheClients element does not have any attributes. But the child dataCacheClient elements have several available attributes. These attributes are described in the following table.

The following sections describe the available child elements within each dataCacheClient element.

autoDiscover

The autoDiscover element assists cache clients with automatically connecting to a target cache cluster. This cache cluster must be hosted by a role within the same cloud service deployment.

The following table describes the available attributes for the autoDiscover element.

<autoDiscover isEnabled="true" identifier="CacheWorkerRole1" />

localCache

The localCache element controls the use of local cache. By default local cache is not enabled. When enabled, items retrieved from the cache cluster are locally stored in memory on the client machine. This improves performance of subsequent get requests, but it can result in inconsistency of data between the locally cached version and the actual item in the cache cluster. For more information, see Local Cache in Azure In-Role Cache.

The following table describes the available attributes for the localCache element.

<localCache isEnabled="true" sync="TimeoutBased" objectCount="100000" ttlValue="300" />

clientNotification

The following table describes the available attributes for the clientNotification element. This element is responsible for controlling the notification behavior for the cache client.

<clientNotification pollInterval="60" maxQueueLength="10000"/>

serializationProperties

The following table describes the available attributes for the serializationProperties element. This element supports the choice of built-in or custom serialization for cached items. For more information, see Serialization in Azure In-Role Cache.

cacheDiagnostics

This section configures some of the diagnostics setting for In-Role Cache. For more information about diagnostics, see Azure In-Role Cache Troubleshooting and Diagnostics.

The following sections describe the available child elements within each cacheDiagnostics element.

crashDump

The crashDump element controls the type of crash dumps collected for this application. In-Role Cache crash dumps are primarily designed to diagnose problems with cache cluster machines. For this reason, client configuration files should turn off the generation of crash dumps. This can be done by setting the dumpLevel attribute to Off.

When crash dumps are enabled, the caching local store and the diagnostics store should be adjusted in ServiceDefinition.csdef so that the size is always greater than the sum of the crash storage quota and log storage quota that is configured in CacheSettings.xml (the defaults are 1000 MB).

The following table describes the available attributes for the crashDump element.

<crashDump dumpLevel="Off" dumpStorageQuotaInMB="100" scheduledTransferPeriodInMinutes="5" />