Skip to content

Add PipelineStoppedException notes to PowerShell API #15324

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adityapatwardhan merged 4 commits into from
Jun 3, 2021
Merged

Add PipelineStoppedException notes to PowerShell API #15324

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9e8eef2
Add PipelineStoppedException notes to PowerShell API
rjmholt Apr 29, 2021
4a4077d
Add comments to Stop()
rjmholt Apr 29, 2021
4aaba4e
Update src/System.Management.Automation/engine/hostifaces/PowerShell.cs
rjmholt Apr 30, 2021
e2625fb
Apply suggestions from code review
rjmholt May 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions src/System.Management.Automation/engine/hostifaces/PowerShell.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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"/> 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>
public PSDataCollection<PSObject> EndInvoke(IAsyncResult asyncResult)
{
try
Expand Down Expand Up @@ -3706,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
Expand Down Expand Up @@ -3762,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)
Expand Down Expand Up @@ -3812,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);

Expand Down