PowerShell PowerShell PowerShell Class

Definition

Represents a PowerShell command or script to execute against a Runspace(Pool) if provided, otherwise execute using a default Runspace. Provides access to different result buffers like output, error, debug, verbose, progress, warning, and information.

Provides a simple interface to execute a powershell command:


    Powershell.Create("get-process").Invoke();
 

The above statement creates a local runspace using default configuration, executes the command and then closes the runspace.

Using RunspacePool property, the caller can provide the runspace where the command / script is executed.

public sealed class PowerShell : IDisposable
type PowerShell = class
    interface IDisposable
Public NotInheritable Class PowerShell
Implements IDisposable
Inheritance
PowerShellPowerShellPowerShell
Implements

Properties

Commands Commands Commands

Gets or sets current powershell command line.

HadErrors HadErrors HadErrors

If an error occurred while executing the pipeline, this will be set to true.

HistoryString HistoryString HistoryString

The history string to be used for displaying the history.

InstanceId InstanceId InstanceId

Get unique id for this instance of runspace pool. It is primarily used for logging purposes.

InvocationStateInfo InvocationStateInfo InvocationStateInfo

Gets the execution state of the current PowerShell instance.

IsNested IsNested IsNested

Gets the property which indicates if this PowerShell instance is nested.

IsRunspaceOwner IsRunspaceOwner IsRunspaceOwner

Indicates if this PowerShell object is the owner of the runspace or RunspacePool assigned to this object

Runspace Runspace Runspace

Sets an associated Runspace for this PowerShell instance. This can be null in which case a new runspace is created whenever Invoke* method is called.

RunspacePool RunspacePool RunspacePool

Sets an associated RunspacePool for this PowerShell instance. A Runspace from this pool is used whenever Invoke* method is called.

This can be null in which case a new runspace is created whenever Invoke* method is called.

Streams Streams Streams

Streams generated by PowerShell invocations

Methods

AddArgument(Object) AddArgument(Object) AddArgument(Object)

Adds an argument to the last added command. For example, to construct a command string "get-process | select-object name"


         PowerShell shell = PowerShell.Create("get-process").
                                     AddCommand("select-object").AddParameter("name");
     

This will add the value "name" to the positional parameter list of "select-object" cmdlet. When the command is invoked, this value will get bound to positional parameter 0 of the "select-object" cmdlet which is "Property".

AddCommand(CommandInfo) AddCommand(CommandInfo) AddCommand(CommandInfo)

CommandInfo object for the command to add.

AddCommand(String) AddCommand(String) AddCommand(String)

Add a cmdlet to construct a command pipeline. For example, to construct a command string "get-process | sort-object",


        PowerShell shell = PowerShell.Create("get-process").AddCommand("sort-object");
    
AddCommand(String, Boolean) AddCommand(String, Boolean) AddCommand(String, Boolean)

Add a cmdlet to construct a command pipeline. For example, to construct a command string "get-process | sort-object",


        PowerShell shell = PowerShell.Create("get-process").AddCommand("sort-object");
    
AddParameter(String) AddParameter(String) AddParameter(String)

Adds a switch parameter to the last added command. For example, to construct a command string "get-process | sort-object -descending"


        PSCommand command = new PSCommand("get-process").
                                    AddCommand("sort-object").AddParameter("descending");
    
AddParameter(String, Object) AddParameter(String, Object) AddParameter(String, Object)

Add a parameter to the last added command. For example, to construct a command string "get-process | select-object -property name"


        PowerShell shell = PowerShell.Create("get-process").
                                    AddCommand("select-object").AddParameter("property","name");
    
AddParameters(IDictionary) AddParameters(IDictionary) AddParameters(IDictionary)

Adds a set of parameters to the last added command.

AddParameters(IList) AddParameters(IList) AddParameters(IList)

Adds a set of parameters to the last added command.

AddScript(String) AddScript(String) AddScript(String)

Add a piece of script to construct a command pipeline. For example, to construct a command string "get-process | foreach { $_.Name }"


        PowerShell shell = PowerShell.Create("get-process").
                                    AddCommand("foreach { $_.Name }", true);
    
AddScript(String, Boolean) AddScript(String, Boolean) AddScript(String, Boolean)

Add a piece of script to construct a command pipeline. For example, to construct a command string "get-process | foreach { $_.Name }"


        PowerShell shell = PowerShell.Create("get-process").
                                    AddCommand("foreach { $_.Name }", true);
    
AddStatement() AddStatement() AddStatement()

Adds an additional statement for execution

For example,


         Runspace rs = RunspaceFactory.CreateRunspace();
         PowerShell ps = PowerShell.Create();

         ps.Runspace = rs;
         ps.AddCommand("Get-Process").AddArgument("idle");
         ps.AddStatement().AddCommand("Get-Service").AddArgument("audiosrv");
         ps.Invoke();
     
AsJobProxy() AsJobProxy() AsJobProxy()

Returns a job object which can be used to control the invocation of the command with AsJob Parameter

BeginInvoke() BeginInvoke() BeginInvoke()

Invoke the Command asynchronously. Use EndInvoke() to obtain the output of the command.

BeginInvoke<T>(PSDataCollection<T>) BeginInvoke<T>(PSDataCollection<T>) BeginInvoke<T>(PSDataCollection<T>)

