diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index f8e9e3ef8200..a0f57953b52a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,7 +1,7 @@ --- description: Explains how to add parameters to advanced functions. Locale: en-US -ms.date: 01/06/2025 +ms.date: 02/25/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced_Parameters @@ -36,8 +36,8 @@ combination with the `[Alias()]` attribute or any of the parameter validation attributes. Parameter names follow the rules for variable names. Parameter names consist of -decimal digits, alphabetic characters, and underscores. For a complete list of -naming rules, see [about_Variables][20]. +decimal digits, alphabetical characters, and underscores. For a complete list +of naming rules, see [about_Variables][20]. > [!IMPORTANT] > It's possible to define a parameter that starts with a decimal digit. @@ -189,24 +189,23 @@ has a **false** value. For example, the **Recurse** parameter of `Get-ChildItem` is a switch parameter. -To create a switch parameter in a function, specify the `switch` type in the -parameter definition. - -For example, your function may have an option to output data as a byte array: +To create a switch parameter in a function, specify the `[switch]` type in the +parameter definition. The following example shows the definition of a switch +parameter that could be used to provide an option to output data as a byte +array: ```powershell param([switch]$AsByteArray) ``` -Switch parameters are easy to use and are preferred over Boolean parameters, -which have a less natural syntax for PowerShell. +Switch parameters are easy to use and are preferred over Boolean parameters +that have a less natural syntax for PowerShell. -For example, to use a switch parameter, the user types the parameter in the -command. +To use a switch parameter, include the parameter in the command. For example: `-IncludeAll` -To use a Boolean parameter, the user types the parameter and a Boolean value. +To use a Boolean parameter, you must provide the parameter and a Boolean value. `-IncludeAll $true` @@ -217,29 +216,37 @@ value is required. ### Switch parameter design considerations -- Switch parameters shouldn't be given default values. They should always +- Don't set a default value for a switch parameter. Switch parameter always default to false. -- Switch parameters are excluded from positional parameters by default. Even - when other parameters are implicitly positional, switch parameters aren't. - You _can_ override that in the Parameter attribute, but it will confuse - users. -- Switch parameters should be designed so that setting them moves a command - from its default behavior to a less common or more complicated mode. The - simplest behavior of a command should be the default behavior that doesn't - require the use of switch parameters. -- Switch parameters shouldn't be mandatory. The only case where it's necessary - to make a switch parameter mandatory is when it's needed to differentiate a +- Don't make switch parameters positional. By default, switch parameters are + excluded from positional parameters. You _can_ override that in the + **Parameter** attribute, but it can confuse users. +- Design switch parameters so that using parameter changes the default behavior + of the command to a less common or more complicated mode. The simplest + behavior of a command should be the default behavior that doesn't require the + use of switch parameters. +- Don't make switch parameters mandatory. The only case where it's helpful to + make a switch parameter mandatory is when it's needed to differentiate a parameter set. -- Explicitly setting a switch from a boolean can be done with - `-MySwitch:$boolValue` and in splatting with - `$params = @{ MySwitch = $boolValue }`. -- Switch parameters are of type `SwitchParameter`, which implicitly converts to - Boolean. The parameter variable can be used directly in a conditional - expression. For example: +- Use the switch parameter variable directly in a conditional expression. The + `SwitchParameter` type implicitly converts to Boolean. For example: + + ```powershell + if ($MySwitch) { ... } + ``` + +- Always base the behavior controlled by the switch on the value of the switch, + not the presence of the parameter. There are several ways to test for the + presence of a switch parameters: - `if ($MySwitch) { ... }` + - `$PSBoundParameters` contains the switch parameter name as a key + - `$MyInvocation.BoundParameters` contains the switch parameter name as a key + - `$PSCmdlet.ParameterSetName` when the switch defines a unique parameter set - There's no need to write `if ($MySwitch.IsPresent) { ... }` + For example, it's possible to provide an explicit value for the switch using + `-MySwitch:$false` or splatting. If you only test for the presence of the + parameter, the command behaves as if the switch value is `$true` instead of + `$false`. ## Dynamic parameters @@ -594,7 +601,7 @@ function Test-Remainder { "${i}: $($Remaining[$i])" } } -Test-Remainder first one,two +Test-Remainder first one, two ``` ```Output diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index fa57cd7758e8..23a0b4c58ae1 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,7 +1,7 @@ --- description: Explains how to add parameters to advanced functions. Locale: en-US -ms.date: 01/06/2025 +ms.date: 02/25/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced_Parameters @@ -36,8 +36,8 @@ combination with the `[Alias()]` attribute or any of the parameter validation attributes. Parameter names follow the rules for variable names. Parameter names consist of -decimal digits, alphabetic characters, and underscores. For a complete list of -naming rules, see [about_Variables][20]. +decimal digits, alphabetical characters, and underscores. For a complete list +of naming rules, see [about_Variables][20]. > [!IMPORTANT] > It's possible to define a parameter that starts with a decimal digit. @@ -184,24 +184,23 @@ has a **false** value. For example, the **Recurse** parameter of `Get-ChildItem` is a switch parameter. -To create a switch parameter in a function, specify the `switch` type in the -parameter definition. - -For example, your function may have an option to output data as a byte array: +To create a switch parameter in a function, specify the `[switch]` type in the +parameter definition. The following example shows the definition of a switch +parameter that could be used to provide an option to output data as a byte +array: ```powershell param([switch]$AsByteArray) ``` -Switch parameters are easy to use and are preferred over Boolean parameters, -which have a less natural syntax for PowerShell. +Switch parameters are easy to use and are preferred over Boolean parameters +that have a less natural syntax for PowerShell. -For example, to use a switch parameter, the user types the parameter in the -command. +To use a switch parameter, include the parameter in the command. For example: `-IncludeAll` -To use a Boolean parameter, the user types the parameter and a Boolean value. +To use a Boolean parameter, you must provide the parameter and a Boolean value. `-IncludeAll $true` @@ -212,29 +211,37 @@ value is required. ### Switch parameter design considerations -- Switch parameters shouldn't be given default values. They should always +- Don't set a default value for a switch parameter. Switch parameter always default to false. -- Switch parameters are excluded from positional parameters by default. Even - when other parameters are implicitly positional, switch parameters aren't. - You _can_ override that in the Parameter attribute, but it will confuse - users. -- Switch parameters should be designed so that setting them moves a command - from its default behavior to a less common or more complicated mode. The - simplest behavior of a command should be the default behavior that doesn't - require the use of switch parameters. -- Switch parameters shouldn't be mandatory. The only case where it's necessary - to make a switch parameter mandatory is when it's needed to differentiate a +- Don't make switch parameters positional. By default, switch parameters are + excluded from positional parameters. You _can_ override that in the + **Parameter** attribute, but it can confuse users. +- Design switch parameters so that using parameter changes the default behavior + of the command to a less common or more complicated mode. The simplest + behavior of a command should be the default behavior that doesn't require the + use of switch parameters. +- Don't make switch parameters mandatory. The only case where it's helpful to + make a switch parameter mandatory is when it's needed to differentiate a parameter set. -- Explicitly setting a switch from a boolean can be done with - `-MySwitch:$boolValue` and in splatting with - `$params = @{ MySwitch = $boolValue }`. -- Switch parameters are of type `SwitchParameter`, which implicitly converts to - Boolean. The parameter variable can be used directly in a conditional - expression. For example: +- Use the switch parameter variable directly in a conditional expression. The + `SwitchParameter` type implicitly converts to Boolean. For example: + + ```powershell + if ($MySwitch) { ... } + ``` + +- Always base the behavior controlled by the switch on the value of the switch, + not the presence of the parameter. There are several ways to test for the + presence of a switch parameters: - `if ($MySwitch) { ... }` + - `$PSBoundParameters` contains the switch parameter name as a key + - `$MyInvocation.BoundParameters` contains the switch parameter name as a key + - `$PSCmdlet.ParameterSetName` when the switch defines a unique parameter set - There's no need to write `if ($MySwitch.IsPresent) { ... }` + For example, it's possible to provide an explicit value for the switch using + `-MySwitch:$false` or splatting. If you only test for the presence of the + parameter, the command behaves as if the switch value is `$true` instead of + `$false`. ## Dynamic parameters diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index cd03414c1c02..8e262fd0d25d 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,7 +1,7 @@ --- description: Explains how to add parameters to advanced functions. Locale: en-US -ms.date: 01/06/2025 +ms.date: 02/25/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced_Parameters @@ -36,8 +36,8 @@ combination with the `[Alias()]` attribute or any of the parameter validation attributes. Parameter names follow the rules for variable names. Parameter names consist of -decimal digits, alphabetic characters, and underscores. For a complete list of -naming rules, see [about_Variables][20]. +decimal digits, alphabetical characters, and underscores. For a complete list +of naming rules, see [about_Variables][20]. > [!IMPORTANT] > It's possible to define a parameter that starts with a decimal digit. @@ -184,24 +184,23 @@ has a **false** value. For example, the **Recurse** parameter of `Get-ChildItem` is a switch parameter. -To create a switch parameter in a function, specify the `switch` type in the -parameter definition. - -For example, your function may have an option to output data as a byte array: +To create a switch parameter in a function, specify the `[switch]` type in the +parameter definition. The following example shows the definition of a switch +parameter that could be used to provide an option to output data as a byte +array: ```powershell param([switch]$AsByteArray) ``` -Switch parameters are easy to use and are preferred over Boolean parameters, -which have a less natural syntax for PowerShell. +Switch parameters are easy to use and are preferred over Boolean parameters +that have a less natural syntax for PowerShell. -For example, to use a switch parameter, the user types the parameter in the -command. +To use a switch parameter, include the parameter in the command. For example: `-IncludeAll` -To use a Boolean parameter, the user types the parameter and a Boolean value. +To use a Boolean parameter, you must provide the parameter and a Boolean value. `-IncludeAll $true` @@ -212,29 +211,37 @@ value is required. ### Switch parameter design considerations -- Switch parameters shouldn't be given default values. They should always +- Don't set a default value for a switch parameter. Switch parameter always default to false. -- Switch parameters are excluded from positional parameters by default. Even - when other parameters are implicitly positional, switch parameters aren't. - You _can_ override that in the Parameter attribute, but it will confuse - users. -- Switch parameters should be designed so that setting them moves a command - from its default behavior to a less common or more complicated mode. The - simplest behavior of a command should be the default behavior that doesn't - require the use of switch parameters. -- Switch parameters shouldn't be mandatory. The only case where it's necessary - to make a switch parameter mandatory is when it's needed to differentiate a +- Don't make switch parameters positional. By default, switch parameters are + excluded from positional parameters. You _can_ override that in the + **Parameter** attribute, but it can confuse users. +- Design switch parameters so that using parameter changes the default behavior + of the command to a less common or more complicated mode. The simplest + behavior of a command should be the default behavior that doesn't require the + use of switch parameters. +- Don't make switch parameters mandatory. The only case where it's helpful to + make a switch parameter mandatory is when it's needed to differentiate a parameter set. -- Explicitly setting a switch from a boolean can be done with - `-MySwitch:$boolValue` and in splatting with - `$params = @{ MySwitch = $boolValue }`. -- Switch parameters are of type `SwitchParameter`, which implicitly converts to - Boolean. The parameter variable can be used directly in a conditional - expression. For example: +- Use the switch parameter variable directly in a conditional expression. The + `SwitchParameter` type implicitly converts to Boolean. For example: + + ```powershell + if ($MySwitch) { ... } + ``` + +- Always base the behavior controlled by the switch on the value of the switch, + not the presence of the parameter. There are several ways to test for the + presence of a switch parameters: - `if ($MySwitch) { ... }` + - `$PSBoundParameters` contains the switch parameter name as a key + - `$MyInvocation.BoundParameters` contains the switch parameter name as a key + - `$PSCmdlet.ParameterSetName` when the switch defines a unique parameter set - There's no need to write `if ($MySwitch.IsPresent) { ... }` + For example, it's possible to provide an explicit value for the switch using + `-MySwitch:$false` or splatting. If you only test for the presence of the + parameter, the command behaves as if the switch value is `$true` instead of + `$false`. ## Dynamic parameters diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index af9d755c9b75..f6c31aa04ddf 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,7 +1,7 @@ --- description: Explains how to add parameters to advanced functions. Locale: en-US -ms.date: 01/06/2025 +ms.date: 02/25/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced_Parameters @@ -36,8 +36,8 @@ combination with the `[Alias()]` attribute or any of the parameter validation attributes. Parameter names follow the rules for variable names. Parameter names consist of -decimal digits, alphabetic characters, and underscores. For a complete list of -naming rules, see [about_Variables][20]. +decimal digits, alphabetical characters, and underscores. For a complete list +of naming rules, see [about_Variables][20]. > [!IMPORTANT] > It's possible to define a parameter that starts with a decimal digit. @@ -184,24 +184,23 @@ has a **false** value. For example, the **Recurse** parameter of `Get-ChildItem` is a switch parameter. -To create a switch parameter in a function, specify the `switch` type in the -parameter definition. - -For example, your function may have an option to output data as a byte array: +To create a switch parameter in a function, specify the `[switch]` type in the +parameter definition. The following example shows the definition of a switch +parameter that could be used to provide an option to output data as a byte +array: ```powershell param([switch]$AsByteArray) ``` -Switch parameters are easy to use and are preferred over Boolean parameters, -which have a less natural syntax for PowerShell. +Switch parameters are easy to use and are preferred over Boolean parameters +that have a less natural syntax for PowerShell. -For example, to use a switch parameter, the user types the parameter in the -command. +To use a switch parameter, include the parameter in the command. For example: `-IncludeAll` -To use a Boolean parameter, the user types the parameter and a Boolean value. +To use a Boolean parameter, you must provide the parameter and a Boolean value. `-IncludeAll $true` @@ -212,29 +211,37 @@ value is required. ### Switch parameter design considerations -- Switch parameters shouldn't be given default values. They should always +- Don't set a default value for a switch parameter. Switch parameter always default to false. -- Switch parameters are excluded from positional parameters by default. Even - when other parameters are implicitly positional, switch parameters aren't. - You _can_ override that in the Parameter attribute, but it will confuse - users. -- Switch parameters should be designed so that setting them moves a command - from its default behavior to a less common or more complicated mode. The - simplest behavior of a command should be the default behavior that doesn't - require the use of switch parameters. -- Switch parameters shouldn't be mandatory. The only case where it's necessary - to make a switch parameter mandatory is when it's needed to differentiate a +- Don't make switch parameters positional. By default, switch parameters are + excluded from positional parameters. You _can_ override that in the + **Parameter** attribute, but it can confuse users. +- Design switch parameters so that using parameter changes the default behavior + of the command to a less common or more complicated mode. The simplest + behavior of a command should be the default behavior that doesn't require the + use of switch parameters. +- Don't make switch parameters mandatory. The only case where it's helpful to + make a switch parameter mandatory is when it's needed to differentiate a parameter set. -- Explicitly setting a switch from a boolean can be done with - `-MySwitch:$boolValue` and in splatting with - `$params = @{ MySwitch = $boolValue }`. -- Switch parameters are of type `SwitchParameter`, which implicitly converts to - Boolean. The parameter variable can be used directly in a conditional - expression. For example: +- Use the switch parameter variable directly in a conditional expression. The + `SwitchParameter` type implicitly converts to Boolean. For example: + + ```powershell + if ($MySwitch) { ... } + ``` + +- Always base the behavior controlled by the switch on the value of the switch, + not the presence of the parameter. There are several ways to test for the + presence of a switch parameters: - `if ($MySwitch) { ... }` + - `$PSBoundParameters` contains the switch parameter name as a key + - `$MyInvocation.BoundParameters` contains the switch parameter name as a key + - `$PSCmdlet.ParameterSetName` when the switch defines a unique parameter set - There's no need to write `if ($MySwitch.IsPresent) { ... }` + For example, it's possible to provide an explicit value for the switch using + `-MySwitch:$false` or splatting. If you only test for the presence of the + parameter, the command behaves as if the switch value is `$true` instead of + `$false`. ## Dynamic parameters diff --git a/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-parameters.md b/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-parameters.md index 9d1f416ed222..34197af12aa4 100644 --- a/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-parameters.md +++ b/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-parameters.md @@ -1,18 +1,24 @@ --- description: Types of Cmdlet Parameters -ms.date: 09/13/2016 +ms.date: 02/25/2025 ms.topic: reference title: Types of Cmdlet Parameters --- # Types of Cmdlet Parameters -This topic describes the different types of parameters that you can declare in cmdlets. Cmdlet parameters can be positional, named, required, optional, or switch parameters. +This topic describes the different types of parameters that you can declare in cmdlets. Cmdlet +parameters can be positional, named, required, optional, or switch parameters. ## Positional and Named Parameters -All cmdlet parameters are either named or positional parameters. A named parameter requires that you type the parameter name and argument when calling the cmdlet. A positional parameter requires only that you type the arguments in relative order. The system then maps the first unnamed argument to the first positional parameter. The system maps the second unnamed argument to the second unnamed parameter, and so on. By default, all cmdlet parameters are named parameters. +All cmdlet parameters are either named or positional parameters. A named parameter requires that you +type the parameter name and argument when calling the cmdlet. A positional parameter requires only +that you type the arguments in relative order. The system then maps the first unnamed argument to +the first positional parameter. The system maps the second unnamed argument to the second unnamed +parameter, and so on. By default, all cmdlet parameters are named parameters. -To define a named parameter, omit the `Position` keyword in the **Parameter** attribute declaration, as shown in the following parameter declaration. +To define a named parameter, omit the `Position` keyword in the **Parameter** attribute declaration, +as shown in the following parameter declaration. ```csharp [Parameter(ValueFromPipeline=true)] @@ -24,7 +30,10 @@ public string UserName private string userName; ``` -To define a positional parameter, add the `Position` keyword in the Parameter attribute declaration, and then specify a position. In the following sample, the `UserName` parameter is declared as a positional parameter with position 0. This means that the first argument of the call will be automatically bound to this parameter. +To define a positional parameter, add the `Position` keyword in the Parameter attribute declaration, +and then specify a position. In the following sample, the `UserName` parameter is declared as a +positional parameter with position 0. This means that the first argument of the call is +automatically bound to this parameter. ```csharp [Parameter(Position = 0)] @@ -37,11 +46,19 @@ private string userName; ``` > [!NOTE] -> Good cmdlet design recommends that the most-used parameters be declared as positional parameters so that the user does not have to enter the parameter name when the cmdlet is run. +> Good cmdlet design recommends that the most-used parameters be declared as positional parameters +> so that the user doesn't have to enter the parameter name when the cmdlet is run. -Positional and named parameters accept single arguments or multiple arguments separated by commas. Multiple arguments are allowed only if the parameter accepts a collection such as an array of strings. You may mix positional and named parameters in the same cmdlet. In this case, the system retrieves the named arguments first, and then attempts to map the remaining unnamed arguments to the positional parameters. +Positional and named parameters accept single arguments or multiple arguments separated by commas. +Multiple arguments are allowed only if the parameter accepts a collection such as an array of +strings. You may mix positional and named parameters in the same cmdlet. In this case, the system +retrieves the named arguments first, and then attempts to map the remaining unnamed arguments to the +positional parameters. -The following commands show the different ways in which you can specify single and multiple arguments for the parameters of the `Get-Command` cmdlet. Notice that in the last two samples, **-name** does not need to be specified because the `Name` parameter is defined as a positional parameter. +The following commands show the different ways in which you can specify single and multiple +arguments for the parameters of the `Get-Command` cmdlet. Notice that in the last two samples, +**-name** doesn't need to be specified because the `Name` parameter is defined as a positional +parameter. ```powershell Get-Command -Name get-service @@ -52,9 +69,12 @@ Get-Command get-service,set-service ## Mandatory and Optional Parameters -You can also define cmdlet parameters as mandatory or optional parameters. (A mandatory parameter must be specified before the Windows PowerShell runtime invokes the cmdlet.) By default, parameters are defined as optional. +You can also define cmdlet parameters as mandatory or optional parameters. (A mandatory parameter +must be specified before the PowerShell runtime invokes the cmdlet.) By default, parameters +are defined as optional. -To define a mandatory parameter, add the `Mandatory` keyword in the Parameter attribute declaration, and set it to `true`, as shown in the following parameter declaration. +To define a mandatory parameter, add the `Mandatory` keyword in the Parameter attribute declaration, +and set it to `true`, as shown in the following parameter declaration. ```csharp [Parameter(Position = 0, Mandatory = true)] @@ -66,7 +86,8 @@ public string UserName private string userName; ``` -To define an optional parameter, omit the `Mandatory` keyword in the **Parameter** attribute declaration, as shown in the following parameter declaration. +To define an optional parameter, omit the `Mandatory` keyword in the **Parameter** attribute +declaration, as shown in the following parameter declaration. ```csharp [Parameter(Position = 0)] @@ -80,16 +101,19 @@ private string userName; ## Switch Parameters -Windows PowerShell provides a [System.Management.Automation.SwitchParameter](/dotnet/api/System.Management.Automation.SwitchParameter) type that allows you to define a parameter whose value is automatically set to `false` if the parameter is not specified when the cmdlet is called. Whenever possible, use switch parameters in place of Boolean parameters. +PowerShell provides a [System.Management.Automation.SwitchParameter][02] type that allows you to +define a parameter whose default value `false` unless the parameter is specified when the cmdlet is +called. Whenever possible, use switch parameters instead of Boolean parameters. -Consider the following sample. By default, several Windows PowerShell cmdlets do not pass an output object down the pipeline. However, these cmdlets have a `PassThru` switch parameter that overrides the default behavior. If the `PassThru` parameter is specified when these cmdlets are called, the cmdlet returns an output object to the pipeline. +Consider the following example. Many PowerShell cmdlets return output. However, these cmdlets have a +`PassThru` switch parameter that overrides the default behavior. When you use the `PassThru` +parameter, the cmdlet returns output objects to the pipeline. -If you need the parameter to have a default value of `true` when the parameter is not specified in the call, consider reversing the sense of the parameter. For sample, instead of setting the parameter attribute to a Boolean value of `true`, declare the property as the [System.Management.Automation.SwitchParameter](/dotnet/api/System.Management.Automation.SwitchParameter) type, and then set the default value of the parameter to `false`. - -To define a switch parameter, declare the property as the [System.Management.Automation.SwitchParameter](/dotnet/api/System.Management.Automation.SwitchParameter) type, as shown in the following sample. +To define a switch parameter, declare the property as the `[SwitchParameter]` type, as shown in the +following sample. ```csharp -[Parameter(Position = 1)] +[Parameter()] public SwitchParameter GoodBye { get { return goodbye; } @@ -98,19 +122,41 @@ public SwitchParameter GoodBye private bool goodbye; ``` -To make the cmdlet act on the parameter when it is specified, use the following structure within one of the input processing methods. +To make the cmdlet act on the parameter when it's specified, use the following structure within one +of the input processing methods. ```csharp protected override void ProcessRecord() { WriteObject("Switch parameter test: " + userName + "."); - if(goodbye) + if (goodbye) { WriteObject(" Goodbye!"); } } // End ProcessRecord ``` +By default, switch parameters are excluded from positional parameters. You _can_ override that in +the **Parameter** attribute, but it can confuse users. + +Design switch parameters so that using parameter changes the default behavior of the command to a +less common or more complicated mode. The simplest behavior of a command should be the default +behavior that doesn't require the use of switch parameters. Base the behavior controlled by the +switch on the value of the switch, not the presence of the parameter. + +There are several ways to test for the presence of a switch parameters: + +- `Invocation.BoundParameters` contains the switch parameter name as a key +- `PSCmdlet.ParameterSetName` when the switch defines a unique parameter set + +For example, it's possible to provide an explicit value for the switch using `-MySwitch:$false` or +splatting. If you only test for the presence of the parameter, the command behaves as if the switch +value is `$true` instead of `$false`. + ## See Also -[Writing a Windows PowerShell Cmdlet](./writing-a-windows-powershell-cmdlet.md) +[Writing a Windows PowerShell Cmdlet][01] + + +[01]: writing-a-windows-powershell-cmdlet.md +[02]: xref:System.Management.Automation.SwitchParameter