Export (0) Print
Expand All

Cmdlet Parameter Sets

Windows PowerShell uses parameter sets to enable you to write a single cmdlet that can perform different actions for different scenarios. Parameter sets enable you to expose different parameters to the user and to return different information based on the parameters specified by the user.

Examples of Parameter Sets

For example, the Get-EventLog cmdlet (provided by Windows PowerShell) returns different information depending on whether the user specifies the List or LogName parameter. If the List parameter is specified, the cmdlet returns information about the log files themselves but not the event information they contain. If the LogName parameter is specified, the cmdlet returns information about the events in a specific event log. The List and LogName parameters identify two separate parameter sets.

Unique Parameter

Each parameter set must have a unique parameter that the Windows PowerShell runtime can use to expose the appropriate parameter set. If possible, the unique parameter should be a mandatory parameter. When a parameter is mandatory, the user is forced to specify the parameter, and the Windows PowerShell runtime can use that parameter to identify the parameter set to use. The unique parameter cannot be mandatory if your cmdlet is designed to be run without specifying any parameters.

Multiple Parameter Sets

In the following illustration, the left column shows three valid parameter sets. Parameter A is unique to the first parameter set, parameter B is unique to the second parameter set, and parameter C is unique to the third parameter set. However, in the right column, the parameter sets do not have a unique parameter.


Parameter Set Requirements

The following requirements apply to all parameter sets.

  • Each parameter set must have at least one unique parameter. If possible, make this parameter a mandatory parameter.

  • A parameter set that contains multiple positional parameters must define unique positions for each parameter. No two positional parameters can specify the same position.

  • Only one parameter in a set can declare the ValueFromPipeline keyword with a value of true. Multiple parameters can define the ValueFromPipelineByPropertyName keyword with a value of true.

  • If no parameter set is specified for a parameter, the parameter belongs to all parameter sets.

Default Parameter Sets

When multiple parameter sets are defined, you can use the DefaultParameterSetName keyword of the Cmdlet attribute to specify the default parameter set. Windows PowerShell uses the default parameter set if it cannot determine the parameter set to use based on the information provided by the command. For more information about the Cmdlet attribute, see Cmdlet Attribute Declaration.

Declaring Parameter Sets

To create a parameter set, you must specify the ParameterSetName keyword when you declare the Parameter attribute for every parameter in the parameter set. For parameters that belong to multiple parameter sets, add a Parameter attribute for each parameter set. This enables you to define the parameter differently for each parameter set. For example, you can define a parameter as mandatory in one set and optional in another. However, each parameter set must contain one unique parameter.

In the following example, the UserName parameter is the unique parameter of the Test01 parameter set, and the ComputerName parameter is the unique parameter of the Test02 parameter set. The SharedParam parameter belongs to both sets and is mandatory for the Test01 parameter set but optional for the Test02 parameter set.

[Parameter(Position = 0, Mandatory = true, 
           ParameterSetName = "Test01")]
public string UserName
  get { return userName; }
  set { userName = value; }
private string userName;

[Parameter(Position = 0, Mandatory = true, 
           ParameterSetName = "Test02")]
public string ComputerName
  get { return computerName; }
  set { computerName = value; }
private string computerName;

[Parameter(Mandatory= true, ParameterSetName = "Test01")]
[Parameter(ParameterSetName = "Test02")]
public string SharedParam
    get { return sharedParam; }
    set { sharedParam = value; }
private string sharedParam;

© 2014 Microsoft