Reputation: 4994

How to exit from ForEach-Object in PowerShell

I have the following code:

$project.PropertyGroup | Foreach-Object {
    if($_.GetAttribute('Condition').Trim() -eq $propertyGroupConditionName.Trim()) {
        $a = $project.RemoveChild($_);
        Write-Host $_.GetAttribute('Condition')"has been removed.";
    }
};

Question #1: How do I exit from ForEach-Object? I tried using "break" and "continue", but it doesn't work.

Question #2: I found that I can alter the list within a foreach loop... We can't do it like that in C#... Why does PowerShell allow us to do that?

Upvotes: 103

Answers (12)

Uber Kluger

Reputation: 502

(TLDR; put the breaking part of the pipeline inside a loop statement)

Consolidation of various comments about other answers.

ForEach-Object is not a loop. It is a filter cmdlet, meaning that it takes input objects from a preceding pipeline (available in the -Process scriptblock as $PSItem or $_) and (possibly) produces output objects via return or indeed any expression/pipeline value that is not "used" (by assignment / conditional test / sent into a child pipeline / etc...). These output objects are sent into any succeeding pipeline (meaning "coming after", not "successful"). ForEach-Object does not, of itself, determine how many times its process block is executed. That is determined by how many input objects arrive from the pipeline. Note that it is irrelevant whether or not the input objects are actually used, just how many there are. For example,
```
"a","b","c" |
  ForEach-Object -begin { $count = 0 } -process { (++$count) } -end { "Had $count items" }
```
produces
```
1
2
3
Had 3 items
```
(Aside: ++$count would normally be considered to be an assignment statement. It is literally the same as $count += 1. As such, it would produce no output. By enclosing it in ( ) it becomes an expression (which is not used) and so produces output. In Powershell, assignments are statements unless the surrounding syntax requires an expression.)
break and continue are statements that affect the operation of looping statements. break causes the loop to exit. continue causes the loop to immediately start its next iteration, if any (skipping any further loop block statements after the continue). Both behave similarly for a switch statement where the switch expression is a collection because, in this case, the switch "loops over" (enumerates) the collection. break ends processing of the entire collection while continue ends processing of only the current item and starts processing the next item, also if any. If the switch expression is a scalar then the behaviour is the same as for a collection of one item (i.e. both effectively break). Both are also used in trap statements but that is a separate issue from the use in this question.
break and continue have no direct effect on ForEach-Object but will affect a pipeline (whether or not ForEach-Object is used, see Notes at end). A link to a Powershell forum in a comment for another answer correctly describes their behaviour but the Powershell documentation provides definitive descriptions for break and continue when used inappropriately. In summary, break and continue affect an enclosing loop/switch/trap statement. If there isn't one then the whole pipeline (actually, the whole runspace) exits.
Solutions of the form
```
$do_more_processing = $True;
generate_some_or_many_objects |
  Where-Object { $do_more_processing } |
  ForEach-Object { $do_more_processing = process_and_check_if_more_required $_ }
```
do not "break out of the loop" but merely cease processing the generated objects. The objects are still being generated but are ignored. Where-Object can not (yet) stop the upstream pipeline the way Select-Object can but, even if it could, the value of $do_more_processing is "volatile" (being modified from outside the Where-Object scriptblock) so there is no way for Where-Object to determine that it will not possibly become $True again.

