Cache Administration with PowerShell (Velocity)

  • Article

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

PowerShell 1.0 is the exclusive management tool for Microsoft project code named "Velocity." With more than 130 standard command line tools, this new administration-focused scripting language helps you achieve control and productivity. In addition to the standard command line tools that come with PowerShell, "Velocity" provides additional commands for managing your distributed cache environment.

By using PowerShell, you can administer the cache cluster, cache hosts, and the cache itself. You can start this tool from the PowerShell shortcut that is installed on the desktop of each cache server.

The tables in this document describe the PowerShell commands available for administering "Velocity." Some commands appear in more than one table, showing different parameters as they apply to each of the three categories of commands:

  • Cache Cluster-related Commands

  • Cache Host-related Commands

  • Cache-related Commands

  • Console Management Commands

Important Considerations

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

  • The security identity of the person using these 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.

  • 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 host running while the rest of the cache hosts stop and start.

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

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

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

Note

On Microsoft Windows Vista and Microsoft Windows Server 2008 operating systems, you must right-click the "Velocity" PowerShell shortcut and select Run as administrator for the cache administration tool to work correctly.

The following table lists the "Velocity" PowerShell commands available to perform cluster-related operations.

Command Description

Use-CacheCluster

[[-Name] <Name>

[-Provider] <Provider>

[-ConnectionString] <ConnectionString>]

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

When starting a PowerShell session on a cache host, this command runs automatically, by using the connection parameters specified in the cache host configuration file.

Parameter (alias) descriptions are as follows:

  • Name (N): The name of the cache cluster.

  • Provider (P): The provider that is used to store the cluster configuration settings.

  • ConnectionString (C): The connection string to the database.

Start-CacheCluster

Starts all cache host services in the cluster. Lead hosts are started first.

Stop-CacheCluster

Stops all cache host services in the cluster.

Restart-CacheCluster

Restarts all cache host services in the cluster in the correct sequence.

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 How to: Edit Cluster Configuration Settings (Velocity).

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 for the XML-based configuration file. If a file already exists by this name, it will be overwritten.

Example: Export-CacheClusterConfig -File c:\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 How to: Edit Cluster Configuration Settings (Velocity).

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 (F): 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.

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

The following table lists commands available to perform cluster-related operations in PowerShell.

Command Description

Get-CacheHost

Lists all cache host services that are members of the cache cluster.

Example: Get-CacheHost

Get-CacheConfig

[-HostName] <HostName>

[-CachePort] <CachePort>

(cache host-related parameters)

Returns the configuration information about the specified cache host.

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-CacheConfig -HostName CacheServer1 -CachePort 22233

Set-CacheConfig

[-HostName] <HostName>

[-CachePort] <CachePort>

[-ClusterPortNumber <ClusterPortNumber>]

[-CachePortNumber <CachePortNumber>]

[-CacheSize <CacheSize>]

[-HighWM <HighWM>]

[-LowWM <LowWM>]

(cache host-related parameters)

Updates the cache host configuration to the values specified in the command parameters Except for H and P, all parameters are optional. For more information, see How to: Edit Cluster Configuration Settings (Velocity).

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 current cache port number of the cache host.

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

  • CachePortNumber (SPort): The new cache port number.

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

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

  • LowWM (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

[-HostName] <HostName>

[-CachePort] <CachePort>

Starts the specified cache host service. After a cache server reboot, this command is required to allow the cache host service to re-join a running 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: Start-CacheHost -HostName CacheServer1 -CachePort 22233

Stop-CacheHost

[-HostName] <HostName>

[-CachePort] <CachePort>

Stops the specified cache host 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 (Velocity).

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: Stop-CacheHost -HostName CacheServer1 -CachePort 22233

Get-CacheStatistics

[-HostName] <HostName>

[-CachePort] <CachePort>

(cache host-related parameters)

Shows statistics for the specified cache host including: size (in bytes), number of caches, regions, cached objects, 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

[-HostName] <HostName>

[-CachePort] <CachePort>

(cache host-related parameters)

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

Note: See the next table for information about using this command with no parameters.

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-Cache -HostName CacheServer1 -CachePort 22233

Get-CacheRegion

[-HostName] <HostName>

[-CachePort] <CachePort>

(cache host-related parameters)

Returns a list of all regions in the cache cluster or only those on a cache host, as specified by the HostName and CachePort parameters. Regions can only be created or removed by the cache client. But, the cache cluster controls on which cache host they will reside.

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-CacheRegion -HostName CacheServer1 -CachePort 22233

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

Command Description

New-Cache

[-CacheName] <CacheName>

[-Secondaries <Secondaries>]

[-NotificationsEnabled]

[-Eviction <Eviction>]

[-TTL <TTL>]

[-NotExpirable]

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

For more information, see How to: Edit Cache Configuration Settings with PowerShell (Velocity).

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): When this parameter is present, the cache notifications feature will be enabled.

  • Eviction (E): 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.

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

  • NotExpirable (NE): Use this switch parameter to disable expiration; otherwise expiration will be enabled at the default settings.

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

Remove-Cache

[-CacheName] <CacheName>

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

(with no parameters)

Lists all caches and regions in the cluster and the cache host where each region resides.

Get-Cache

[-HostName] <HostName>

[-CachePort] <CachePort>

(cache host-related parameters)

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 (P): The cache port number of the cache host.

Example: Get-Cache -HostName CacheServer1 -CachePort 22233

Get-CacheConfig

[-CacheName] <CacheName>

(cache-related parameters)

Returns the configuration details for the named cache 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-CacheConfig -CacheName NamedCache1

Set-CacheConfig

[-CacheName] <CacheName>

[-Secondaries <Secondaries>]

[-NotificationsEnabled]

[-Eviction <Eviction>]

[-TTL <TTL>]

[-NotExpirable]

(cache-related parameters)

Updates the configuration settings of the named cache, as specified by the CacheName parameter. This command re-creates the named cache; all desired parameters do not persist and must be re-specified.

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.

For more information, see How to: Edit Cache Configuration Settings with PowerShell (Velocity).

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

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): When this parameter is present, the cache notifications feature will be enabled.

  • Eviction (E): A value of LRU enables Least Recently Used (LRU) 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.

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

  • NotExpirable (NE): Use this switch parameter to disable expiration; otherwise expiration will be enabled at the default settings.

Example: Set-CacheConfig -CacheName NamedCache1 -TTL 30

Get-CacheStatistics

[-CacheName] <CacheName>

(cache-related parameters)

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

[-CacheName] <CacheName>

(cache-related parameters)

Returns a list of all regions in the cache cluster or only those 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 PowerShell-based cache administration tool.

Command Description

Set-CacheLogging

[-LogLevel]<LogLevel>

[[-File]<LogFilePath>]

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

By default, logging is enabled with a LogLevel of ERROR and a File value directing the logs to the V1.0\AdminLogs installation sub folder.

If a file by the same name is already present, 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. Valued 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 PowerShell session's Windows' process ID. ".log" is appended to all filenames 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 PowerShell session, not the cache client or cache host. For information about log sinks on the cache client and cache host, see Log Sink Settings (Velocity).

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

Get-CacheHelp

Provides a summary of "Velocity"-specific commands.

exit

Quits the PowerShell session.

cls

Clears the PowerShell screen.

See Also

Concepts

Configuration (Velocity)
Troubleshooting (Velocity)

Other Resources

Installation and Deployment (Velocity)
Configuration Settings (Velocity)
Cache Concepts (Velocity)
Programming Guide (Velocity)