Cache Administration with Windows PowerShell (Windows Server AppFabric Caching)

  • Article

By using Windows PowerShell, you can administer the cache cluster, cache hosts, and the cache itself. If you are using a computer with the Cache Administration feature installed, there are two ways of using Windows PowerShell for managing the caching features of AppFabric. On the Start Menu, go to Administrative Tools, and then select Windows PowerShell Modules. Or you can go to the Start Menu, click All Programs, Windows Server AppFabric, and then click Caching Administration Windows PowerShell.

Note

On the Windows Vista, Windows 7, and Windows Server 2008 operating systems, you must run Windows PowerShell with administrative privileges for some administration commands to work correctly. For the Caching Administration Windows PowerShell shortcut, you must right-click the shortcut and select Run as administrator.

There are two main categories of AppFabric caching PowerShell commands: administration commands and configuration commands. This topic focuses on administration commands. For more information on the configuration commands, see Cache Configuration with Windows PowerShell (Windows Server AppFabric Caching). The tables in this topic divide the administration commands into categories. Some commands appear in more than one table, showing different parameters as they apply to each of the four categories of commands:

  • Cache Cluster-Related Commands

  • Cache Host-Related Commands

  • Cache-Related Commands

  • Console Management Commands

Getting Help within the Windows PowerShell Session

The information below provides a summary of the administration commands for the caching features of AppFabric. It is important to realize that you can get help inside your Windows PowerShell session as well. For example, the following command displays all of the administration commands:

get-command -module DistributedCacheAdministration

If you need help on a particular command, you can use the get-help command to do this. For example, the following command displays the complete help for the New-Cache command:

get-help New-Cache -full

Important Considerations

When using the Windows PowerShell commands described in this topic, it is important to consider the following points:

  • The security identity of the person using these Windows PowerShell commands must have administrator privileges on all cache servers in the cache cluster.

  • Parameter values for the commands are case sensitive. For example, if you create a cache called NamedCache1, the command Get-CacheConfig -CacheName namedcache1 will not work. You must match the case, as in Get-CacheConfig -CacheName NamedCache1.

  • When making XML-based cluster configuration changes with the Export-CacheClusterConfig and Import-CacheClusterConfig commands, you can change cluster configuration settings (XML attributes) in the XML file, but adding or removing named caches and cache hosts by inserting or removing XML elements is not supported.

  • The Start-CacheCluster, Stop-CacheCluster, and Restart-CacheCluster cache cluster commands involve coordinating the state of the cache host Windows service on all cache servers in the cluster. These commands may take longer when lead hosts perform the cluster management role; there must be a majority of lead hosts running while the rest of the cache hosts stop and start.

  • Always start and stop the Caching Service with the Start-CacheCluster, Stop-CacheCluster, and Restart-CacheCluster cache cluster commands. Starting and stopping the service from the services administrative tool can result in a hang. Also, these commands must be run from an elevated Windows PowerShell session with administrative privileges.

  • The Stop-CacheCluster or Restart-CacheCluster cache cluster commands cause all data to be flushed from the memory of all cache hosts in the cluster.

  • The Set-CacheConfig and Import-CacheClusterConfig commands require you to restart the cache cluster with Restart-CacheCluster for changes to take effect.

  • The Remove-Cache and New-Cache commands can be used to change a named cache configuration without impacting other named caches in the cluster.

The following table lists the Cache Administration Windows Powershell commands available to perform cluster-related operations.

Command Description

Use-CacheCluster

Sets the context of your Windows PowerShell session to the desired cache cluster.

When you start a Windows PowerShell session, you must first run this command. If it is on a cache host, you run the command with no parameters, because the parameters are taken from the cache configuration on the computer. If you are running it from a non-host computer, you can use the parameters below to specify the desired cache cluster.

Parameter (alias) descriptions are as follows:

  • Provider (P): The provider that is used to store the cluster configuration settings. This can be either System.Data.SqlClient or XML depending on how the configuration information is stored.

  • ConnectionString (C): The connection string to the database or location of the XML configuration file.

Start-CacheCluster

