Cache Host Configuration Settings (Velocity)

Article
06/24/2009

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

Within Microsoft project code named "Velocity," cache host settings are stored in two places: at the cluster-level in the cluster configuration settings and at the cache host-level on each individual cache host.

Cluster-Level Cache Host Settings

The cache host settings stored at the cluster level are related to how the cache host performs as a participant in the cluster, for example, the memory consumption and network port settings for communication. These cluster-level cache host settings are discussed in the topic: Cluster Configuration Settings (Velocity).

Most cluster-level settings are also available to the PowerShell-based cache administration tool for viewing and editing. For more information, see Cache Administration with PowerShell (Velocity).

Host-Level Cache Host Settings

The cache host settings stored on each cache host are functional and are related to settings required for the software to run; for example, they set where the cache host can find the cluster configuration storage location and how log sinks should be configured.

To store cache host settings, each cache host uses a configuration file that is named DistributedCache.exe.config. This file is automatically created and configured during the installation, and is located in the folder chosen during installation. The settings that are used in this configuration file do not usually have to be edited. The only time that you may have to edit this file is to set log sinks levels or change the log location.

Note

Other settings found in the DistributedCache.exe.config file that are not described here are used by "Velocity" for internal operations.

The dataCacheConfig Element Settings

The settings in the dataCacheConfig element are meaningful to the cache host with regard to the cache cluster. Settings such as the cluster name, cluster configuration storage location, and the name of the cache host service can be found in the dataCacheConfig element.

The settings in the dataCacheConfig element, outlined in the following table, are also used by the PowerShell administration tool upon starting it, so that you do not have to type cluster connection parameters. For more information, see Cache Administration with PowerShell (Velocity).

Setting	XML Configuration Location
Cluster name (of which the cache host is a member)	The `clusterName` attribute of the `dataCacheConfig` element.
Cache server name	The `hostName` attribute of the `dataCacheConfig` element.
Cache host service name	The `cacheHostName` attribute of the `dataCacheConfig` element.
Cache host timeout value	The `timeout` attribute of the `dataCacheConfig` element. Values are in milliseconds. We do not recommend specifying a value less than `10000` (10 seconds). Default value is `15000`. This value should match the settings for the cache client.
Log sink settings for the default file-based log sink created at installation time	The `location` attribute of the `log` element. The `log` element is a child of the `dataCacheConfig` element.
Cluster configuration location connection string	The `connectionString` element of the `clusterConfig` element. The `clusterConfig` element is a child of the `dataCacheConfig` element.

Note

When you use a SQL Server database to store cluster configuration settings, the SQL Server connection string is stored in clear text in the DistributedCache.exe.config file. Whenever possible, use Windows integrated security to secure the database so that passwords are not required in connection strings.

Log Sink Settings

Log sinks are used to trace "Velocity" events such as errors, warnings, and other informational messages. By default, each cache host is configured to run a file-based log sink at installation with the event trace level set to Error.

The configuration settings for the default log sink are specified in the log element of the dataCacheConfig element. The installation default for this log sink is to write log files to a folder named log within the folder chosen for installation.

To change the event trace level or the location where the logs are written, change the settings on the log element and restart the cache host with the PowerShell cache administration tool. For more information about PowerShell commands, see Cache Administration with PowerShell (Velocity).

Note

Restarting a cache host causes the loss of all objects stored on that cache host. For those caches with high availability enabled, the cache clients will receive secondary copies of the objects lost from another cache host.

Unlike the cache client, cache host log sinks cannot be configured programmatically. But you can override the default trace settings and define other log sinks, such as a different file-based log sink, or an Event Tracing for Windows (ETW), or console-based log sink.

To explicitly define log sink settings that override the default log sink, configure these settings in the fabric element found in DistributedCache.exe.config. For more information, see Log Sink Settings (Velocity).

Example

The following example shows what the cache host configuration file, DistributedCache.exe.config, looks like. In this example, the default file-based log sink is used (specified in the log element, child of the dataCacheConfig element).

By default, the fabric element is also present on the cache host and is used for more than log sinks. The console-based log sink is specified but disabled. The ETW-based log sink is set to Verbose, but will consume very few resources on the server before it is subscribed to.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    
    <section 
      name="dataCacheConfig" 
      type="Microsoft.Data.Caching.DataCacheConfigSection, 
      CacheBaseLibrary, Version=1.0.0.0, 
      Culture=neutral, PublicKeyToken=63118e5b4b42c36a" />
    
    <section name="fabric"
      type="System.Data.Fabric.Common.ConfigFile, FabricCommon"
      allowLocation="true" allowDefinition="Everywhere"/>
  
  </configSections>
  
  <dataCacheConfig clusterName="ClusterName1" hostName="CACHESERVER1"
    cacheHostName="DistributedCacheService">
    
    <log 
      location="C:\Program Files\Microsoft Distributed Cache\V1.0\Logs"
      logLevel="0" />
    
    <clusterConfig 
      provider="System.Data.SqlClient" 
      connectionString="Server=SQLServer1;Database=ClusterConfigurationDB;Trusted_Connection=true"/>
    
  </dataCacheConfig>
  <system.data>
    <DbProviderFactories> 
      <!--Add providers for System.Data.SqlServerCe.3.5 private deployement-->
      <remove invariant="System.Data.SqlServerCe.3.5" />
      <add name="Microsoft SQL Server Compact Data Provider"
           invariant="System.Data.SqlServerCe.3.5"
           description=".NET Framework Data Provider for Microsoft SQL Server Compact"
           type="System.Data.SqlServerCe.SqlCeProviderFactory, 
           System.Data.SqlServerCe, Version=3.5.1.0, Culture=neutral, 
           PublicKeyToken=89845dcd8080cc91"/>
    </DbProviderFactories>
  </system.data>
      
  <fabric>
    
    <section name="logging" path="">
      <collection name="sinks" collectionType="list">
        <customType 
          className="System.Data.Fabric.Common.EventLogger,FabricCommon" 
          sinkName="System.Data.Fabric.Common.ConsoleSink,FabricCommon" 
          sinkParam="" defaultLevel="-1" />
        <customType 
          className="System.Data.Fabric.Common.EventLogger,FabricCommon" 
          sinkName="Microsoft.Data.Caching.ETWSink, CacheBaseLibrary" 
          sinkParam="" defaultLevel="3" />
      </collection>
    </section>
    
    <section name="param" path="">
      <key 
        name="SeedNodeConfigClass" 
        value="Microsoft.Data.Caching.SeedNodeConfig,ServiceLibrary" />
      <key 
        name="ArbitratorConfigClass" 
        value="System.Data.Cas.Main.CasArbitratorList,CasMain" />
      <section name="CAS_PM" path="">
        <key 
          name="DroppedReplicaKeepDuration" 
          value="30" />
        <key 
          name="ClusterStableNodeUpInterval" 
          value="10" />
        <key 
          name="ReplicationQueueCapacity" 
          value="128" />
        <key 
          name="ThrowOnAssert" 
          value="true" />
      </section>
      
    </section>
  </fabric>

  <runtime>
    <gcServer enabled="true" />
  </runtime>
  
</configuration>

Cache Host Configuration Settings (Velocity)

Cluster-Level Cache Host Settings

Host-Level Cache Host Settings

The dataCacheConfig Element Settings

Log Sink Settings

Example

See Also

Concepts

Other Resources

Additional resources