From 9e8eef2bd691d4d0481f848cf548e19a42401759 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Thu, 29 Apr 2021 14:03:16 -0700
Subject: [PATCH 1/4] Add PipelineStoppedException notes to PowerShell API

---
 .../engine/hostifaces/PowerShell.cs           | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/src/System.Management.Automation/engine/hostifaces/PowerShell.cs b/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
index 3829634c8c8..503f6a4b8f7 100644
--- a/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
+++ b/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
@@ -3079,6 +3079,10 @@ public IAsyncResult BeginInvoke<TInput, TOutput>(PSDataCollection<TInput> input,
         /// <exception cref="ObjectDisposedException">
         /// Object is disposed.
         /// </exception>
+        /// <exception cref="System.Management.Automation.PipelineStoppedException">
+        /// The running PowerShell pipeline was stopped.
+        /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
+        /// </exception>
         public Task<PSDataCollection<PSObject>> InvokeAsync()
             => Task<PSDataCollection<PSObject>>.Factory.FromAsync(BeginInvoke(), _endInvokeMethod);
 
@@ -3120,6 +3124,10 @@ public Task<PSDataCollection<PSObject>> InvokeAsync()
         /// <exception cref="ObjectDisposedException">
         /// Object is disposed.
         /// </exception>
+        /// <exception cref="System.Management.Automation.PipelineStoppedException">
+        /// The running PowerShell pipeline was stopped.
+        /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
+        /// </exception>
         public Task<PSDataCollection<PSObject>> InvokeAsync<T>(PSDataCollection<T> input)
             => Task<PSDataCollection<PSObject>>.Factory.FromAsync(BeginInvoke<T>(input), _endInvokeMethod);
 
@@ -3174,6 +3182,10 @@ public Task<PSDataCollection<PSObject>> InvokeAsync<T>(PSDataCollection<T> input
         /// <exception cref="ObjectDisposedException">
         /// Object is disposed.
         /// </exception>
+        /// <exception cref="System.Management.Automation.PipelineStoppedException">
+        /// The running PowerShell pipeline was stopped.
+        /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
+        /// </exception>
         public Task<PSDataCollection<PSObject>> InvokeAsync<T>(PSDataCollection<T> input, PSInvocationSettings settings, AsyncCallback callback, object state)
             => Task<PSDataCollection<PSObject>>.Factory.FromAsync(BeginInvoke<T>(input, settings, callback, state), _endInvokeMethod);
 
@@ -3222,6 +3234,14 @@ public Task<PSDataCollection<PSObject>> InvokeAsync<T>(PSDataCollection<T> input
         /// <exception cref="ObjectDisposedException">
         /// Object is disposed.
         /// </exception>
+        /// <exception cref="System.Management.Automation.PipelineStoppedException">
+        /// The running PowerShell pipeline was stopped.
+        /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
+        /// To collect partial output in this scenario,
+        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}"> for the <paramref name="output"/> parameter,
+        /// and either add a handler for the <see cref="System.Management.Automation.PSDataCollection{T}.DataAdding"/> event
+        /// or catch the exception and enumerate the object supplied for <paramref name="output"/>.
+        /// </exception>
         public Task<PSDataCollection<PSObject>> InvokeAsync<TInput, TOutput>(PSDataCollection<TInput> input, PSDataCollection<TOutput> output)
             => Task<PSDataCollection<PSObject>>.Factory.FromAsync(BeginInvoke<TInput, TOutput>(input, output), _endInvokeMethod);
 
@@ -3284,6 +3304,14 @@ public Task<PSDataCollection<PSObject>> InvokeAsync<TInput, TOutput>(PSDataColle
         /// <exception cref="ObjectDisposedException">
         /// Object is disposed.
         /// </exception>
+        /// <exception cref="System.Management.Automation.PipelineStoppedException">
+        /// The running PowerShell pipeline was stopped.
+        /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
+        /// To collect partial output in this scenario,
+        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}"> for the <paramref name="output"/> parameter,
+        /// and either add a handler for the <see cref="System.Management.Automation.PSDataCollection{T}.DataAdding"/> event
+        /// or catch the exception and use object supplied for <paramref name="output"/>.
+        /// </exception>
         public Task<PSDataCollection<PSObject>> InvokeAsync<TInput, TOutput>(PSDataCollection<TInput> input, PSDataCollection<TOutput> output, PSInvocationSettings settings, AsyncCallback callback, object state)
             => Task<PSDataCollection<PSObject>>.Factory.FromAsync(BeginInvoke<TInput, TOutput>(input, output, settings, callback, state), _endInvokeMethod);
 
@@ -3655,6 +3683,14 @@ private void AppendExceptionToErrorStream(Exception e)
         /// asyncResult object was not created by calling BeginInvoke
         /// on this PowerShell instance.
         /// </exception>
+        /// <exception cref="System.Management.Automation.PipelineStoppedException">
+        /// The running PowerShell pipeline was stopped.
+        /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
+        /// To collect partial output in this scenario,
+        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}"> to <see cref="PowerShell.BeginInvoke"/>
+        /// and either add a handler for the <see cref="System.Management.Automation.PSDataCollection{T}.DataAdding"/> event
+        /// or catch the exception and enumerate the object supplied.
+        /// </exception>
         public PSDataCollection<PSObject> EndInvoke(IAsyncResult asyncResult)
         {
             try

From 4a4077dc9d8bbbbdbc72373826b98bdd338ba541 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Thu, 29 Apr 2021 16:20:25 -0700
Subject: [PATCH 2/4] Add comments to Stop()

---
 .../engine/hostifaces/PowerShell.cs                  | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/System.Management.Automation/engine/hostifaces/PowerShell.cs b/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
index 503f6a4b8f7..60f8e18adf0 100644
--- a/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
+++ b/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
@@ -3742,6 +3742,10 @@ public PSDataCollection<PSObject> EndInvoke(IAsyncResult asyncResult)
         /// <exception cref="ObjectDisposedException">
         /// Object is disposed.
         /// </exception>
+        /// <remarks>
+        /// When used with <see cref="PowerShell.Invoke()"/>, that call will return a partial result.
+        /// When used with <see cref="PowerShell.InvokeAsync"/>, that call will throw a <see cref="System.Management.Automation.PipelineStoppedException"/>. 
+        /// </remarks>
         public void Stop()
         {
             try
@@ -3798,6 +3802,10 @@ public IAsyncResult BeginStop(AsyncCallback callback, object state)
         /// asyncResult object was not created by calling BeginStop
         /// on this PowerShell instance.
         /// </exception>
+        /// <remarks>
+        /// When used with <see cref="PowerShell.Invoke()"/>, that call will return a partial result.
+        /// When used with <see cref="PowerShell.InvokeAsync"/>, that call will throw a <see cref="System.Management.Automation.PipelineStoppedException"/>. 
+        /// </remarks>
         public void EndStop(IAsyncResult asyncResult)
         {
             if (asyncResult == null)
@@ -3848,6 +3856,10 @@ public void EndStop(IAsyncResult asyncResult)
         /// <exception cref="ObjectDisposedException">
         /// Object is disposed.
         /// </exception>
+        /// <remarks>
+        /// When used with <see cref="PowerShell.Invoke()"/>, that call will return a partial result.
+        /// When used with <see cref="PowerShell.InvokeAsync"/>, that call will throw a <see cref="System.Management.Automation.PipelineStoppedException"/>. 
+        /// </remarks>
         public Task StopAsync(AsyncCallback callback, object state)
             => Task.Factory.FromAsync(BeginStop(callback, state), _endStopMethod);
 

From 4aaba4e5b67c8d84a75560d7d505bbf568f15c0d Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt@gmail.com>
Date: Fri, 30 Apr 2021 05:56:03 -0700
Subject: [PATCH 3/4] Update
 src/System.Management.Automation/engine/hostifaces/PowerShell.cs

Co-authored-by: Dongbo Wang <dongbow@microsoft.com>
---
 .../engine/hostifaces/PowerShell.cs                             | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/System.Management.Automation/engine/hostifaces/PowerShell.cs b/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
index 60f8e18adf0..7cf79583edc 100644
--- a/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
+++ b/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
@@ -3687,7 +3687,7 @@ private void AppendExceptionToErrorStream(Exception e)
         /// The running PowerShell pipeline was stopped.
         /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
         /// To collect partial output in this scenario,
-        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}"> to <see cref="PowerShell.BeginInvoke"/>
+        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}"> to <see cref="PowerShell.BeginInvoke"/> for the <paramref name="output"/> parameter
         /// and either add a handler for the <see cref="System.Management.Automation.PSDataCollection{T}.DataAdding"/> event
         /// or catch the exception and enumerate the object supplied.
         /// </exception>

From e2625fb346ed1f21a04cd4e009c39ac2f4fcc7fd Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt@gmail.com>
Date: Wed, 5 May 2021 15:17:34 -0700
Subject: [PATCH 4/4] Apply suggestions from code review

Co-authored-by: Aditya Patwardhan <adityap@microsoft.com>
---
 .../engine/hostifaces/PowerShell.cs                         | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/System.Management.Automation/engine/hostifaces/PowerShell.cs b/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
index 7cf79583edc..850d3e1116e 100644
--- a/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
+++ b/src/System.Management.Automation/engine/hostifaces/PowerShell.cs
@@ -3238,7 +3238,7 @@ public Task<PSDataCollection<PSObject>> InvokeAsync<T>(PSDataCollection<T> input
         /// The running PowerShell pipeline was stopped.
         /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
         /// To collect partial output in this scenario,
-        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}"> for the <paramref name="output"/> parameter,
+        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}" /> for the <paramref name="output"/> parameter,
         /// and either add a handler for the <see cref="System.Management.Automation.PSDataCollection{T}.DataAdding"/> event
         /// or catch the exception and enumerate the object supplied for <paramref name="output"/>.
         /// </exception>
@@ -3308,7 +3308,7 @@ public Task<PSDataCollection<PSObject>> InvokeAsync<TInput, TOutput>(PSDataColle
         /// The running PowerShell pipeline was stopped.
         /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
         /// To collect partial output in this scenario,
-        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}"> for the <paramref name="output"/> parameter,
+        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}" /> for the <paramref name="output"/> parameter,
         /// and either add a handler for the <see cref="System.Management.Automation.PSDataCollection{T}.DataAdding"/> event
         /// or catch the exception and use object supplied for <paramref name="output"/>.
         /// </exception>
@@ -3687,7 +3687,7 @@ private void AppendExceptionToErrorStream(Exception e)
         /// The running PowerShell pipeline was stopped.
         /// This occurs when <see cref="PowerShell.Stop"/> or <see cref="PowerShell.StopAsync(AsyncCallback, object)"/> is called.
         /// To collect partial output in this scenario,
-        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}"> to <see cref="PowerShell.BeginInvoke"/> for the <paramref name="output"/> parameter
+        /// supply a <see cref="System.Management.Automation.PSDataCollection{T}" /> to <see cref="PowerShell.BeginInvoke"/> for the <paramref name="output"/> parameter
         /// and either add a handler for the <see cref="System.Management.Automation.PSDataCollection{T}.DataAdding"/> event
         /// or catch the exception and enumerate the object supplied.
         /// </exception>