Cache Client Configuration Settings for Azure Managed Cache Service
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 requirements for supporting Managed Cache Service in a .NET Framework web.config or app.config configuration file. It also describes the available configuration options for cache clients.
Tip
When you use the NuGet package for Managed Cache Service, the package automatically modifies the configuration file. However, you can use this topic to further customize the cache client settings that NuGet inserts. For more information about the Caching NuGet package, see Configure a Cache Client using the Caching NuGet Package.
The following sections are covered in this topic.
<configSections>
<dataCacheClients>
<dataCacheClient>
<autoDiscover>
<localCache>
<clientNotification>
<serializationProperties>
<securityProperties>
<cacheDiagnostics>
- <crashDump>
Cache Client Configuration Example
The following example shows the sections of a web.config or app.config file that are relevant to Managed Cache Service. In this example, the default
cache client is accessing the cache hosted at mycache.cache.windows.net
, and local cache is enabled.
<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">
<!--To use the in-role flavor of Azure Caching,
set identifier to be the cache cluster role name -->
<!--To use the Azure Caching Service,
set identifier to be the endpoint of the cache cluster -->
<autoDiscover isEnabled="true" identifier="mycache.cache.windows.net" />
<localCache isEnabled="true" sync="TimeoutBased" objectCount="100000" ttlValue="300" />
<!--Use this section to specify security settings for connecting to your cache.
This section is not required if your cache is hosted on a role that is a part
of your cloud service. -->
<securityProperties mode="Message" sslEnabled="false">
<messageSecurity authorizationInfo="MyAuthorizationKey" />
</securityProperties>
</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 Managed Cache Service. |
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 |
useConnectionPool |
Enables or disables the connection pool. Possible value include |
maxConnectionsToServer |
When useConnectionPool is set to |
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.
The following table describes the available attributes for the autoDiscover element.
Attribute | Description |
---|---|
isEnabled |
Set to |
identifier |
For Managed Cache Service, it is the name of the cache endpoint. For In-Role Cache, it is the name of the role in the same cloud service deployment that hosts In-Role Cache. |
<autoDiscover isEnabled="true" identifier="mycache.cache.windows.net" />
localCache
The localCache element controls the use of local cache. By default local cache is not enabled. When enabled, items retrieved from the cache 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. For more information, see Local Cache for Azure Managed Cache Service.
The following table describes the available attributes for the localCache element.
Attribute | Description |
---|---|
isEnabled |
Set to |
sync |
Determines how the local cache is invalidated. Possible values are |
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. |
Note
Notifications are supported in the Standard and Premium cache offerings, and named caches within those offerings must be configured to enable notifications. For more information, see Notifications for Azure Managed Cache Service.
<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.
Attribute | Description |
---|---|
pollInterval |
The number of seconds between polling attempts. Polling is used to check for notifications on the cache. The default is |
maxQueueLength |
The maximum number of notifications to queue for this cache client between polling attempts. The default is |
<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 for Azure Managed Cache Service.
Attribute | Description |
---|---|
serializer |
Determines the type of serialization for cached items. Possible values are |
securityProperties
The following table describes the available attributes for the securityProperties element.
Attribute | Description |
---|---|
mode |
Possible values include |
sslEnabled |
Possible values are |
The securityProperties element has a child element, messageSecurity. The following table describes the available attributes for the messageSecurity element.
Attribute | Description |
---|---|
authorizationInfo |
The access key for the cache, which can be retrieved from the cache dashboard in the . If this is not configured properly, the cache client will not be able to establish communication with the cache. |
<securityProperties mode="Message" sslEnabled="false">
<messageSecurity authorizationInfo="iz8zOmJ0dJBzzzzxa8JxdGJkb281bzxudGF0az9udGxzdGluZi111z8oZS5Ji28lP38jb250Pm9sLmludDMud2luZG93Pi1pb8Qubmx0L1dSQxB2MP45LiZxd25lPii0eDJJZQA5SlZQQUQ2xzIizk8iazlES1P08X8zOFIxZjdzZxp0i3lFQ2FFPSZodJRzOi8xS8JxdGJEb281bzxudGF0az9uxGxzdGluZi5jiz8oZS5pb8QzL8dpbmRxd3MQaz50Lm5ldA==" />
</securityProperties>
cacheDiagnostics
This section configures some of the diagnostics setting for Managed Cache Service.
Warning
In the Managed Cache Service release, the cacheDiagnostics and related sections described in this topic apply only for role-based cloud service cache clients. If your cache client is not a cloud service then these sections are not added by the Cache NuGet package. For more information, see About ClientDiagnosticLevel for Azure Managed Cache Service.
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. Managed Cache Service crash dumps are primarily designed to diagnose problems with cache 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 |
dumpStorageQuotaInMB |
The upper limit for crash dump size. |
scheduledTransferPeriodInMinutes |
The number of minutes between transfers of the crash dumps to the diagnostic store. |
<crashDump dumpLevel="Off" dumpStorageQuotaInMB="100" scheduledTransferPeriodInMinutes="5" />