While this "solution" might give the appearance that the "loop" ended (especially for small test cases such as those given in the answers), the generate_some_or_many_objects process still runs to completion. This is a problem if generating each object is expensive (either in time or resources) or only the first few of a great many objects are actually used or, even worse, if the generation process does not stop but is relying on the "loop exit" to terminate. Consider:
```
$keep_going = $True;
&{ for ([byte]$i = 1; $i; ++$i) { $i } } |
  Where-Object { $keep_going } |
  ForEach-Object { $keep_going = $_ -lt 100; $_ }
```
This "correctly" outputs 1 .. 100 but runs until ++$i fails when $i is 255 (256 won't fit in [byte]). Replacing [byte] with [uint16] causes the termination delay to substantially increase with failure occurring at 65535. If you want the rest of the day off, try it using [uint32]. If you're Rip Van Winkle, have a go using [uint64]. (Actually, in this case we're talking timescales that make continental drift seem fast. Note the use of an invoked scriptblock to allow a statement to provide input to a pipeline. This will be important later.)
The correct solution is to carefully read the warning in the Powershell documentation and realize that if there is an enclosing loop (or switch) then it will catch the break and exit cleanly, leaving any remaining portion of the pipeline functional. Some may argue that this is all just theoretical and that a clean exit or crashing the pipeline does not make any difference. This is only true in cases where the pipeline processes each object to completion before processing the next. For example,
```
1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_ }
```
still produces the expected output (1, 5, 3, 8). Similarly,
```
1,5,3,8,9,3,5,7,2,5,7,6,9 |
  ForEach-Object { Write-Host $_; if ($_ -eq 9) { break } $_ } |
  Select-Object -First 2 -Wait
```
also works, producing (1, 5) as pipeline output interspersed in the Write-Host displayed (1, 5, 3, 8, 9). -⁠Wait is included so that Select-Object does not prematurely stop the pipeline before the break occurs, thereby invalidating the example.

However, in cases where the output is collected before being used, crashing the pipeline produces unexpected results. Consider,
```
$output = 1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_ }
```
In this case the output must be collected into an array before being assigned to $output. When the pipeline crashes, this assignment is aborted and the collected output is simply displayed. Another example might be,
```
1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_} | Sort-Object
```
Here, Sort-Object is collecting the output in order to sort it. When the pipeline crashes, it takes Sort-Object with it and the output is lost. Both of these situations can be avoided by using the enclosing loop method. Some other answers/comments used somewhat simplistic examples where the output was simply displayed, e.g.
```
$array = 'a'..'z'
do{
   $array | ForEach-Object {
      $_
      if ($_ -eq 'c') {
         break
      }
   }
} until ($true)
# (Sorry to pick on you again, Maybe)
```
While this example is correct, it is also another of the "doesn't make any difference if the pipeline crashes" examples. This is pretty much the case for any pipeline that is just placed within a loop in its entirety. If it works in the loop then it probably worked without it. For those pipelines that fail, more care is often required. For example,
```
do {
  $output = 1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_ }
} while ($False)
```
still does not work. $output is not assigned and the output is just displayed as before. In this case, the correct solution is to place the assignment outside of the breaking loop:
```
$output = do {
   1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_ }
} while ($False)
```
leaving $output with (1, 5, 3, 8) as required. For other situations, it is even more complicated.
```
do {
  1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_} | Sort-Object
} while ($False)
```
still produces no output because the loop is terminated before Sort-Object has processed its input. Sort-Object must be placed outside the breaking loop like the assignment example. Unfortunately,
```
do {
  1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_} 
} while ($False) | Sort-Object
```
does not work because a statement cannot be used as the input to a pipeline, only a command or expression. But
```
(
  do {
    1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_}
  } while ($False)
) | Sort-Object
```
also fails despite the fact that, syntactically, the input to the pipeline is now an expression because of the ( ). The reason is that the content of the ( ) is syntactically invalid (as an expression) and so is treated as a command and thus fails because there is no "do" command (probably wouldn't "do" what you want even if there were). (Preempting some comments: see Notes regarding use of $( )) The answer here (as before) is to invoke a scriptblock containing the breaking loop statement in order to provide the input to Sort-Object,
```
&{
  do {
    1,5,3,8,9,3,5,7,2,5,7,6,9 | ForEach-Object { if ($_ -eq 9) { break } $_ }
  } while ($False)
} | Sort-Object
```
thus obtaining the desired output (1, 3, 5, 8).

Notes:

The subexpression operator $( ) can be used instead of the call/invoke operator on a script block &{ }. The main difference is that &{ } will pass each object as it is generated while $( ) collects all the generated objects into an array which is then enumerated into the subsequent pipeline. Don't know which is more efficient overall but collecting all the objects before processing could be memory hungry for large data sets and might delay the initial production of output. Probably no real difference if all the desired input objects must be processed before the output is used, e.g. saved in a collection (for later processing), sorted or examined to determine the best fit output formatting (Format-Table -AutoSize).
The use of a one time loop is so that if the breaking condition is not met and the pipeline runs to normal completion then it is not continually re-invoked by the loop as it would be if loops such as while (1) { ... } or for (;;) { ... } were used. Seems obvious but just being thorough in my explanation.

Don't have Powershell 7+ but still want a ternary operator? Try

$( if (condition) { true expression } else { false expression } )

All testing performed in Powershell 4.0 (going it old school).
Using break not in ForEach-Object (a somewhat contrived example):
```
1 .. 10 | Format-Wide -Column 3 -Force { if ($_ -eq 5) { break } $_ }
```
produces only
```
1                       2                       3
```
Crashing the pipeline has lost the anticipated line containing just 4. The calculated property expression scriptblock is run in a "child scope" but is still within the entire pipeline's runspace. However,
```
1 .. 10 | Format-Wide -Column 3 -Force { do { if ($_ -eq 5) { break } $_ } while ($False) }
```
produces
```
1                       2                       3
4                                               6
7                       8                       9
10
```
i.e. the pipeline did not break but just the 5 has been replaced with $null. Note that this behaviour is not the same as if $null had been passed into Format-Wide. In that case it is simply ignored and has no effect on the output. Here, however, a not $null value was passed in thereby creating a place for it in the output but that value was replaced by $null (strictly System.Management.Automation.Internal.AutomationNull.Value being the "value" of no output) which is then displayed as [String]::Empty. I am unsure about the possibility of "cleanly breaking" the pipeline to produce
```
1                       2                       3
4
```
but I suspect the required syntax would be horribly complicated. You would need to have the calculated property expression scriptblock inside a loop statement that encompassed the pipeline but the Format-Wide outside the loop. Since cmdlets are (AFAIK) not dimensionally transcendental, the notion that a parameter of Format-Wide is within a loop that encompasses the pipeline but the Format-Wide itself is not seems implausible. A viable solution would be to have the calculated property expression scriptblock control the breaking but perform the break outside of the Format-Wide,
```
$global:breaknow = $False
&{ do { 1 .. 10 | Where-Object { if ($global:breaknow) { break } $True } } while ($False) } |
   Format-Wide -Column 3 -Force { $global:breaknow = $_ -eq 4; $_ }
```
Note that, because the calculated property expression scriptblock (try saying that 5 times fast) is run in a child scope, feeding back boolean values to a preceding Where-Object won't work unless it is scoped using global: or script: (assuming this doesn't create usage conflicts elsewhere in the script). Further, the breaking condition has to be changed since the breaking is occurring before the breaking object reaches Format-Wide so the breaking condition is the arrival of the last desired object. In this case '4' is known to be the object prior to the breaking object (5) but it is a problem if there is no relationship between the last desired object and the breaking object. However, most situations are far less contrived than trying to feed back from a later stage in the pipeline in order to stop some potentially random breaking object from reaching that point. The next example is a more likely situation where the breaking is done at the point where the breaking object is detected.

Breaking within Where-Object provides a way for it to achieve the "stop the upstream pipeline" behaviour of Select-Object, but based on a predicate (boolean) expression instead of an object count. This is useful for cases where you have no control over the breaking behaviour of subsequent portions of the pipeline, e.g. piping directly to a cmdlet or legacy command.

Another highly contrived example with much better solutions to achieve the same result (this is a demonstration, not a recommendation):
```
$now = [DateTime]::now

1..1000000 |
  Where-Object { $_ -le 10 } |
  Sort-Object -Descending |
  Format-Wide -Column 10 -Force { $_ }

[DateTime]::now - $now

10  9   8   7   6   5   4   3   2   1

.
.
.
TotalMilliseconds : 18231.5353

$now = [DateTime]::now

&{ do { 1..1000000 | Where-Object { if ($_ -gt 10) { break } $True } } while ($False) } |
  Sort-Object -Descending |
  Format-Wide -Column 10 -Force { $_ }

[DateTime]::now - $now

10  9   8   7   6   5   4   3   2   1

.
.
.
TotalMilliseconds : 62.4388
```
Warning: be careful about the logic used in the predicate expression. Changing the above example to
```
... Where-Object { $True; if ($_ -eq 10) { break } } ...
```
might be imagined to break after the current object (10) is passed because the Where-Object scriptblock returns $True before breaking. There are at least 3 possible results here:
1. It works as expected because Where-Object sees the $True and passes the object before the break is executed.
2. It fails on the last desired object because Where-Object runs the scriptblock to completion before checking its output. (Result on my system.)
3. Even worse, it creates a race condition based on whether Where-Object is faster at passing the object than the break is at ending the loop. Particularly problematic if the implementation uses a multi-threaded pipeline (assuming that there are or will be any such implementations).
Those with knowledge of the inner workings of Powershell would probably identify the correct option but the average user would not be able to do so. Further, the behaviour could vary between versions and implementations (this is not exactly "standard" usage as per the documentation). The safest way is to ensure that the scriptblock either breaks or returns $True but not both. (It could alternatively just return $False if you don't want the current object but want to continue processing.)

Upvotes: 0

zett42

Reputation: 27756

There is a way to break from ForEach-Object without throwing an exception. It employs a lesser-known feature of Select-Object, using the -First parameter, which actually breaks the pipeline when the specified number of pipeline items have been processed.

Simplified example

$null = 1..5 | ForEach-Object {

    # Do something...
    Write-Host $_
 
    # Evaluate "break" condition -> output $true to the pipeline
    if( $_ -eq 2 ) { $true }  
 
} | Select-Object -First 1     # Actually breaks the pipeline

Console Output:

1
2

Explanation

The assignment to $null is there to hide the output of $true, which is produced by the break condition. The value $true could be replaced by 42, "skip", "foobar", or any other value. The key is to pipe something to Select-Object so it breaks the pipeline.

Important Note:

While this example displays several items, the actual pipeline output is only one item: $true (which is then discarded by assigning to $null). This distinction is crucial, as it highlights the difference between what is displayed (via Write-Host) and what is output in the pipeline.

If ForEach-Object is performing all necessary actions, this method works well. However, it cannot pass multiple objects into a continuing pipeline unless the number of such objects is known ahead of time. This limitation should be considered when designing your script.

Upvotes: 14

ThePennyDrops

Reputation: 171

Below is a suggested approach to Question #1 which I use if I wish to use the ForEach-Object cmdlet. It does not directly answer the question because it does not EXIT the pipeline. However, it may achieve the desired effect in Q#1. The only drawback an amateur like myself can see is when processing large pipeline iterations.

    $zStop = $false
    (97..122) | Where-Object {$zStop -eq $false} | ForEach-Object {
    $zNumeric = $_
    $zAlpha = [char]$zNumeric
    Write-Host -ForegroundColor Yellow ("{0,4} = {1}" -f ($zNumeric, $zAlpha))
    if ($zAlpha -eq "m") {$zStop = $true}
    }
    Write-Host -ForegroundColor Green "My PSVersion = 5.1.18362.145"

Upvotes: 4

Eddie Kumar

Reputation: 1480

You have two options to abruptly exit out of ForEach-Object pipeline in PowerShell:

Apply exit logic in Where-Object first, then pass objects to Foreach-Object, or
(where possible) convert Foreach-Object into a standard Foreach looping construct.

Let's see examples: Following scripts exit out of Foreach-Object loop after 2nd iteration (i.e. pipeline iterates only 2 times)":

Solution-1: use Where-Object filter BEFORE Foreach-Object:

[boolean]$exit = $false;
1..10 | Where-Object {$exit -eq $false} | Foreach-Object {
     if($_ -eq 2) {$exit = $true}    #OR $exit = ($_ -eq 2);
     $_;
}

1..10 | Where-Object {$_ -le 2} | Foreach-Object {
     $_;
}

Solution-2: Converted Foreach-Object into standard Foreach looping construct:

Foreach ($i in 1..10) { 
     if ($i -eq 3) {break;}
     $i;
}

PowerShell should really provide a bit more straightforward way to exit or break out from within the body of a Foreach-Object pipeline. Note: return doesn't exit, it only skips specific iteration (similar to continue in most programming languages), here is an example of return:

Write-Host "Following will only skip one iteration (actually iterates all 10 times)";
1..10 | Foreach-Object {
     if ($_ -eq 3) {return;}  #skips only 3rd iteration.
     $_;
}

Upvotes: 0

Maybe

Reputation: 965

While this is a bit hacky, it works:

$array = 'a'..'z'
:pipe do{
    $array | ForEach-Object {
        $_
        if ($_ -eq 'c') {
            break :pipe
        }
    }
} until ($true)

Output:
a
b
c

The code can also be condensed easily, like so:

$array = 'a'..'z'
:_ do{ $array | ForEach-Object {
    $_
    if ($_ -eq 'c') {
        break :_
    }
}}until(1)

# OR:
#}}until({})
# not sure why {} evaluates to True, but whatever
# anything that evaluates to True will work, e.g.: !''

Upvotes: 0

smeltplate

Reputation: 1835

First of all, Foreach-Object is not an actual loop and calling break in it will cancel the whole script rather than skipping to the statement after it.

Conversely, break and continue will work as you expect in an actual foreach loop.

Item #1. Putting a break within the foreach loop does exit the loop, but it does not stop the pipeline. It sounds like you want something like this:

$todo=$project.PropertyGroup 
foreach ($thing in $todo){
    if ($thing -eq 'some_condition'){
        break
    }
}

Item #2. PowerShell lets you modify an array within a foreach loop over that array, but those changes do not take effect until you exit the loop. Try running the code below for an example.

$a=1,2,3
foreach ($value in $a){
  Write-Host $value
}
Write-Host $a

I can't comment on why the authors of PowerShell allowed this, but most other scripting languages (Perl, Python and shell) allow similar constructs.

Upvotes: 155

marsze

Reputation: 17035

Since ForEach-Object is a cmdlet, break and continue will behave differently here than with the foreach keyword. Both will stop the loop but will also terminate the entire script:

break:

0..3 | foreach {
    if ($_ -eq 2) { break }
    $_
}
echo "Never printed"

# OUTPUT:
# 0
# 1

continue:

0..3 | foreach {
    if ($_ -eq 2) { continue }
    $_
}
echo "Never printed"

# OUTPUT:
# 0
# 1

So far, I have not found a "good" way to break a foreach script block without breaking the script, except "abusing" exceptions, although powershell core uses this approach:

throw:

class CustomStopUpstreamException : Exception {}
try {
    0..3 | foreach {
        if ($_ -eq 2) { throw [CustomStopUpstreamException]::new() }
        $_
    }
} catch [CustomStopUpstreamException] { }
echo "End"

# OUTPUT:
# 0
# 1
# End

The alternative (which is not always possible) would be to use the foreach keyword:

foreach:

foreach ($_ in (0..3)) {
    if ($_ -eq 2) { break }
    $_
}
echo "End"

# OUTPUT:
# 0
# 1
# End

Upvotes: 9

Rikki

Reputation: 3518

If you insist on using ForEach-Object, then I would suggest adding a "break condition" like this:

$Break = $False;

1,2,3,4 | Where-Object { $Break -Eq $False } | ForEach-Object {

    $Break = $_ -Eq 3;

    Write-Host "Current number is $_";
}

The above code must output 1,2,3 and then skip (break before) 4. Expected output:

Current number is 1
Current number is 2
Current number is 3

Upvotes: 6

Alex Hague

Reputation: 1981

I found this question while looking for a way to have fine grained flow control to break from a specific block of code. The solution I settled on wasn't mentioned...

Using labels with the break keyword

From: about_break

A Break statement can include a label that lets you exit embedded loops. A label can specify any loop keyword, such as Foreach, For, or While, in a script.

Here's a simple example

:myLabel for($i = 1; $i -le 2; $i++) {
        Write-Host "Iteration: $i"
        break myLabel
}

Write-Host "After for loop"

# Results:
# Iteration: 1
# After for loop

And then a more complicated example that shows the results with nested labels and breaking each one.

:outerLabel for($outer = 1; $outer -le 2; $outer++) {

    :innerLabel for($inner = 1; $inner -le 2; $inner++) {
        Write-Host "Outer: $outer / Inner: $inner"
        #break innerLabel
        #break outerLabel
    }

    Write-Host "After Inner Loop"
}

Write-Host "After Outer Loop"

# Both breaks commented out
# Outer: 1 / Inner: 1
# Outer: 1 / Inner: 2
# After Inner Loop
# Outer: 2 / Inner: 1
# Outer: 2 / Inner: 2
# After Inner Loop
# After Outer Loop

# break innerLabel Results
# Outer: 1 / Inner: 1
# After Inner Loop
# Outer: 2 / Inner: 1
# After Inner Loop
# After Outer Loop

# break outerLabel Results
# Outer: 1 / Inner: 1
# After Outer Loop

You can also adapt it to work in other situations by wrapping blocks of code in loops that will only execute once.

:myLabel do {
    1..2 | % {

        Write-Host "Iteration: $_"
        break myLabel

    }
} while ($false)

Write-Host "After do while loop"

# Results:
# Iteration: 1
# After do while loop

Upvotes: 3

Thomas Giboney

Reputation: 7

Answer for Question #1 - You could simply have your if statement stop being TRUE

$project.PropertyGroup | Foreach {
    if(($_.GetAttribute('Condition').Trim() -eq $propertyGroupConditionName.Trim()) -and !$FinishLoop) {
        $a = $project.RemoveChild($_);
        Write-Host $_.GetAttribute('Condition')"has been removed.";
        $FinishLoop = $true
    }
};

Upvotes: -1

Stoffi

Reputation: 754

There are differences between foreach and foreach-object.

A very good description you can find here: MS-ScriptingGuy

For testing in PS, here you have scripts to show the difference.

ForEach-Object:

# Omit 5.
1..10 | ForEach-Object {
if ($_ -eq 5) {return}
# if ($_ -ge 5) {return} # Omit from 5.
Write-Host $_
}
write-host "after1"

# Cancels whole script at 15, "after2" not printed.
11..20 | ForEach-Object {
if ($_ -eq 15) {continue}
Write-Host $_
}
write-host "after2"

# Cancels whole script at 25, "after3" not printed.
21..30 | ForEach-Object {
if ($_ -eq 25) {break}
Write-Host $_
}
write-host "after3"

foreach

# Ends foreach at 5.
foreach ($number1 in (1..10)) {
if ($number1 -eq 5) {break}
Write-Host "$number1"
}
write-host "after1"

# Omit 15. 
foreach ($number2 in (11..20)) {
if ($number2 -eq 15) {continue}
Write-Host "$number2"
}
write-host "after2"

# Cancels whole script at 25, "after3" not printed.
foreach ($number3 in (21..30)) {
if ($number3 -eq 25) {return}
Write-Host "$number3"
}
write-host "after3"

Upvotes: 51

darlove

Reputation: 317

To stop the pipeline of which ForEach-Object is part just use the statement continue inside the script block under ForEach-Object. continue behaves differently when you use it in foreach(...) {...} and in ForEach-Object {...} and this is why it's possible. If you want to carry on producing objects in the pipeline discarding some of the original objects, then the best way to do it is to filter out using Where-Object.

Upvotes: 11

How to exit from ForEach-Object in PowerShell

Answers (12)

Simplified example

Explanation

Using labels with the break keyword

Related Questions