Share via

Application Configuration Settings (Velocity)

  • Article

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

With Microsoft project code named "Velocity," 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 (Velocity).

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

For more information about how to use these settings in your application, see the examples covered in Configuring the Cache Client with XML (Velocity).

Security Considerations

Cache clients should be used only by applications residing on application servers in your datacenter, within the perimeter of the corporate firewall. Communications between cache servers and cache hosts is not encrypted and is vulnerable to malicious network "sniffing" and "replay" attacks.

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

Cache Client Setting

The cache client type setting determines whether the cache client is routing or simple. For more information about these types, see Cache Clients and Local Cache (Velocity).

Setting XML Configuration Location Code Configuration Location

Client type

The deployment attribute in the dataCacheClient element. Values may be simple or routing.

The routingClient parameter in the DataCacheFactory class constructor. Values are true for a routing client or false for a simple client.

Client timeout

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

The Timeout property of the DataCacheFactory class.

Note

For best performance, we recommend that you use a routing client whenever possible. Only use a simple client when the computer that is running the cache client application does not have network connectivity to all cache hosts in the cluster.

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 by using parameters of the DataCacheFactory class constructor. For more information about local cache, see Cache Clients and Local Cache (Velocity).

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 localCache parameter in the DataCacheFactory class constructor. This value is true for enabled or false for disabled.

Local cache invalidation method

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

The syncPolicy parameter in the DataCacheFactory class constructor. Use the DataCacheLocalCacheSyncPolicy enumeration to specify TimeoutBased or NotificationBased.

Local cache time-out (seconds)

The ttlValue attribute in the localCache element.

The localCacheTimeout parameter in the DataCacheFactory class constructor.

Specific cache notifications poll interval (seconds)

(optional) Specified by the pollInterval attribute of the clientNotifications element. The clientNotifications 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 parameter in the DataCacheFactory class constructor.

Maximum locally-cached object count

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

This setting is not able to be configured programmatically. The default value of 100,000 objects will be used for programmatic client configuration.

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.

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 the Physical Model section of General Concept Models (Velocity).

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. Once instantiated, those DataCacheServerEndPoint objects are then passed to the DataCacheFactory class constructor as a single parameter.

Note

Routing clients use their internal routing table for tracking which cache hosts are in the cluster. These tables are maintained by the lead hosts in the cluster. Routing clients are not limited to the hosts specified in the application configuration settings for passing data. The hosts specified in the routing client's application configuration settings provide connectivity to a lead host in the cluster so that its routing table can be synchronized.

Setting XML Configuration Location Code Configuration Location

Cache server name

The name attribute of the host element.

The hostName string-based parameter in the DataCacheServerEndPoint class constructor.

Cache port number

The cachePort attribute of the host element.

The cachePort integer-based parameter in the DataCacheServerEndPoint class constructor.

Cache host name (name of the cache host service on the cache server)

The cacheHostName attribute of the host element. The default value is DistributedCacheService.

The cacheHostName string-based parameter in the DataCacheServerEndPoint class constructor.

Log Sink Settings

Log sinks are used to trace "Velocity" events, such as errors, warnings, and other informational messages. By default, each cache client automatically creates a console-based log sink with the event trace level set to Error. If you want to override this default log sink, you can explicitly define other log sinks, such as a different console-based log sink, an Event Tracing for Windows (ETW), or a file-based log sink. Log sink settings may be configured in the application configuration file or programmatically; programmatic settings will always take precedence. For more information, see Log Sink Settings (Velocity).

XML-Only Application Configuration Settings

In order for the "Velocity" 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 two section elements so that the application can read the dataCacheClient and fabric elements.

The dataCacheClient section element tells the "Velocity" assemblies how to read the cache client configuration settings. The fabric section element tells the "Velocity" assemblies how to read the log sink settings in case they are added later to configure log sinks. It is a good practice to include both dataCacheClient and fabric section elements, even if you do not start with any log sinks enabled.

The following code example shows what section elements for the dataCacheClient and fabric elements look like.

<!--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>

See Also

Concepts

Client Configuration Options (Velocity)
Cluster Configuration Settings (Velocity)
Log Sink Settings (Velocity)
Troubleshooting (Velocity)
Cache Administration with PowerShell (Velocity)

Other Resources

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