You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: developer/cmdlet/cmdlet-parameter-sets.md
+52-26Lines changed: 52 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,45 +9,78 @@ ms.topic: "article"
9
9
ms.assetid: f902fd4d-8f6e-4ef1-b07f-59983039a0d1
10
10
caps.latest.revision: 10
11
11
---
12
-
# Cmdlet Parameter Sets
13
12
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
15
14
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.
17
18
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 parametersets
19
20
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.
21
27
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
23
29
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.
25
35
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
The following requirements apply to all parameter sets.
33
48
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.
35
51
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.
37
54
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`.
39
58
40
59
- If no parameter set is specified for a parameter, the parameter belongs to all parameter sets.
41
60
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
43
65
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).
45
70
46
-
## Declaring Parameter Sets
71
+
## Declaring parameter sets
47
72
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).
49
79
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
0 commit comments