XML-Based Client Configuration (Velocity)

  • Article

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

In Microsoft project code named "Velocity," using an XML based configuration for the cache client is an excellent choice when configuration details can change after compiling the application. By having an application configuration file, changes such as setting cache host connection details or trace levels are quick and easy.

Using an XML application configuration file is not the only choice you have for configuring the cache client. You can also configure the cache client programmatically by providing configuration settings as parameters to the DataCacheFactory class constructor. For more information, see Programmatic Client Configuration (Velocity).

Note

If any settings are specified in the application configuration file when configuring the cache client programmatically, the programmatic settings always take precedence.

Security Considerations

Data in the cache is not encrypted and is available to any cache client that has the appropriate configuration settings. We highly recommend that you secure the application configuration files used to communicate with the cache.

Cache Client Settings

When using an application configuration file to configure the cache client, almost the same settings are used as if you were to configure your client programmatically. The only exception is the configSections element, which "Velocity" needs in order to read the configuration file.

The cache client settings configured are:

  • Client Type: Defines the client as routing or simple.

  • Local Cache: Enables local caches and determines how long locally cached objects are used before they are invalidated.

  • Hosts: Defines one or more lead hosts, including the server name, cache port number, and the name of the cache host service.

  • Log Sink Levels: Define how cache client events should be traced, if at all.

Configuration Elements

The following XML elements are used to configure the cache client in the application configuration file.

  • <configSections>: In order for "Velocity" to work, this element must be the first element in the application configuration file. It contains child elements that tell the runtime how to use the dataCacheClient and fabric elements, when present.

  • <dataCacheClient>: This element is the primary element used to configure the cache client. It is the parent to the elements used to enable local cache (localCache) and specify the cache hosts (hosts). The deployment attribute of the dataCacheClient element determines whether it is a routing or simple client. This element is a child of the configuration element.

  • <localCache>: This optional element specifies the local cache settings, and is a child of the dataCacheClient element. If not present, or the isEnabled attribute is false, local cache is disabled. The ttlValue attribute specifies for how many seconds locally cached objects will be used by the client before they are invalidated. The sync attribute allows you to specify how locally cached objects will be invalidated: TTLBased or NotificationBased. For more information about invalidation, see Expiration and Eviction (Velocity).

  • <clientNotification>: This optional element allows you to specify a custom poll interval value, the default is 300 seconds. The pollInterval is used to specify how many seconds it should wait before checking for new cache notifications. For more information about cache notifications, see Cache Notifications (Velocity).

  • <hosts>: This element is a parent to the host elements that specify the cache hosts. It is a child of the dataCacheClient element.

  • <host>: This element specifies one cache host. Ideally, use host to specify a lead host. This element is a child of the hosts element.

  • <fabric>: This optional element specifies the log sink settings. It is a child of the configuration element.

  • <customType>: This element is wrapped by the <collection> and <section> elements, and are all children of the <fabric> element. Each customType element specifies a separate log sink. The sinkName attribute specifies the type of log sink; if it will be a file-based, console-based, or an Event Tracing for Windows (ETW)-based log sink. The sinkParam attribute specifies log file details for the file-based log sink. The defaultLevel specifies the type of log level in correspondence with the System.Diagnostics.TraceLevel enumeration. For more information about log sinks, see Log Sink Settings (Velocity).

For more information about the application configuration file settings, see Application Configuration Settings (Velocity).

Process Summary

To specify cache client settings using XML elements, complete the following steps:

  1. Whenever developing a new cache-enabled application, prepare the development environment. For more information, see How to: Prepare the Development Environment (Velocity).

  2. Add an application configuration file to the Visual Studio solution.

  3. Decide what options you want for your cache client. For more information, see Cache Clients and Local Cache (Velocity).

  4. Add the required XML elements and attributes to specify configuration settings. You can do this manually one element at a time. Or, you can copy examples. For examples to copy and more information, see the topics listed in Configuring the Cache Client with XML (Velocity).

  5. When your application configuration file is ready, you can start writing cache-enabled applications. Because you will not be specifying configuration settings programmatically, you do not need to provide any parameters to the DataCacheFactory class constructor. For more information, see Using Basic Cache Methods (Velocity).

Example

The following code is an example of what an application configuration file looks like when used only to specify the cache client settings. This particular example is for a routing client with local cache enabled, and a single cache host called CacheServer1.

<?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.Data.Caching.DataCacheClientSection,
       CacheBaseLibrary"
       allowLocation="true"
       allowDefinition="Everywhere"/>
    
    <!-- required to read the <fabric> element, when present -->
    <section name="fabric"
       type="System.Data.Fabric.Common.ConfigFile,
       FabricCommon"
       allowLocation="true"
       allowDefinition="Everywhere"/>
    
  </configSections>
  
  <!-- routing client-->
  <dataCacheClient deployment="routing">
    
    <!-- local cache enabled -->
    <localCache
      isEnabled="true"
      sync="TTLBased"
      objectCount="100000"
      ttlValue="300" />
    
    <!--(optional) specify cache notifications poll interval 
    <clientNotification pollInterval="300" />
    -->

    <!-- cache host(s) -->   
    <hosts>
      <host
         name="CacheServer1"
         cachePort="22233"
         cacheHostName="DistributedCacheService"/>
    </hosts>
  </dataCacheClient>
</configuration>

See Also

Concepts

Programmatic Client Configuration (Velocity)
Troubleshooting (Velocity)
Cache Administration with PowerShell (Velocity)

Other Resources

Configuring the Cache Client with XML (Velocity)
Installation and Deployment (Velocity)
Configuration Settings (Velocity)
Programming Guide (Velocity)
Cache Concepts (Velocity)