Cluster Configuration Settings (Windows Server AppFabric Caching)

  • Article

Windows Server AppFabric provides the ability to edit your cache cluster configuration settings in XML or by using Windows PowerShell directly. This topic describes the cluster configuration settings that are available and how they are specified with XML or Windows PowerShell. For more information about how to make cluster configuration changes, see Configuring the Cache Cluster (Windows Server AppFabric Caching).

There are four types of settings configured in the cluster configuration settings:

  • Cluster settings: Describe settings related to the cache cluster.

  • Cache settings: Describe settings related to each of the caches in the cluster.

  • Host settings: Describe settings related to each of the cache hosts that are members of the cluster.

  • Cluster configuration storage location settings: Describe the storage location and designate the cluster management role. For more information about the cluster management role, see Lead Hosts and Cluster Management (Windows Server AppFabric Caching).

Note

The XML file produced by the Export-CacheClusterConfig Windows PowerShell command is referred to as the "XML file" throughout this topic.

Important

Many of the attributes and elements described below are case sensitive. When modifying these settings, it is important to use the casing as it documented in the following tables.

Cluster Settings

The only way to create a cluster and specify its initial settings is to install Windows Server AppFabric and run the AppFabric Configuration Wizard on at least one cache host.

Two settings are used to describe the cluster itself: the name and the size (small, medium or large). In the XML file, these settings are defined as attributes of the dataCache element and are assigned when the AppFabric Configuration Wizard runs on the first cache server of the cluster.

Setting XML Configuration Location Setting assigned when…

Cluster size

The size attribute in the dataCache element. Possible values include Small, Medium, or Large.

Cluster size is assigned when the AppFabric Caching Service is configured on the first cache server.

Cache Settings

The only way to create a cache and to specify its initial settings is to use the Windows PowerShell-based cache administration tool New-Cache command.

The cache settings are stored at the cluster level. For this reason, these settings can be found in the XML file as a child of the caches element. In Windows PowerShell, use the Get-CacheConfig command to view the cache configuration settings, and the Set-CacheConfig command to change the cache settings.

Note

To change cache configuration settings with the XML file or the Set-CacheConfig command, you must restart the whole cluster with the Windows PowerShell Restart-CacheCluster command. You can also use Windows PowerShell to remove and re-create a cache by the same name (and different settings) without restarting the cluster.

The following table lists the settings available to each cache:

Setting XML Configuration Location Windows PowerShell Configuration Location

Cache name

The name attribute in the cache element.

Assigned with the CacheName parameter in the New-Cache command. View this setting with the Get-CacheConfig command using the CacheName parameter.

If cache notifications is enabled

The isEnabled attribute in the serverNotification element. Values may be true or false. The serverNotification element is a child of the policy element, which is a child of the cache element.

Assigned with the NotificationsEnabled parameter in the New-Cache command. Notifications are enabled when this parameter is present. View this setting with the Get-CacheConfig command using the CacheName parameter.

If the high availability feature is enabled

The secondaries attribute of the cache element. High availability is enabled when this attribute is set to 1, disabled when it is set to 0. Alternatively, removing this attribute disables the high availability feature.

Assigned with the Secondaries parameter in the New-Cache command. High availability is enabled when Secondaries equals 1, disabled when Secondaries equals 0. View this setting with the Get-CacheConfig command using the CacheName parameter.

Cache type

The type attribute in the cache element. Only the Partitioned (default) value is allowed.

Assigned with the Type parameter in the New-Cache command. Only the Partitioned (default) value is allowed. View this setting with the Get-CacheConfig command using the CacheName parameter.

Eviction type

The type attribute in the eviction element. Values may be LRU for least recently used or None. The eviction element is a child of the policy element, which is a child of the cache element.

Assigned with the Eviction parameter in the New-Cache command. Values may be LRU for least recently used or None. View this setting with the Get-CacheConfig command using the CacheName parameter.

If expiration is enabled

The isExpirable attribute in the expiration element. Values may be true or false. The expiration element is a child of the policy element, which is a child of the cache element.

Assigned with the Expirable switch in the New-Cache command. Values may be true or false. View this setting with the Get-CacheConfig command using the CacheName parameter.

Default object time-out (minutes)

The defaultTTL attribute in the expiration element. Values may be true or false. The expiration element is a child of the policy element, which is a child of the cache element.

Assigned with the TimeToLive parameter in the New-Cache command. View this setting with the Get-CacheConfig command using the CacheName parameter.

