The ability to stop a pipeline on demand is currently only available internally, as used by Select-Object -First <n>, for instance.

To quote from this uservoice.com issue:

It is of great value to be able to stop the pipeline if your mission is completed before the emitting cmdlet has provided all results.

In fact, the PS pipeline would gain a completely new "feature". Currently, it is a memory throttle and provides realtime feedback at the cost of performance. If stopping the pipeline was something available to users, it could also be a generic means of running cmdlets only partially.

Select-Object is a great start but you do not always know beforehand how many elements you need. So it would be beneficial to have a Stop-Pipeline cmdlet or at least a public StopUpstreamCommandsException that a script programme can throw.

A real-world example.

Also note that there are two distinct ways to "stop" a pipeline:

• Exiting the entire pipeline instantly (effectively aborting it) - with downstream cmdlets not getting a chance to run their End blocks, as simulated by this command using break with a dummy loop to break out of:

# Produces NO output, because Sort-Object's End block never runs.
do { 
  1..10 | % { if ($_ -gt 2) { break }; $_ } | Sort-Object -Descending
 } while ($False)

Note that without the final Sort-Object -Descending pipeline stage, you would see output, because the objects are being output in the % script block as they're being received.

This quiet termination of the entire pipeline is similar to a statement-terminating error that is silenced.

• Stopping only the upstream cmdlets (the cmdlet calls in earlier pipeline stages), as Select-Object -First <n> does, for instance, giving downstream cmdlets a chance to run their End blocks.

# Produces (2, 1), because Sort-Object's End block IS run.
1..10 | Select-Object -First 2 | Sort-Object -Descending

This scenario is about stopping further input, while still allowing remaining pipeline stages to finish their processing.

However, the fact that the upstream cmdlets do not also get to run their End blocks can be problematic, as that may be required for cleanup tasks: see #7930; PR #9900 would instead introduce a cleanup block to ensure cleanup even when stopped via StopUpstreamCommandsException.

Originally reported for:

PowerShell Core v6.0.0-beta (v6.0.0-beta.1)