Application Configuration Settings (AppFabric 1.1 Caching)

With the caching features of Microsoft AppFabric 1.1 for Windows Server, 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 Configuring a Cache Client.

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.

Cache Client Setting

Each cache client has configuration settings defined. If you are using a configuration file these are included in one or more dataCachClient sections which can be embedded in a dataCacheClients section. For example:

  <dataCacheClients>
    <dataCacheClient name="default">
      <hosts>
        <host name="CacheServer1" cachePort="22233" />
        <host name="CacheServer2" cachePort="22233" />
      </hosts>
    </dataCacheClient>
    <dataCacheClient name="compressedCache" isCommpressionEnabled="true">
      <hosts>
        <host name="CacheServer1" cachePort="22233" />
        <host name="CacheServer2" cachePort="22233" />
      </hosts>
    </dataCacheClient>
  </dataCacheClients>

In the previous example, there are two cache clients defined in the configuration file: default and compressedCache. To access the default cache, you don't have to specify the cache client name. For example:

DataCacheFactory factory = new DataCacheFactory();

To specify any other named dataCacheClient section, you must specify the cache client section name using the DataCacheFactoryConfiguration constructor.

DataCacheFactoryConfiguration factoryConfig = new DataCacheFactoryConfiguration("compressedCache");
DataCacheFactory factory = new DataCacheFactory(factoryConfig)

If you are not using an application configuration file, you can programmatically define all settings with the properties of the DataCacheFactoryConfiguration class.

Setting	XML Configuration Location	Code Configuration Location
Compression (boolean)	The isCompressionEnabled attribute in the dataCacheClient element. Default value is false.	The IsCompressionEnabled property of the DataCacheFactoryConfiguration class.
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. 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 AppFabric Caching Physical Architecture Diagram (AppFabric 1.1 Caching).

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 (AppFabric 1.1 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.

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.

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.

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

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

  2012-09-12