Host Settings

The only way to create a host and specify its initial settings is to install Windows Server AppFabric on a server and then run the AppFabric Configuration Wizard to configure the Caching Service. You have the option to either create a new cache cluster or join an existing cache cluster.

The cache cluster must keep track of each cache host that is a member of the cluster. In the XML file, a host element is used to specify each host in the cluster. In Windows PowerShell, the Get-CacheConfig and Set-CacheConfig commands can be used to view or reconfigure the cache host configuration.

The settings available to each cache host are as follows:

Setting XML Configuration Location Windows PowerShell Configuration Location

Cache server name

The name attribute in the host element. The host element is a child of the hosts element.

Assigned based on the computer name. View this setting with the Get-CacheHostConfig command.

Cache host name (name of the host service)

The cacheHostName attribute in the host element. The default value is DistributedCacheService. The host element is a child of the hosts element.

Assigned at installation time. View this setting with the Get-CacheHostConfig command.

Cache port number (default value is 22233)

The cachePort attribute in the host element. The host element is a child of the hosts element.

Assigned at installation time. Reconfigure this setting with the CachePort parameter of the Set-CacheHostConfig command. View this setting with the Get-CacheHostConfig command.

Cluster port number (default value is 22234)

The clusterPort attribute in the host element. The host element is a child of the hosts element.

Assigned at installation time. Reconfigure this setting with the ClusterPortNumber parameter of the Set-CacheHostConfig command. View this setting with the Get-CacheHostConfig command.

Lead host designation

The leadHost attribute in the host element. Values can be true or false. The host element is a child of the hosts element.

Assigned at installation time. View this setting with the Get-CacheHostConfig command.

Cache size (MB)(total space allocated for storing data on the cache host)

The size attribute in the host element. The host element is a child of the hosts element.

Assigned at installation time. Reconfigure this setting with the CacheSize parameter of the Set-CacheHostConfig command. View this setting with the Get-CacheHostConfig command.

Low watermark

The lowWaterMark attribute in the host element. The host element is a child of the hosts element.

Assigned at installation time. Reconfigure this setting with the LWM parameter of the Set-CacheHostConfig command. View this setting with the Get-CacheHostConfig command.

High watermark

The highWaterMark attribute in the host element. The host element is a child of the hosts element.

Assigned at installation time. Reconfigure this setting with the HWM parameter of the Set-CacheHostConfig command. View this setting with the Get-CacheHostConfig command.

Cluster Configuration Storage Location Settings

The configuration storage location settings are assigned when AppFabric caching features are first configured. They describe the storage location and designate the cluster management role.

In the XML file, these settings are specified in the partitionStoreConnectionSettings element, a child of the advancedProperties element (which is a child of the dataCache element).

In Windows PowerShell, the provider name and connection string must be specified when you set context to the cluster with the Use-CacheCluster command. If these parameters are not supplied to Windows PowerShell, they are taken from the cluster configuration storage location.

The settings related to these properties are as follows:

Setting XML Configuration Location Setting assigned when…

Cluster Management Role

The leadHostManagement attribute of the partitionStoreConnectionSettings element, a child of the advancedProperties element. Values are true for lead hosts or false for SQL Server. If cluster configuration settings are stored in a shared folder, the only valid value is true.

The cluster management role is assigned at configuration time depending on where you store your cluster configuration settings. For more information, see Lead Hosts and Cluster Management (Windows Server AppFabric Caching).

Security Properties

Security properties for the cache cluster are set in the securityProperties node in the advancedProperties element. The mode attribute can be set to either None or Transport. The protectionLevel attribute can be set to one of the following values: None, Sign, or EncryptAndSign.

The default values for the cluster are Transport mode and EncryptAndSign protection level. If the securityProperties node is not provided or if either of the attributes are missing, the default values apply. The security properties can be changed with the Set-CacheClusterSecurity Windows PowerShell command.

See Also

Concepts

Edit Cluster Configuration Settings (Windows Server AppFabric Caching)
Cluster Configuration Storage Options (Windows Server AppFabric Caching)
Using Windows PowerShell to Manage Windows Server AppFabric Caching Features
Application Configuration Settings (Windows Server AppFabric Caching)
Configuring the Cache Cluster (Windows Server AppFabric Caching)
Windows Server AppFabric Caching Concepts
Developing a Cache Client (Windows Server AppFabric Caching)