Invoke the Command asynchronously. Use EndInvoke() to obtain the output of the command.

BeginInvoke<T>(PSDataCollection<T>, PSInvocationSettings, AsyncCallback, Object) BeginInvoke<T>(PSDataCollection<T>, PSInvocationSettings, AsyncCallback, Object) BeginInvoke<T>(PSDataCollection<T>, PSInvocationSettings, AsyncCallback, Object)

Invoke the Command asynchronously. Use EndInvoke() to obtain the output of the command.

BeginInvoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>) BeginInvoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>) BeginInvoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>)

Invoke the Command asynchronously. When this method is used EndInvoke() returns a null buffer.

BeginInvoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>, PSInvocationSettings, AsyncCallback, Object) BeginInvoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>, PSInvocationSettings, AsyncCallback, Object) BeginInvoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>, PSInvocationSettings, AsyncCallback, Object)

Invoke the Command asynchronously and collect output data into the buffer output. When this method is used EndInvoke() returns a null buffer.

BeginStop(AsyncCallback, Object) BeginStop(AsyncCallback, Object) BeginStop(AsyncCallback, Object)

Stop the currently running command asynchronously. If the command is not started, the state of PowerShell instance is changed to Stopped and corresponding events will be raised.

The returned IAsyncResult object can be used to wait for the stop operation to complete.

Connect() Connect() Connect()

Synchronously connects to a running command on a remote server.

ConnectAsync() ConnectAsync() ConnectAsync()

Asynchronously connects to a running command on a remote server. The returned IAsyncResult object can be used with EndInvoke() method to wait on command and/or get command returned data.

ConnectAsync(PSDataCollection<PSObject>, AsyncCallback, Object) ConnectAsync(PSDataCollection<PSObject>, AsyncCallback, Object) ConnectAsync(PSDataCollection<PSObject>, AsyncCallback, Object)

Asynchronously connects to a running command on a remote server. The returned IAsyncResult object can be used with EndInvoke() method to wait on command and/or get command returned data.

Create(RunspaceMode) Create(RunspaceMode) Create(RunspaceMode)

Constructs an empty PowerShell instance; a script or command must be added before invoking this instance

Create(InitialSessionState) Create(InitialSessionState) Create(InitialSessionState)

Constructs an empty PowerShell instance; a script or command must be added before invoking this instance

Create() Create() Create()

Constructs an empty PowerShell instance; a script or command must be added before invoking this instance

CreateNestedPowerShell() CreateNestedPowerShell() CreateNestedPowerShell()

Creates a nested powershell within the current instance. Nested PowerShell is used to do simple operations like checking state of a variable while another command is using the runspace.

Nested PowerShell should be invoked from the same thread as the parent PowerShell invocation thread. So effectively the parent Powershell invocation thread is blocked until nested invoke() operation is complete.

Implement PSHost.EnterNestedPrompt to perform invoke() operation on the nested powershell.

Dispose() Dispose() Dispose()

Dispose all managed resources. This will suppress finalizer on the object from getting called by calling System.GC.SuppressFinalize(this).

EndInvoke(IAsyncResult) EndInvoke(IAsyncResult) EndInvoke(IAsyncResult)

Waits for the pending asynchronous BeginInvoke to complete.

EndStop(IAsyncResult) EndStop(IAsyncResult) EndStop(IAsyncResult)

Waits for the pending asynchronous BeginStop to complete.

Invoke(IEnumerable, PSInvocationSettings) Invoke(IEnumerable, PSInvocationSettings) Invoke(IEnumerable, PSInvocationSettings)

Invoke the Command synchronously and return the output PSObject collection.

Invoke(IEnumerable) Invoke(IEnumerable) Invoke(IEnumerable)

Invoke the Command synchronously and return the output PSObject collection.

Invoke() Invoke() Invoke()

Invoke the Command synchronously and return the output PSObject collection.

Invoke<T>() Invoke<T>() Invoke<T>()

Invoke the Command synchronously and return the output.

Invoke<T>(IEnumerable) Invoke<T>(IEnumerable) Invoke<T>(IEnumerable)

Invoke the Command synchronously and return the output.

Invoke<T>(IEnumerable, IList<T>) Invoke<T>(IEnumerable, IList<T>) Invoke<T>(IEnumerable, IList<T>)

Invoke the Command synchronously and collect output data into the buffer output

Invoke<T>(IEnumerable, PSInvocationSettings) Invoke<T>(IEnumerable, PSInvocationSettings) Invoke<T>(IEnumerable, PSInvocationSettings)

Invoke the Command synchronously and return the output.

Invoke<T>(IEnumerable, IList<T>, PSInvocationSettings) Invoke<T>(IEnumerable, IList<T>, PSInvocationSettings) Invoke<T>(IEnumerable, IList<T>, PSInvocationSettings)

Invoke the Command synchronously and collect output data into the buffer output

Invoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>, PSInvocationSettings) Invoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>, PSInvocationSettings) Invoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>, PSInvocationSettings)

Invoke the Command synchronously and stream output data into the buffer output

Stop() Stop() Stop()

Stop the currently running command synchronously.

Events

InvocationStateChanged InvocationStateChanged InvocationStateChanged

Event raised when PowerShell Execution State Changes.

Applies to