From f858b4a5281172995cd69270a28d0b677b284218 Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Tue, 25 Mar 2025 14:35:54 +1000 Subject: [PATCH 1/3] Add PipelineStopToken documentation Adds the documentation for the new PipelineStopToken property on $PSCmdlet. This property is used to remove boilerplate currently needed for invoking async methods in PowerShell functions. --- .../About/about_Functions_Advanced.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md index 99d317d26910..a3b674e5fe83 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md @@ -69,6 +69,40 @@ Advanced functions differ from compiled cmdlets in the following ways: named parameters. - Advanced functions can't be used in transactions. +## PipelineStopToken + +Beginning with PowerShell 7.6, you can access the `PipelineStopToken` property +on the `$PSCmdlet` variable to access a [CancellationToken][07] tied to the +PowerShell stop event source. This token will be automatically triggered when +the PowerShell pipeline has been requested to stop. It is designed to be used +with .NET methods that accept a `CancellationToken` overload so that the +method can exit when requested rather than wait until the method returns from +what it is doing. + +A common example is if the function is calling a .NET async compatible API. In +the below example the function is calling `HttpClient.GetStringAsync` which +could take a while to respond if the network is slow or there is a lot of data +being returned. + +```powershell +Function Invoke-WebGetRequest { + [CmdletBinding()] + param( + [Parameter(Mandatory=$true)] + [string] + $Url + ) + + $client = [System.Net.Http.HttpClient]::new() + $client.GetStringAsync( + $Url, + $PSCmdlet.PipelineStopToken).GetAwaiter().GetResult() +} + +Invoke-WebGetRequest -Url https://httpbin.org/delay/10 +# Press ctrl+c to cancel +``` + ## See also - [about_Functions][05] @@ -85,3 +119,4 @@ Advanced functions differ from compiled cmdlets in the following ways: [04]: about_Functions_OutputTypeAttribute.md [05]: about_Functions.md [06]: about_Variables.md +[07]: xref:System.Threading.CancellationToken From c99a063be1d7ba99c3170ef407527df545036ade Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 25 Mar 2025 08:08:45 -0500 Subject: [PATCH 2/3] Editorial update --- .../About/about_Functions_Advanced.md | 26 +++++++++---------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md index a3b674e5fe83..4bcdaa98d33d 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md @@ -1,7 +1,7 @@ --- description: Introduces advanced functions that are a way to create cmdlets using scripts. Locale: en-US -ms.date: 01/02/2025 +ms.date: 03/25/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions_Advanced @@ -71,21 +71,19 @@ Advanced functions differ from compiled cmdlets in the following ways: ## PipelineStopToken -Beginning with PowerShell 7.6, you can access the `PipelineStopToken` property -on the `$PSCmdlet` variable to access a [CancellationToken][07] tied to the -PowerShell stop event source. This token will be automatically triggered when -the PowerShell pipeline has been requested to stop. It is designed to be used -with .NET methods that accept a `CancellationToken` overload so that the -method can exit when requested rather than wait until the method returns from -what it is doing. +Beginning with PowerShell 7.6, `$PSCmdlet` includes the `PipelineStopToken` +property allowing access a [CancellationToken][07] tied to the PowerShell stop +event source. The token is triggered when the PowerShell pipeline receives a +request to stop. Use it with a .NET method that accepts a `CancellationToken` +overload to exit the method when requested rather than waiting until the method +returns. -A common example is if the function is calling a .NET async compatible API. In -the below example the function is calling `HttpClient.GetStringAsync` which -could take a while to respond if the network is slow or there is a lot of data -being returned. +In the following example the function is calling `HttpClient.GetStringAsync` +that can take a while to respond when the network is slow or there is a lot of +data being returned. ```powershell -Function Invoke-WebGetRequest { +function Invoke-CancelableWebRequest { [CmdletBinding()] param( [Parameter(Mandatory=$true)] @@ -99,7 +97,7 @@ Function Invoke-WebGetRequest { $PSCmdlet.PipelineStopToken).GetAwaiter().GetResult() } -Invoke-WebGetRequest -Url https://httpbin.org/delay/10 +Invoke-CancelableWebRequest -Url https://httpbin.org/delay/10 # Press ctrl+c to cancel ``` From 3ba124832aef7644c10d72078b394ddc63b4a4fd Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 25 Mar 2025 10:20:10 -0500 Subject: [PATCH 3/3] Update PipelineStopToken description and example --- .../About/about_Functions_Advanced.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md index 4bcdaa98d33d..04469813e547 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md @@ -71,15 +71,15 @@ Advanced functions differ from compiled cmdlets in the following ways: ## PipelineStopToken -Beginning with PowerShell 7.6, `$PSCmdlet` includes the `PipelineStopToken` -property allowing access a [CancellationToken][07] tied to the PowerShell stop -event source. The token is triggered when the PowerShell pipeline receives a -request to stop. Use it with a .NET method that accepts a `CancellationToken` -overload to exit the method when requested rather than waiting until the method -returns. - -In the following example the function is calling `HttpClient.GetStringAsync` -that can take a while to respond when the network is slow or there is a lot of +Beginning with PowerShell 7.6-preview.4, `$PSCmdlet` includes the +`PipelineStopToken` property allowing access a [CancellationToken][07] tied to +the PowerShell stop event source. The token is triggered when the PowerShell +pipeline receives a request to stop. Use it with a .NET method that accepts a +`CancellationToken` overload to exit the method when requested rather than +waiting until the method returns. + +In the following example, the function is calling `HttpClient.GetStringAsync`, +which can take time to respond when the network is slow or there is a lot of data being returned. ```powershell