PowerShell.BeginInvoke Method (PSDataCollection, PSDataCollection)

Asynchronously runs the commands of the PowerShell object pipeline by using a specified input buffer for the first command of the pipeline and a specified output buffer for the results of the invocation. This method is introduced in Windows PowerShell 2.0.


Namespace: System.Management.Automation
Assembly: System.Management.Automation (in System.Management.Automation.dll)

'Usage
Dim instance As PowerShell
Dim input As PSDataCollection(Of TInput)
Dim output As PSDataCollection(Of TOutput)
Dim returnValue As IAsyncResult

returnValue = instance.BeginInvoke(input, output)

public IAsyncResult BeginInvoke<TInput,TOutput> (
	PSDataCollection<TInput> input,
	PSDataCollection<TOutput> output
)

GenericParameters

TInput

The type of the objects used as input to the first command of the pipeline.

TOutput

The type of the output objects expected from invoking the commands of the pipeline.

Parameters

input

A PSDataCollection of type parameter TInput that contains the input data for the first command of the pipeline.

output

A PSDataCollection of type parameter TOutput that contains the output of the pipeline.

Return Value

An IAsyncResult interface that represents the status of the asynchronous operation. The EndInvoke method uses this interface to determine when to return the results of the operation.

The following example asynchronously runs the Sort-Object cmdlet based on input from a supplied input buffer, returning the results to the specified output buffer.

// Use the PowerShell.Create and Powers.AddCommand 
// methods to create a command pipeline that includes the  
// Sort-Object cmdlet. Do not include spaces immediatly 
// before or after the cmdlet name as that will cause 
// the command to fail.
PowerShell ps = PowerShell.Create().AddCommand("Sort-Object");

// Create the data to be sorted by the Sort-Object cmdlet.
PSDataCollection<int> input =
      new PSDataCollection<int>();
      input.Add(5);
      input.Add(3);
      input.Add(2);
      input.Complete();

// Create the output buffer for the results.
PSDataCollection<PSObject> output =
      new PSDataCollection<PSObject>();

// Create an IAsyncResult object and call the
// BeginInvoke method to start running the 
// command pipeline asynchronously.
IAsyncResult async = 
    ps.BeginInvoke<int,PSObject>(input,output);

// Using the PowerShell.EndInvoke method, run the command
// pipeline using the default runspace.
foreach (PSObject result in output)
{
  Console.WriteLine(result);
} // End foreach.

Exception typeCondition
InvalidOperationException

Cannot perform the operation because the operation is already started, or there are no commands in the pipeline.

ObjectDisposedException

The PowerShell object is disposed.

When providing input data, the input buffer must be closed before the asynchronous invocation of the pipeline can be completed. To close the input buffer, the caller of the BeginInvoke(Generic PSDataCollection,Generic PSDataCollection) method must call the Complete method after all input is written to the buffer. If you do not call the Complete method, Windows PowerShell will continue to wait for input data and not invoke the pipeline. If you observe that the invocation is not doing anything, this might be the reason.


Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

 

Target Platforms

Windows Developer Preview, Windows Server Developer Preview

Send comments about this topic to Microsoft.
Show:
© 2014 Microsoft