Skip to content

5/19/2025 PM Publish #12082

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 19, 2025
Merged

5/19/2025 PM Publish #12082

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2a07ffb
Further clarification of switch behavior (#12080)
sdwheeler May 19, 2025
00a3382
Fixes #11978 - Create new article about parallel execution (#12074)
sdwheeler May 19, 2025
b29ff5b
Updated azps quick filter link for 14.0.0 (#12081)
mikefrobbins May 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
240 changes: 102 additions & 138 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Explains how to use a switch to handle multiple `if` statements.
Locale: en-US
ms.date: 05/15/2025
ms.date: 05/19/2025
online version: https://learn.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
Expand All @@ -20,11 +20,11 @@ variables and the properties of objects.

To check multiple conditions, you can use a `switch` statement. The `switch`
statement is similar to a series of `if` statements, but it's simpler. The
`switch` statement lists each condition and an optional action. If a condition
matches, the action is performed.
`switch` statement lists each condition and the corresponding action. If a
condition matches, the action is performed.

The `switch` statement can use the `$_` and `$switch` automatic variables. For
more information, see [about_Automatic_Variables][03].
> [!IMPORTANT]
> The `switch` statement converts all values to strings before comparison.

## Syntax

Expand All @@ -37,33 +37,33 @@ switch (<test-expression>) {
}
```

This is similar to the following `if` statements:
The syntax of a `switch` statement is similar to the following `if` statements:

```Syntax
if (<result1-to-be-matched> -eq (<test-expression>)) {<action>}
if (<result2-to-be-matched> -eq (<test-expression>)) {<action>}
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's 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. For an example, see
Expressions include literal values (strings or numbers), variables, and
scriptblocks that return a boolean value. The `switch` statement converts all
values to strings before comparison. For an example, see
[Impact of string conversion][02] later in this article.

It's 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][05]
The `<test-expression>` is evaluated in expression mode. If the expression
returns more than one value, such as an array or other enumerable type, the
`switch` statement evaluates each enumerated value separately.

The `<result-to-be-matched>` is an expression must resolve to a single value.
That value is compared to the input value.

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 `switch` statement can use the `$_` and `$switch` automatic variables. 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. For more information, see
[about_Automatic_Variables][03].

The complete `switch` statement syntax is as follows:

Expand Down Expand Up @@ -109,7 +109,8 @@ conditions. It's equivalent to an `else` clause in an `if` statement. Only one
file is read a line at a time and evaluated by the `switch` statement. By
default, the comparison is case-insensitive. The **File** parameter only
supports one file. If multiple **File** parameters are included, only the
last one is used. For more information see [File parameter examples][01].
last one is used. For more information see the
[**File** parameter examples][01].
- **Regex** - Performs regular expression matching of the value to the
condition. If the match clause isn't a string, this parameter is ignored.
The comparison is case-insensitive. The `$Matches` automatic variable is
Expand All @@ -121,7 +122,11 @@ conditions. It's equivalent to an `else` clause in an `if` statement. Only one
> ignored. Multiple instances of parameters are also permitted. However, only
> the last parameter listed is used.

## Simple match examples
## Examples

The following examples demonstrate the use of the `switch` statement.

### Simple match 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
Expand Down Expand Up @@ -159,69 +164,44 @@ It's three.
Three again.
```

To direct the `switch` to stop comparing after a match, use the `break`
statement. The `break` statement terminates the `switch` statement.

```powershell
switch (3) {
1 { "It's one." }
2 { "It's two." }
3 { "It's three."; break }
4 { "It's four." }
3 { "Three again." }
}
```

```Output
It's three.
```
### Use `break` and `continue` to control the flow

If the test value is a collection, such as an array, each item in the
collection is evaluated in the order in which it appears. The following
examples evaluates 4 and then 2.
If the value matches multiple conditions, the action for each condition is
executed. To change this behavior, use the `break` or `continue` keywords.

```powershell
switch (4, 2) {
1 { "It's one." }
2 { "It's two." }
3 { "It's three." }
4 { "It's four." }
3 { "Three again." }
}
```
The `break` keyword stops processing and exits the `switch` statement.

```Output
It's four.
It's two.
```
The `continue` keyword stops processing the current value, but continues
processing any subsequent values.

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.
The following example processes an array of numbers and displays if they're
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 (4, 2) {
1 { "It's one."; break }
2 { "It's two." ; break }
3 { "It's three." ; break }
4 { "It's four." ; break }
3 { "Three again." }
switch (1,4,-1,3,"Hello",2,1) {
{$_ -lt 0} { continue }
{$_ -isnot [int32]} { break }
{$_ % 2} { "$_ is Odd" }
{-not ($_ % 2)} { "$_ is Even" }
}
```

```Output
It's four.
1 is Odd
4 is Even
3 is Odd
```

## Impact of string conversion
### Impact of string conversion

Any unquoted value that's not recognized as a number is treated as a string. To
avoid unintended string conversion, use script blocks to evaluate the switch
value.
All values, both input and the comparison value are converted to strings for
comparison. To avoid unintended string conversion, use script blocks to
evaluate the switch value.

```powershell
switch ( ([datetime]'1 Jan 1970').DayOfWeek ) {
4 { 'The value matches a Thursday.' }
4 { 'The integer value matches a Thursday.' }
"4" { 'The numeric string matches a Thursday.' }
"Thursday" { 'The string value matches a Thursday.' }
{ 4 -eq $_ } { 'The expression matches a Thursday.' }
Expand All @@ -242,59 +222,69 @@ statement.

```powershell
if (4 -eq ([datetime]'1 Jan 1970').DayOfWeek) {
'The value matches a Thursday.'
'The integer value matches a Thursday.'
}
```

```Output
The value matches a Thursday.
```

## More complex match examples

In this example, the `switch` statement is testing for the type of the value in
the hashtable. You must use and expression that returns a boolean value to
select the scriptblock to execute.
In this example, a hashtable is passed to the `switch` statement. The `switch`
converts the hashtable to a string.

```powershell
$var = @{A = 10; B = 'abc'}

foreach ($key in $var.Keys) {
switch ($var[$key].GetType()) {
{ $_ -eq [int32] } { "$key + 10 = $($var[$key] + 10)" }
{ $_ -eq [string] } { "$key = $($var[$key])" }
}
$test = @{
Test = 'test'
Test2 = 'test2'
}

$test.ToString()
```

```Output
A + 10 = 20
B = abc
System.Collections.Hashtable
```

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
evaluates the outcome.
Notice that the string representation of the hashtable is not the same as the
value of the **Test** key.

```powershell
$test = @{
Test = 'test'
Test2 = 'test2'
}

$test.ToString()

switch -Exact ($test) {
'System.Collections.Hashtable' { 'Hashtable string coercion' }
'test' { 'Hashtable value' }
}
```

```Output
System.Collections.Hashtable
Hashtable string coercion
```

### Use `switch` to test the values in a hashtable

In this example, the `switch` statement is testing for the type of the value in
the hashtable. We must enumerate the items in the hashtable before we can test
the values. To avoid the complications of string conversion, use a script block
that returns a boolean value to select the action scriptblock to execute.

```powershell
$var = @{A = 10; B = 'abc'}

foreach ($key in $var.Keys) {
switch ($var[$key].GetType()) {
{ $_ -eq [int32] } { "$key + 10 = $($var[$key] + 10)" }
{ $_ -eq [string] } { "$key = $($var[$key])" }
}
}
```

```Output
A + 10 = 20
B = abc
```

### Use wildcards with `switch`

In this example, there is no matching case so there is no output.

```powershell
Expand Down Expand Up @@ -342,6 +332,8 @@ switch -Wildcard ("fourteen") {
That's too many.
```

### Use regular expressions with `switch`

The following example uses the `-Regex` parameter.

```powershell
Expand Down Expand Up @@ -400,34 +392,7 @@ switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) {
}
```

If the value matches multiple conditions, the action for each condition is
executed. To change this behavior, use the `break` or `continue` keywords.

The `break` keyword stops processing and exits the `switch` statement.

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're
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 }
{$_ % 2} { "$_ is Odd" }
{-not ($_ % 2)} { "$_ is Even" }
}
```

```Output
1 is Odd
4 is Even
3 is Odd
```

## File parameter examples
### Read the content of a file with `switch`

Using the `switch` statement with the **File** parameter is an efficient way to
process large files line by line. PowerShell streams the lines of the file to
Expand All @@ -450,10 +415,10 @@ switch -Regex -File .\README.md {
}
```

The `<filename>` argument is interpreted as a wildcard expression, but it must
match only one file. The following example is the same as the previous one
except it uses a wildcard in the `<filename>` argument. This example works
because the wildcard pattern matches only one file.
The `<filename>` argument accepts wildcard expressions, but it must match only
one file. The following example is the same as the previous one except it uses
a wildcard in the `<filename>` argument. This example works because the
wildcard pattern matches only one file.

```powershell
switch -Regex -File .\README.* {
Expand All @@ -478,16 +443,15 @@ switch -File $fileEscaped { foo { 'Foo' } }
## See also

- [about_Break][04]
- [about_Continue][06]
- [about_If][07]
- [about_Script_Blocks][08]
- [about_Continue][05]
- [about_If][06]
- [about_Script_Blocks][07]

<!-- updated link references -->
[01]: #file-parameter-examples
<!-- link references -->
[01]: #read-the-content-of-a-file-with-switch
[02]: #impact-of-string-conversion
[03]: about_Automatic_Variables.md
[04]: about_break.md
[05]: about_Comparison_Operators.md
[06]: about_Continue.md
[07]: about_If.md
[08]: about_Script_Blocks.md
[05]: about_Continue.md
[06]: about_If.md
[07]: about_Script_Blocks.md
Loading