Application Configuration Settings (Windows Server AppFabric Caching)

With the caching features of Windows Server AppFabric, you may configure your application's cache client settings programmatically, by using an application configuration file, or by using both approaches at different places in your application. For more information about each of these configuration methods and how to select each, see Client Configuration Options (Windows Server AppFabric Caching).

Regardless of the approach you take, you are configuring the same cache client setting. The tables in this topic present the settings available to the cache client and show how they are configured in the XML-based application configuration file and programmatically, by using code.

For more information about how to use these settings in your application, see the examples covered in XML-Based Client Configuration (Windows Server AppFabric Caching).

Cache Client Setting

Setting XML Configuration Location Code Configuration Location

Client time-out (milliseconds)

The requestTimeout attribute in the dataCacheClient element. We do not recommend specifying a value less than 10000 (10 seconds). Default value is 15000.

The RequestTimeout property of the DataCacheFactoryConfiguration class.

Channel open time-out (milliseconds)

The channelOpenTimeout attribute in the dataCacheClient element. This value can be set to 0 in order to immediately handle any network problems. For more information, see Configuring Cache Client Timeouts (Windows Server AppFabric Caching). The default value is 3000.

The ChannelOpenTimeout property of the DataCacheFactoryConfigurationc class.

Maximum number of connections to the server

The maxConnectionsToServer attribute in the dataCacheClient element. The default value is 1.

The MaxConnectionsToServer property of the DataCacheFactoryConfiguration class.

Cache Host Settings

For each cache client, you must specify one or more cache hosts in the cluster. Specify lead hosts because cache hosts designated as lead hosts help manage the cluster. Initially, lead hosts are the first cache hosts installed in the cluster. For more information about lead hosts, see Windows Server AppFabric Caching Physical Architecture Diagram.

In the application configuration file, the settings for each cache host are specified in a host element, a child of the hosts element. Programmatically, each host is defined in the class constructor of the DataCacheServerEndpoint class. After they are instantiated, those DataCacheServerEndPoint objects are then passed to the Servers property of the DataCacheServerEndpoint class.

Setting XML Configuration Location Code Configuration Location

Cache server name

The name attribute of the host element.

The HostName property of the DataCacheServerEndpoint class.

Cache port number

The cachePort attribute of the host element.

The CachePort property of the DataCacheServerEndpoint class.

Local Cache Settings

The local cache settings specify whether local cache should be enabled, the way locally cached objects should be invalidated, the object time-out, and whether cache notifications should be used to invalidate locally cached objects.

In the application configuration file, local cache settings are defined in the localCache element, a child of the dataCacheClient element. Programmatically, local cache is configured with an instance of the DataCacheFactoryConfiguration class that is passed to the constructor of the DataCacheFactory class constructor. For more information about local cache, see Cache Clients and Local Cache (Windows Server AppFabric Caching).

Setting XML Configuration Location Code Configuration Location

Local cache enabled

The isEnabled attribute in the localCache element. Values may be true or false. The localCache element may also be missing to indicate that it is disabled.

The IsEnabled property of the DataCacheLocalCacheProperties class. This is then assigned to the LocalCacheProperties property of the DataCacheFactoryConfiguration class.

Local cache invalidation method

The sync attribute in the localCache element. Use the TimeoutBased value to indicate a time-out value should be used. Use NotificationBased to indicate cache notifications should also be used.

The InvalidationPolicy property of the DataCacheLocalCacheProperties class. Possible values include NotificationBased and TimeoutBased.

Local cache time-out (seconds)

The ttlValue attribute in the localCache element.

The DefaultTimeout property of the DataCacheLocalCacheProperties class.

Specific cache notifications poll interval (seconds)

(optional) Specified by the pollInterval attribute of the clientNotification element. The clientNotification element is a child of the dataCacheClient element, and not a child of the localCache element. If not specified, a value of 300 seconds will be used.

The PollInterval property of the DataCacheNotificationProperties class. This is then assigned to the NotificationProperties property of the DataCacheFactoryConfiguration class.

Maximum locally-cached object count

(optional) Specified by the objectCount attribute in the localCache element. Triggers when eviction on the local cache should start; it will then attempt to remove 20 percent of the least recently used locally cached objects. If not specified, the default value of 10,000 objects is used.

The ObjectCount property of the DataCacheLocalCacheProperties class.

Note

For best performance, only enable local cache for objects that change infrequently. Using local cache for frequently changing data may increase the chance that the client will be working with stale objects. Although you could lower the ttlValue and make a process refresh the local cache more frequently, the increased load on the cluster may outweigh the benefits of having the local cache. In such cases of frequently changing data, it is best to disable local cache and pull data directly from the cluster.

Notification Settings

In the application configuration file, notification properties are defined in the clientNotification element, a child of the dataCacheClient element. Programmatically, notification properties are configured with an instance of the DataCacheFactoryConfiguration class that is passed to the constructor of the DataCacheFactory class constructor. For more information, see Configuration Methods (Windows Server AppFabric Caching).