Starts all cache services in the cluster. Lead hosts are started first. Note that the cache services are not started automatically after a reboot, so either Start-CacheCluster or Start-CacheHost must be called to start the service. This command requires administrator privileges.

Stop-CacheCluster

Stops all cache services in the cluster. This command requires administrator privileges.

Restart-CacheCluster

Restarts all cache services in the cluster in the correct sequence. This command requires administrator privileges.

Get-CacheClusterHealth

Returns statistics on the health of the cache cluster.

Export-CacheClusterConfig

Designed to be used in tandem with Import-CacheClusterConfig, this command enables you to edit the cluster configuration settings with XML. For more information, see Edit Cluster Configuration Settings (Windows Server AppFabric Caching).

This command exports the cluster configuration settings, as they currently exist in the cluster, to the specified XML-based configuration file. This command can be used regardless of where you chose to store your cluster configuration settings (SQL Server or shared network folder).

Parameter (alias) description is:

  • File (F): The fully qualified path and name of the XML-based configuration file to create, describing the current cache cluster configuration settings.

Example: Export-CacheClusterConfig -File c:\Temp\CurrentClusterConfig.xml

Import-CacheClusterConfig

Designed to be used in tandem with Export-CacheClusterConfig, this command enables you to edit the cluster configuration settings with XML. For more information, see Edit Cluster Configuration Settings (Windows Server AppFabric Caching).

This command imports the cluster configuration settings as described in the specified XML-based configuration file. This command can be used regardless of where you chose to store your cluster configuration settings (SQL Server or shared network folder).

You must restart the cluster with the Restart-CacheCluster for any changes to take effect.

Parameter (alias) description is:

  • File (Fi): The fully qualified path and name of the XML-based configuration file that describes the cache cluster configuration settings to be applied to the cluster.

  • Force (Fo): Imports the configuration file without prompting for confirmation.

Example: Import-CacheClusterConfig -File c:\CurrentClusterConfig.xml

Grant-CacheAllowedClientAccount

Grants a Windows account access to the cache cluster. By default, any administrator accounts on the cache hosts have access to the cache cluster. Other accounts must be explicitly added to the allowed client account list by using this command.

Parameter (alias) description is:

  • Account (A): The Windows account to grant access to the cache cluster.

  • Force (F): Adds the specified client account without validating that it exists.

Revoke-CacheAllowedClientAccount

Revokes a Windows account access to the cache cluster. Note that this will not prevent administrators on the cache hosts from accessing the cache cluster.

Parameter (alias) description is:

  • Account (A): The Windows account to grant access to the cache cluster.

Get-Cache

When used with no parameters, lists information about all of the caches across the cache cluster.

Note

See the next table for information about how to use this command with the HostName parameter.

The following table lists commands available to perform cache host-related operations in Windows PowerShell.

Command Description

Get-CacheHost

Lists information about the specified cache host. If no parameters are passed, then it lists all cache services that are members of the cache cluster.

Parameter (alias) descriptions are as follows:

  • HostName (H): The name of the cache host.

  • CachePort (P): The cache port number of the cache host.

Example: Get-CacheHost

Get-CacheHostConfig

Returns the configuration information about the specified cache host.

Parameter (alias) descriptions are as follows:

  • HostName (H): The name of the cache host.

  • CachePort (P): The cache port number of the cache host.

Example: Get-CacheConfig -HostName CacheServer1 -CachePort 22233

Set-CacheHostConfig

Updates the cache host configuration to the values specified in the command parameters. Except for HostName and CachePort, all parameters are optional. For more information, see Edit Cluster Configuration Settings (Windows Server AppFabric Caching).

Parameter (alias) descriptions are as follows:

  • HostName (H): The name of the cache host.

  • CachePort (P): The current cache port number of the cache host.

  • ClusterPortNumber (CPort): The cluster port number that is used by the cache host.

  • ArbitratorPortNumber (APort): The new arbitrator port number.

  • ReplicationPortNumber (RPort): The new replication port number.

  • CacheSize (Size): The total amount of memory allocated for storing data on the cache host, in units of megabytes (MB).

  • HWM (HWM): The high watermark percentage of memory, when eviction should begin evicting objects that have not yet expired.

  • LWM (LWM): The low watermark percentage of memory, when eviction should begin evicting expired objects. After reaching HWM, when eviction should stop evicting objects that have not yet expired.

