Using Cmdlet Parameters

Updated: August 9, 2012

Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0

The parameters of a cmdlet let you customize the behavior of the cmdlet. This topic explains elements that are common to all Windows PowerShell cmdlet parameters. For information about specific parameters, see the Help topic for the cmdlet.

Cmdlet Parameter Basics

Windows PowerShell cmdlets can have none, one, or many parameters. Most cmdlets have several parameters, and it's important to become acquainted with them, because they can make the cmdlet do just what you need it to do.

Cmdlet parameters are identified by a hyphen (-) preceding the parameter name. (Slashes (/ and \) are not used with parameters in Windows PowerShell.)

When you type a parameter name, you can type the whole name, but you only need to type enough characters to distinguish the parameter name from the names other parameters of the cmdlet.

For example, the Get-Help cmdlet has a parameter named "Detailed," but you can type "-det", which is just enough to distinguish it from the Debug parameter of Get-Help.

Some parameter names are optional. You can use the parameter by typing a parameter value without typing the parameter name. However, if you omit the parameter name, the parameter value must appear in the in the same position in the command that it appears in the syntax diagram.

For example, the Get-Help cmdlet has a Name parameter that specifies the name of a cmdlet or concept. You can type the name of the Name parameter or leave it out. To get Help for the Get-Alias cmdlet, type:

get-help -name get-alias

or

get-help get-alias

To determine which parameter names are options, see the syntax diagram in the Help topic. Optional parameter names appear in square brackets, such as:

Get-Help [[-Name] <string>]...

For more information about the syntax diagram, see about_Command_Syntax.

Finding Cmdlet Parameters

The Get-Command and Get-Help cmdlets both list the parameters of a cmdlet. Get-Command gets its information from the cmdlet code. Get-Help gets its information from the Help topic for the cmdlet.

Finding Cmdlet Parameters in Help Topics

Each cmdlet Help topic lists and describes the parameters of a cmdlet. To display the parameter section of a Help topic, use the Detailed or Parameter parameters of the Get-Help cmdlet. The Parameters parameter of the Get-Help cmdlet is particularly useful because it displays only the parameters and includes detailed information about the parameters.

To display basic descriptions of all parameters of a cmdlet, along with other useful information about the parameters, use the Detailed parameter of Get-Help.

For example, to display detailed information about the Get-Service cmdlet, including its parameters, type:

get-help get-service -detailed

Use the Parameter parameter of Get-Help to display detailed information about the parameters of a cmdlet. In the value of the Parameter parameter, you can type a parameter name or use a wildcard character (*) to display multiple parameters.

For example, to display detailed information about all the parameters of the Get-Service cmdlet, type:

get-help get-service -parameter *

To display detailed information about a particular parameter, type the parameter name in the value of the Parameter parameter of Get-Help. For example, to display a detailed explanation of the RequiredServices parameter of the Get-Service cmdlet, type:

get-help get-service -parameter RequiredServices

Finding Cmdlet Parameters in Code

The Get-Command cmdlet displays cmdlet parameters in its syntax diagram and in the Parameters property of the CmdletInfo object that Get-Command returns.

For example, to list the parameters of the Get-Service cmdlet, type:

(get-command get-service).parameters

To display the syntax diagram for the Get-Service cmdlet, type:

(get-command get-service).definition

Common Parameters

All cmdlets have a set of parameters that are called common parameters. This feature provides a consistent interface to Windows PowerShell.

Some of the cmdlets use the common parameters, but others do not. The effect of each common parameter varies from cmdlet to cmdlet, and some common parameters have no effect in some cmdlets.

For more information about the common parameters, type:

get-help about_commonparameters