diff --git a/reference/5.1/CimCmdlets/New-CimSession.md b/reference/5.1/CimCmdlets/New-CimSession.md index 687175f80302..a9f84fa49aa4 100644 --- a/reference/5.1/CimCmdlets/New-CimSession.md +++ b/reference/5.1/CimCmdlets/New-CimSession.md @@ -331,8 +331,8 @@ By default, the `New-CimSession` cmdlet establishes a connection with a remote W endpoint for two reasons: to verify that the remote server is listening on the port number that is specified using the **Port** parameter, and to verify the specified account credentials. The verification is accomplished using a standard WS-Identity operation. You can add the -**SkipTestConnection** switch parameter if the remote WS-Management endpoint cannot use WS-Identify, -or to reduce some data transmission time. +**SkipTestConnection** `[switch]` parameter if the remote WS-Management endpoint cannot use +WS-Identify, or to reduce some data transmission time. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index 0cbfa2cb82a1..eb54a11d33e4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -198,19 +198,18 @@ The syntax diagrams use the following symbols: - Parameters with no values Some parameters don't accept input, so they don't have a parameter value. - Parameters without values are _switch parameters_. Switch parameters are used - like boolean values. They default to `$false`. When you use a switch - parameter, the value is set to `$true`. + Parameters without values are _`[switch]` parameters_. `[switch]` parameters + are used like boolean values. They default to `$false`. When you use a + `[switch]` parameter, the value is set to `$true`. - For example, the **ListImported** parameter of `Get-Command` is a switch - parameter. When you use the **ListImported** parameter, the cmdlet return + For example, the **ListImported** parameter of `Get-Command` is a `[switch]` + parameter. When you use the **ListImported** parameter, the cmdlet returns only commands that were imported from modules in the current session. ```Syntax Get-Command [-ListImported] ``` - - Brackets `[ ]` around parameters indicate optional items. A parameter and its value can be optional. For example, the **CommandType** parameter of `Get-Command` and its value are enclosed in brackets because they're both diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md index c0334ae13d05..98986fd78f55 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md @@ -239,7 +239,7 @@ For more information about the standard PowerShell verbs, see ## Functions with parameters You can use parameters with functions, including named parameters, positional -parameters, switch parameters, and dynamic parameters. For more information +parameters, `[switch]` parameters, and dynamic parameters. For more information about dynamic parameters in functions, see [about_Functions_Advanced_Parameters][09]. @@ -379,13 +379,12 @@ Get-Extension myTextFile myTextFile.txt ``` -### Switch parameters +### `[switch]` parameters A switch is a parameter that doesn't require a value. Instead, you type the -function name followed by the name of the switch parameter. +function name followed by the name of the `[switch]` parameter. -To define a switch parameter, specify the type `[switch]` before the parameter -name, as shown in the following example: +The following example shows how you define a `[switch]` parameter: ```powershell function Switch-Item { @@ -395,8 +394,9 @@ function Switch-Item { } ``` -When you type the `On` switch parameter after the function name, the function -displays `Switch on`. Without the switch parameter, it displays `Switch off`. +When you type the `On` `[switch]` parameter after the function name, the +function displays `Switch on`. Without the `[switch]` parameter, it displays +`Switch off`. ```powershell Switch-Item -On 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 88ec2b4f554b..11191eef65c7 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: 03/10/2026 +ms.date: 04/08/2026 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 @@ -178,29 +178,28 @@ param( ) ``` -## Switch parameters +## `[switch]` parameters -Switch parameters are parameters that take no parameter value. Instead, they -convey a Boolean true-or-false value through their presence or absence, so that -when a switch parameter is present it has a **true** value and when absent it -has a **false** value. +`[switch]` parameters are parameters that take no parameter value. Instead, +they convey a Boolean true-or-false value through their presence or absence, so +that when a `[switch]` parameter is present it has a **true** value and when +absent it has a **false** value. -For example, the **Recurse** parameter of `Get-ChildItem` is a switch +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. 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: +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 +`[switch]` parameters are easy to use and are preferred over Boolean parameters that have a less natural syntax for PowerShell. -To use a switch parameter, include the parameter in the command. For example: +To use a `[switch]` parameter, include the parameter in the command. For +example: `-IncludeAll` @@ -208,38 +207,39 @@ To use a Boolean parameter, you must provide the parameter and a Boolean value. `-IncludeAll $true` -When creating switch parameters, choose the parameter name carefully. Be sure -that the parameter name communicates the effect of the parameter to the user. -Avoid ambiguous terms, such as **Filter** or **Maximum** that might imply a -value is required. +When creating `[switch]` parameters, choose the parameter name carefully. Be +sure that the parameter name communicates the effect of the parameter to the +user. Avoid ambiguous terms, such as **Filter** or **Maximum** that might imply +a value is required. -### Switch parameter design considerations +### `[switch]` parameter design considerations -- Don't set a default value for a switch parameter. Switch parameter always - default to false. -- 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 +- Don't set a default value for a `[switch]` parameter. `[switch]` parameters + always default to false. +- 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 them 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. -- Use the switch parameter variable directly in a conditional expression. The - `SwitchParameter` type implicitly converts to Boolean. For example: + 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. +- 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: +- Always base the behavior controlled by the `[switch]` parameter on the + _value_ of the parameter, not its _presence_. There are several ways to test + for the presence of a `[switch]` parameters: - - `$PSBoundParameters` contains the switch parameter name as a key - - `$MyInvocation.BoundParameters` contains the switch parameter name as a key + - `$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 For example, it's possible to provide an explicit value for the switch using @@ -773,7 +773,7 @@ Use the **System.Obsolete** attribute to mark parameters that are no longer supported. This can be useful when you want to remove a parameter from a function but you don't want to break existing scripts that use the function. -For example, consider a function that has a **NoTypeInformation** switch +For example, consider a function that has a **NoTypeInformation** `[switch]` parameter that controls whether type information is included in the output. You want to make that behavior the default and remove the parameter from the function. However, you don't want to break existing scripts that use the @@ -783,7 +783,7 @@ explains the change. ```powershell param( [System.Obsolete("The NoTypeInformation parameter is obsolete.")] - [SwitchParameter]$NoTypeInformation + [switch]$NoTypeInformation ) ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index b231fe3690e4..750508f33337 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -104,8 +104,8 @@ $PSDefaultParameterValues = @{ ``` The cmdlet and parameter names can contain wildcard characters. Use `$true` and -`$false` to set values for switch parameters, such as **Verbose**. This example -sets the common parameter **Verbose** to `$true` for all commands. +`$false` to set values for `[switch]` parameters, such as **Verbose**. This +example sets the common parameter **Verbose** to `$true` for all commands. ```powershell $PSDefaultParameterValues = @{'*:Verbose'=$true} @@ -162,9 +162,9 @@ You can use a scriptblock to specify different default values for a parameter under different conditions. PowerShell evaluates the scriptblock and uses the result as the default parameter value. -The `Format-Table:AutoSize` key sets that switch parameter to a default value -of `$true` The `if` statement contains a condition that the `$Host.Name` must -be `ConsoleHost`. +The `Format-Table:AutoSize` key sets that `[switch]` parameter to a default +value of `$true`. The `if` statement contains a condition that the `$Host.Name` +must be `ConsoleHost`. ```powershell $PSDefaultParameterValues = @{ diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md index f5e2c8c4b39f..b0a543d48ecc 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md @@ -211,11 +211,11 @@ For example: #### -RunAsAdministrator -When this switch parameter is added to your `#Requires` statement, it specifies -that the PowerShell session in which you're running the script must be started -with elevated user rights. The **RunAsAdministrator** parameter is ignored on a -non-Windows operating system. The **RunAsAdministrator** parameter was -introduced in PowerShell 4.0. +When this `[switch]` parameter is added to your `#Requires` statement, it +specifies that the PowerShell session in which you're running the script must +be started with elevated user rights. The **RunAsAdministrator** parameter is +ignored on a non-Windows operating system. The **RunAsAdministrator** parameter +was introduced in PowerShell 4.0. For example: diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md index c119df374449..2783f756404a 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -49,7 +49,7 @@ command so you don't pass more than one value for each parameter. ## Splatting with hash tables Use a hash table to splat parameter name and value pairs. You can use this -format for all parameter types, including positional and switch parameters. +format for all parameter types, including positional and `[switch]` parameters. Positional parameters must be assigned by name. The following examples compare two `Copy-Item` commands that copy the Test.txt @@ -68,7 +68,7 @@ table of parameter-name and parameter-value pairs and stores it in the variable in a command with splatting. The At symbol (`@HashArguments`) replaces the dollar sign (`$HashArguments`) in the command. -To provide a value for the **WhatIf** switch parameter, use `$true` or +To provide a value for the **WhatIf** `[switch]` parameter, use `$true` or `$false`. ```powershell diff --git a/reference/5.1/Microsoft.PowerShell.Core/Disable-PSRemoting.md b/reference/5.1/Microsoft.PowerShell.Core/Disable-PSRemoting.md index cc81423447a5..a17495599680 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Disable-PSRemoting.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Disable-PSRemoting.md @@ -212,7 +212,7 @@ A loopback connection is created when the following conditions are met: - The computer name to connect to is 'localhost'. - No credentials are passed in. Current logged in user (implicit credentials) is used for the connection. -- The **EnableNetworkAccess** switch parameter is used. +- The **EnableNetworkAccess** `[switch]` parameter is used. For more information on loopback connections, see [New-PSSession](New-PSSession.md) document. diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-Help.md b/reference/5.1/Microsoft.PowerShell.Core/Get-Help.md index 100dab982437..f8a6565d5556 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-Help.md @@ -191,7 +191,7 @@ Get-Help Format-Table -Parameter GroupBy ``` The **Examples** parameter displays the help file's **NAME** and **SYNOPSIS** sections, and all the -Examples. You can't specify an Example number because the **Examples** parameter is a switch +Examples. You can't specify an Example number because the **Examples** parameter is a `[switch]` parameter. The **Parameter** parameter displays only the descriptions of the specified parameters. If you diff --git a/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md b/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md index c3c3594cb8f2..510d7507feb2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md @@ -256,9 +256,9 @@ command. All PowerShell comparison operators are valid in the scriptblock format. For more information, see [about_Comparison_Operators](./About/about_Comparison_Operators.md). -- **Simplified syntax**. To enable the simiplified syntax, `Where-Object` includes 31 switch +- **Simplified syntax**. To enable the simplified syntax, `Where-Object` includes 31 `[switch]` parameters that represent the comparison operators. The simplified syntax is easier to read and - write than the scriptblock syntax. You can combine one of the switch parameters with the + write than the scriptblock syntax. You can combine one of the `[switch]` parameters with the **Property** and **Value** parameters to create a command that filters objects based on the values of their properties. @@ -271,7 +271,7 @@ command. As shown in the example, the parameter names **Property** and **Value** are optional. The **Property** parameter is a positional parameter mapped to position `0`. The **Value** parameter - is a positional parameter mapped to position `1`. The switch parameter, used to specify the + is a positional parameter mapped to position `1`. The `[switch]` parameter, used to specify the comparison, can be used in any position. The simplified syntax was introduced in Windows PowerShell 3.0. For more information, see diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Show-Command.md b/reference/5.1/Microsoft.PowerShell.Utility/Show-Command.md index ec5078d4719f..d8be16f1747a 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Show-Command.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Show-Command.md @@ -35,10 +35,10 @@ all installed modules. To find the commands in a module, select the module from drop-down list. To select a command, click the command name. To use the command window, select a command, either by using the Name or by clicking the command -name in the **Commands** list. Each parameter set is displayed on a separate tab. Asterisks indicate -the mandatory parameters. To enter values for a parameter, type the value in the text box or select -the value from the drop-down box. To add a switch parameter, click to select the parameter check -box. +name in the **Commands** list. Each parameter set is displayed on a separate tab. Asterisks +indicate the mandatory parameters. To enter values for a parameter, type the value in the text box +or select the value from the drop-down box. To add a `[switch]` parameter, click to select the +parameter check box. When you're ready, you can click **Copy** to copy the command that you've created to the clipboard or click **Run** to run the command. You can also use the **PassThru** parameter to return the diff --git a/reference/7.4/CimCmdlets/New-CimSession.md b/reference/7.4/CimCmdlets/New-CimSession.md index e33f602ed563..a00e50d04f72 100644 --- a/reference/7.4/CimCmdlets/New-CimSession.md +++ b/reference/7.4/CimCmdlets/New-CimSession.md @@ -333,8 +333,8 @@ By default, the `New-CimSession` cmdlet establishes a connection with a remote W endpoint for two reasons: to verify that the remote server is listening on the port number that is specified using the **Port** parameter, and to verify the specified account credentials. The verification is accomplished using a standard WS-Identity operation. You can add the -**SkipTestConnection** switch parameter if the remote WS-Management endpoint cannot use WS-Identify, -or to reduce some data transmission time. +**SkipTestConnection** `[switch]` parameter if the remote WS-Management endpoint cannot use +WS-Identify, or to reduce some data transmission time. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index 9b275b6a46f8..d7f773f1ebc8 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -198,19 +198,18 @@ The syntax diagrams use the following symbols: - Parameters with no values Some parameters don't accept input, so they don't have a parameter value. - Parameters without values are _switch parameters_. Switch parameters are used - like boolean values. They default to `$false`. When you use a switch - parameter, the value is set to `$true`. + Parameters without values are _`[switch]` parameters_. `[switch]` parameters + are used like boolean values. They default to `$false`. When you use a + `[switch]` parameter, the value is set to `$true`. - For example, the **ListImported** parameter of `Get-Command` is a switch - parameter. When you use the **ListImported** parameter, the cmdlet return + For example, the **ListImported** parameter of `Get-Command` is a `[switch]` + parameter. When you use the **ListImported** parameter, the cmdlet returns only commands that were imported from modules in the current session. ```Syntax Get-Command [-ListImported] ``` - - Brackets `[ ]` around parameters indicate optional items. A parameter and its value can be optional. For example, the **CommandType** parameter of `Get-Command` and its value are enclosed in brackets because they're both diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md index 466d1276527b..55b304340433 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md @@ -263,7 +263,7 @@ For more information about the standard PowerShell verbs, see ## Functions with parameters You can use parameters with functions, including named parameters, positional -parameters, switch parameters, and dynamic parameters. For more information +parameters, `[switch]` parameters, and dynamic parameters. For more information about dynamic parameters in functions, see [about_Functions_Advanced_Parameters][09]. @@ -403,13 +403,12 @@ Get-Extension myTextFile myTextFile.txt ``` -### Switch parameters +### `[switch]` parameters A switch is a parameter that doesn't require a value. Instead, you type the -function name followed by the name of the switch parameter. +function name followed by the name of the `[switch]` parameter. -To define a switch parameter, specify the type `[switch]` before the parameter -name, as shown in the following example: +The following example shows how you define a `[switch]` parameter: ```powershell function Switch-Item { @@ -419,8 +418,9 @@ function Switch-Item { } ``` -When you type the `On` switch parameter after the function name, the function -displays `Switch on`. Without the switch parameter, it displays `Switch off`. +When you type the `On` `[switch]` parameter after the function name, the +function displays `Switch on`. Without the `[switch]` parameter, it displays +`Switch off`. ```powershell Switch-Item -On 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 7673a43ce83b..287e8410a9e5 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: 03/10/2026 +ms.date: 04/08/2026 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 @@ -173,29 +173,28 @@ param( ) ``` -## Switch parameters +## `[switch]` parameters -Switch parameters are parameters that take no parameter value. Instead, they -convey a Boolean true-or-false value through their presence or absence, so that -when a switch parameter is present it has a **true** value and when absent it -has a **false** value. +`[switch]` parameters are parameters that take no parameter value. Instead, +they convey a Boolean true-or-false value through their presence or absence, so +that when a `[switch]` parameter is present it has a **true** value and when +absent it has a **false** value. -For example, the **Recurse** parameter of `Get-ChildItem` is a switch +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. 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: +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 +`[switch]` parameters are easy to use and are preferred over Boolean parameters that have a less natural syntax for PowerShell. -To use a switch parameter, include the parameter in the command. For example: +To use a `[switch]` parameter, include the parameter in the command. For +example: `-IncludeAll` @@ -203,38 +202,39 @@ To use a Boolean parameter, you must provide the parameter and a Boolean value. `-IncludeAll $true` -When creating switch parameters, choose the parameter name carefully. Be sure -that the parameter name communicates the effect of the parameter to the user. -Avoid ambiguous terms, such as **Filter** or **Maximum** that might imply a -value is required. +When creating `[switch]` parameters, choose the parameter name carefully. Be +sure that the parameter name communicates the effect of the parameter to the +user. Avoid ambiguous terms, such as **Filter** or **Maximum** that might imply +a value is required. -### Switch parameter design considerations +### `[switch]` parameter design considerations -- Don't set a default value for a switch parameter. Switch parameter always - default to false. -- 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 +- Don't set a default value for a `[switch]` parameter. `[switch]` parameters + always default to false. +- 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 them 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. -- Use the switch parameter variable directly in a conditional expression. The - `SwitchParameter` type implicitly converts to Boolean. For example: + 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. +- 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: +- Always base the behavior controlled by the `[switch]` parameter on the + _value_ of the parameter, not its _presence_. There are several ways to test + for the presence of a `[switch]` parameters: - - `$PSBoundParameters` contains the switch parameter name as a key - - `$MyInvocation.BoundParameters` contains the switch parameter name as a key + - `$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 For example, it's possible to provide an explicit value for the switch using @@ -802,7 +802,7 @@ Use the **System.Obsolete** attribute to mark parameters that are no longer supported. This can be useful when you want to remove a parameter from a function but you don't want to break existing scripts that use the function. -For example, consider a function that has a **NoTypeInformation** switch +For example, consider a function that has a **NoTypeInformation** `[switch]` parameter that controls whether type information is included in the output. You want to make that behavior the default and remove the parameter from the function. However, you don't want to break existing scripts that use the @@ -812,7 +812,7 @@ explains the change. ```powershell param( [System.Obsolete("The NoTypeInformation parameter is obsolete.")] - [SwitchParameter]$NoTypeInformation + [switch]$NoTypeInformation ) ``` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index a991d55df656..c31ff73921ad 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -104,8 +104,8 @@ $PSDefaultParameterValues = @{ ``` The cmdlet and parameter names can contain wildcard characters. Use `$true` and -`$false` to set values for switch parameters, such as **Verbose**. This example -sets the common parameter **Verbose** to `$true` for all commands. +`$false` to set values for `[switch]` parameters, such as **Verbose**. This +example sets the common parameter **Verbose** to `$true` for all commands. ```powershell $PSDefaultParameterValues = @{'*:Verbose'=$true} @@ -162,9 +162,9 @@ You can use a scriptblock to specify different default values for a parameter under different conditions. PowerShell evaluates the scriptblock and uses the result as the default parameter value. -The `Format-Table:AutoSize` key sets that switch parameter to a default value -of `$true` The `if` statement contains a condition that the `$Host.Name` must -be `ConsoleHost`. +The `Format-Table:AutoSize` key sets that `[switch]` parameter to a default +value of `$true`. The `if` statement contains a condition that the `$Host.Name` +must be `ConsoleHost`. ```powershell $PSDefaultParameterValues = @{ diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md index f1e5b73b2629..21d44eccc19c 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md @@ -198,8 +198,8 @@ Get-Module -ListAvailable BitsTransfer # No output ``` -In both cases, the `-SkipEditionCheck` switch parameter can be used to override -this behavior: +In both cases, the `-SkipEditionCheck` `[switch]` parameter can be used to +override this behavior: ```powershell Get-Module -ListAvailable -SkipEditionCheck BitsTransfer diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Pwsh.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Pwsh.md index 90e31cca00c5..364666ceda68 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Pwsh.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Pwsh.md @@ -69,15 +69,15 @@ and any parameters. File must be the last parameter in the command, because all characters typed after the File parameter name are interpreted as the script filepath followed by the script parameters. -Typically, the switch parameters of a script are either included or omitted. -For example, the following command uses the **All** parameter of the +Typically, the `[switch]` parameters of a script are either included or +omitted. For example, the following command uses the **All** parameter of the `Get-Script.ps1` script file: `-File .\Get-Script.ps1 -All` -In rare cases, you might need to provide a **Boolean** value for a switch -parameter. To provide a **Boolean** value for a switch parameter in the value -of the **File** parameter, Use the parameter normally followed immediately by a -colon and the boolean value, such as the following: -`-File .\Get-Script.ps1 -All:$false`. +In rare cases, you might need to provide a **Boolean** value for a `[switch]` +parameter. To provide a **Boolean** value for a `[switch]` parameter in the +value of the **File** parameter, use the parameter normally followed +immediately by a colon and the boolean value, such as the following: `-File +.\Get-Script.ps1 -All:$false`. Parameters passed to the script are passed as literal strings, after interpretation by the current shell. For example, if you are in `cmd.exe` and diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Requires.md index 88c83c0a8668..04ebf64ae8a4 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Requires.md @@ -183,11 +183,11 @@ For example: #### -RunAsAdministrator -When this switch parameter is added to your `#Requires` statement, it specifies -that the PowerShell session in which you're running the script must be started -with elevated user rights. The **RunAsAdministrator** parameter is ignored on a -non-Windows operating system. The **RunAsAdministrator** parameter was -introduced in PowerShell 4.0. +When this `[switch]` parameter is added to your `#Requires` statement, it +specifies that the PowerShell session in which you're running the script must +be started with elevated user rights. The **RunAsAdministrator** parameter is +ignored on a non-Windows operating system. The **RunAsAdministrator** parameter +was introduced in PowerShell 4.0. For example: diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Splatting.md index d27ea6e3fbd8..29ddff1c0399 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -52,7 +52,7 @@ defining a parameter in a command. ## Splatting with hash tables Use a hash table to splat parameter name and value pairs. You can use this -format for all parameter types, including positional and switch parameters. +format for all parameter types, including positional and `[switch]` parameters. Positional parameters must be assigned by name. The following examples compare two `Copy-Item` commands that copy the Test.txt @@ -71,7 +71,7 @@ table of parameter-name and parameter-value pairs and stores it in the variable in a command with splatting. The At symbol (`@HashArguments`) replaces the dollar sign (`$HashArguments`) in the command. -To provide a value for the **WhatIf** switch parameter, use `$true` or +To provide a value for the **WhatIf** `[switch]` parameter, use `$true` or `$false`. ```powershell diff --git a/reference/7.4/Microsoft.PowerShell.Core/Disable-PSRemoting.md b/reference/7.4/Microsoft.PowerShell.Core/Disable-PSRemoting.md index 11bc6555cc04..ba6ac27ee71c 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/Disable-PSRemoting.md +++ b/reference/7.4/Microsoft.PowerShell.Core/Disable-PSRemoting.md @@ -235,7 +235,7 @@ A loopback connection is created when the following conditions are met: - The computer name to connect to is 'localhost'. - No credentials are passed in. Current logged in user (implicit credentials) is used for the connection. -- The **EnableNetworkAccess** switch parameter is used. +- The **EnableNetworkAccess** `[switch]` parameter is used. For more information on loopback connections, see [New-PSSession](New-PSSession.md) document. diff --git a/reference/7.4/Microsoft.PowerShell.Core/Get-Help.md b/reference/7.4/Microsoft.PowerShell.Core/Get-Help.md index 9aa538cc862d..b9dfc0d913bb 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/7.4/Microsoft.PowerShell.Core/Get-Help.md @@ -191,7 +191,7 @@ Get-Help Format-Table -Parameter GroupBy ``` The **Examples** parameter displays the help file's **NAME** and **SYNOPSIS** sections, and all the -Examples. You can't specify an Example number because the **Examples** parameter is a switch +Examples. You can't specify an Example number because the **Examples** parameter is a `[switch]` parameter. The **Parameter** parameter displays only the descriptions of the specified parameters. If you diff --git a/reference/7.4/Microsoft.PowerShell.Core/Where-Object.md b/reference/7.4/Microsoft.PowerShell.Core/Where-Object.md index cd686687ffa4..33495034ace6 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/7.4/Microsoft.PowerShell.Core/Where-Object.md @@ -263,9 +263,9 @@ command. All PowerShell comparison operators are valid in the scriptblock format. For more information, see [about_Comparison_Operators](./About/about_Comparison_Operators.md). -- **Simplified syntax**. To enable the simiplified syntax, `Where-Object` includes 31 switch +- **Simplified syntax**. To enable the simplified syntax, `Where-Object` includes 31 `[switch]` parameters that represent the comparison operators. The simplified syntax is easier to read and - write than the scriptblock syntax. You can combine one of the switch parameters with the + write than the scriptblock syntax. You can combine one of the `[switch]` parameters with the **Property** and **Value** parameters to create a command that filters objects based on the values of their properties. @@ -278,7 +278,7 @@ command. As shown in the example, the parameter names **Property** and **Value** are optional. The **Property** parameter is a positional parameter mapped to position `0`. The **Value** parameter - is a positional parameter mapped to position `1`. The switch parameter, used to specify the + is a positional parameter mapped to position `1`. The `[switch]` parameter, used to specify the comparison, can be used in any position. The simplified syntax was introduced in Windows PowerShell 3.0. For more information, see diff --git a/reference/7.4/Microsoft.PowerShell.Management/Resolve-Path.md b/reference/7.4/Microsoft.PowerShell.Management/Resolve-Path.md index 863e3bcf1011..5ad633a4e506 100644 --- a/reference/7.4/Microsoft.PowerShell.Management/Resolve-Path.md +++ b/reference/7.4/Microsoft.PowerShell.Management/Resolve-Path.md @@ -113,8 +113,8 @@ Resolve-Path -LiteralPath 'test[xml]' ### Example 7: Resolve a path relative to another folder This example uses the **RelativeBasePath** parameter to resolve the path of the `pwsh` executable -relative to `$Env:TEMP`. When the command includes the **Relative** switch parameter, it returns a -**String** representing the relative path from `$Env:TEMP` to the `pwsh` executable. +relative to `$Env:TEMP`. When the command includes the **Relative** `[switch]` parameter, it +returns a **String** representing the relative path from `$Env:TEMP` to the `pwsh` executable. ```powershell $ExecutablePath = Get-Command -Name pwsh | Select-Object -ExpandProperty Source @@ -211,7 +211,7 @@ Accept wildcard characters: False Specifies a path to resolve the relative path from. When you use this parameter, the cmdlet returns the **System.Management.Automation.PathInfo** object for the resolved path. -When you use this parameter with the **Relative** switch parameter, the cmdlet returns a string +When you use this parameter with the **Relative** `[switch]` parameter, the cmdlet returns a string representing the relative path from **RelativeBasePath** to **Path**. This parameter was added in PowerShell 7.4. diff --git a/reference/7.4/Microsoft.PowerShell.Utility/ConvertTo-Json.md b/reference/7.4/Microsoft.PowerShell.Utility/ConvertTo-Json.md index c479db0ef6bc..769dc423c26d 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/ConvertTo-Json.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/ConvertTo-Json.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 04/08/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-json?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertTo-Json @@ -28,18 +28,19 @@ The `ConvertTo-Json` cmdlet converts any .NET object to a string in JavaScript O property values, and the methods are removed. > [!NOTE] -> As of PowerShell 7.2, Extended Type System properties of **DateTime** and -> **String** objects are no longer serialized and only the simple object is -> converted to JSON format +> As of PowerShell 7.2, Extended Type System properties of **DateTime** and **String** objects are +> no longer serialized and only the simple object is converted to JSON format -You can then use the `ConvertFrom-Json` cmdlet to convert a JSON-formatted string to a JSON -object, which is easily managed in PowerShell. +You can then use the `ConvertFrom-Json` cmdlet to convert a JSON-formatted string to a JSON object, +which is easily managed in PowerShell. Many web sites use JSON instead of XML to serialize data for communication between servers and web-based apps. -As of PowerShell 7.1, `ConvertTo-Json` emits a warning if the depth of the input object exceeds -the depth specified for the command. This prevents unwanted data loss when converting objects. +As of PowerShell 7.1, `ConvertTo-Json` emits a warning if the depth of the input object exceeds the +depth specified for the command. This prevents unwanted data loss when converting objects. + +As of PowerShell 7.5, `ConvertTo-Json` can serialize **BigInteger** values as raw JSON numbers. This cmdlet was introduced in Windows PowerShell 3.0. @@ -206,8 +207,8 @@ Accept wildcard characters: False ### -Depth Specifies how many levels of contained objects are included in the JSON representation. The value -can be any number from `0` to `100`. The default value is `2`. `ConvertTo-Json` emits a -warning if the number of levels in an input object exceeds this number. +can be any number from `0` to `100`. The default value is `2`. `ConvertTo-Json` emits a warning if +the number of levels in an input object exceeds this number. ```yaml Type: System.Int32 @@ -223,7 +224,8 @@ Accept wildcard characters: False ### -EnumsAsStrings -Provides an alternative serialization option that converts all enumerations to their string representation. +Provides an alternative serialization option that converts all enumerations to their string +representation. ```yaml Type: System.Management.Automation.SwitchParameter @@ -244,9 +246,9 @@ characters (like newline) are escaped. Acceptable values are: -- Default - Only control characters are escaped. -- EscapeNonAscii - All non-ASCII and control characters are escaped. -- EscapeHtml - HTML (`<`, `>`, `&`, `'`, `"`) and control characters are escaped. +- `Default` - Only control characters are escaped. +- `EscapeNonAscii` - All non-ASCII and control characters are escaped. +- `EscapeHtml` - HTML (`<`, `>`, `&`, `'`, `"`) and control characters are escaped. This parameter was introduced in PowerShell 6.2. @@ -289,7 +291,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Show-Command.md b/reference/7.4/Microsoft.PowerShell.Utility/Show-Command.md index 7acc9fc0027b..b605729f4225 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Show-Command.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Show-Command.md @@ -37,10 +37,10 @@ all installed modules. To find the commands in a module, select the module from drop-down list. To select a command, click the command name. To use the command window, select a command, either by using the Name or by clicking the command -name in the **Commands** list. Each parameter set is displayed on a separate tab. Asterisks indicate -the mandatory parameters. To enter values for a parameter, type the value in the text box or select -the value from the drop-down box. To add a switch parameter, click to select the parameter check -box. +name in the **Commands** list. Each parameter set is displayed on a separate tab. Asterisks +indicate the mandatory parameters. To enter values for a parameter, type the value in the text box +or select the value from the drop-down box. To add a `[switch]` parameter, click to select the +parameter check box. When you're ready, you can click **Copy** to copy the command that you've created to the clipboard or click **Run** to run the command. You can also use the **PassThru** parameter to return the diff --git a/reference/7.5/CimCmdlets/New-CimSession.md b/reference/7.5/CimCmdlets/New-CimSession.md index 9e601fd89f51..a7727bfe3e2b 100644 --- a/reference/7.5/CimCmdlets/New-CimSession.md +++ b/reference/7.5/CimCmdlets/New-CimSession.md @@ -333,8 +333,8 @@ By default, the `New-CimSession` cmdlet establishes a connection with a remote W endpoint for two reasons: to verify that the remote server is listening on the port number that is specified using the **Port** parameter, and to verify the specified account credentials. The verification is accomplished using a standard WS-Identity operation. You can add the -**SkipTestConnection** switch parameter if the remote WS-Management endpoint cannot use WS-Identify, -or to reduce some data transmission time. +**SkipTestConnection** `[switch]` parameter if the remote WS-Management endpoint cannot use +WS-Identify, or to reduce some data transmission time. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index 0f7f31b98845..b1cb074b139f 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -198,19 +198,18 @@ The syntax diagrams use the following symbols: - Parameters with no values Some parameters don't accept input, so they don't have a parameter value. - Parameters without values are _switch parameters_. Switch parameters are used - like boolean values. They default to `$false`. When you use a switch - parameter, the value is set to `$true`. + Parameters without values are _`[switch]` parameters_. `[switch]` parameters + are used like boolean values. They default to `$false`. When you use a + `[switch]` parameter, the value is set to `$true`. - For example, the **ListImported** parameter of `Get-Command` is a switch - parameter. When you use the **ListImported** parameter, the cmdlet return + For example, the **ListImported** parameter of `Get-Command` is a `[switch]` + parameter. When you use the **ListImported** parameter, the cmdlet returns only commands that were imported from modules in the current session. ```Syntax Get-Command [-ListImported] ``` - - Brackets `[ ]` around parameters indicate optional items. A parameter and its value can be optional. For example, the **CommandType** parameter of `Get-Command` and its value are enclosed in brackets because they're both diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md index e729af388ff1..5c7aee7a1cd8 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md @@ -263,7 +263,7 @@ For more information about the standard PowerShell verbs, see ## Functions with parameters You can use parameters with functions, including named parameters, positional -parameters, switch parameters, and dynamic parameters. For more information +parameters, `[switch]` parameters, and dynamic parameters. For more information about dynamic parameters in functions, see [about_Functions_Advanced_Parameters][09]. @@ -403,13 +403,12 @@ Get-Extension myTextFile myTextFile.txt ``` -### Switch parameters +### `[switch]` parameters A switch is a parameter that doesn't require a value. Instead, you type the -function name followed by the name of the switch parameter. +function name followed by the name of the `[switch]` parameter. -To define a switch parameter, specify the type `[switch]` before the parameter -name, as shown in the following example: +The following example shows how you define a `[switch]` parameter: ```powershell function Switch-Item { @@ -419,8 +418,9 @@ function Switch-Item { } ``` -When you type the `On` switch parameter after the function name, the function -displays `Switch on`. Without the switch parameter, it displays `Switch off`. +When you type the `On` `[switch]` parameter after the function name, the +function displays `Switch on`. Without the `[switch]` parameter, it displays +`Switch off`. ```powershell Switch-Item -On 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 eb97af896607..8b2bda21f7be 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: 03/10/2026 +ms.date: 04/08/2026 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 @@ -173,29 +173,28 @@ param( ) ``` -## Switch parameters +## `[switch]` parameters -Switch parameters are parameters that take no parameter value. Instead, they -convey a Boolean true-or-false value through their presence or absence, so that -when a switch parameter is present it has a **true** value and when absent it -has a **false** value. +`[switch]` parameters are parameters that take no parameter value. Instead, +they convey a Boolean true-or-false value through their presence or absence, so +that when a `[switch]` parameter is present it has a **true** value and when +absent it has a **false** value. -For example, the **Recurse** parameter of `Get-ChildItem` is a switch +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. 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: +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 +`[switch]` parameters are easy to use and are preferred over Boolean parameters that have a less natural syntax for PowerShell. -To use a switch parameter, include the parameter in the command. For example: +To use a `[switch]` parameter, include the parameter in the command. For +example: `-IncludeAll` @@ -203,38 +202,39 @@ To use a Boolean parameter, you must provide the parameter and a Boolean value. `-IncludeAll $true` -When creating switch parameters, choose the parameter name carefully. Be sure -that the parameter name communicates the effect of the parameter to the user. -Avoid ambiguous terms, such as **Filter** or **Maximum** that might imply a -value is required. +When creating `[switch]` parameters, choose the parameter name carefully. Be +sure that the parameter name communicates the effect of the parameter to the +user. Avoid ambiguous terms, such as **Filter** or **Maximum** that might imply +a value is required. -### Switch parameter design considerations +### `[switch]` parameter design considerations -- Don't set a default value for a switch parameter. Switch parameter always - default to false. -- 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 +- Don't set a default value for a `[switch]` parameter. `[switch]` parameters + always default to false. +- 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 them 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. -- Use the switch parameter variable directly in a conditional expression. The - `SwitchParameter` type implicitly converts to Boolean. For example: + 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. +- 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: +- Always base the behavior controlled by the `[switch]` parameter on the + _value_ of the parameter, not its _presence_. There are several ways to test + for the presence of a `[switch]` parameters: - - `$PSBoundParameters` contains the switch parameter name as a key - - `$MyInvocation.BoundParameters` contains the switch parameter name as a key + - `$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 For example, it's possible to provide an explicit value for the switch using @@ -802,7 +802,7 @@ Use the **System.Obsolete** attribute to mark parameters that are no longer supported. This can be useful when you want to remove a parameter from a function but you don't want to break existing scripts that use the function. -For example, consider a function that has a **NoTypeInformation** switch +For example, consider a function that has a **NoTypeInformation** `[switch]` parameter that controls whether type information is included in the output. You want to make that behavior the default and remove the parameter from the function. However, you don't want to break existing scripts that use the @@ -812,7 +812,7 @@ explains the change. ```powershell param( [System.Obsolete("The NoTypeInformation parameter is obsolete.")] - [SwitchParameter]$NoTypeInformation + [switch]$NoTypeInformation ) ``` diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index aa8cb55b493d..64d69534942f 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -104,8 +104,8 @@ $PSDefaultParameterValues = @{ ``` The cmdlet and parameter names can contain wildcard characters. Use `$true` and -`$false` to set values for switch parameters, such as **Verbose**. This example -sets the common parameter **Verbose** to `$true` for all commands. +`$false` to set values for `[switch]` parameters, such as **Verbose**. This +example sets the common parameter **Verbose** to `$true` for all commands. ```powershell $PSDefaultParameterValues = @{'*:Verbose'=$true} @@ -162,9 +162,9 @@ You can use a scriptblock to specify different default values for a parameter under different conditions. PowerShell evaluates the scriptblock and uses the result as the default parameter value. -The `Format-Table:AutoSize` key sets that switch parameter to a default value -of `$true` The `if` statement contains a condition that the `$Host.Name` must -be `ConsoleHost`. +The `Format-Table:AutoSize` key sets that `[switch]` parameter to a default +value of `$true`. The `if` statement contains a condition that the `$Host.Name` +must be `ConsoleHost`. ```powershell $PSDefaultParameterValues = @{ diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md index 6d5d896fd91c..fa48dd4a06ea 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md @@ -198,8 +198,8 @@ Get-Module -ListAvailable BitsTransfer # No output ``` -In both cases, the `-SkipEditionCheck` switch parameter can be used to override -this behavior: +In both cases, the `-SkipEditionCheck` `[switch]` parameter can be used to +override this behavior: ```powershell Get-Module -ListAvailable -SkipEditionCheck BitsTransfer diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Pwsh.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Pwsh.md index 8fba3d4bec73..dfa22c00d750 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Pwsh.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Pwsh.md @@ -69,15 +69,15 @@ and any parameters. File must be the last parameter in the command, because all characters typed after the File parameter name are interpreted as the script filepath followed by the script parameters. -Typically, the switch parameters of a script are either included or omitted. -For example, the following command uses the **All** parameter of the +Typically, the `[switch]` parameters of a script are either included or +omitted. For example, the following command uses the **All** parameter of the `Get-Script.ps1` script file: `-File .\Get-Script.ps1 -All` -In rare cases, you might need to provide a **Boolean** value for a switch -parameter. To provide a **Boolean** value for a switch parameter in the value -of the **File** parameter, Use the parameter normally followed immediately by a -colon and the boolean value, such as the following: -`-File .\Get-Script.ps1 -All:$false`. +In rare cases, you might need to provide a **Boolean** value for a `[switch]` +parameter. To provide a **Boolean** value for a `[switch]` parameter in the +value of the **File** parameter, use the parameter normally followed +immediately by a colon and the boolean value, such as the following: `-File +.\Get-Script.ps1 -All:$false`. Parameters passed to the script are passed as literal strings, after interpretation by the current shell. For example, if you are in `cmd.exe` and diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Requires.md index 406328a4be2d..b53c42199b3c 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Requires.md @@ -183,11 +183,11 @@ For example: #### -RunAsAdministrator -When this switch parameter is added to your `#Requires` statement, it specifies -that the PowerShell session in which you're running the script must be started -with elevated user rights. The **RunAsAdministrator** parameter is ignored on a -non-Windows operating system. The **RunAsAdministrator** parameter was -introduced in PowerShell 4.0. +When this `[switch]` parameter is added to your `#Requires` statement, it +specifies that the PowerShell session in which you're running the script must +be started with elevated user rights. The **RunAsAdministrator** parameter is +ignored on a non-Windows operating system. The **RunAsAdministrator** parameter +was introduced in PowerShell 4.0. For example: diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Splatting.md index 8e74cf530400..e37d4cf06b43 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -52,7 +52,7 @@ defining a parameter in a command. ## Splatting with hash tables Use a hash table to splat parameter name and value pairs. You can use this -format for all parameter types, including positional and switch parameters. +format for all parameter types, including positional and `[switch]` parameters. Positional parameters must be assigned by name. The following examples compare two `Copy-Item` commands that copy the Test.txt @@ -71,7 +71,7 @@ table of parameter-name and parameter-value pairs and stores it in the variable in a command with splatting. The At symbol (`@HashArguments`) replaces the dollar sign (`$HashArguments`) in the command. -To provide a value for the **WhatIf** switch parameter, use `$true` or +To provide a value for the **WhatIf** `[switch]` parameter, use `$true` or `$false`. ```powershell diff --git a/reference/7.5/Microsoft.PowerShell.Core/Disable-PSRemoting.md b/reference/7.5/Microsoft.PowerShell.Core/Disable-PSRemoting.md index efb9eb380446..29c138c39929 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Disable-PSRemoting.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Disable-PSRemoting.md @@ -236,7 +236,7 @@ A loopback connection is created when the following conditions are met: - The computer name to connect to is 'localhost'. - No credentials are passed in. Current logged in user (implicit credentials) is used for the connection. -- The **EnableNetworkAccess** switch parameter is used. +- The **EnableNetworkAccess** `[switch]` parameter is used. For more information on loopback connections, see [New-PSSession](New-PSSession.md) document. diff --git a/reference/7.5/Microsoft.PowerShell.Core/Get-Help.md b/reference/7.5/Microsoft.PowerShell.Core/Get-Help.md index c84b2e9a99ee..1035ccafcbf4 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Get-Help.md @@ -191,7 +191,7 @@ Get-Help Format-Table -Parameter GroupBy ``` The **Examples** parameter displays the help file's **NAME** and **SYNOPSIS** sections, and all the -Examples. You can't specify an Example number because the **Examples** parameter is a switch +Examples. You can't specify an Example number because the **Examples** parameter is a `[switch]` parameter. The **Parameter** parameter displays only the descriptions of the specified parameters. If you diff --git a/reference/7.5/Microsoft.PowerShell.Core/Where-Object.md b/reference/7.5/Microsoft.PowerShell.Core/Where-Object.md index d10c9acde17d..0d0b94dc0455 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Where-Object.md @@ -263,9 +263,9 @@ command. All PowerShell comparison operators are valid in the scriptblock format. For more information, see [about_Comparison_Operators](./About/about_Comparison_Operators.md). -- **Simplified syntax**. To enable the simiplified syntax, `Where-Object` includes 31 switch +- **Simplified syntax**. To enable the simplified syntax, `Where-Object` includes 31 `[switch]` parameters that represent the comparison operators. The simplified syntax is easier to read and - write than the scriptblock syntax. You can combine one of the switch parameters with the + write than the scriptblock syntax. You can combine one of the `[switch]` parameters with the **Property** and **Value** parameters to create a command that filters objects based on the values of their properties. @@ -278,7 +278,7 @@ command. As shown in the example, the parameter names **Property** and **Value** are optional. The **Property** parameter is a positional parameter mapped to position `0`. The **Value** parameter - is a positional parameter mapped to position `1`. The switch parameter, used to specify the + is a positional parameter mapped to position `1`. The `[switch]` parameter, used to specify the comparison, can be used in any position. The simplified syntax was introduced in Windows PowerShell 3.0. For more information, see diff --git a/reference/7.5/Microsoft.PowerShell.Management/Resolve-Path.md b/reference/7.5/Microsoft.PowerShell.Management/Resolve-Path.md index 6564915e0fd9..9bb6ff2b1b06 100644 --- a/reference/7.5/Microsoft.PowerShell.Management/Resolve-Path.md +++ b/reference/7.5/Microsoft.PowerShell.Management/Resolve-Path.md @@ -113,8 +113,8 @@ Resolve-Path -LiteralPath 'test[xml]' ### Example 7: Resolve a path relative to another folder This example uses the **RelativeBasePath** parameter to resolve the path of the `pwsh` executable -relative to `$Env:TEMP`. When the command includes the **Relative** switch parameter, it returns a -**String** representing the relative path from `$Env:TEMP` to the `pwsh` executable. +relative to `$Env:TEMP`. When the command includes the **Relative** `[switch]` parameter, it +returns a **String** representing the relative path from `$Env:TEMP` to the `pwsh` executable. ```powershell $ExecutablePath = Get-Command -Name pwsh | Select-Object -ExpandProperty Source @@ -266,7 +266,7 @@ Accept wildcard characters: False Specifies a path to resolve the relative path from. When you use this parameter, the cmdlet returns the **System.Management.Automation.PathInfo** object for the resolved path. -When you use this parameter with the **Relative** switch parameter, the cmdlet returns a string +When you use this parameter with the **Relative** `[switch]` parameter, the cmdlet returns a string representing the relative path from **RelativeBasePath** to **Path**. This parameter was added in PowerShell 7.4. diff --git a/reference/7.5/Microsoft.PowerShell.Utility/ConvertTo-Json.md b/reference/7.5/Microsoft.PowerShell.Utility/ConvertTo-Json.md index 2c62266cdfee..696db12d2d08 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/ConvertTo-Json.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/ConvertTo-Json.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 05/16/2024 +ms.date: 04/08/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-json?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertTo-Json @@ -31,17 +31,16 @@ property values, and the methods are removed. > As of PowerShell 7.2, Extended Type System properties of **DateTime** and **String** objects are > no longer serialized and only the simple object is converted to JSON format -You can then use the `ConvertFrom-Json` cmdlet to convert a JSON-formatted string to a JSON -object, which is easily managed in PowerShell. +You can then use the `ConvertFrom-Json` cmdlet to convert a JSON-formatted string to a JSON object, +which is easily managed in PowerShell. Many web sites use JSON instead of XML to serialize data for communication between servers and web-based apps. -As of PowerShell 7.1, `ConvertTo-Json` emits a warning if the depth of the input object exceeds -the depth specified for the command. This prevents unwanted data loss when converting objects. +As of PowerShell 7.1, `ConvertTo-Json` emits a warning if the depth of the input object exceeds the +depth specified for the command. This prevents unwanted data loss when converting objects. -As of PowerShell 7.5-preview.3, `ConvertTo-Json` can serialize **BigInteger** values as raw JSON -numbers. +As of PowerShell 7.5, `ConvertTo-Json` can serialize **BigInteger** values as raw JSON numbers. This cmdlet was introduced in Windows PowerShell 3.0. @@ -208,8 +207,8 @@ Accept wildcard characters: False ### -Depth Specifies how many levels of contained objects are included in the JSON representation. The value -can be any number from `0` to `100`. The default value is `2`. `ConvertTo-Json` emits a -warning if the number of levels in an input object exceeds this number. +can be any number from `0` to `100`. The default value is `2`. `ConvertTo-Json` emits a warning if +the number of levels in an input object exceeds this number. ```yaml Type: System.Int32 @@ -247,9 +246,9 @@ characters (like newline) are escaped. Acceptable values are: -- Default - Only control characters are escaped. -- EscapeNonAscii - All non-ASCII and control characters are escaped. -- EscapeHtml - HTML (`<`, `>`, `&`, `'`, `"`) and control characters are escaped. +- `Default` - Only control characters are escaped. +- `EscapeNonAscii` - All non-ASCII and control characters are escaped. +- `EscapeHtml` - HTML (`<`, `>`, `&`, `'`, `"`) and control characters are escaped. This parameter was introduced in PowerShell 6.2. diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Show-Command.md b/reference/7.5/Microsoft.PowerShell.Utility/Show-Command.md index 5b9d05cdf239..c64913da5b0a 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Show-Command.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Show-Command.md @@ -37,10 +37,10 @@ all installed modules. To find the commands in a module, select the module from drop-down list. To select a command, click the command name. To use the command window, select a command, either by using the Name or by clicking the command -name in the **Commands** list. Each parameter set is displayed on a separate tab. Asterisks indicate -the mandatory parameters. To enter values for a parameter, type the value in the text box or select -the value from the drop-down box. To add a switch parameter, click to select the parameter check -box. +name in the **Commands** list. Each parameter set is displayed on a separate tab. Asterisks +indicate the mandatory parameters. To enter values for a parameter, type the value in the text box +or select the value from the drop-down box. To add a `[switch]` parameter, click to select the +parameter check box. When you're ready, you can click **Copy** to copy the command that you've created to the clipboard or click **Run** to run the command. You can also use the **PassThru** parameter to return the diff --git a/reference/7.6/CimCmdlets/New-CimSession.md b/reference/7.6/CimCmdlets/New-CimSession.md index 14b5ed7bd13c..1d56932755b9 100644 --- a/reference/7.6/CimCmdlets/New-CimSession.md +++ b/reference/7.6/CimCmdlets/New-CimSession.md @@ -333,8 +333,8 @@ By default, the `New-CimSession` cmdlet establishes a connection with a remote W endpoint for two reasons: to verify that the remote server is listening on the port number that is specified using the **Port** parameter, and to verify the specified account credentials. The verification is accomplished using a standard WS-Identity operation. You can add the -**SkipTestConnection** switch parameter if the remote WS-Management endpoint cannot use WS-Identify, -or to reduce some data transmission time. +**SkipTestConnection** `[switch]` parameter if the remote WS-Management endpoint cannot use +WS-Identify, or to reduce some data transmission time. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index 9cddeb993df0..e00f94f9b616 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -198,19 +198,18 @@ The syntax diagrams use the following symbols: - Parameters with no values Some parameters don't accept input, so they don't have a parameter value. - Parameters without values are _switch parameters_. Switch parameters are used - like boolean values. They default to `$false`. When you use a switch - parameter, the value is set to `$true`. + Parameters without values are _`[switch]` parameters_. `[switch]` parameters + are used like boolean values. They default to `$false`. When you use a + `[switch]` parameter, the value is set to `$true`. - For example, the **ListImported** parameter of `Get-Command` is a switch - parameter. When you use the **ListImported** parameter, the cmdlet return + For example, the **ListImported** parameter of `Get-Command` is a `[switch]` + parameter. When you use the **ListImported** parameter, the cmdlet returns only commands that were imported from modules in the current session. ```Syntax Get-Command [-ListImported] ``` - - Brackets `[ ]` around parameters indicate optional items. A parameter and its value can be optional. For example, the **CommandType** parameter of `Get-Command` and its value are enclosed in brackets because they're both diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions.md index 125cf409748d..174420c52314 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions.md @@ -263,7 +263,7 @@ For more information about the standard PowerShell verbs, see ## Functions with parameters You can use parameters with functions, including named parameters, positional -parameters, switch parameters, and dynamic parameters. For more information +parameters, `[switch]` parameters, and dynamic parameters. For more information about dynamic parameters in functions, see [about_Functions_Advanced_Parameters][09]. @@ -403,13 +403,12 @@ Get-Extension myTextFile myTextFile.txt ``` -### Switch parameters +### `[switch]` parameters A switch is a parameter that doesn't require a value. Instead, you type the -function name followed by the name of the switch parameter. +function name followed by the name of the `[switch]` parameter. -To define a switch parameter, specify the type `[switch]` before the parameter -name, as shown in the following example: +The following example shows how you define a `[switch]` parameter: ```powershell function Switch-Item { @@ -419,8 +418,9 @@ function Switch-Item { } ``` -When you type the `On` switch parameter after the function name, the function -displays `Switch on`. Without the switch parameter, it displays `Switch off`. +When you type the `On` `[switch]` parameter after the function name, the +function displays `Switch on`. Without the `[switch]` parameter, it displays +`Switch off`. ```powershell Switch-Item -On 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 328cc07c5bcb..daeb5b535c73 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: 03/10/2026 +ms.date: 04/08/2026 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 @@ -173,29 +173,28 @@ param( ) ``` -## Switch parameters +## `[switch]` parameters -Switch parameters are parameters that take no parameter value. Instead, they -convey a Boolean true-or-false value through their presence or absence, so that -when a switch parameter is present it has a **true** value and when absent it -has a **false** value. +`[switch]` parameters are parameters that take no parameter value. Instead, +they convey a Boolean true-or-false value through their presence or absence, so +that when a `[switch]` parameter is present it has a **true** value and when +absent it has a **false** value. -For example, the **Recurse** parameter of `Get-ChildItem` is a switch +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. 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: +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 +`[switch]` parameters are easy to use and are preferred over Boolean parameters that have a less natural syntax for PowerShell. -To use a switch parameter, include the parameter in the command. For example: +To use a `[switch]` parameter, include the parameter in the command. For +example: `-IncludeAll` @@ -203,38 +202,39 @@ To use a Boolean parameter, you must provide the parameter and a Boolean value. `-IncludeAll $true` -When creating switch parameters, choose the parameter name carefully. Be sure -that the parameter name communicates the effect of the parameter to the user. -Avoid ambiguous terms, such as **Filter** or **Maximum** that might imply a -value is required. +When creating `[switch]` parameters, choose the parameter name carefully. Be +sure that the parameter name communicates the effect of the parameter to the +user. Avoid ambiguous terms, such as **Filter** or **Maximum** that might imply +a value is required. -### Switch parameter design considerations +### `[switch]` parameter design considerations -- Don't set a default value for a switch parameter. Switch parameter always - default to false. -- 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 +- Don't set a default value for a `[switch]` parameter. `[switch]` parameters + always default to false. +- 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 them 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. -- Use the switch parameter variable directly in a conditional expression. The - `SwitchParameter` type implicitly converts to Boolean. For example: + 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. +- 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: +- Always base the behavior controlled by the `[switch]` parameter on the + _value_ of the parameter, not its _presence_. There are several ways to test + for the presence of a `[switch]` parameters: - - `$PSBoundParameters` contains the switch parameter name as a key - - `$MyInvocation.BoundParameters` contains the switch parameter name as a key + - `$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 For example, it's possible to provide an explicit value for the switch using @@ -802,7 +802,7 @@ Use the **System.Obsolete** attribute to mark parameters that are no longer supported. This can be useful when you want to remove a parameter from a function but you don't want to break existing scripts that use the function. -For example, consider a function that has a **NoTypeInformation** switch +For example, consider a function that has a **NoTypeInformation** `[switch]` parameter that controls whether type information is included in the output. You want to make that behavior the default and remove the parameter from the function. However, you don't want to break existing scripts that use the @@ -812,7 +812,7 @@ explains the change. ```powershell param( [System.Obsolete("The NoTypeInformation parameter is obsolete.")] - [SwitchParameter]$NoTypeInformation + [switch]$NoTypeInformation ) ``` diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md index 337bc79e27b5..e1502be39acb 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Parameters_Default_Values.md @@ -104,8 +104,8 @@ $PSDefaultParameterValues = @{ ``` The cmdlet and parameter names can contain wildcard characters. Use `$true` and -`$false` to set values for switch parameters, such as **Verbose**. This example -sets the common parameter **Verbose** to `$true` for all commands. +`$false` to set values for `[switch]` parameters, such as **Verbose**. This +example sets the common parameter **Verbose** to `$true` for all commands. ```powershell $PSDefaultParameterValues = @{'*:Verbose'=$true} @@ -162,9 +162,9 @@ You can use a scriptblock to specify different default values for a parameter under different conditions. PowerShell evaluates the scriptblock and uses the result as the default parameter value. -The `Format-Table:AutoSize` key sets that switch parameter to a default value -of `$true` The `if` statement contains a condition that the `$Host.Name` must -be `ConsoleHost`. +The `Format-Table:AutoSize` key sets that `[switch]` parameter to a default +value of `$true`. The `if` statement contains a condition that the `$Host.Name` +must be `ConsoleHost`. ```powershell $PSDefaultParameterValues = @{ diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md index 992d90e2a828..46b1edad6d18 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md @@ -198,8 +198,8 @@ Get-Module -ListAvailable BitsTransfer # No output ``` -In both cases, the `-SkipEditionCheck` switch parameter can be used to override -this behavior: +In both cases, the `-SkipEditionCheck` `[switch]` parameter can be used to +override this behavior: ```powershell Get-Module -ListAvailable -SkipEditionCheck BitsTransfer diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Pwsh.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Pwsh.md index 1e38805dd44a..4be59a6cda73 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Pwsh.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Pwsh.md @@ -69,15 +69,15 @@ and any parameters. File must be the last parameter in the command, because all characters typed after the File parameter name are interpreted as the script filepath followed by the script parameters. -Typically, the switch parameters of a script are either included or omitted. -For example, the following command uses the **All** parameter of the +Typically, the `[switch]` parameters of a script are either included or +omitted. For example, the following command uses the **All** parameter of the `Get-Script.ps1` script file: `-File .\Get-Script.ps1 -All` -In rare cases, you might need to provide a **Boolean** value for a switch -parameter. To provide a **Boolean** value for a switch parameter in the value -of the **File** parameter, Use the parameter normally followed immediately by a -colon and the boolean value, such as the following: -`-File .\Get-Script.ps1 -All:$false`. +In rare cases, you might need to provide a **Boolean** value for a `[switch]` +parameter. To provide a **Boolean** value for a `[switch]` parameter in the +value of the **File** parameter, use the parameter normally followed +immediately by a colon and the boolean value, such as the following: `-File +.\Get-Script.ps1 -All:$false`. Parameters passed to the script are passed as literal strings, after interpretation by the current shell. For example, if you are in `cmd.exe` and diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Requires.md index f29aa723600c..be32ef1c7756 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Requires.md @@ -183,11 +183,11 @@ For example: #### -RunAsAdministrator -When this switch parameter is added to your `#Requires` statement, it specifies -that the PowerShell session in which you're running the script must be started -with elevated user rights. The **RunAsAdministrator** parameter is ignored on a -non-Windows operating system. The **RunAsAdministrator** parameter was -introduced in PowerShell 4.0. +When this `[switch]` parameter is added to your `#Requires` statement, it +specifies that the PowerShell session in which you're running the script must +be started with elevated user rights. The **RunAsAdministrator** parameter is +ignored on a non-Windows operating system. The **RunAsAdministrator** parameter +was introduced in PowerShell 4.0. For example: diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Splatting.md index d568b15ea19e..56603090cfb2 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -52,7 +52,7 @@ defining a parameter in a command. ## Splatting with hash tables Use a hash table to splat parameter name and value pairs. You can use this -format for all parameter types, including positional and switch parameters. +format for all parameter types, including positional and `[switch]` parameters. Positional parameters must be assigned by name. The following examples compare two `Copy-Item` commands that copy the Test.txt @@ -71,7 +71,7 @@ table of parameter-name and parameter-value pairs and stores it in the variable in a command with splatting. The At symbol (`@HashArguments`) replaces the dollar sign (`$HashArguments`) in the command. -To provide a value for the **WhatIf** switch parameter, use `$true` or +To provide a value for the **WhatIf** `[switch]` parameter, use `$true` or `$false`. ```powershell diff --git a/reference/7.6/Microsoft.PowerShell.Core/Disable-PSRemoting.md b/reference/7.6/Microsoft.PowerShell.Core/Disable-PSRemoting.md index 37d7dfc9efae..5f93d0c8a5de 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/Disable-PSRemoting.md +++ b/reference/7.6/Microsoft.PowerShell.Core/Disable-PSRemoting.md @@ -235,7 +235,7 @@ A loopback connection is created when the following conditions are met: - The computer name to connect to is 'localhost'. - No credentials are passed in. Current logged in user (implicit credentials) is used for the connection. -- The **EnableNetworkAccess** switch parameter is used. +- The **EnableNetworkAccess** `[switch]` parameter is used. For more information on loopback connections, see [New-PSSession](New-PSSession.md) document. diff --git a/reference/7.6/Microsoft.PowerShell.Core/Get-Help.md b/reference/7.6/Microsoft.PowerShell.Core/Get-Help.md index 54ff838f08ee..936e1d44149c 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/7.6/Microsoft.PowerShell.Core/Get-Help.md @@ -191,7 +191,7 @@ Get-Help Format-Table -Parameter GroupBy ``` The **Examples** parameter displays the help file's **NAME** and **SYNOPSIS** sections, and all the -Examples. You can't specify an Example number because the **Examples** parameter is a switch +Examples. You can't specify an Example number because the **Examples** parameter is a `[switch]` parameter. The **Parameter** parameter displays only the descriptions of the specified parameters. If you diff --git a/reference/7.6/Microsoft.PowerShell.Core/Where-Object.md b/reference/7.6/Microsoft.PowerShell.Core/Where-Object.md index 4c2ee64c9ae5..48e8fc41be03 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/7.6/Microsoft.PowerShell.Core/Where-Object.md @@ -263,9 +263,9 @@ command. All PowerShell comparison operators are valid in the scriptblock format. For more information, see [about_Comparison_Operators](./About/about_Comparison_Operators.md). -- **Simplified syntax**. To enable the simiplified syntax, `Where-Object` includes 31 switch +- **Simplified syntax**. To enable the simplified syntax, `Where-Object` includes 31 `[switch]` parameters that represent the comparison operators. The simplified syntax is easier to read and - write than the scriptblock syntax. You can combine one of the switch parameters with the + write than the scriptblock syntax. You can combine one of the `[switch]` parameters with the **Property** and **Value** parameters to create a command that filters objects based on the values of their properties. @@ -278,7 +278,7 @@ command. As shown in the example, the parameter names **Property** and **Value** are optional. The **Property** parameter is a positional parameter mapped to position `0`. The **Value** parameter - is a positional parameter mapped to position `1`. The switch parameter, used to specify the + is a positional parameter mapped to position `1`. The `[switch]` parameter, used to specify the comparison, can be used in any position. The simplified syntax was introduced in Windows PowerShell 3.0. For more information, see diff --git a/reference/7.6/Microsoft.PowerShell.Management/Join-Path.md b/reference/7.6/Microsoft.PowerShell.Management/Join-Path.md index d487bf827bb3..8200e6357440 100644 --- a/reference/7.6/Microsoft.PowerShell.Management/Join-Path.md +++ b/reference/7.6/Microsoft.PowerShell.Management/Join-Path.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 12/10/2025 +ms.date: 04/08/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/join-path?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: Join-Path @@ -16,7 +16,7 @@ Combines a path and a child path into a single path. ``` Join-Path [-Path] [-ChildPath] [[-AdditionalChildPath] ] [-Resolve] - [-Credential ] [-Extension ] [] + [-Credential ] [] ``` ## DESCRIPTION @@ -150,46 +150,6 @@ Join-Path -Path a -ChildPath b, c, d, e, f, g a\b\c\d\e\f\g ``` -### Example 9: Add extension to file without extension - -```powershell -Join-Path C:\Temp myfile -Extension txt -``` - -```Output -C:\Temp\myfile.txt -``` - -### Example 10: Change existing extension - -```powershell -Join-Path C:\Temp myfile.txt -Extension .log -``` - -```Output -C:\Temp\myfile.log -``` - -### Example 11: Extension without leading dot - -```powershell -Join-Path C:\Temp file.txt -Extension log -``` - -```Output -C:\Temp\file.log -``` - -### Example 12: Remove extension with empty string - -```powershell -Join-Path C:\Temp file.txt -Extension "" -``` - -```Output -C:\Temp\file -``` - ## PARAMETERS ### -AdditionalChildPath @@ -251,28 +211,6 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Extension - -Specifies the extension to use for the resulting path. If not specified, the original extension is -preserved. The leading dot in the extension is optional. If omitted, the command adds it -automatically. - -- If the path has an existing extension, it's replaced with the specified extension. -- If the path has no extension, the specified extension is added. -- If you provide an empty string, the existing extension is removed. - -```yaml -Type: System.String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: True -``` - ### -Path Specifies the main path (or paths) to which the child-path is appended. The value of **Path** diff --git a/reference/7.6/Microsoft.PowerShell.Management/Resolve-Path.md b/reference/7.6/Microsoft.PowerShell.Management/Resolve-Path.md index 4e76b97dc210..88e138326cb4 100644 --- a/reference/7.6/Microsoft.PowerShell.Management/Resolve-Path.md +++ b/reference/7.6/Microsoft.PowerShell.Management/Resolve-Path.md @@ -113,8 +113,8 @@ Resolve-Path -LiteralPath 'test[xml]' ### Example 7: Resolve a path relative to another folder This example uses the **RelativeBasePath** parameter to resolve the path of the `pwsh` executable -relative to `$Env:TEMP`. When the command includes the **Relative** switch parameter, it returns a -**String** representing the relative path from `$Env:TEMP` to the `pwsh` executable. +relative to `$Env:TEMP`. When the command includes the **Relative** `[switch]` parameter, it +returns a **String** representing the relative path from `$Env:TEMP` to the `pwsh` executable. ```powershell $ExecutablePath = Get-Command -Name pwsh | Select-Object -ExpandProperty Source @@ -266,7 +266,7 @@ Accept wildcard characters: False Specifies a path to resolve the relative path from. When you use this parameter, the cmdlet returns the **System.Management.Automation.PathInfo** object for the resolved path. -When you use this parameter with the **Relative** switch parameter, the cmdlet returns a string +When you use this parameter with the **Relative** `[switch]` parameter, the cmdlet returns a string representing the relative path from **RelativeBasePath** to **Path**. This parameter was added in PowerShell 7.4. diff --git a/reference/7.6/Microsoft.PowerShell.Utility/ConvertTo-Json.md b/reference/7.6/Microsoft.PowerShell.Utility/ConvertTo-Json.md index f99c04183d81..e57b24d4970f 100644 --- a/reference/7.6/Microsoft.PowerShell.Utility/ConvertTo-Json.md +++ b/reference/7.6/Microsoft.PowerShell.Utility/ConvertTo-Json.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 05/16/2024 +ms.date: 04/08/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-json?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: ConvertTo-Json @@ -28,21 +28,19 @@ The `ConvertTo-Json` cmdlet converts any .NET object to a string in JavaScript O property values, and the methods are removed. > [!NOTE] -> As of PowerShell 7.2, Extended Type System properties of **DateTime** and -> **String** objects are no longer serialized and only the simple object is -> converted to JSON format +> As of PowerShell 7.2, Extended Type System properties of **DateTime** and **String** objects are +> no longer serialized and only the simple object is converted to JSON format -You can then use the `ConvertFrom-Json` cmdlet to convert a JSON-formatted string to a JSON -object, which is easily managed in PowerShell. +You can then use the `ConvertFrom-Json` cmdlet to convert a JSON-formatted string to a JSON object, +which is easily managed in PowerShell. Many web sites use JSON instead of XML to serialize data for communication between servers and web-based apps. -As of PowerShell 7.1, `ConvertTo-Json` emits a warning if the depth of the input object exceeds -the depth specified for the command. This prevents unwanted data loss when converting objects. +As of PowerShell 7.1, `ConvertTo-Json` emits a warning if the depth of the input object exceeds the +depth specified for the command. This prevents unwanted data loss when converting objects. -As of PowerShell 7.5-preview.3, `ConvertTo-Json` can serialize **BigInteger** values as raw JSON -numbers. +As of PowerShell 7.5, `ConvertTo-Json` can serialize **BigInteger** values as raw JSON numbers. This cmdlet was introduced in Windows PowerShell 3.0. @@ -209,8 +207,8 @@ Accept wildcard characters: False ### -Depth Specifies how many levels of contained objects are included in the JSON representation. The value -can be any number from `0` to `100`. The default value is `2`. `ConvertTo-Json` emits a -warning if the number of levels in an input object exceeds this number. +can be any number from `0` to `100`. The default value is `2`. `ConvertTo-Json` emits a warning if +the number of levels in an input object exceeds this number. ```yaml Type: System.Int32 @@ -226,7 +224,8 @@ Accept wildcard characters: False ### -EnumsAsStrings -Provides an alternative serialization option that converts all enumerations to their string representation. +Provides an alternative serialization option that converts all enumerations to their string +representation. ```yaml Type: System.Management.Automation.SwitchParameter @@ -247,9 +246,9 @@ characters (like newline) are escaped. Acceptable values are: -- Default - Only control characters are escaped. -- EscapeNonAscii - All non-ASCII and control characters are escaped. -- EscapeHtml - HTML (`<`, `>`, `&`, `'`, `"`) and control characters are escaped. +- `Default` - Only control characters are escaped. +- `EscapeNonAscii` - All non-ASCII and control characters are escaped. +- `EscapeHtml` - HTML (`<`, `>`, `&`, `'`, `"`) and control characters are escaped. This parameter was introduced in PowerShell 6.2. @@ -292,7 +291,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.6/Microsoft.PowerShell.Utility/Show-Command.md b/reference/7.6/Microsoft.PowerShell.Utility/Show-Command.md index 2f74d00481fa..4e1a97570ab3 100644 --- a/reference/7.6/Microsoft.PowerShell.Utility/Show-Command.md +++ b/reference/7.6/Microsoft.PowerShell.Utility/Show-Command.md @@ -37,10 +37,10 @@ all installed modules. To find the commands in a module, select the module from drop-down list. To select a command, click the command name. To use the command window, select a command, either by using the Name or by clicking the command -name in the **Commands** list. Each parameter set is displayed on a separate tab. Asterisks indicate -the mandatory parameters. To enter values for a parameter, type the value in the text box or select -the value from the drop-down box. To add a switch parameter, click to select the parameter check -box. +name in the **Commands** list. Each parameter set is displayed on a separate tab. Asterisks +indicate the mandatory parameters. To enter values for a parameter, type the value in the text box +or select the value from the drop-down box. To add a `[switch]` parameter, click to select the +parameter check box. When you're ready, you can click **Copy** to copy the command that you've created to the clipboard or click **Run** to run the command. You can also use the **PassThru** parameter to return the diff --git a/reference/docs-conceptual/developer/cmdlet/background-jobs.md b/reference/docs-conceptual/developer/cmdlet/background-jobs.md index 52e9ca8d0a6b..258cdcefb63a 100644 --- a/reference/docs-conceptual/developer/cmdlet/background-jobs.md +++ b/reference/docs-conceptual/developer/cmdlet/background-jobs.md @@ -23,7 +23,8 @@ For more information about how background jobs are handled at the command line, To write a cmdlet that can be run as a background job, you must complete the following tasks: -- Define an `asJob` switch parameter so that the user can decide whether to run the cmdlet as a background job. +- Define an `AsJob` `[switch]` parameter so that the user can decide whether to run the cmdlet as a + background job. - Create an object that derives from the [System.Management.Automation.Job](/dotnet/api/System.Management.Automation.Job) class. This object can be a custom job object or a job object provided by Windows PowerShell, such as a [System.Management.Automation.PSEventJob](/dotnet/api/System.Management.Automation.PSEventJob) object. diff --git a/reference/docs-conceptual/developer/cmdlet/cmdlet-dynamic-parameters.md b/reference/docs-conceptual/developer/cmdlet/cmdlet-dynamic-parameters.md index cc297bf9039e..f45b3c528ce6 100644 --- a/reference/docs-conceptual/developer/cmdlet/cmdlet-dynamic-parameters.md +++ b/reference/docs-conceptual/developer/cmdlet/cmdlet-dynamic-parameters.md @@ -9,7 +9,7 @@ title: Cmdlet Dynamic Parameters Cmdlets can define parameters that are available to the user under special conditions, such as when the argument of another parameter is a specific value. These parameters are added at runtime and are referred to as dynamic parameters because they're only added when needed. For example, you can -design a cmdlet that adds several parameters only when a specific switch parameter is specified. +design a cmdlet that adds several parameters only when a specific `[switch]` parameter is specified. > [!NOTE] > Providers and PowerShell functions can also define dynamic parameters. diff --git a/reference/docs-conceptual/developer/cmdlet/cmdlet-overview.md b/reference/docs-conceptual/developer/cmdlet/cmdlet-overview.md index ed5977f4c09b..a1e3101bf6c6 100644 --- a/reference/docs-conceptual/developer/cmdlet/cmdlet-overview.md +++ b/reference/docs-conceptual/developer/cmdlet/cmdlet-overview.md @@ -49,8 +49,8 @@ about this attribute, see [Cmdlet Attribute Declaration](cmdlet-attribute-declar ### Cmdlet parameter The public properties that define the parameters that are available to the user or to the -application that is running the cmdlet. Cmdlets can have required, named, positional, and *switch* -parameters. Switch parameters allow you to define parameters that are evaluated only if the +application that is running the cmdlet. Cmdlets can have required, named, positional, and `[switch]` +parameters. `[switch]` parameters allow you to define parameters that are evaluated only if the parameters are specified in the call. For more information about the different types of parameters, see [Cmdlet Parameters](cmdlet-parameters.md). diff --git a/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-to-access-a-data-store.md b/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-to-access-a-data-store.md index e6992c90c7fb..7d5ff7ae360b 100644 --- a/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-to-access-a-data-store.md +++ b/reference/docs-conceptual/developer/cmdlet/creating-a-cmdlet-to-access-a-data-store.md @@ -145,10 +145,11 @@ public ScriptBlock Script ScriptBlock script; ``` -The `SimpleMatch` parameter is a switch parameter that indicates whether the cmdlet is to explicitly -match the patterns as they are supplied. When the user specifies the parameter at the command line -(`true`), the cmdlet uses the patterns as they are supplied. If the parameter is not specified -(`false`), the cmdlet uses regular expressions. The default for this parameter is `false`. +The `SimpleMatch` parameter is a `[switch]` parameter that indicates whether the cmdlet is to +explicitly match the patterns as they are supplied. When the user specifies the parameter at the +command line (`true`), the cmdlet uses the patterns as they are supplied. If the parameter is not +specified (`false`), the cmdlet uses regular expressions. The default for this parameter is +`false`. ```csharp [Parameter] @@ -160,12 +161,12 @@ public SwitchParameter SimpleMatch private bool simpleMatch; ``` -The `CaseSensitive` parameter is a switch parameter that indicates whether a case-sensitive search -is performed. When the user specifies the parameter at the command line (`true`), the cmdlet checks -for the uppercase and lowercase of characters when comparing patterns. If the parameter is not -specified (`false`), the cmdlet does not distinguish between uppercase and lowercase. For example -"MyFile" and "myfile" would both be returned as positive hits. The default for this parameter is -`false`. +The `CaseSensitive` parameter is a `[switch]` parameter that indicates whether a case-sensitive +search is performed. When the user specifies the parameter at the command line (`true`), the cmdlet +checks for the uppercase and lowercase of characters when comparing patterns. If the parameter is +not specified (`false`), the cmdlet does not distinguish between uppercase and lowercase. For +example "MyFile" and "myfile" would both be returned as positive hits. The default for this +parameter is `false`. ```csharp [Parameter] diff --git a/reference/docs-conceptual/developer/cmdlet/how-to-declare-cmdlet-parameters.md b/reference/docs-conceptual/developer/cmdlet/how-to-declare-cmdlet-parameters.md index 31dd723f9d3d..ef2d96ce67ad 100644 --- a/reference/docs-conceptual/developer/cmdlet/how-to-declare-cmdlet-parameters.md +++ b/reference/docs-conceptual/developer/cmdlet/how-to-declare-cmdlet-parameters.md @@ -5,7 +5,8 @@ title: How to Declare Cmdlet Parameters --- # How to Declare Cmdlet Parameters -These examples show how to declare named, positional, required, optional, and switch parameters. These examples also show how to define a parameter alias. +These examples show how to declare named, positional, required, optional, and `[switch]` +parameters. These examples also show how to define a parameter alias. ## How to Declare a Named Parameter @@ -69,7 +70,7 @@ For more information about the Parameter attribute, see [Parameter Attribute Dec private string userName; ``` -## How to Declare a Switch Parameter +## How to Declare a `[switch]` parameter - Define a public property as type [System.Management.Automation.SwitchParameter](/dotnet/api/System.Management.Automation.SwitchParameter), and then declare the Parameter attribute. diff --git a/reference/docs-conceptual/developer/cmdlet/how-to-declare-dynamic-parameters.md b/reference/docs-conceptual/developer/cmdlet/how-to-declare-dynamic-parameters.md index 2ed1ebee8aa9..a7814ed635fb 100644 --- a/reference/docs-conceptual/developer/cmdlet/how-to-declare-dynamic-parameters.md +++ b/reference/docs-conceptual/developer/cmdlet/how-to-declare-dynamic-parameters.md @@ -7,7 +7,7 @@ title: How to Declare Dynamic Parameters This example shows how to define dynamic parameters that are added to the cmdlet at runtime. In this example, the `Department` parameter is added to the cmdlet whenever the user specifies the -`Employee` switch parameter. For more information about dynamic parameters, see +`Employee` `[switch]` parameter. For more information about dynamic parameters, see [Cmdlet Dynamic Parameters][02]. ## To define dynamic parameters diff --git a/reference/docs-conceptual/developer/cmdlet/how-to-support-jobs.md b/reference/docs-conceptual/developer/cmdlet/how-to-support-jobs.md index 2e820f781a5e..5e03eada2f48 100644 --- a/reference/docs-conceptual/developer/cmdlet/how-to-support-jobs.md +++ b/reference/docs-conceptual/developer/cmdlet/how-to-support-jobs.md @@ -11,8 +11,8 @@ information about background jobs, see [Background Jobs](./background-jobs.md). ## To support jobs -1. Define an `AsJob` switch parameter so that the user can decide whether to run the cmdlet as a - job. +1. Define an `AsJob` `[switch]` parameter so that the user can decide whether to run the cmdlet as + a job. The following example shows an AsJob parameter declaration. diff --git a/reference/docs-conceptual/developer/cmdlet/requesting-confirmation-from-cmdlets.md b/reference/docs-conceptual/developer/cmdlet/requesting-confirmation-from-cmdlets.md index 7b18229ba4f9..f55b8e6448c3 100644 --- a/reference/docs-conceptual/developer/cmdlet/requesting-confirmation-from-cmdlets.md +++ b/reference/docs-conceptual/developer/cmdlet/requesting-confirmation-from-cmdlets.md @@ -48,9 +48,10 @@ additional confirmation. For these cases, supplement the to more finely control the scope of the **Yes to all** response to the confirmation prompt. If a cmdlet calls the [System.Management.Automation.Cmdlet.ShouldContinue][02] method, the cmdlet -must also provide a `Force` switch parameter. If the user specifies `Force` when the user invokes -the cmdlet, the cmdlet should still call [System.Management.Automation.Cmdlet.ShouldProcess][03], -but it should bypass the call to [System.Management.Automation.Cmdlet.ShouldContinue][02]. +must also provide a `Force` `[switch]` parameter. If the user specifies `Force` when the user +invokes the cmdlet, the cmdlet should still call +[System.Management.Automation.Cmdlet.ShouldProcess][03], but it should bypass the call to +[System.Management.Automation.Cmdlet.ShouldContinue][02]. [System.Management.Automation.Cmdlet.ShouldContinue][02] will throw an exception when it's called from a non-interactive environment where the user can't be prompted. Adding a `Force` parameter diff --git a/reference/docs-conceptual/developer/cmdlet/strongly-encouraged-development-guidelines.md b/reference/docs-conceptual/developer/cmdlet/strongly-encouraged-development-guidelines.md index ac6eec52d1f6..c78cef466fba 100644 --- a/reference/docs-conceptual/developer/cmdlet/strongly-encouraged-development-guidelines.md +++ b/reference/docs-conceptual/developer/cmdlet/strongly-encouraged-development-guidelines.md @@ -110,9 +110,9 @@ cmdlet, do not make the `Process` parameter for another cmdlet a If your parameter takes only `true` and `false`, define the parameter as type [System.Management.Automation.SwitchParameter](/dotnet/api/System.Management.Automation.SwitchParameter). -A switch parameter is treated as `true` when it is specified in a command. If the parameter is not -included in a command, Windows PowerShell considers the value of the parameter to be `false`. Do not -define Boolean parameters. +A `[switch]` parameter is treated as `true` when it is specified in a command. If the parameter is +not included in a command, Windows PowerShell considers the value of the parameter to be `false`. +Do not define Boolean parameters. If your parameter needs to differentiate between 3 values: $true, $false and "unspecified", then define a parameter of type Nullable\. The need for a 3rd, "unspecified" value typically occurs diff --git a/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-output.md b/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-output.md index 9010d06c97c9..8e25be27d694 100644 --- a/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-output.md +++ b/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-output.md @@ -23,9 +23,9 @@ method. We recommend that you call this method instead of the [System.Management.Automation.Host.PSHostUserInterface.WriteLine](/dotnet/api/System.Management.Automation.Host.PSHostUserInterface.WriteLine) methods. -You can provide a **PassThru** switch parameter for cmdlets that do not typically return objects. -When the **PassThru** switch parameter is specified at the command line, the cmdlet is asked to -return an object. For an example of a cmdlet that has a **PassThru** parameter, see +You can provide a **PassThru** `[switch]` parameter for cmdlets that do not typically return +objects. When the **PassThru** `[switch]` parameter is specified at the command line, the cmdlet is +asked to return an object. For an example of a cmdlet that has a **PassThru** parameter, see [Add-History](/powershell/module/Microsoft.PowerShell.Core/Add-History). ### Error output 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 18076e75d47a..3cb861241092 100644 --- a/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-parameters.md +++ b/reference/docs-conceptual/developer/cmdlet/types-of-cmdlet-parameters.md @@ -6,7 +6,7 @@ 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. +parameters can be positional, named, required, optional, or `[switch]` parameters. ## Positional and Named Parameters @@ -98,18 +98,17 @@ public string UserName private string userName; ``` -## Switch Parameters +## `[switch]` 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. +called. Whenever possible, use `[switch]` parameters instead of Boolean parameters. 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` +`PassThru` `[switch]` parameter that overrides the default behavior. When you use the `PassThru` parameter, the cmdlet returns output objects to the pipeline. -To define a switch parameter, declare the property as the `[SwitchParameter]` type, as shown in the -following sample. +The following sample shows how to define a `[switch]` parameter: ```csharp [Parameter()] @@ -135,18 +134,18 @@ protected override void ProcessRecord() } // End ProcessRecord ``` -By default, switch parameters are excluded from positional parameters. You _can_ override that in -the **Parameter** attribute, but it can confuse users. +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. +Design `[switch]` parameters so that using the 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]` parameter on the _value_ of the parameter, not its _presence_. -There are several ways to test for the presence of a switch parameters: +There are several ways to test for the presence of a `[switch]` parameter: -- `Invocation.BoundParameters` contains the switch parameter name as a key -- `PSCmdlet.ParameterSetName` when the switch defines a unique parameter set +- `MyInvocation.BoundParameters` contains the `[switch]` parameter name as a key +- `PSCmdlet.ParameterSetName` when the `[switch]` parameter 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 diff --git a/reference/docs-conceptual/developer/help/how-to-add-dynamic-parameters-to-a-provider-help-topic.md b/reference/docs-conceptual/developer/help/how-to-add-dynamic-parameters-to-a-provider-help-topic.md index 1b9d05dbda24..9b60c98dc7d3 100644 --- a/reference/docs-conceptual/developer/help/how-to-add-dynamic-parameters-to-a-provider-help-topic.md +++ b/reference/docs-conceptual/developer/help/how-to-add-dynamic-parameters-to-a-provider-help-topic.md @@ -115,8 +115,8 @@ If a provider doesn't implement any dynamic parameters, the provider help topic 1. Add the `PossibleValues` element and its child elements. Together, these elements describe the values of the dynamic parameter. This element is designed for enumerated values. If the dynamic - parameter doesn't take a value, such as is the case with a switch parameter, or the values can't - be enumerated, add an empty `PossibleValues` element. + parameter doesn't take a value, such as is the case with a `[switch]` parameter, or the values + can't be enumerated, add an empty `PossibleValues` element. The following table lists and describes the `PossibleValues` element and its child elements. diff --git a/reference/docs-conceptual/developer/help/how-to-add-syntax-to-a-cmdlet-help-topic.md b/reference/docs-conceptual/developer/help/how-to-add-syntax-to-a-cmdlet-help-topic.md index 9d74515d543f..e85f13a083ea 100644 --- a/reference/docs-conceptual/developer/help/how-to-add-syntax-to-a-cmdlet-help-topic.md +++ b/reference/docs-conceptual/developer/help/how-to-add-syntax-to-a-cmdlet-help-topic.md @@ -109,7 +109,7 @@ aren't required, because they're one of several values that might be used with t List all values of enumerations, such as the `-Type` parameter in the previous example, which can be set to **basic** or **advanced**. - Switch parameters, such as `-List` in the previous example, don't have values. + `[switch]` parameters, such as `-List` in the previous example, don't have values. 1. Add angle brackets to parameters values that are placeholder, as compared to parameter values that are literals. diff --git a/reference/docs-conceptual/lang-spec/chapter-02.md b/reference/docs-conceptual/lang-spec/chapter-02.md index 573316031592..3e0f0e0057fd 100644 --- a/reference/docs-conceptual/lang-spec/chapter-02.md +++ b/reference/docs-conceptual/lang-spec/chapter-02.md @@ -556,7 +556,7 @@ matching parameters to arguments is called _parameter binding_. There are three kinds of argument: -- Switch parameter ([§8.10.5][§8.10.5]) -- This has the form _command-parameter_ where +- `[switch]` parameter ([§8.10.5][§8.10.5]) -- This has the form _command-parameter_ where _first-parameter-char_ and _parameter-chars_ together make up the switch name, which corresponds to the name of a parameter (without its leading `-`) in the command being invoked. If the trailing colon is omitted, the presence of this argument indicates that the corresponding parameter be set @@ -644,7 +644,7 @@ hexadecimal-integer-literal: hexadecimal-digits: hexadecimal-digit - hexadecimal-digit decimal-digits + hexadecimal-digit hexadecimal-digits hexadecimal-digit: one of 0 1 2 3 4 5 6 7 8 9 a b c d e f diff --git a/reference/docs-conceptual/lang-spec/chapter-04.md b/reference/docs-conceptual/lang-spec/chapter-04.md index b8eb70831dcb..4561e7b199e3 100644 --- a/reference/docs-conceptual/lang-spec/chapter-04.md +++ b/reference/docs-conceptual/lang-spec/chapter-04.md @@ -869,21 +869,21 @@ In PowerShell, this type is `System.Management.Automation.ExternalScriptInfo`. This type encapsulates the state of a function. It has the following accessible members: -| **Member** | **Member Kind** | **Type** | **Purpose** | -| ------------------- | ------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CmdletBinding | Instance property (read-only) | bool | Indicates whether the function uses the same parameter binding that compiled cmdlets use (see [§12.3.5][§12.3.5]). | -| CommandType | Instance property (read-only) | Implementation defined | Can be compared for equality with "Function" or "Filter" to see which of those this object represents. | -| DefaultParameterSet | Instance property (read-only) | string | Specifies the parameter set to use if that cannot be determined from the arguments (see [§12.3.5][§12.3.5]). | -| Definition | Instance property (read-only) | string | A string version of ScriptBlock | -| Description | Instance property (read-write) | string | The description of the function. | -| Module | Instance property (read-only) | Implementation defined ([§4.5.12][§4.5.12]) | The module from which this function was exported | -| ModuleName | Instance property (read-only) | string | The module in which this function was defined | -| Name | Instance property (read-only) | string | The name of the function | -| Options | Instance property (read-write) | Implementation defined | The scope options for the function ([§3.5.4][§3.5.4]). | -| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output, in order (see [§12.3.6][§12.3.6]). | -| Parameters | Instance property (read-only) | Implementation defined collection | Specifies the parameter names, in order. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][common parameters] are included at the end of the collection. | -| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. For each parameter, the result shows the parameter name and type, and indicates if the parameter is mandatory, by position or a switch parameter. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][common parameters] are included at the end of the collection. | -| ScriptBlock | Instance property (read-only) | scriptblock ([§4.3.6][§4.3.6]) | The body of the function | +| **Member** | **Member Kind** | **Type** | **Purpose** | +| ------------------- | ------------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CmdletBinding | Instance property (read-only) | bool | Indicates whether the function uses the same parameter binding that compiled cmdlets use (see [§12.3.5][§12.3.5]). | +| CommandType | Instance property (read-only) | Implementation defined | Can be compared for equality with "Function" or "Filter" to see which of those this object represents. | +| DefaultParameterSet | Instance property (read-only) | string | Specifies the parameter set to use if that cannot be determined from the arguments (see [§12.3.5][§12.3.5]). | +| Definition | Instance property (read-only) | string | A string version of ScriptBlock | +| Description | Instance property (read-write) | string | The description of the function. | +| Module | Instance property (read-only) | Implementation defined ([§4.5.12][§4.5.12]) | The module from which this function was exported | +| ModuleName | Instance property (read-only) | string | The module in which this function was defined | +| Name | Instance property (read-only) | string | The name of the function | +| Options | Instance property (read-write) | Implementation defined | The scope options for the function ([§3.5.4][§3.5.4]). | +| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output, in order (see [§12.3.6][§12.3.6]). | +| Parameters | Instance property (read-only) | Implementation defined collection | Specifies the parameter names, in order. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][common parameters] are included at the end of the collection. | +| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. For each parameter, the result shows the parameter name and type, and indicates if the parameter is mandatory, by position or a `[switch]` parameter. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][common parameters] are included at the end of the collection. | +| ScriptBlock | Instance property (read-only) | scriptblock ([§4.3.6][§4.3.6]) | The body of the function | In PowerShell, this type is `System.Management.Automation.FunctionInfo`. diff --git a/reference/docs-conceptual/lang-spec/chapter-06.md b/reference/docs-conceptual/lang-spec/chapter-06.md index 84be60cef3af..5a9fc9bf42bb 100644 --- a/reference/docs-conceptual/lang-spec/chapter-06.md +++ b/reference/docs-conceptual/lang-spec/chapter-06.md @@ -36,7 +36,7 @@ The rules for converting any value to type bool are as follows: converted to True. - A value of null type is converted to False. - A string of length 0 is converted to False; a string of length > 0 is converted to True. -- A switch parameter with value `$true` is converted to True, and one with value `$false` is +- A `[switch]` parameter with value `$true` is converted to True, and one with value `$false` is converted to False. - All other non-null reference type values are converted to True. diff --git a/reference/docs-conceptual/lang-spec/chapter-08.md b/reference/docs-conceptual/lang-spec/chapter-08.md index aeeb91a28f27..4adf884d3de3 100644 --- a/reference/docs-conceptual/lang-spec/chapter-08.md +++ b/reference/docs-conceptual/lang-spec/chapter-08.md @@ -228,8 +228,8 @@ governing arguments are as follows: - Putting parentheses around an argument causes that expression to be evaluated with the result being passed instead of the text of the original expression. -- To pass an argument that looks like a switch parameter ([§2.3.4][§2.3.4]) but is not intended as - such, enclose that argument in quotes. +- To pass an argument that looks like a `[switch]` parameter ([§2.3.4][§2.3.4]) but is not intended + as such, enclose that argument in quotes. - When specifying an argument that matches a parameter having the `[switch]` type constraint ([§8.10.5][§8.10.5]), the presence of the argument name on its own causes that parameter to be @@ -1386,7 +1386,7 @@ Find-Str "abcabc" 2 # 2nd argument present, so it is used for $StartPos ### 8.10.5 The [switch] type constraint -When a switch parameter is passed, the corresponding parameter in the command must be constrained by +When a `[switch]` parameter is passed, the corresponding parameter in the command must be constrained by the type switch. Type switch has two values, True and False. Consider the following function definition and calls: @@ -1637,8 +1637,8 @@ Several of these steps involve conversion, as described in [§6.][§6.] However, used in binding is not exactly the same as that used in language conversions. Specifically, - Although the value `$null` can be cast to bool, `$null` cannot be bound to `bool`. -- When the value `$null` is passed to a switch parameter for a cmdlet, it is treated as if `$true` - was passed. However, when passed to a switch parameter for a function, it is treated as if +- When the value `$null` is passed to a `[switch]` parameter for a cmdlet, it is treated as if `$true` + was passed. However, when passed to a `[switch]` parameter for a function, it is treated as if `$false` was passed. - Parameters of type bool or switch can only bind to numeric or bool arguments. - If the parameter type is not a collection, but the argument is some sort of collection, no diff --git a/reference/docs-conceptual/learn/Glossary.md b/reference/docs-conceptual/learn/Glossary.md index d071f004646d..fdcd8d756097 100644 --- a/reference/docs-conceptual/learn/Glossary.md +++ b/reference/docs-conceptual/learn/Glossary.md @@ -196,10 +196,10 @@ a module manifest. The script defines the members that the script module exports The command interpreter that's used to pass commands to the operating system. -### switch parameter +### `[switch]` parameter -A parameter that doesn't take an argument. The value of a switch parameter defaults to `$false`. -When a switch parameter is used, its value becomes `$true`. +A parameter that doesn't take an argument. The value of a `[switch]` parameter defaults to +`$false`. When a `[switch]` parameter is used, its value becomes `$true`. ## T diff --git a/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md b/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md index 21ae139dfa1a..848f8cf0b0c5 100644 --- a/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md +++ b/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md @@ -84,13 +84,14 @@ S - Pause the current pipeline and return to the command prompt. Type "exit" to This prompt is localized in PowerShell so the language changes based on the language of your operating system. This is one more thing that PowerShell manages for you. -### Switch parameters +### `[switch]` parameters -Let's take quick moment to look at ways to pass a value to a switch parameter. The main reason I -call this out is that you often want to pass parameter values to functions you call. +Let's take a quick moment to look at ways to pass a value to a `[switch]` parameter. The main +reason I call this out is that you often want to pass parameter values to functions you call. -The first approach is a specific parameter syntax that can be used for all parameters but you mostly -see it used for switch parameters. You specify a colon to attach a value to the parameter. +The first approach is a specific parameter syntax that can be used for all parameters but you +mostly see it used for `[switch]` parameters. You specify a colon to attach a value to the +parameter. ```powershell Remove-Item -Path:* -WhatIf:$true diff --git a/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md b/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md index 42d67acebf83..6ba75c434006 100644 --- a/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md +++ b/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md @@ -180,18 +180,18 @@ in the next section where this variable is used. ## Parameters -A unique feature of the PowerShell `switch` is that it has a number of switch parameters that +A unique feature of the PowerShell `switch` is that it has a number of `[switch]` parameters that change how it performs. ### -CaseSensitive The matches aren't case-sensitive by default. If you need to be case-sensitive, you can use -`-CaseSensitive`. This can be used in combination with the other switch parameters. +`-CaseSensitive`. This can be used in combination with the other `[switch]` parameters. ### -Wildcard -We can enable wildcard support with the `-Wildcard` switch. This uses the same wildcard logic as the -`-like` operator to do each match. +We can enable wildcard support with the `-Wildcard` `[switch]` parameter. This uses the same +wildcard logic as the `-like` operator to do each match. ``` powershell $Message = 'Warning, out of disk space' diff --git a/reference/docs-conceptual/learn/ps101/02-help-system.md b/reference/docs-conceptual/learn/ps101/02-help-system.md index dd85115358f9..7fbc1457f2c5 100644 --- a/reference/docs-conceptual/learn/ps101/02-help-system.md +++ b/reference/docs-conceptual/learn/ps101/02-help-system.md @@ -251,14 +251,14 @@ Furthermore, **InstanceId** has its own pair of square brackets, indicating that parameter similar to the **LogName** parameter. Following the datatype, an empty set of square brackets implies that **InstanceId** can accept multiple values. -### Switch parameters +### `[switch]` parameters -A parameter that doesn't require a value is called a switch parameter. You can easily identify -switch parameters because there's no datatype following the parameter name. When you specify a -switch parameter, its value is `true`. When you don't specify a switch parameter, its value is -`false`. +A parameter that doesn't require a value is called a `[switch]` parameter. You can easily identify +`[switch]` parameters because there's no datatype following the parameter name. When you specify a +`[switch]` parameter, its value is `true`. When you don't specify a `[switch]` parameter, its value +is `false`. -The second parameter set includes a **List** parameter, which is a switch parameter. When you +The second parameter set includes a **List** parameter, which is a `[switch]` parameter. When you specify the **List** parameter, it returns a list of event logs on the local computer. ```Syntax diff --git a/reference/docs-conceptual/samples/Sorting-Objects.md b/reference/docs-conceptual/samples/Sorting-Objects.md index 6d6b24f91599..d424924ad276 100644 --- a/reference/docs-conceptual/samples/Sorting-Objects.md +++ b/reference/docs-conceptual/samples/Sorting-Objects.md @@ -35,7 +35,8 @@ LastWriteTime Name ... ``` -You can also sort the objects in reverse order by specifying the **Descending** switch parameter. +You can also sort the objects in reverse order by specifying the **Descending** `[switch]` +parameter. ```powershell Get-ChildItem | diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-74.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-74.md index 252b3cd4a804..40b965ef387d 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-74.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-74.md @@ -160,7 +160,7 @@ Many thanks to **@CarloToso** and others for all the work on improving web cmdle - Add `Get-SecureRandom` cmdlet ([#19587][19587]) - `Set-Clipboard -AsOSC52` for remote usage ([#18222][18222]) (Thanks @dkaszews!) - Speed up `Resolve-Path` relative path resolution ([#19171][19171]) (Thanks @MartinGC94!) -- Added the switch parameter `-CaseInsensitive` to `Select-Object` and `Get-Unique` cmdlets +- Added the `[switch]` parameter `-CaseInsensitive` to `Select-Object` and `Get-Unique` cmdlets ([#19683][19683]) (Thanks @ArmaanMcleod!) - `Restart-Computer` and `Stop-Computer` should fail with error when not running via sudo on Unix ([#19824][19824]) diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md index aeae865fa727..b95f0d88c1e5 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md @@ -1,7 +1,7 @@ --- title: What's New in PowerShell 7.6 description: New features and changes released in PowerShell 7.6 -ms.date: 03/26/2026 +ms.date: 04/07/2026 --- # What's New in PowerShell 7.6 @@ -11,6 +11,8 @@ PowerShell 7.6 includes the following features, updates, and breaking changes. P For a complete list of changes, see the [CHANGELOG][log] in the GitHub repository. +[log]: https://github.com/PowerShell/PowerShell/blob/master/CHANGELOG/7.6.md + ## Updated modules PowerShell 7.6 includes the following updated modules: @@ -206,8 +208,6 @@ This release includes the following experimental features: [05]: ../learn/experimental-features.md#psserializejsonlongenumasnumber [06]: ../learn/experimental-features.md#pssubsystempluginmodel -[log]: https://github.com/PowerShell/PowerShell/blob/master/CHANGELOG/preview.md - [14553]: https://github.com/PowerShell/PowerShell/pull/14553 [17687]: https://github.com/PowerShell/PowerShell/pull/17687 [17785]: https://github.com/PowerShell/PowerShell/pull/17785 diff --git a/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md b/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md index 53e5666418f8..6355e8e42a35 100644 --- a/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md +++ b/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md @@ -318,8 +318,8 @@ was added. Switch values are also supported. ## Improved backwards compatibility with Windows PowerShell -For Windows, a new switch parameter **UseWindowsPowerShell** is added to `Import-Module`. This -switch creates a proxy module in PowerShell 7 that uses a local Windows PowerShell process to +For Windows, a new `[switch]` parameter **UseWindowsPowerShell** is added to `Import-Module`. This +parameter creates a proxy module in PowerShell 7 that uses a local Windows PowerShell process to implicitly run any cmdlets contained in that module. For more information, see [Import-Module][14]. For more information on which Microsoft modules work with PowerShell 7.0, see the @@ -818,8 +818,8 @@ When PowerShell starts up, it automatically includes `$windir\System32` as part `PSModulePath` environment variable. However, it only exposes modules to `Get-Module` and `Import-Module` if its `CompatiblePSEdition` is marked as compatible with `Core`. -You can override this behavior to show all modules using the `-SkipEditionCheck` switch parameter. -We've also added a `PSEdition` property to the table output. +You can override this behavior to show all modules using the `-SkipEditionCheck` `[switch]` +parameter. We've also added a `PSEdition` property to the table output. ### `-lp` alias for all `-LiteralPath` parameters