Setting XML Configuration Location Code Configuration Location

Specific cache notifications poll interval (seconds)

Specified by the pollInterval attribute of the clientNotification element. If not specified, a value of 300 seconds will be used.

The PollInterval property of the DataCacheNotificationProperties class. This is then assigned to the NotificationProperties property of the DataCacheFactoryConfiguration class.

Maximum queue length

The maxQueueLength attribute of the clientNotification element. If not specified, the default value is 10000.

The MaxQueueLength property of the DataCacheNotificationProperties class.

Security Settings

In the application configuration file, security properties are defined in the securityProperties element, a child of the dataCacheClient element. Programmatically, security properties are configured with an instance of the DataCacheFactoryConfiguration class that is passed to the constructor of the DataCacheFactory class constructor. For more information, see Configuration Methods (Windows Server AppFabric Caching).

Setting XML Configuration Location Code Configuration Location

Mode

The mode attribute of the securityProperties element. Possible values include Transport and None. The default value is Transport.

The SecurityMode property of the DataCacheSecurity class. Possible values include None and Transport. The DataCacheSecurity object is then assigned to the SecurityProperties property of the DataCacheFactoryConfiguration class.

Protection level

The protectionLevel attribute of the securityProperties element. Possible values include None, Sign, and EncryptAndSign. The default value is EncryptAndSign.

The ProtectionLevel property of the DataCacheSecurity class. Possible values include None, Sign, and EncryptAndSign.

Transport Settings

In the application configuration file, transport properties are defined in the transportProperties element, a child of the dataCacheClient element. Programmatically, transport properties are configured with an instance of the DataCacheFactoryConfiguration class that is passed to the constructor of the DataCacheFactory class constructor. For more information, see Configuration Methods (Windows Server AppFabric Caching).

Setting XML Configuration Location Code Configuration Location

Connection buffer size (bytes)

The connectionBufferSize attribute of the transportProperties element.

The ConnectionBufferSize property of the DataCacheTransportProperties class. This is then assigned to the TransportProperties property of the DataCacheFactoryConfiguration class.

Maximum buffer pool size (bytes)

The maxBufferPoolSize attribute of the transportProperties element.

The MaxBufferPoolSize property of the DataCacheTransportProperties class.

Maximum buffer size (bytes)

The maxBufferSize attribute of the transportProperties element.

The MaxBufferSize property of the DataCacheTransportProperties class.

Maximum output delay (milliseconds)

The maxOutputDelay attribute of the transportProperties element.

The MaxOutputDelay property of the DataCacheTransportProperties class.

Channel initialization timeout (milliseconds)

The channelInitializationTimeout attribute of the transportProperties element.

The ChannelInitializationTimeout property of the DataCacheTransportProperties class.

Receive timeout (milliseconds)

The receiveTimeout attribute of the transportProperties element.

The ReceiveTimeout property of the DataCacheTransportProperties class.

Example Application Configuration File

For the AppFabric assemblies to read the XML elements in the application configuration file, you must include the configSections element as the first element in the file under the configuration tag. Within the configSections element, you must include one section element associated with the dataCacheClient element.

The following example shows an application configuration file that uses many of the cache client configuration options discussed in this topic. It is important to note that only the hosts element is required in the dataCacheClient to connect to the cluster. The other child elements all have default values.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
   <!--configSections must be the FIRST element -->
<configSections>
   <!-- required to read the <dataCacheClient> element -->
   <section name="dataCacheClient"
         type="Microsoft.ApplicationServer.Caching.DataCacheClientSection,
            Microsoft.ApplicationServer.Caching.Core, Version=1.0.0.0, 
            Culture=neutral, PublicKeyToken=31bf3856ad364e35"
          allowLocation="true"
          allowDefinition="Everywhere"/>
</configSections>

   <dataCacheClient requestTimeout="15000" channelOpenTimeout="3000" maxConnectionsToServer="1">
      <localCache isEnabled="true" sync="TimeoutBased" ttlValue="300" objectCount="10000"/>
      <clientNotification pollInterval="300" maxQueueLength="10000"/>
      <hosts>
         <host name="CacheServer1" cachePort="22233"/>
         <host name="CacheServer2" cachePort="22233"/>
      </hosts>
      <securityProperties mode="Transport" protectionLevel="EncryptAndSign" />
      <transportProperties connectionBufferSize="131072" maxBufferPoolSize="268435456" 
                           maxBufferSize="8388608" maxOutputDelay="2" channelInitializationTimeout="60000" 
                           receiveTimeout="600000"/>
   </dataCacheClient>
</configuration>

See Also

Concepts

Client Configuration Options (Windows Server AppFabric Caching)
Cluster Configuration Settings (Windows Server AppFabric Caching)
Troubleshooting Windows Server AppFabric Caching
Using Windows PowerShell to Manage Windows Server AppFabric Caching Features
Windows Server AppFabric Caching Concepts
Developing a Cache Client (Windows Server AppFabric Caching)