Example: Set-CacheConfig -HostName CacheServer1 -CachePort 22233 -LowWM 80

Start-CacheHost

Starts the specified cache service. After a cache server reboot, this command is required to allow the cache service to rejoin a running cache cluster. Note that if cache cluster is down, then you should use the Start-CacheCluster command instead. Also the cache services are not started automatically after a reboot, so either Start-CacheHost or Start-CacheCluster must be called to start the service.

Parameter (alias) descriptions are as follows:

  • HostName (HostN): The name of the cache host.

  • CachePort (P): The cache port number of the cache host.

  • HostTimeout(T): The time-out value in seconds for starting the specified cache host. The default is 60 seconds.

Example: Start-CacheHost -HostName CacheServer1 -CachePort 22233

Stop-CacheHost

Stops the specified cache service.

Note

The Stop-CacheHost command will not stop a cache host Windows service if it is performing the cluster management role and stopping the cache host will cause the entire cluster to shut down. For more information, see Lead Hosts and Cluster Management (Windows Server AppFabric Caching).

Parameter (alias) descriptions are as follows:

  • HostName (HostN): The name of the cache host.

  • CachePort (P): The cache port number of the cache host.

  • HostTimeout(T): The time-out value in seconds for starting the specified cache host.

Example: Stop-CacheHost -HostName CacheServer1 -CachePort 22233

Get-CacheStatistics

Shows statistics for the specified cache host including: total size (in bytes), and the number of cached objects, regions, named caches, requests, and cache misses.

Note

See the next table for information about how to use this command with the CacheName parameter.

Parameter (alias) descriptions are as follows:

  • HostName (H): The name of the cache host.

  • CachePort (P): The cache port number of the cache host.

Example: Get-CacheStatistics -HostName CacheServer1 -CachePort 22233

Get-Cache

Lists all caches and regions that reside on the specified cache host.

Parameter (alias) descriptions are as follows:

  • HostName (H): The name of the cache host.

  • CachePort (C): The cache port number of the cache host.

Example: Get-Cache -HostName CacheServer1 -CachePort 22233

Get-CacheRegion

Returns a list of all regions in the cache cluster. Regions can only be created or removed by the cache client. But the cache cluster determines the cache host on which they will reside. All parameters are optional.

Note

See the next table for information about how to use this command with the CacheName parameter.

Parameter (alias) descriptions are as follows:

  • MaxRegions: The maximum number of regions to display. This cannot be used with the MaxRegionsPerHost parameter.

  • MaxRegionsPerHost: The maximum number of regions to display from each host in the cache cluster.

Example: Get-CacheRegion -MaxRegionsPerHost 4

The following table lists commands available to perform cache-related operations by using Windows PowerShell.

Command Description

New-Cache

Creates a new named cache when the cluster is running. All values except for CacheName are optional.

Note

There is a limit of 128 named caches.

Parameter (alias) descriptions are as follows:

  • CacheName (N): The name of the cache.

  • Secondaries (S): A value of 1 enables the high availability feature. A value of 0 disables the high availability feature. The default value is 0.

  • NotificationsEnabled (Notif): A value of True enables the cache notifications feature, whereas a value of False disables it.

  • Eviction (Evict): A value of LRU enables Least Recently Used eviction. A value of None disables eviction. The default value is LRU.

    Warning

    A value of None may cause a cache host to run out of memory.

  • TimeToLive (T): The default time-out for objects stored in cache before they expire, in minutes. The default value is 10.

  • Expirable: A value of True enables expiration, whereas False disables expiration. The default is True.

Example: New-Cache -CacheName NamedCache1 -Secondaries 1 -TimeToLive 15

Remove-Cache

Removes a named cache, as specified by the CacheName parameter.

Parameter (alias) description is:

  • CacheName (N): The name of the cache.

Example: Remove-Cache -CacheName NamedCache1

Get-CacheConfig

Returns the configuration details for the named cache specified by the CacheName parameter.

Parameter (alias) description is:

  • CacheName (N): The name of the cache.

Example: Get-CacheConfig -CacheName NamedCache1

