Application Configuration Settings (Windows Server AppFabric Caching)

Article
09/20/2010

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>

Share via