Cache Administration with Windows PowerShell (AppFabric 1.1)
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, you can go to the Start Menu, click All Programs, Microsoft AppFabric 1.1 for Windows Server, and then click Caching Administration Windows PowerShell.
Note
You must run Windows PowerShell with administrative privileges for some administration commands to work correctly. For the Caching Administration Windows PowerShell shortcut, 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 (AppFabric 1.1 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
Command Name Changes in the Cumulative Update for AppFabric 1.1
The Cumulative Update for AppFabric 1.1 update included name changes to the Windows PowerShell commands for AppFabric. These changes improve the understandability and consistency of the commands. The following tables include the original command name (RTM) and the updated command. To obtain the update, see Cumulative update package 2 for Microsoft AppFabric 1.1 for Windows Server.
In order to preserve backwards compatibility, a PowerShell script has been provided to alias the new commands with the old command names. Any parameter name changes have been aliased within the PowerShell module itself.
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:
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.
Cache Cluster-Related Commands
The following table lists the Cache Administration Windows Powershell commands available to perform cluster-related operations.
Command (RTM)
Command (QFE)
Description
Use-CacheCluster
Connect-AFCacheClusterConfiguration
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 descriptions are as follows:
Provider: 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: The connection string to the database or location of the XML configuration file.
Start-CacheCluster
Start-AFCacheCluster
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
Stop-AFCacheCluster
Stops all cache services in the cluster. This command requires administrator privileges.
Restart-CacheCluster
Restart-AFCacheCluster
Restarts all cache services in the cluster in the correct sequence. This command requires administrator privileges.
Get-CacheClusterHealth
Get-AFCacheClusterHealth
Returns statistics on the health of the cache cluster.
Export-CacheClusterConfig
Export-AFCacheClusterConfiguration
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.
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 description is:
File: The fully qualified path and name of the XML-based configuration file to create, describing the current cache cluster configuration settings.
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.
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 description is:
File: 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: Imports the configuration file without prompting for confirmation.
RefreshNow: Changes the cache cluster configuration settings of the running cluster. This currently only works with settings related to memory management. However, even then, individual cache hosts must be restarted or added to the cluster in order for the memory management settings to take effect.
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 description is:
Account: The Windows account to grant access to the cache cluster.
Force: Adds the specified client account without validating that it exists.
Revoke-CacheAllowedClientAccount
Revoke-AFCacheAllowedClientAccount
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 description is:
Account: The Windows account to grant access to the cache cluster.
Get-Cache
Get-AFCache
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.
Update-CacheHostAllowedVersions
Update-AFCacheHostAllowedVersions
Updates the version ranges of cache hosts and cache clients permitted to access the cache cluster. Currently, the version numbers relate to the following releases:
1 = Windows Server AppFabric v1.0
3 = Microsoft AppFabric 1.1 for Windows Server
Parameter descriptions are as follows:
BeginClientVersion: The begin value of the cache client version range.
EndClientVersion: The end value of the cache client version range.
BeginServerVersion: The begin value of cache host version range.
EndServerVersion: The end value of the cache host version range.
Updates the cache configuration store after an upgrade of AppFabric. When upgrading to Microsoft AppFabric 1.1 for Windows Server, this has the visible effect of translating cache host names to their fully-qualified domain name (FQDN) equivalents.
Cache Host-Related Commands
The following table lists commands available to perform cache host-related operations in Windows PowerShell.
Command (RTM)
Command (QFE)
Description
Get-CacheHost
Get-AFCacheHost
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. Note that a status of Shutting Down indicates that a graceful shutdown is in progress.
Parameter descriptions are as follows:
HostName: The name of the cache host.
CachePort: The cache port number of the cache host.
Example: Get-CacheHost
Get-CacheHostConfig
Get-AFCacheHostConfiguration
Returns the configuration information about the specified cache host.
Parameter descriptions are as follows:
HostName: The name of the cache host.
CachePort: The cache port number of the cache host.
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.
Parameter descriptions are as follows:
HostName: The name of the cache host.
CachePort: The current cache port number of the cache host.
ClusterPortNumber: The cluster port number that is used by the cache host.
ArbitratorPortNumber: The new arbitrator port number.
ReplicationPortNumber: The new replication port number.
CacheSize: The total amount of memory allocated for storing data on the cache host, in units of megabytes (MB).
IsLeadHost: The lead host status for the cache host ("true" or "false").
HWM: The high watermark percentage of memory, when eviction should begin evicting objects that have not yet expired.
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.
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 descriptions are as follows:
HostName: The name of the cache host.
CachePort: The cache port number of the cache host.
HostTimeout: The time-out value in seconds for starting the specified cache host. The default is 60 seconds.
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 (AppFabric 1.1 Caching).
Parameter descriptions are as follows:
HostName: The name of the cache host.
CachePort: The cache port number of the cache host.
HostTimeout: The time-out value in seconds for starting the specified cache host.
Graceful: Specifies that a graceful shutdown should be initiated. A graceful shutdown moves cache items to other cache hosts before stopping the Caching Service. This avoids data loss and the requirement for cache clients to repopulate those items. Note that the cache cluster can be created using New-CacheCluster command with the GracefulShutdownEnabled option to make graceful shutdowns the default behavior of the Stop-CacheHost command. This also requires the cache cluster to specify the GracefulShutdownTimeout.
Warning
Only initiate a graceful shutdown when you have verified that there are enough servers and remaining memory to handle the cache items that are moved to the running servers. Otherwise the graceful shutdown could hang and must be cancelled.
Cancels a graceful shutdown that is in-progress. The cache host remains running, and no data is lost. Regular load balancing might follow if necessary.
Parameter descriptions are as follows:
HostName: The name of the cache host.
CachePort: The cache port number of the cache host.
Restart-CacheHost
Restart-AFCacheHost
Restarts the specified cache service. The settings are the same as those for Stop-CacheHost.
Get-CacheStatistics
Get-AFCacheStatistics
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 descriptions are as follows:
HostName: The name of the cache host.
CachePort: The cache port number of the cache host.
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 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
Cache-Related Commands
The following table lists commands available to perform cache-related operations by using Windows PowerShell.
Command (RTM)
Command (QFE)
Description
New-Cache
New-AFCache
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 descriptions are as follows:
CacheName: The name of the cache.
Secondaries: A value of 1 enables the high availability feature. A value of 0 disables the high availability feature. The default value is 0.
NotificationsEnabled: A value of True enables the cache notifications feature, whereas a value of False disables it.
Eviction: 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: 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.
MinSecondaries: The minimum number of secondary copies of an item required for write operations on that item to succeed. The default is 0.
WriteBehindEnabled: Enables the write-behind feature. The default is false.
WriteBehindInterval: The number of seconds by which time a cache item should be written to the provider after being written to the cache. The minimum is 60, and the default is 300.
WriteBehindRetryInterval: The retry interval, in seconds, to wait between retry attempts in the case of a connection failure to the write-behind provider. The default value is 60, which is also the minimum value.
WriteBehindRetryCount: The maximum number of connection retries to the write-behind provider. The default is -1, which means inifinite retries.
ReadThroughEnabled: Enables the read-through feature. The default is false.
Provider Type: The fully qualified name of the provider assembly type. This provider implements the write-behind and read-through features. The name is case-sensitive. For example: RTProvider.Provider, RTProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=80e2cb5f6ba933f0.
ProviderSettings: One or more key/value pairs that specify connection information for the provider. For example: @{"setting1"="value1";"setting2"="value2"}.
Removes a named cache, as specified by the CacheName parameter.
Parameter description is:
CacheName: The name of the cache.
Example: Remove-Cache -CacheName NamedCache1
Get-CacheConfig
Get-AFCacheConfiguration
Returns the configuration details for the named cache specified by the CacheName parameter.
Parameter description is:
CacheName: The name of the cache.
Example: Get-CacheConfig -CacheName NamedCache1
Set-CacheConfig
Set-AFCacheConfiguration
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.
Secondaries: 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: A value of True enables the cache notifications feature, whereas a value of False disables it.
Eviction: 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: 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.
MinSecondaries: The minimum number of secondary copies of an item required for write operations on that item to succeed. The default is 0.
WriteBehindEnabled: Enables the write-behind feature. The default is false.
WriteBehindInterval: The number of seconds by which time a cache item should be written to the provider after being written to the cache. The minimum is 60, and the default is 300.
WriteBehindRetryInterval: The retry interval, in seconds, to wait between retry attempts in the case of a connection failure to the write-behind provider. The default value is 60, which is also the minimum value.
WriteBehindRetryCount: The maximum number of connection retries to the write-behind provider. The default is -1, which means inifinite retries.
ReadThroughEnabled: Enables the read-through feature. The default is false.
Provider Type: The fully qualified name of the provider assembly type. This provider implements the write-behind and read-through features. The name is case-sensitive. For example: RTProvider.Provider, RTProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=80e2cb5f6ba933f0.
ProviderSettings: One or more key/value pairs that specify connection information for the provider. For example: @{"setting1"="value1";"setting2"="value2"}.
RefreshNow: Updates the read-through and write-behind settings on a running cache cluster. Other settings cannot be updated with this switch.
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 description is:
CacheName: 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 (RTM)
Command (QFE)
Description
Set-CacheLogging
Set-AFCacheLogging
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 descriptions are:
LogLevel: The event level specifying the types of events captured by the trace. Valid values are NONE, ERROR, WARNING, INFO, and VERBOSE.
File: 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:
This command tracks events only for the Windows PowerShell session, not the cache client or cache host.
Clear-CacheLogging
Clear-AFCacheLogging
Stops the logging that was started by Set-CacheLogging.
Invoke-CacheGC
Invoke-AFCacheGarbageCollector
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.