Set-CacheConfig

Updates the configuration settings of the named cache, as specified by the CacheName parameter.

The cache cluster may not be running when using the CacheName parameter to make cache changes. Alternatively, you may want to consider using Remove-Cache and New-Cache commands. These can be used to change a named cache configuration without impacting other named caches in the cluster by having to stop the cluster.

For more information, see Edit Cache Configuration Settings with Windows PowerShell (Windows Server AppFabric Caching).

Parameter (alias) descriptions are as follows:

  • CacheName (N): The name of the cache.

  • Secondaries (S): A value of 1 enables the high availability feature. A value of 0 disables the high availability feature. The default value is 0. Note that this feature is only supported for cache hosts running the Enterprise or DataCenter editions of Windows Server.

  • NotificationsEnabled (Notif): A value of True enables the cache notifications feature, whereas a value of False disables it.

  • Eviction (Evict): A value of LRU enables Least Recently Used eviction. A value of None disables eviction. The default value is LRU.

    Warning

    A value of None may cause a cache host to run out of memory.

  • TimeToLive (T): The default time-out for objects stored in cache before they expire, in minutes. The default value is 10.

  • Expirable: A value of True enables expiration, whereas False disables expiration. The default is True.

Example: Set-CacheConfig -CacheName NamedCache1 -TimeToLive 30

Get-CacheStatistics

Returns statistics of a named cache, as specified by the CacheName parameter.

Note

See the previous table for information about how to use this command with the HostName and CachePort parameters.

Parameter (alias) description is:

  • CacheName (N): The name of the cache.

Example: Get-CacheStatistics -CacheName NamedCache1

Get-CacheRegion

Returns a list of all regions in a named cache, as specified by the CacheName parameter. Regions can only be created or removed by the cache client. The cache cluster controls on which cache host each region will reside.

Note

See the previous table for information about how to use this command with the HostName and CachePort parameters.

Parameter (alias) description is:

  • CacheName (N): The name of the cache.

Example: Get-CacheRegion -CacheName NamedCache1

Console Management Commands

The following table lists commands available to perform operations related to managing the Windows PowerShell-based cache administration tool.

Command Description

Set-CacheLogging

This command enables file-based logging for your Windows PowerShell-based cache administration tool session. The event tracing initiated by this command lasts only for the duration of the Windows PowerShell sessions from which it was called.

By default, logging is enabled at the VERBOSE level. The default log file is in the users %temp% directory with a name that consists of the prefix DCacheAdministration followed by the process identifier and creation time stamp.

If a file by the same name is already present, Windows PowerShell tries to append to the log file.

Parameter (alias) descriptions are:

  • LogLevel (L): The event level specifying the types of events captured by the trace. Valid values are NONE, ERROR, WARNING, INFO, and VERBOSE.

  • File (F): An absolute folder or file path where the logs should be written. If the file name is not specified, it will default to DCacheAdminTrace[<ProcessId>].log, where <ProcessId> is the number of the Windows PowerShell session's Windows process ID. ".log" is appended to all file names that are specified.

This example creates the file c:\WarningLog.log that captures warning and error messages:

Set-CacheLogging -LogLevel WARNING -File c:\WarningLog

This command tracks events only for the Windows PowerShell session, not the cache client or cache host.

Invoke-GC

Manually invokes garbage collection on the cache cluster to free unused memory. This is only available for special circumstances. Typically garbage collection is managed by the .NET Framework and the memory management features of the AppFabric cache cluster.

Get-Help

Provides Help information for all supported commands. This keyword may also be used with a "*" character to filter the amount of Help information displayed, for example:

Get-Help new*

Get-Help Start*

Get-Help *cache

Get-Help *cachehost

exit

Quits the Windows PowerShell session.

cls

Clears the Windows PowerShell screen.

See Also

Concepts

Cache Configuration with Windows PowerShell (Windows Server AppFabric Caching)
Configuration Settings (Windows Server AppFabric Caching)
Windows Server AppFabric Caching Configuration Options
Troubleshooting Windows Server AppFabric Caching
Windows Server AppFabric Caching Concepts
Developing a Cache Client (Windows Server AppFabric Caching)