Export (0) Print
Expand All

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

Updated: July 17, 2010

noteNote
For guidance on choosing the right Azure Cache offering for your application, see Which Azure Cache offering is right for me?.

This topic describes the requirements for supporting Microsoft Azure 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 caching.

TipTip
When you use the NuGet pacakage for caching, the package automatically modifies the configuration file. However, you can use this topic to configure caching clients without the use of NutGet. You can also use this information to further customize the cache client settings that NuGet inserts.

The following sections are covered in this topic.

Cache Client Configuration Example

The following example shows the sections of a web.config or app.config file that are relevant to caching. 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.

 

Name Description

dataCacheClients

Defines the dataCacheClients element of the configuration file. This section specifies the settings for all cache client configurations.

cacheDiagnostics

Defines the cacheDiagnostics element of the configuration file. This section configures diagnostics specific to caching.

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.

 

Attribute Description

Name

The name of the cache client configuration.

isCompressionEnabled

Enables or disables compression. Possible values include true or false. The default is false (disabled).

useConnectionPool

Enables or disables the connection pool. Possible value include true or false. The default is true (enabled).

maxConnectionsToServer

When useConnectionPool is set to true, this attribute specifies the number of connections in the connection pool for this cache client configuration. When useConnectionPool is set to false, this attribute specifies the number of connections to use for each DataCacheFactory object in code.

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. This attribute is not supported in Shared Caching.

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

 

Attribute Description

isEnabled

Set to true or false to enable or disable local automatic connection to the role that hosts caching.

identifier

The name of the role in the same cloud service deployment that hosts caching.

<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-Role Cache for Azure Cache).

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

 

Attribute Description

isEnabled

Set to true or false to enable or disable local cache.

sync

Determines how the local cache is invalidated. Possible values are TimeoutBased and NotificationBased.

objectCount

The maximum number of objects to store in the local cache. The default is 10000.

ttlValue

The number of seconds that objects stay in the local cache. The default is 300 seconds.

noteNote
Notifications are a In-Role Cache feature supported only in caches that are hosted on roles. Those caches must be configured to enable notifications. Notifications are not supported in Microsoft Azure Shared Caching.

<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. This attribute is not supported in Shared Caching.

 

Attribute Description

pollInterval

The number of seconds between polling attempts. Polling is used to check for notifications on the cache cluster. The default is 300 seconds.

maxQueueLength

The maximum number of notifications to queue for this cache client between polling attempts. The default is 10000 notifications.

<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-Role Cache for Azure Cache).

 

Attribute Description

serializer

Determines the type of serialization for cached items. Possible values are NetDataContractSerializer, BinaryFormatter, and CustomSerializer. The default is NetDataContractSerializer.

hosts

ImportantImportant
The hosts and host elements are used only with Shared Caching.

The hosts element contains a host element. For Shared Caching, only one host element is supported. The following table describes the available attributes for the child host element.

 

Attribute Description

name

The name of the Shared Caching Service URL for the cache.

cachePort

The port for the Shared Caching service communication. This is typically 22233.

<hosts>
    <host name="yourcachename.cache.windows.net" cachePort="22233" />
</hosts>

securityProperties

ImportantImportant
The securityProperties and messageSecurity elements are used only with Shared Caching.

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

 

Attribute Description

mode

Possible values include None, Transport, and Message. Only Message is supported with Shared Caching. The other two settings are related to Microsoft AppFabric 1.1 for Windows Server.

The securityProperties element can have a child element, messageSecurity. The following table describes the available attributes for the messageSecurity element.

 

Attribute Description

authorizationInfo

The ACS key taken from the Authentication Token property in the .

<securityProperties mode="Message">
   <messageSecurity authorizationInfo="iz8zOmJ0dJBzzzzxa8JxdGJkb281bzxudGF0az9udGxzdGluZi111z8oZS5Ji28lP38jb250Pm9sLmludDMud2luZG93Pi1pb8Qubmx0L1dSQxB2MP45LiZxd25lPii0eDJJZQA5SlZQQUQ2xzIizk8iazlES1P08X8zOFIxZjdzZxp0i3lFQ2FFPSZodJRzOi8xS8JxdGJEb281bzxudGF0az9uxGxzdGluZi5jiz8oZS5pb8QzL8dpbmRxd3MQaz50Lm5ldA==">
   </messageSecurity>
</securityProperties>

cacheDiagnostics

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

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. caching 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.

 

Attribute Description

dumpLevel

Possible values include Off, Mini, and Full.

dumpStorageQuotaInMB

The port for the Shared Caching service communication. This is typically 22233.

scheduledTransferPeriodInMinutes

The number of minutes between transfers of the crash dumps to the diagnostic store.

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

Community Additions

ADD
Show:
© 2014 Microsoft