Allow user code to stop a pipeline on demand / to terminate upstream cmdlets.

[mklement0]

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)

[dragonwolf83]

There is a good detailed blog post on how to implement this in PowerShell today: Cancelling a Pipeline. I think it would be useful to implement something like as a built-in cmdlet.

[mklement0]

Thanks, @dragonwolf83; the blog post's author, Tobias Weltner, is the same person who created the linked uservoice.com issue; the blog post elicited the following @jpsnover response (dated "over 7 years ago"):

We have wanted to add pipeline stopping for quite a while and it never got raised above the bar.

That's one lofty bar! :)

[SteveL-MSFT]

Things that don't necessarily align with the PowerShell Team's priorities (which is not static) can still get done if contributed by the community :)

[iSazonov]

We need RFC for new cmdlet and examples of how to use the cmdlet.

[alx9r]

Does anyone have a working link to Tobias' blog post mentioned above? That link seems to be dead.

[TobiasPSP]

Here‘s some material: http://www.powertheshell.com/stop_pipeline/

[SeeminglyScience]

Adding Needs-Triage so WG-Engine can discuss it. This comes up surprisingly often. Typically for profile functions, but still. The lengths one has to go through to get the same behavior is pretty wild (and unsupported).

My proposal:

  namespace System.Management.Automation
  {
      public abstract class PSCmdlet
      {
+         [DoesNotReturn]
+         public void StopUpstreamCommands();
      }
  }

If added this should be tested both for binary cmdlets (this.StopUpstreamCommands()) and script cmdlets ($PSCmdlet.StopUpstreamCommands())

[vexx32]

WG-Engine discussed this today (6/23/2022).

We agree that users should have access to this functionality in some way that is not exclusive to Select-Object. It came up in discussion that there may be undesirable elements of the current behaviour of Select-Object -First $x; for instance, it doesn't appear to call upstream C# cmdlets' StopProcessing() when it cancels the remainder of a pipeline.

We need more investigation on whether this behaviour would be problematic to expose as a commonly usable API, and whether we should:

• Make changes to the existing behaviour of the pipeline's handling of StopUpstreamCommandsException, and/or:
  • Expose the same Select-Object -First $x behaviour as-is as a public API similar to the suggestions in this issue, or
  • Expose a new public API that handles the stop upstream commands request somewhat differently to the current method used for Select-Object -First $x

[SeeminglyScience]

I went through every command that overrides StopProcessing but does not implement IDisposable with this command:

Find-Type -Base System.Management.Automation.PSCmdlet |
    Find-Type -Not -ImplementsInterface System.IDisposable |
    Find-Member StopProcessing -Force -Declared |
    ForEach-Object {
        dnSpy.Console.exe $_.Module.Assembly.Location --md $_.MetadataToken --no-tokens |
            bat --language cs --style 'grid,numbers,snip'

        Read-Host -Prompt 'Press enter to continue'
    }

Of all of them I found only one command that is using StopProcessing for resource cleanup (Get-Counter).

I would recommend we just fix Get-Counter as pipeline terminating errors, Select-Object -First 1 and pipeline stop exceptions thrown outside of stop requests will already cause a leak here.

[microsoft-github-policy-service]

This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.

[microsoft-github-policy-service]

This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.

[microsoft-github-policy-service]

This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.