| Service | Microsoft Docs article | Related commit history on GitHub | Change details |
|---|---|---|---|
| Microsoft.PowerShell.Core | About Comparison Operators (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md | --- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 11/02/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators zzz zzz ``` +The equality operator can compare objects of different types. It is important +to understand that the value is on the right-hand side of the comparison can be +converted to the type of the left-hand side value for comparison. ++For example, the string `'1.0'` is converted to an integer to be compared to +the value `1`. This example returns `True`. ++```powershell +PS> 1 -eq '1.0' +True +``` ++In this example, the value `1` is converted to a string to be compared to +string `'1.0'`. This example returns `False`. ++```powershell +PS> '1.0' -eq 1 +False +``` + The equality operators accept any two objects, not just a scalar or collection. But the comparison result is not guaranteed to be meaningful for the end-user. The following example demonstrates the issue. |
| Microsoft.PowerShell.Core | About Pipelines (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Pipelines.md | --- description: Combining commands into pipelines in the PowerShell Locale: en-US Previously updated : 03/18/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pipelines?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Pipelines For example, It's important to remember that objects sent down the pipeline are delivered one at a time. +## Using native commands in the pipeline ++PowerShell allows you to include native external commands in the pipeline. +However, it is important to note that PowerShell's pipeline is object-oriented +and does not support raw byte data. ++Piping or redirecting output from a native program that outputs raw byte data +converts the output to .NET strings. This conversion can cause corruption of +the raw data output. ++As a workaround, call the native commands using `cmd.exe /c` and use the `|` +and `>` operators provided by the native shell. + ## Investigating pipeline errors When PowerShell can't associate the piped objects with a parameter of the |
| Microsoft.PowerShell.Core | About Switch (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md | --- -description: Explains how to use a switch to handle multiple `If` statements. +description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US Previously updated : 06/10/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Switch Title: about Switch # about_Switch ## Short description-Explains how to use a switch to handle multiple `If` statements. +Explains how to use a switch to handle multiple `if` statements. ## Long description -To check a condition in a script or function, use an `If` statement. The `If` +To check a condition in a script or function, use an `if` statement. The `if` statement can check many types of conditions, including the value of variables and the properties of objects. -To check multiple conditions, use a `Switch` statement. The `Switch` statement -is equivalent to a series of `If` statements, but it is simpler. The `Switch` +To check multiple conditions, use a `switch` statement. The `switch` statement +is equivalent to a series of `if` statements, but it is simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. -The `Switch` statement can use the `$_` and `$switch` automatic variables. For +The `switch` statement can use the `$_` and `$switch` automatic variables. For more information, see [about_Automatic_Variables](about_Automatic_Variables.md). -A basic `Switch` statement has the following format: +## Syntax -```powershell -Switch (<test-value>) +A basic `switch` statement has the following format: ++```Syntax +Switch (<test-expression>) {- <condition> {<action>} - <condition> {<action>} + <result1-to-be-matched> {<action>} + <result2-to-be-matched> {<action>} } ``` -For example, the following `Switch` statement compares the test value, 3, to +The equivalent `if` statements are: ++```Syntax +if (<result1-to-be-matched> -eq (<test-expression>)) {<action>} +if (<result2-to-be-matched> -eq (<test-expression>)) {<action>} +``` ++The `<test-expression>` is single expression that is evaluated in expression +mode to return a value. ++The `<result-to-be-matched>` is an expression whose value is compared to the +input value. Expressions include literal values (strings or numbers), +variables, and scriptblocks that return a boolean value. ++Any unquoted value that is not recognized as a number is treated as a string. +To avoid confusion or unintended string conversion, you should always quote +string values. Enclose any expressions in parentheses `()`, creating +subexpressions, to ensure that the expression is evaluated correctly. ++It is important to understand that the `<result-to-be-matched>` value is on the +left-hand side of the comparison expression. That means the result of the +`<test-expression>` is on the right-hand side, which can be converted to the +type of the left-hand side value for comparison. For more information, see +[about_Comparison_Operators](about_Comparison_Operators.md) ++The value `default` is reserved for the action used when there are no other +matches. ++The `$_` automatic variable contains the value of the expression passed to the +`switch` statement and is available for evaluation and use within the scope of +the `<result-to-be-matched>` statements. ++The complete `switch` statement syntax is as follows: ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] (<test-expression>) +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++or ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] -file filename +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++If no parameters are used, `switch` behaves the same as using the **Exact** +parameter. It performs a case-insensitive match for the value. If the value is +a collection, each element is evaluated in the order in which it appears. ++The `switch` statement must include at least one condition statement. ++The `default` clause is triggered when the value does not match any of the +conditions. It is equivalent to an `else` clause in an `if` statement. Only one +`default` clause is permitted in each `switch` statement. ++`switch` has the following parameters: ++- **Wildcard** - Indicates that the condition is a wildcard string. If the + match clause is not a string, the parameter is ignored. The comparison is + case-insensitive. +- **Exact** - Indicates that the match clause, if it is a string, must match + exactly. If the match clause is not a string, this parameter is ignored. The + comparison is case-insensitive. +- **CaseSensitive** - Performs a case-sensitive match. If the match clause is + not a string, this parameter is ignored. +- **File**- Takes input from a file rather than a `<test-expression>`. If + multiple **File** parameters are included, only the last one is used. Each + line of the file is read and evaluated by the `switch` statement. The + comparison is case-insensitive. +- **Regex** - Performs regular expression matching of the value to the + condition. If the match clause is not a string, this parameter is ignored. + The comparison is case-insensitive. The `$matches` automatic variable is + available for use within the matching statement block. ++> [!NOTE] +> When specifying conflicting values, like **Regex** and **Wildcard**, the last +> parameter specified takes precedence, and all conflicting parameters are +> ignored. Multiple instances of parameters are also permitted. However, only +> the last parameter listed is used. ++## Examples ++In the following example, the `switch` statement compares the test value, 3, to each of the conditions. When the test value matches the condition, the action is performed. It is three. ``` In this simple example, the value is compared to each condition in the list,-even though there is a match for the value 3. The following `Switch` statement +even though there is a match for the value 3. The following `switch` statement has two conditions for a value of 3. It demonstrates that, by default, all conditions are tested. It is three. Three again. ``` -To direct the `Switch` to stop comparing after a match, use the `Break` -statement. The `Break` statement terminates the `Switch` statement. +To direct the `switch` to stop comparing after a match, use the `break` +statement. The `break` statement terminates the `switch` statement. ```powershell switch (3) It is four. It is two. ``` -Any `Break` statements apply to the collection, not to each value, as shown -in the following example. The `Switch` statement is terminated by the `Break` +Any `break` statements apply to the collection, not to each value, as shown +in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell switch (4, 2) It is four. ``` -### Syntax --The complete `Switch` statement syntax is as follows: --``` -switch [-regex|-wildcard|-exact][-casesensitive] (<value>) -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --or --``` -switch [-regex|-wildcard|-exact][-casesensitive] -file filename -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --If no parameters are used, `Switch` behaves the same as using the **Exact** -parameter. It performs a case-insensitive match for the value. If the value is -a collection, each element is evaluated in the order in which it appears. --The `Switch` statement must include at least one condition statement. --The `Default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `Else` clause in an `If` statement. Only one -`Default` clause is permitted in each `Switch` statement. --`Switch` has the following parameters: --- **Wildcard** - Indicates that the condition is a wildcard string. If the- match clause is not a string, the parameter is ignored. The comparison is - case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match- exactly. If the match clause is not a string, this parameter is ignored. The - comparison is case-insensitive. -- **CaseSensitive** - Performs a case-sensitive match. If the match clause is- not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a value statement. If multiple- **File** parameters are included, only the last one is used. Each line of the - file is read and evaluated by the `Switch` statement. The comparison is - case-insensitive. -- **Regex** - Performs regular expression matching of the value to the- condition. If the match clause is not a string, this parameter is ignored. - The comparison is case-insensitive. The `$matches` automatic variable is - available for use within the matching statement block. --> [!NOTE] -> When specifying conflicting values, like **Regex** and **Wildcard**, the last -> parameter specified takes precedence, and all conflicting parameters are -> ignored. Multiple instances of parameters are also permitted. However, only -> the last parameter used is effective. - In this example, an object that's not a string or numerical data is passed to-the `Switch`. The `Switch` performs a string coercion on the object and +the `switch`. The `switch` performs a string coercion on the object and evaluates the outcome. ```powershell switch ("fourteen") } ``` -By adding the `Default` clause, you can perform an action when no other +By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell switch -Regex ($target) https://bing.com is a web address that uses https ``` -A `Switch` statement condition may be either: --- An expression whose value is compared to the input value-- A script block which should return `$true` if a condition is met.--The `$_` automatic variable contains the value passed to the `switch` statement -and is available for evaluation and use within the scope of the condition -statements. --The action for each condition is independent of the actions in other -conditions. --The following example demonstrates the use of script blocks as `Switch` +The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell Found a string This Test executes as well ``` +The following example processes an array containing two date values. The +`<value-scriptblock>` compares the **Year** property of each date. The +`<action-scriptblock>` displays a welcome message or the number of days until +the beginning of the year 2022. ++```powershell +switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { + { $_.Year -eq 2021 } { + $days = ((Get-Date 1/1/2022) - $_).days + "There are $days days until 2022." + } + { $_.Year -eq 2022 } { 'Welcome to 2022!' } +} +``` + If the value matches multiple conditions, the action for each condition is-executed. To change this behavior, use the `Break` or `Continue` keywords. +executed. To change this behavior, use the `break` or `continue` keywords. -The `Break` keyword stops processing and exits the `Switch` statement. +The `break` keyword stops processing and exits the `switch` statement. -The `Continue` keyword stops processing the current value, but continues +The `continue` keyword stops processing the current value, but continues processing any subsequent values. The following example processes an array of numbers and displays if they are-odd or even. Negative numbers are skipped with the `Continue` keyword. If a -non-number is encountered, execution is terminated with the `Break` keyword. +odd or even. Negative numbers are skipped with the `continue` keyword. If a +non-number is encountered, execution is terminated with the `break` keyword. ```powershell switch (1,4,-1,3,"Hello",2,1) {- {$_ -lt 0} { Continue } - {$_ -isnot [Int32]} { Break } + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } {$_ % 2} { "$_ is Odd" } |
| Microsoft.PowerShell.Core | Get Module (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md | external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 12/03/2020 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-module?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Module Accept wildcard characters: False Specifies modules with names that are specified in the form of **ModuleSpecification** objects. See the Remarks section of-[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#Microsoft_PowerShell_Commands_ModuleSpecification__ctor_System_Collections_Hashtable_). +[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#microsoft-powershell-commands-modulespecification-ctor(system-collections-hashtable)). For example, the **FullyQualifiedModule** parameter accepts a module name that is specified in either of these formats: either of these formats: **FullyQualifiedModule** parameter in the same command as a **Module** parameter. the two parameters are mutually exclusive. +> [!NOTE] +> This parameter also accepts simpler forms of input: +> +> - A module name +> - A fully-qualified path to the module +> - A relative path to the module. When used in a script, the relative path is resolved to a +> fully-qualified path relative to the location of the script file. + ```yaml Type: Microsoft.PowerShell.Commands.ModuleSpecification[] Parameter Sets: (All) |
| Microsoft.PowerShell.Core | About Comparison Operators (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md | --- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 11/02/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators zzz zzz ``` +The equality operator can compare objects of different types. It is important +to understand that the value is on the right-hand side of the comparison can be +converted to the type of the left-hand side value for comparison. ++For example, the string `'1.0'` is converted to an integer to be compared to +the value `1`. This example returns `True`. ++```powershell +PS> 1 -eq '1.0' +True +``` ++In this example, the value `1` is converted to a string to be compared to +string `'1.0'`. This example returns `False`. ++```powershell +PS> '1.0' -eq 1 +False +``` + The equality operators accept any two objects, not just a scalar or collection. But the comparison result is not guaranteed to be meaningful for the end-user. The following example demonstrates the issue. |
| Microsoft.PowerShell.Core | About Pipelines (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Pipelines.md | --- description: Combining commands into pipelines in the PowerShell Locale: en-US Previously updated : 03/18/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pipelines?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Pipelines For example, It's important to remember that objects sent down the pipeline are delivered one at a time. +## Using native commands in the pipeline ++PowerShell allows you to include native external commands in the pipeline. +However, it is important to note that PowerShell's pipeline is object-oriented +and does not support raw byte data. ++Piping or redirecting output from a native program that outputs raw byte data +converts the output to .NET strings. This conversion can cause corruption of +the raw data output. ++As a workaround, call the native commands using `cmd.exe /c` or `sh -c` and use +of the `|` and `>` operators provided by the native shell. + ## Investigating pipeline errors When PowerShell can't associate the piped objects with a parameter of the |
| Microsoft.PowerShell.Core | About Switch (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Switch.md | --- -description: Explains how to use a switch to handle multiple `If` statements. +description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US Previously updated : 06/10/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Switch Title: about Switch # about_Switch ## Short description-Explains how to use a switch to handle multiple `If` statements. +Explains how to use a switch to handle multiple `if` statements. ## Long description -To check a condition in a script or function, use an `If` statement. The `If` +To check a condition in a script or function, use an `if` statement. The `if` statement can check many types of conditions, including the value of variables and the properties of objects. -To check multiple conditions, use a `Switch` statement. The `Switch` statement -is equivalent to a series of `If` statements, but it is simpler. The `Switch` +To check multiple conditions, use a `switch` statement. The `switch` statement +is equivalent to a series of `if` statements, but it is simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. -The `Switch` statement can use the `$_` and `$switch` automatic variables. For +The `switch` statement can use the `$_` and `$switch` automatic variables. For more information, see [about_Automatic_Variables](about_Automatic_Variables.md). -A basic `Switch` statement has the following format: +## Syntax -```powershell -Switch (<test-value>) +A basic `switch` statement has the following format: ++```Syntax +Switch (<test-expression>) {- <condition> {<action>} - <condition> {<action>} + <result1-to-be-matched> {<action>} + <result2-to-be-matched> {<action>} } ``` -For example, the following `Switch` statement compares the test value, 3, to +The equivalent `if` statements are: ++```Syntax +if (<result1-to-be-matched> -eq (<test-expression>)) {<action>} +if (<result2-to-be-matched> -eq (<test-expression>)) {<action>} +``` ++The `<test-expression>` is single expression that is evaluated in expression +mode to return a value. ++The `<result-to-be-matched>` is an expression whose value is compared to the +input value. Expressions include literal values (strings or numbers), +variables, and scriptblocks that return a boolean value. ++Any unquoted value that is not recognized as a number is treated as a string. +To avoid confusion or unintended string conversion, you should always quote +string values. Enclose any expressions in parentheses `()`, creating +subexpressions, to ensure that the expression is evaluated correctly. ++It is important to understand that the `<result-to-be-matched>` value is on the +left-hand side of the comparison expression. That means the result of the +`<test-expression>` is on the right-hand side, which can be converted to the +type of the left-hand side value for comparison. For more information, see +[about_Comparison_Operators](about_Comparison_Operators.md) ++The value `default` is reserved for the action used when there are no other +matches. ++The `$_` automatic variable contains the value of the expression passed to the +`switch` statement and is available for evaluation and use within the scope of +the `<result-to-be-matched>` statements. ++The complete `switch` statement syntax is as follows: ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] (<test-expression>) +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++or ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] -file filename +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++If no parameters are used, `switch` behaves the same as using the **Exact** +parameter. It performs a case-insensitive match for the value. If the value is +a collection, each element is evaluated in the order in which it appears. ++The `switch` statement must include at least one condition statement. ++The `default` clause is triggered when the value does not match any of the +conditions. It is equivalent to an `else` clause in an `if` statement. Only one +`default` clause is permitted in each `switch` statement. ++`switch` has the following parameters: ++- **Wildcard** - Indicates that the condition is a wildcard string. If the + match clause is not a string, the parameter is ignored. The comparison is + case-insensitive. +- **Exact** - Indicates that the match clause, if it is a string, must match + exactly. If the match clause is not a string, this parameter is ignored. The + comparison is case-insensitive. +- **CaseSensitive** - Performs a case-sensitive match. If the match clause is + not a string, this parameter is ignored. +- **File**- Takes input from a file rather than a `<test-expression>`. If + multiple **File** parameters are included, only the last one is used. Each + line of the file is read and evaluated by the `switch` statement. The + comparison is case-insensitive. +- **Regex** - Performs regular expression matching of the value to the + condition. If the match clause is not a string, this parameter is ignored. + The comparison is case-insensitive. The `$matches` automatic variable is + available for use within the matching statement block. ++> [!NOTE] +> When specifying conflicting values, like **Regex** and **Wildcard**, the last +> parameter specified takes precedence, and all conflicting parameters are +> ignored. Multiple instances of parameters are also permitted. However, only +> the last parameter listed is used. ++## Examples ++In the following example, the `switch` statement compares the test value, 3, to each of the conditions. When the test value matches the condition, the action is performed. It is three. ``` In this simple example, the value is compared to each condition in the list,-even though there is a match for the value 3. The following `Switch` statement +even though there is a match for the value 3. The following `switch` statement has two conditions for a value of 3. It demonstrates that, by default, all conditions are tested. It is three. Three again. ``` -To direct the `Switch` to stop comparing after a match, use the `Break` -statement. The `Break` statement terminates the `Switch` statement. +To direct the `switch` to stop comparing after a match, use the `break` +statement. The `break` statement terminates the `switch` statement. ```powershell switch (3) It is four. It is two. ``` -Any `Break` statements apply to the collection, not to each value, as shown -in the following example. The `Switch` statement is terminated by the `Break` +Any `break` statements apply to the collection, not to each value, as shown +in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell switch (4, 2) It is four. ``` -### Syntax --The complete `Switch` statement syntax is as follows: --``` -switch [-regex|-wildcard|-exact][-casesensitive] (<value>) -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --or --``` -switch [-regex|-wildcard|-exact][-casesensitive] -file filename -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --If no parameters are used, `Switch` behaves the same as using the **Exact** -parameter. It performs a case-insensitive match for the value. If the value is -a collection, each element is evaluated in the order in which it appears. --The `Switch` statement must include at least one condition statement. --The `Default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `Else` clause in an `If` statement. Only one -`Default` clause is permitted in each `Switch` statement. --`Switch` has the following parameters: --- **Wildcard** - Indicates that the condition is a wildcard string. If the- match clause is not a string, the parameter is ignored. The comparison is - case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match- exactly. If the match clause is not a string, this parameter is ignored. The - comparison is case-insensitive. -- **CaseSensitive** - Performs a case-sensitive match. If the match clause is- not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a value statement. If multiple- **File** parameters are included, only the last one is used. Each line of the - file is read and evaluated by the `Switch` statement. The comparison is - case-insensitive. -- **Regex** - Performs regular expression matching of the value to the- condition. If the match clause is not a string, this parameter is ignored. - The comparison is case-insensitive. The `$matches` automatic variable is - available for use within the matching statement block. --> [!NOTE] -> When specifying conflicting values, like **Regex** and **Wildcard**, the last -> parameter specified takes precedence, and all conflicting parameters are -> ignored. Multiple instances of parameters are also permitted. However, only -> the last parameter used is effective. - In this example, an object that's not a string or numerical data is passed to-the `Switch`. The `Switch` performs a string coercion on the object and +the `switch`. The `switch` performs a string coercion on the object and evaluates the outcome. ```powershell switch ("fourteen") } ``` -By adding the `Default` clause, you can perform an action when no other +By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell switch -Regex ($target) https://bing.com is a web address that uses https ``` -A `Switch` statement condition may be either: --- An expression whose value is compared to the input value-- A script block which should return `$true` if a condition is met.--The `$_` automatic variable contains the value passed to the `switch` statement -and is available for evaluation and use within the scope of the condition -statements. --The action for each condition is independent of the actions in other -conditions. --The following example demonstrates the use of script blocks as `Switch` +The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell Found a string This Test executes as well ``` +The following example processes an array containing two date values. The +`<value-scriptblock>` compares the **Year** property of each date. The +`<action-scriptblock>` displays a welcome message or the number of days until +the beginning of the year 2022. ++```powershell +switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { + { $_.Year -eq 2021 } { + $days = ((Get-Date 1/1/2022) - $_).days + "There are $days days until 2022." + } + { $_.Year -eq 2022 } { 'Welcome to 2022!' } +} +``` + If the value matches multiple conditions, the action for each condition is-executed. To change this behavior, use the `Break` or `Continue` keywords. +executed. To change this behavior, use the `break` or `continue` keywords. -The `Break` keyword stops processing and exits the `Switch` statement. +The `break` keyword stops processing and exits the `switch` statement. -The `Continue` keyword stops processing the current value, but continues +The `continue` keyword stops processing the current value, but continues processing any subsequent values. The following example processes an array of numbers and displays if they are-odd or even. Negative numbers are skipped with the `Continue` keyword. If a -non-number is encountered, execution is terminated with the `Break` keyword. +odd or even. Negative numbers are skipped with the `continue` keyword. If a +non-number is encountered, execution is terminated with the `break` keyword. ```powershell switch (1,4,-1,3,"Hello",2,1) {- {$_ -lt 0} { Continue } - {$_ -isnot [Int32]} { Break } + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } {$_ % 2} { "$_ is Odd" } |
| Microsoft.PowerShell.Core | Get Module (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/Get-Module.md | external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 10/22/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-module?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Module Accept wildcard characters: False Specifies modules with names that are specified in the form of **ModuleSpecification** objects. See the Remarks section of-[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#Microsoft_PowerShell_Commands_ModuleSpecification__ctor_System_Collections_Hashtable_). +[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#microsoft-powershell-commands-modulespecification-ctor(system-collections-hashtable)). For example, the **FullyQualifiedModule** parameter accepts a module name that is specified in either of these formats: either of these formats: **FullyQualifiedModule** parameter in the same command as a **Module** parameter. the two parameters are mutually exclusive. +> [!NOTE] +> This parameter also accepts simpler forms of input: +> +> - A module name +> - A fully-qualified path to the module +> - A relative path to the module. When used in a script, the relative path is resolved to a +> fully-qualified path relative to the location of the script file. + ```yaml Type: Microsoft.PowerShell.Commands.ModuleSpecification[] Parameter Sets: (All) |
| Microsoft.PowerShell.Core | About Comparison Operators (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md | --- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 11/02/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators zzz zzz ``` +The equality operator can compare objects of different types. It is important +to understand that the value is on the right-hand side of the comparison can be +converted to the type of the left-hand side value for comparison. ++For example, the string `'1.0'` is converted to an integer to be compared to +the value `1`. This example returns `True`. ++```powershell +PS> 1 -eq '1.0' +True +``` ++In this example, the value `1` is converted to a string to be compared to +string `'1.0'`. This example returns `False`. ++```powershell +PS> '1.0' -eq 1 +False +``` + The equality operators accept any two objects, not just a scalar or collection. But the comparison result is not guaranteed to be meaningful for the end-user. The following example demonstrates the issue. |
| Microsoft.PowerShell.Core | About Pipelines (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Pipelines.md | --- description: Combining commands into pipelines in the PowerShell Locale: en-US Previously updated : 03/18/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pipelines?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Pipelines For example, It's important to remember that objects sent down the pipeline are delivered one at a time. +## Using native commands in the pipeline ++PowerShell allows you to include native external commands in the pipeline. +However, it is important to note that PowerShell's pipeline is object-oriented +and does not support raw byte data. ++Piping or redirecting output from a native program that outputs raw byte data +converts the output to .NET strings. This conversion can cause corruption of +the raw data output. ++As a workaround, call the native commands using `cmd.exe /c` or `sh -c` and use +of the `|` and `>` operators provided by the native shell. + ## Investigating pipeline errors When PowerShell can't associate the piped objects with a parameter of the |
| Microsoft.PowerShell.Core | About Switch (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Switch.md | --- -description: Explains how to use a switch to handle multiple `If` statements. +description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US Previously updated : 06/10/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Switch Title: about Switch # about_Switch ## Short description-Explains how to use a switch to handle multiple `If` statements. +Explains how to use a switch to handle multiple `if` statements. ## Long description -To check a condition in a script or function, use an `If` statement. The `If` +To check a condition in a script or function, use an `if` statement. The `if` statement can check many types of conditions, including the value of variables and the properties of objects. -To check multiple conditions, use a `Switch` statement. The `Switch` statement -is equivalent to a series of `If` statements, but it is simpler. The `Switch` +To check multiple conditions, use a `switch` statement. The `switch` statement +is equivalent to a series of `if` statements, but it is simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. -The `Switch` statement can use the `$_` and `$switch` automatic variables. For +The `switch` statement can use the `$_` and `$switch` automatic variables. For more information, see [about_Automatic_Variables](about_Automatic_Variables.md). -A basic `Switch` statement has the following format: +## Syntax -```powershell -Switch (<test-value>) +A basic `switch` statement has the following format: ++```Syntax +Switch (<test-expression>) {- <condition> {<action>} - <condition> {<action>} + <result1-to-be-matched> {<action>} + <result2-to-be-matched> {<action>} } ``` -For example, the following `Switch` statement compares the test value, 3, to +The equivalent `if` statements are: ++```Syntax +if (<result1-to-be-matched> -eq (<test-expression>)) {<action>} +if (<result2-to-be-matched> -eq (<test-expression>)) {<action>} +``` ++The `<test-expression>` is single expression that is evaluated in expression +mode to return a value. ++The `<result-to-be-matched>` is an expression whose value is compared to the +input value. Expressions include literal values (strings or numbers), +variables, and scriptblocks that return a boolean value. ++Any unquoted value that is not recognized as a number is treated as a string. +To avoid confusion or unintended string conversion, you should always quote +string values. Enclose any expressions in parentheses `()`, creating +subexpressions, to ensure that the expression is evaluated correctly. ++It is important to understand that the `<result-to-be-matched>` value is on the +left-hand side of the comparison expression. That means the result of the +`<test-expression>` is on the right-hand side, which can be converted to the +type of the left-hand side value for comparison. For more information, see +[about_Comparison_Operators](about_Comparison_Operators.md) ++The value `default` is reserved for the action used when there are no other +matches. ++The `$_` automatic variable contains the value of the expression passed to the +`switch` statement and is available for evaluation and use within the scope of +the `<result-to-be-matched>` statements. ++The complete `switch` statement syntax is as follows: ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] (<test-expression>) +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++or ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] -file filename +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++If no parameters are used, `switch` behaves the same as using the **Exact** +parameter. It performs a case-insensitive match for the value. If the value is +a collection, each element is evaluated in the order in which it appears. ++The `switch` statement must include at least one condition statement. ++The `default` clause is triggered when the value does not match any of the +conditions. It is equivalent to an `else` clause in an `if` statement. Only one +`default` clause is permitted in each `switch` statement. ++`switch` has the following parameters: ++- **Wildcard** - Indicates that the condition is a wildcard string. If the + match clause is not a string, the parameter is ignored. The comparison is + case-insensitive. +- **Exact** - Indicates that the match clause, if it is a string, must match + exactly. If the match clause is not a string, this parameter is ignored. The + comparison is case-insensitive. +- **CaseSensitive** - Performs a case-sensitive match. If the match clause is + not a string, this parameter is ignored. +- **File**- Takes input from a file rather than a `<test-expression>`. If + multiple **File** parameters are included, only the last one is used. Each + line of the file is read and evaluated by the `switch` statement. The + comparison is case-insensitive. +- **Regex** - Performs regular expression matching of the value to the + condition. If the match clause is not a string, this parameter is ignored. + The comparison is case-insensitive. The `$matches` automatic variable is + available for use within the matching statement block. ++> [!NOTE] +> When specifying conflicting values, like **Regex** and **Wildcard**, the last +> parameter specified takes precedence, and all conflicting parameters are +> ignored. Multiple instances of parameters are also permitted. However, only +> the last parameter listed is used. ++## Examples ++In the following example, the `switch` statement compares the test value, 3, to each of the conditions. When the test value matches the condition, the action is performed. It is three. ``` In this simple example, the value is compared to each condition in the list,-even though there is a match for the value 3. The following `Switch` statement +even though there is a match for the value 3. The following `switch` statement has two conditions for a value of 3. It demonstrates that, by default, all conditions are tested. It is three. Three again. ``` -To direct the `Switch` to stop comparing after a match, use the `Break` -statement. The `Break` statement terminates the `Switch` statement. +To direct the `switch` to stop comparing after a match, use the `break` +statement. The `break` statement terminates the `switch` statement. ```powershell switch (3) It is four. It is two. ``` -Any `Break` statements apply to the collection, not to each value, as shown -in the following example. The `Switch` statement is terminated by the `Break` +Any `break` statements apply to the collection, not to each value, as shown +in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell switch (4, 2) It is four. ``` -### Syntax --The complete `Switch` statement syntax is as follows: --``` -switch [-regex|-wildcard|-exact][-casesensitive] (<value>) -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --or --``` -switch [-regex|-wildcard|-exact][-casesensitive] -file filename -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --If no parameters are used, `Switch` behaves the same as using the **Exact** -parameter. It performs a case-insensitive match for the value. If the value is -a collection, each element is evaluated in the order in which it appears. --The `Switch` statement must include at least one condition statement. --The `Default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `Else` clause in an `If` statement. Only one -`Default` clause is permitted in each `Switch` statement. --`Switch` has the following parameters: --- **Wildcard** - Indicates that the condition is a wildcard string. If the- match clause is not a string, the parameter is ignored. The comparison is - case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match- exactly. If the match clause is not a string, this parameter is ignored. The - comparison is case-insensitive. -- **CaseSensitive** - Performs a case-sensitive match. If the match clause is- not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a value statement. If multiple- **File** parameters are included, only the last one is used. Each line of the - file is read and evaluated by the `Switch` statement. The comparison is - case-insensitive. -- **Regex** - Performs regular expression matching of the value to the- condition. If the match clause is not a string, this parameter is ignored. - The comparison is case-insensitive. The `$matches` automatic variable is - available for use within the matching statement block. --> [!NOTE] -> When specifying conflicting values, like **Regex** and **Wildcard**, the last -> parameter specified takes precedence, and all conflicting parameters are -> ignored. Multiple instances of parameters are also permitted. However, only -> the last parameter used is effective. - In this example, an object that's not a string or numerical data is passed to-the `Switch`. The `Switch` performs a string coercion on the object and +the `switch`. The `switch` performs a string coercion on the object and evaluates the outcome. ```powershell switch ("fourteen") } ``` -By adding the `Default` clause, you can perform an action when no other +By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell switch -Regex ($target) https://bing.com is a web address that uses https ``` -A `Switch` statement condition may be either: --- An expression whose value is compared to the input value-- A script block which should return `$true` if a condition is met.--The `$_` automatic variable contains the value passed to the `switch` statement -and is available for evaluation and use within the scope of the condition -statements. --The action for each condition is independent of the actions in other -conditions. --The following example demonstrates the use of script blocks as `Switch` +The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell Found a string This Test executes as well ``` +The following example processes an array containing two date values. The +`<value-scriptblock>` compares the **Year** property of each date. The +`<action-scriptblock>` displays a welcome message or the number of days until +the beginning of the year 2022. ++```powershell +switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { + { $_.Year -eq 2021 } { + $days = ((Get-Date 1/1/2022) - $_).days + "There are $days days until 2022." + } + { $_.Year -eq 2022 } { 'Welcome to 2022!' } +} +``` + If the value matches multiple conditions, the action for each condition is-executed. To change this behavior, use the `Break` or `Continue` keywords. +executed. To change this behavior, use the `break` or `continue` keywords. -The `Break` keyword stops processing and exits the `Switch` statement. +The `break` keyword stops processing and exits the `switch` statement. -The `Continue` keyword stops processing the current value, but continues +The `continue` keyword stops processing the current value, but continues processing any subsequent values. The following example processes an array of numbers and displays if they are-odd or even. Negative numbers are skipped with the `Continue` keyword. If a -non-number is encountered, execution is terminated with the `Break` keyword. +odd or even. Negative numbers are skipped with the `continue` keyword. If a +non-number is encountered, execution is terminated with the `break` keyword. ```powershell switch (1,4,-1,3,"Hello",2,1) {- {$_ -lt 0} { Continue } - {$_ -isnot [Int32]} { Break } + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } {$_ % 2} { "$_ is Odd" } |
| Microsoft.PowerShell.Core | Get Module (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/Get-Module.md | external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 10/22/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-module?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Module Accept wildcard characters: False Specifies modules with names that are specified in the form of **ModuleSpecification** objects. See the Remarks section of-[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#Microsoft_PowerShell_Commands_ModuleSpecification__ctor_System_Collections_Hashtable_). +[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#microsoft-powershell-commands-modulespecification-ctor(system-collections-hashtable)). For example, the **FullyQualifiedModule** parameter accepts a module name that is specified in either of these formats: either of these formats: **FullyQualifiedModule** parameter in the same command as a **Module** parameter. the two parameters are mutually exclusive. +> [!NOTE] +> This parameter also accepts simpler forms of input: +> +> - A module name +> - A fully-qualified path to the module +> - A relative path to the module. When used in a script, the relative path is resolved to a +> fully-qualified path relative to the location of the script file. + ```yaml Type: Microsoft.PowerShell.Commands.ModuleSpecification[] Parameter Sets: (All) |
| Microsoft.PowerShell.Core | About Comparison Operators (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md | --- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 11/02/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators zzz zzz ``` +The equality operator can compare objects of different types. It is important +to understand that the value is on the right-hand side of the comparison can be +converted to the type of the left-hand side value for comparison. ++For example, the string `'1.0'` is converted to an integer to be compared to +the value `1`. This example returns `True`. ++```powershell +PS> 1 -eq '1.0' +True +``` ++In this example, the value `1` is converted to a string to be compared to +string `'1.0'`. This example returns `False`. ++```powershell +PS> '1.0' -eq 1 +False +``` + The equality operators accept any two objects, not just a scalar or collection. But the comparison result is not guaranteed to be meaningful for the end-user. The following example demonstrates the issue. |
| Microsoft.PowerShell.Core | About Pipelines (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Pipelines.md | --- description: Combining commands into pipelines in the PowerShell Locale: en-US Previously updated : 03/18/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pipelines?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Pipelines For example, It's important to remember that objects sent down the pipeline are delivered one at a time. +## Using native commands in the pipeline ++PowerShell allows you to include native external commands in the pipeline. +However, it is important to note that PowerShell's pipeline is object-oriented +and does not support raw byte data. ++Piping or redirecting output from a native program that outputs raw byte data +converts the output to .NET strings. This conversion can cause corruption of +the raw data output. ++As a workaround, call the native commands using `cmd.exe /c` or `sh -c` and use +of the `|` and `>` operators provided by the native shell. + ## Investigating pipeline errors When PowerShell can't associate the piped objects with a parameter of the |
| Microsoft.PowerShell.Core | About Switch (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Switch.md | --- -description: Explains how to use a switch to handle multiple `If` statements. +description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US Previously updated : 06/10/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Switch Title: about Switch # about_Switch ## Short description-Explains how to use a switch to handle multiple `If` statements. +Explains how to use a switch to handle multiple `if` statements. ## Long description -To check a condition in a script or function, use an `If` statement. The `If` +To check a condition in a script or function, use an `if` statement. The `if` statement can check many types of conditions, including the value of variables and the properties of objects. -To check multiple conditions, use a `Switch` statement. The `Switch` statement -is equivalent to a series of `If` statements, but it is simpler. The `Switch` +To check multiple conditions, use a `switch` statement. The `switch` statement +is equivalent to a series of `if` statements, but it is simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. -The `Switch` statement can use the `$_` and `$switch` automatic variables. For +The `switch` statement can use the `$_` and `$switch` automatic variables. For more information, see [about_Automatic_Variables](about_Automatic_Variables.md). -A basic `Switch` statement has the following format: +## Syntax -```powershell -Switch (<test-value>) +A basic `switch` statement has the following format: ++```Syntax +Switch (<test-expression>) {- <condition> {<action>} - <condition> {<action>} + <result1-to-be-matched> {<action>} + <result2-to-be-matched> {<action>} } ``` -For example, the following `Switch` statement compares the test value, 3, to +The equivalent `if` statements are: ++```Syntax +if (<result1-to-be-matched> -eq (<test-expression>)) {<action>} +if (<result2-to-be-matched> -eq (<test-expression>)) {<action>} +``` ++The `<test-expression>` is single expression that is evaluated in expression +mode to return a value. ++The `<result-to-be-matched>` is an expression whose value is compared to the +input value. Expressions include literal values (strings or numbers), +variables, and scriptblocks that return a boolean value. ++Any unquoted value that is not recognized as a number is treated as a string. +To avoid confusion or unintended string conversion, you should always quote +string values. Enclose any expressions in parentheses `()`, creating +subexpressions, to ensure that the expression is evaluated correctly. ++It is important to understand that the `<result-to-be-matched>` value is on the +left-hand side of the comparison expression. That means the result of the +`<test-expression>` is on the right-hand side, which can be converted to the +type of the left-hand side value for comparison. For more information, see +[about_Comparison_Operators](about_Comparison_Operators.md) ++The value `default` is reserved for the action used when there are no other +matches. ++The `$_` automatic variable contains the value of the expression passed to the +`switch` statement and is available for evaluation and use within the scope of +the `<result-to-be-matched>` statements. ++The complete `switch` statement syntax is as follows: ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] (<test-expression>) +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++or ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] -file filename +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++If no parameters are used, `switch` behaves the same as using the **Exact** +parameter. It performs a case-insensitive match for the value. If the value is +a collection, each element is evaluated in the order in which it appears. ++The `switch` statement must include at least one condition statement. ++The `default` clause is triggered when the value does not match any of the +conditions. It is equivalent to an `else` clause in an `if` statement. Only one +`default` clause is permitted in each `switch` statement. ++`switch` has the following parameters: ++- **Wildcard** - Indicates that the condition is a wildcard string. If the + match clause is not a string, the parameter is ignored. The comparison is + case-insensitive. +- **Exact** - Indicates that the match clause, if it is a string, must match + exactly. If the match clause is not a string, this parameter is ignored. The + comparison is case-insensitive. +- **CaseSensitive** - Performs a case-sensitive match. If the match clause is + not a string, this parameter is ignored. +- **File**- Takes input from a file rather than a `<test-expression>`. If + multiple **File** parameters are included, only the last one is used. Each + line of the file is read and evaluated by the `switch` statement. The + comparison is case-insensitive. +- **Regex** - Performs regular expression matching of the value to the + condition. If the match clause is not a string, this parameter is ignored. + The comparison is case-insensitive. The `$matches` automatic variable is + available for use within the matching statement block. ++> [!NOTE] +> When specifying conflicting values, like **Regex** and **Wildcard**, the last +> parameter specified takes precedence, and all conflicting parameters are +> ignored. Multiple instances of parameters are also permitted. However, only +> the last parameter listed is used. ++## Examples ++In the following example, the `switch` statement compares the test value, 3, to each of the conditions. When the test value matches the condition, the action is performed. It is three. ``` In this simple example, the value is compared to each condition in the list,-even though there is a match for the value 3. The following `Switch` statement +even though there is a match for the value 3. The following `switch` statement has two conditions for a value of 3. It demonstrates that, by default, all conditions are tested. It is three. Three again. ``` -To direct the `Switch` to stop comparing after a match, use the `Break` -statement. The `Break` statement terminates the `Switch` statement. +To direct the `switch` to stop comparing after a match, use the `break` +statement. The `break` statement terminates the `switch` statement. ```powershell switch (3) It is four. It is two. ``` -Any `Break` statements apply to the collection, not to each value, as shown -in the following example. The `Switch` statement is terminated by the `Break` +Any `break` statements apply to the collection, not to each value, as shown +in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell switch (4, 2) It is four. ``` -### Syntax --The complete `Switch` statement syntax is as follows: --``` -switch [-regex|-wildcard|-exact][-casesensitive] (<value>) -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --or --``` -switch [-regex|-wildcard|-exact][-casesensitive] -file filename -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --If no parameters are used, `Switch` behaves the same as using the **Exact** -parameter. It performs a case-insensitive match for the value. If the value is -a collection, each element is evaluated in the order in which it appears. --The `Switch` statement must include at least one condition statement. --The `Default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `Else` clause in an `If` statement. Only one -`Default` clause is permitted in each `Switch` statement. --`Switch` has the following parameters: --- **Wildcard** - Indicates that the condition is a wildcard string. If the- match clause is not a string, the parameter is ignored. The comparison is - case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match- exactly. If the match clause is not a string, this parameter is ignored. The - comparison is case-insensitive. -- **CaseSensitive** - Performs a case-sensitive match. If the match clause is- not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a value statement. If multiple- **File** parameters are included, only the last one is used. Each line of the - file is read and evaluated by the `Switch` statement. The comparison is - case-insensitive. -- **Regex** - Performs regular expression matching of the value to the- condition. If the match clause is not a string, this parameter is ignored. - The comparison is case-insensitive. The `$matches` automatic variable is - available for use within the matching statement block. --> [!NOTE] -> When specifying conflicting values, like **Regex** and **Wildcard**, the last -> parameter specified takes precedence, and all conflicting parameters are -> ignored. Multiple instances of parameters are also permitted. However, only -> the last parameter used is effective. - In this example, an object that's not a string or numerical data is passed to-the `Switch`. The `Switch` performs a string coercion on the object and +the `switch`. The `switch` performs a string coercion on the object and evaluates the outcome. ```powershell switch ("fourteen") } ``` -By adding the `Default` clause, you can perform an action when no other +By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell switch -Regex ($target) https://bing.com is a web address that uses https ``` -A `Switch` statement condition may be either: --- An expression whose value is compared to the input value-- A script block which should return `$true` if a condition is met.--The `$_` automatic variable contains the value passed to the `switch` statement -and is available for evaluation and use within the scope of the condition -statements. --The action for each condition is independent of the actions in other -conditions. --The following example demonstrates the use of script blocks as `Switch` +The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell Found a string This Test executes as well ``` +The following example processes an array containing two date values. The +`<value-scriptblock>` compares the **Year** property of each date. The +`<action-scriptblock>` displays a welcome message or the number of days until +the beginning of the year 2022. ++```powershell +switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { + { $_.Year -eq 2021 } { + $days = ((Get-Date 1/1/2022) - $_).days + "There are $days days until 2022." + } + { $_.Year -eq 2022 } { 'Welcome to 2022!' } +} +``` + If the value matches multiple conditions, the action for each condition is-executed. To change this behavior, use the `Break` or `Continue` keywords. +executed. To change this behavior, use the `break` or `continue` keywords. -The `Break` keyword stops processing and exits the `Switch` statement. +The `break` keyword stops processing and exits the `switch` statement. -The `Continue` keyword stops processing the current value, but continues +The `continue` keyword stops processing the current value, but continues processing any subsequent values. The following example processes an array of numbers and displays if they are-odd or even. Negative numbers are skipped with the `Continue` keyword. If a -non-number is encountered, execution is terminated with the `Break` keyword. +odd or even. Negative numbers are skipped with the `continue` keyword. If a +non-number is encountered, execution is terminated with the `break` keyword. ```powershell switch (1,4,-1,3,"Hello",2,1) {- {$_ -lt 0} { Continue } - {$_ -isnot [Int32]} { Break } + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } {$_ % 2} { "$_ is Odd" } |
| Microsoft.PowerShell.Core | Get Module (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/Get-Module.md | external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 10/22/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-module?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Module Accept wildcard characters: False Specifies modules with names that are specified in the form of **ModuleSpecification** objects. See the Remarks section of-[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#Microsoft_PowerShell_Commands_ModuleSpecification__ctor_System_Collections_Hashtable_). +[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#microsoft-powershell-commands-modulespecification-ctor(system-collections-hashtable)). For example, the **FullyQualifiedModule** parameter accepts a module name that is specified in either of these formats: either of these formats: **FullyQualifiedModule** parameter in the same command as a **Module** parameter. the two parameters are mutually exclusive. +> [!NOTE] +> This parameter also accepts simpler forms of input: +> +> - A module name +> - A fully-qualified path to the module +> - A relative path to the module. When used in a script, the relative path is resolved to a +> fully-qualified path relative to the location of the script file. + ```yaml Type: Microsoft.PowerShell.Commands.ModuleSpecification[] Parameter Sets: (All) |
| Microsoft.PowerShell.Core | About Comparison Operators (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md | --- description: Describes the operators that compare values in PowerShell. Locale: en-US Previously updated : 11/02/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_comparison_operators?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Comparison Operators zzz zzz ``` +The equality operator can compare objects of different types. It is important +to understand that the value is on the right-hand side of the comparison can be +converted to the type of the left-hand side value for comparison. ++For example, the string `'1.0'` is converted to an integer to be compared to +the value `1`. This example returns `True`. ++```powershell +PS> 1 -eq '1.0' +True +``` ++In this example, the value `1` is converted to a string to be compared to +string `'1.0'`. This example returns `False`. ++```powershell +PS> '1.0' -eq 1 +False +``` + The equality operators accept any two objects, not just a scalar or collection. But the comparison result is not guaranteed to be meaningful for the end-user. The following example demonstrates the issue. |
| Microsoft.PowerShell.Core | About Pipelines (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Pipelines.md | --- description: Combining commands into pipelines in the PowerShell Locale: en-US Previously updated : 03/18/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pipelines?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Pipelines For example, It's important to remember that objects sent down the pipeline are delivered one at a time. +## Using native commands in the pipeline ++PowerShell allows you to include native external commands in the pipeline. +However, it is important to note that PowerShell's pipeline is object-oriented +and does not support raw byte data. ++Piping or redirecting output from a native program that outputs raw byte data +converts the output to .NET strings. This conversion can cause corruption of +the raw data output. ++As a workaround, call the native commands using `cmd.exe /c` or `sh -c` and use +of the `|` and `>` operators provided by the native shell. + ## Investigating pipeline errors When PowerShell can't associate the piped objects with a parameter of the |
| Microsoft.PowerShell.Core | About Switch (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Switch.md | --- -description: Explains how to use a switch to handle multiple `If` statements. +description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US Previously updated : 06/10/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about Switch Title: about Switch # about_Switch ## Short description-Explains how to use a switch to handle multiple `If` statements. +Explains how to use a switch to handle multiple `if` statements. ## Long description -To check a condition in a script or function, use an `If` statement. The `If` +To check a condition in a script or function, use an `if` statement. The `if` statement can check many types of conditions, including the value of variables and the properties of objects. -To check multiple conditions, use a `Switch` statement. The `Switch` statement -is equivalent to a series of `If` statements, but it is simpler. The `Switch` +To check multiple conditions, use a `switch` statement. The `switch` statement +is equivalent to a series of `if` statements, but it is simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. -The `Switch` statement can use the `$_` and `$switch` automatic variables. For +The `switch` statement can use the `$_` and `$switch` automatic variables. For more information, see [about_Automatic_Variables](about_Automatic_Variables.md). -A basic `Switch` statement has the following format: +## Syntax -```powershell -Switch (<test-value>) +A basic `switch` statement has the following format: ++```Syntax +Switch (<test-expression>) {- <condition> {<action>} - <condition> {<action>} + <result1-to-be-matched> {<action>} + <result2-to-be-matched> {<action>} } ``` -For example, the following `Switch` statement compares the test value, 3, to +The equivalent `if` statements are: ++```Syntax +if (<result1-to-be-matched> -eq (<test-expression>)) {<action>} +if (<result2-to-be-matched> -eq (<test-expression>)) {<action>} +``` ++The `<test-expression>` is single expression that is evaluated in expression +mode to return a value. ++The `<result-to-be-matched>` is an expression whose value is compared to the +input value. Expressions include literal values (strings or numbers), +variables, and scriptblocks that return a boolean value. ++Any unquoted value that is not recognized as a number is treated as a string. +To avoid confusion or unintended string conversion, you should always quote +string values. Enclose any expressions in parentheses `()`, creating +subexpressions, to ensure that the expression is evaluated correctly. ++It is important to understand that the `<result-to-be-matched>` value is on the +left-hand side of the comparison expression. That means the result of the +`<test-expression>` is on the right-hand side, which can be converted to the +type of the left-hand side value for comparison. For more information, see +[about_Comparison_Operators](about_Comparison_Operators.md) ++The value `default` is reserved for the action used when there are no other +matches. ++The `$_` automatic variable contains the value of the expression passed to the +`switch` statement and is available for evaluation and use within the scope of +the `<result-to-be-matched>` statements. ++The complete `switch` statement syntax is as follows: ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] (<test-expression>) +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++or ++```Syntax +switch [-regex | -wildcard | -exact] [-casesensitive] -file filename +{ + "string" | number | variable | { <value-scriptblock> } { <action-scriptblock> } + default { <action-scriptblock> } # optional +} +``` ++If no parameters are used, `switch` behaves the same as using the **Exact** +parameter. It performs a case-insensitive match for the value. If the value is +a collection, each element is evaluated in the order in which it appears. ++The `switch` statement must include at least one condition statement. ++The `default` clause is triggered when the value does not match any of the +conditions. It is equivalent to an `else` clause in an `if` statement. Only one +`default` clause is permitted in each `switch` statement. ++`switch` has the following parameters: ++- **Wildcard** - Indicates that the condition is a wildcard string. If the + match clause is not a string, the parameter is ignored. The comparison is + case-insensitive. +- **Exact** - Indicates that the match clause, if it is a string, must match + exactly. If the match clause is not a string, this parameter is ignored. The + comparison is case-insensitive. +- **CaseSensitive** - Performs a case-sensitive match. If the match clause is + not a string, this parameter is ignored. +- **File**- Takes input from a file rather than a `<test-expression>`. If + multiple **File** parameters are included, only the last one is used. Each + line of the file is read and evaluated by the `switch` statement. The + comparison is case-insensitive. +- **Regex** - Performs regular expression matching of the value to the + condition. If the match clause is not a string, this parameter is ignored. + The comparison is case-insensitive. The `$matches` automatic variable is + available for use within the matching statement block. ++> [!NOTE] +> When specifying conflicting values, like **Regex** and **Wildcard**, the last +> parameter specified takes precedence, and all conflicting parameters are +> ignored. Multiple instances of parameters are also permitted. However, only +> the last parameter listed is used. ++## Examples ++In the following example, the `switch` statement compares the test value, 3, to each of the conditions. When the test value matches the condition, the action is performed. It is three. ``` In this simple example, the value is compared to each condition in the list,-even though there is a match for the value 3. The following `Switch` statement +even though there is a match for the value 3. The following `switch` statement has two conditions for a value of 3. It demonstrates that, by default, all conditions are tested. It is three. Three again. ``` -To direct the `Switch` to stop comparing after a match, use the `Break` -statement. The `Break` statement terminates the `Switch` statement. +To direct the `switch` to stop comparing after a match, use the `break` +statement. The `break` statement terminates the `switch` statement. ```powershell switch (3) It is four. It is two. ``` -Any `Break` statements apply to the collection, not to each value, as shown -in the following example. The `Switch` statement is terminated by the `Break` +Any `break` statements apply to the collection, not to each value, as shown +in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell switch (4, 2) It is four. ``` -### Syntax --The complete `Switch` statement syntax is as follows: --``` -switch [-regex|-wildcard|-exact][-casesensitive] (<value>) -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --or --``` -switch [-regex|-wildcard|-exact][-casesensitive] -file filename -{ - "string"|number|variable|{ expression } { statementlist } - default { statementlist } -} -``` --If no parameters are used, `Switch` behaves the same as using the **Exact** -parameter. It performs a case-insensitive match for the value. If the value is -a collection, each element is evaluated in the order in which it appears. --The `Switch` statement must include at least one condition statement. --The `Default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `Else` clause in an `If` statement. Only one -`Default` clause is permitted in each `Switch` statement. --`Switch` has the following parameters: --- **Wildcard** - Indicates that the condition is a wildcard string. If the- match clause is not a string, the parameter is ignored. The comparison is - case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match- exactly. If the match clause is not a string, this parameter is ignored. The - comparison is case-insensitive. -- **CaseSensitive** - Performs a case-sensitive match. If the match clause is- not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a value statement. If multiple- **File** parameters are included, only the last one is used. Each line of the - file is read and evaluated by the `Switch` statement. The comparison is - case-insensitive. -- **Regex** - Performs regular expression matching of the value to the- condition. If the match clause is not a string, this parameter is ignored. - The comparison is case-insensitive. The `$matches` automatic variable is - available for use within the matching statement block. --> [!NOTE] -> When specifying conflicting values, like **Regex** and **Wildcard**, the last -> parameter specified takes precedence, and all conflicting parameters are -> ignored. Multiple instances of parameters are also permitted. However, only -> the last parameter used is effective. - In this example, an object that's not a string or numerical data is passed to-the `Switch`. The `Switch` performs a string coercion on the object and +the `switch`. The `switch` performs a string coercion on the object and evaluates the outcome. ```powershell switch ("fourteen") } ``` -By adding the `Default` clause, you can perform an action when no other +By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell switch -Regex ($target) https://bing.com is a web address that uses https ``` -A `Switch` statement condition may be either: --- An expression whose value is compared to the input value-- A script block which should return `$true` if a condition is met.--The `$_` automatic variable contains the value passed to the `switch` statement -and is available for evaluation and use within the scope of the condition -statements. --The action for each condition is independent of the actions in other -conditions. --The following example demonstrates the use of script blocks as `Switch` +The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell Found a string This Test executes as well ``` +The following example processes an array containing two date values. The +`<value-scriptblock>` compares the **Year** property of each date. The +`<action-scriptblock>` displays a welcome message or the number of days until +the beginning of the year 2022. ++```powershell +switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { + { $_.Year -eq 2021 } { + $days = ((Get-Date 1/1/2022) - $_).days + "There are $days days until 2022." + } + { $_.Year -eq 2022 } { 'Welcome to 2022!' } +} +``` + If the value matches multiple conditions, the action for each condition is-executed. To change this behavior, use the `Break` or `Continue` keywords. +executed. To change this behavior, use the `break` or `continue` keywords. -The `Break` keyword stops processing and exits the `Switch` statement. +The `break` keyword stops processing and exits the `switch` statement. -The `Continue` keyword stops processing the current value, but continues +The `continue` keyword stops processing the current value, but continues processing any subsequent values. The following example processes an array of numbers and displays if they are-odd or even. Negative numbers are skipped with the `Continue` keyword. If a -non-number is encountered, execution is terminated with the `Break` keyword. +odd or even. Negative numbers are skipped with the `continue` keyword. If a +non-number is encountered, execution is terminated with the `break` keyword. ```powershell switch (1,4,-1,3,"Hello",2,1) {- {$_ -lt 0} { Continue } - {$_ -isnot [Int32]} { Break } + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } {$_ % 2} { "$_ is Odd" } |
| Microsoft.PowerShell.Core | Get Module (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/Get-Module.md | external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 10/22/2021 Last updated : 01/27/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/get-module?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 Title: Get-Module Accept wildcard characters: False Specifies modules with names that are specified in the form of **ModuleSpecification** objects. See the Remarks section of-[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#Microsoft_PowerShell_Commands_ModuleSpecification__ctor_System_Collections_Hashtable_). +[ModuleSpecification Constructor (Hashtable)](/dotnet/api/microsoft.powershell.commands.modulespecification.-ctor#microsoft-powershell-commands-modulespecification-ctor(system-collections-hashtable)). For example, the **FullyQualifiedModule** parameter accepts a module name that is specified in either of these formats: either of these formats: **FullyQualifiedModule** parameter in the same command as a **Module** parameter. the two parameters are mutually exclusive. +> [!NOTE] +> This parameter also accepts simpler forms of input: +> +> - A module name +> - A fully-qualified path to the module +> - A relative path to the module. When used in a script, the relative path is resolved to a +> fully-qualified path relative to the location of the script file. + ```yaml Type: Microsoft.PowerShell.Commands.ModuleSpecification[] Parameter Sets: (All) |