Skip to content

Commit f919d05

Browse files
davidsmatlaksdwheeler
authored andcommitted
Fixes #4198, Fixes #4243 - Added note about limit of 32 parameter sets, removed duplicated code block (#4778)
* issues 4198 and 4243 * fixed note for parm set limit
1 parent 0e60f18 commit f919d05

File tree

7 files changed

+1558
-1504
lines changed

7 files changed

+1558
-1504
lines changed

developer/cmdlet/cmdlet-parameter-sets.md

Lines changed: 52 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -9,45 +9,78 @@ ms.topic: "article"
99
ms.assetid: f902fd4d-8f6e-4ef1-b07f-59983039a0d1
1010
caps.latest.revision: 10
1111
---
12-
# Cmdlet Parameter Sets
1312

14-
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.
13+
# Cmdlet parameter sets
1514

16-
## Examples of Parameter Sets
15+
PowerShell uses parameter sets to enable you to write a single cmdlet that can do different actions
16+
for different scenarios. Parameter sets enable you to expose different parameters to the user. And,
17+
to return different information based on the parameters specified by the user.
1718

18-
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.
19+
## Examples of parameter sets
1920

20-
## Unique Parameter
21+
For example, the PowerShell `Get-EventLog` cmdlet returns different information depending on whether
22+
the user specifies the **List** or **LogName** parameter. If the **List** parameter is specified,
23+
the cmdlet returns information about the log files themselves but not the event information they
24+
contain. If the **LogName** parameter is specified, the cmdlet returns information about the events
25+
in a specific event log. The **List** and **LogName** parameters identify two separate parameter
26+
sets.
2127

22-
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.
28+
## Unique parameter
2329

24-
## Multiple Parameter Sets
30+
Each parameter set must have a unique parameter that the PowerShell runtime uses to expose the
31+
appropriate parameter set. If possible, the unique parameter should be a mandatory parameter. When a
32+
parameter is mandatory, the user must specify the parameter, and the PowerShell runtime uses that
33+
parameter to identify the parameter set. The unique parameter can't be mandatory if your cmdlet is
34+
designed to run without specifying any parameters.
2535

26-
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.
36+
## Multiple parameter sets
37+
38+
In the following illustration, the left column shows three valid parameter sets. **Parameter A** is
39+
unique to the first parameter set, **parameter B** is unique to the second parameter set, and
40+
**parameter C** is unique to the third parameter set. In the right column, the parameter sets don't
41+
have a unique parameter.
2742

2843
![ps_parametersets](../media/ps-parametersets.gif)
2944

30-
## Parameter Set Requirements
45+
## Parameter set requirements
3146

3247
The following requirements apply to all parameter sets.
3348

34-
- Each parameter set must have at least one unique parameter. If possible, make this parameter a mandatory parameter.
49+
- Each parameter set must have at least one unique parameter. If possible, make this parameter a
50+
mandatory parameter.
3551

36-
- A parameter set that contains multiple positional parameters must define unique positions for each parameter. No two positional parameters can specify the same position.
52+
- A parameter set that contains multiple positional parameters must define unique positions for each
53+
parameter. No two positional parameters can specify the same position.
3754

38-
- 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`.
55+
- Only one parameter in a set can declare the `ValueFromPipeline` keyword with a value of `true`.
56+
Multiple parameters can define the `ValueFromPipelineByPropertyName` keyword with a value of
57+
`true`.
3958

4059
- If no parameter set is specified for a parameter, the parameter belongs to all parameter sets.
4160

42-
## Default Parameter Sets
61+
> [!NOTE]
62+
> For a cmdlet or function, there is a limit of 32 parameter sets.
63+
64+
## Default parameter sets
4365

44-
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](./cmdlet-attribute-declaration.md).
66+
When multiple parameter sets are defined, you can use the `DefaultParameterSetName` keyword of the
67+
**Cmdlet** attribute to specify the default parameter set. PowerShell uses the default parameter set
68+
if it can't determine the parameter set to use based on the information provided by the command. For
69+
more information about the **Cmdlet** attribute, see [Cmdlet Attribute Declaration](./cmdlet-attribute-declaration.md).
4570

46-
## Declaring Parameter Sets
71+
## Declaring parameter sets
4772

48-
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.
73+
To create a parameter set, you must specify the `ParameterSetName` keyword when you declare the
74+
**Parameter** attribute for every parameter in the parameter set. For parameters that belong to
75+
multiple parameter sets, add a **Parameter** attribute for each parameter set. This attribute
76+
enables you to define the parameter differently for each parameter set. For example, you can define
77+
a parameter as mandatory in one set and optional in another. However, each parameter set must
78+
contain one unique parameter. For more information, see [Parameter Attribute Declaration](parameter-attribute-declaration.md).
4979

50-
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.
80+
In the following example, the **UserName** parameter is the unique parameter of the `Test01`
81+
parameter set, and the **ComputerName** parameter is the unique parameter of the `Test02` parameter
82+
set. The **SharedParam** parameter belongs to both sets and is mandatory for the `Test01` parameter
83+
set but optional for the `Test02` parameter set.
5184

5285
```csharp
5386
[Parameter(Position = 0, Mandatory = true,
@@ -75,12 +108,5 @@ public string SharedParam
75108
get { return sharedParam; }
76109
set { sharedParam = value; }
77110
}
78-
private string sharedParam; [Parameter(Position = 0, Mandatory = true,
79-
ParameterSetName = "Test01")]
80-
public string UserName
81-
{
82-
get { return userName; }
83-
set { userName = value; }
84-
}
85-
private string userName;
86-
```
111+
private string sharedParam;
112+
```

0 commit comments

Comments
 (0)