Администрирование кэша с помощью Windows PowerShell (AppFabric 1.1)

  • Статья

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 для Windows Server, and then click Caching Administration Windows PowerShell.

Примечание

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 PowerShell commands: administration commands and configuration commands. This topic focuses on administration commands. For more information on the configuration commands, see Настройка кэша с помощью Windows PowerShell (кэширование в AppFabric 1.1). 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 Обновление AppFabric 1.1 за март 2012 г.

The Обновление AppFabric 1.1 за март 2012 г. 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 March 2012 command name (QFE).

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:

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 (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 Изменение параметров конфигурации кластера.

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.

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

Import-CacheClusterConfig

Import-AFCacheClusterConfiguration

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 Изменение параметров конфигурации кластера.

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.

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

Grant-CacheAllowedClientAccount

Grant-AFCacheAllowedClientAccount

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.

Примечание

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 для Windows Server

Parameter descriptions are as follows:

  1. BeginClientVersion: The begin value of the cache client version range.

  2. EndClientVersion: The end value of the cache client version range.

  3. BeginServerVersion: The begin value of cache host version range.

  4. EndServerVersion: The end value of the cache host version range.

For more information, see Процедура обновления кластера кэша AppFabric (AppFabric 1.1).

Stop-CacheNonUpdatedHosts

Stop-AFCacheNonUpdatedHosts

Stops cache hosts whose version differs from the specified version values.

Parameter descriptions are as follows:

  1. BeginServerVersion: The begin value of cache host version range.

  2. EndServerVersion: The end value of the cache host version range.

  3. HostTimeout: The timeout in seconds to wait for each cache host to stop.

  4. Version: The code version of the cache host.

For more information, see Процедура обновления кластера кэша AppFabric (AppFabric 1.1).

Update-CacheConfigurationStore

Update-AFCacheConfigurationStore

Updates the cache configuration store after an upgrade of AppFabric. When upgrading to Microsoft AppFabric 1.1 для Windows Server, this has the visible effect of translating cache host names to their fully-qualified domain name (FQDN) equivalents.

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.

Example: Get-CacheConfig -HostName CacheServer1 -CachePort 22233

Set-CacheHostConfig

Set-AFCacheHostConfiguration

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 Изменение параметров конфигурации кластера.

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.

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

Start-CacheHost

Start-AFCacheHost

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.

Example: Start-CacheHost -HostName CacheServer1 -CachePort 22233

Stop-CacheHost

Stop-AFCacheHost

Stops the specified cache service.

Примечание

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 Ведущие узлы и управление кластером (кэширование в AppFabric 1.1).

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.

    Предупреждение

    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.

Example: Stop-CacheHost -HostName CacheServer1 -CachePort 22233

Stop-CacheHostShutdown

Stop-AFCacheHostShutdown

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.

Примечание

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.

Example: Get-CacheStatistics -HostName CacheServer1 -CachePort 22233

Get-Cache

Get-AFCache

Lists all caches and regions that reside on 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.

Example: Get-Cache -HostName CacheServer1 -CachePort 22233

Get-CacheRegion

Get-AFCacheRegion

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.

Примечание

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

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.

Примечание

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.

    Предупреждение

    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"}.

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

Remove-Cache

Remove-AFCache

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.

For more information, see Изменение параметров конфигурации кэша с помощью Windows PowerShell.

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

    Предупреждение

    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.

Example: Set-CacheConfig -CacheName NamedCache1 -TimeToLive 30

Get-CacheStatistics

Get-AFCacheStatistics

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

Примечание

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-CacheStatistics -CacheName NamedCache1

Get-CacheRegion

Get-AFCacheRegion

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.

Примечание

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:

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

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.

exit

exit

Quits the Windows PowerShell session.

cls

cls

Clears the Windows PowerShell screen.

См. также

Основные понятия

Настройка кэша с помощью Windows PowerShell (кэширование в AppFabric 1.1)
Параметры конфигурации
Параметры конфигурации кэша AppFabric
Устранение неполадок функций кэширования AppFabric
Основные принципы кэширования AppFabric (кэширование в AppFabric 1.1)
Разработка клиента кэша

  2012-04-05