PowerShell Class

Definition

Namespace:

System.Management.Automation

Assembly:

System.Management.Automation.dll

Package:

System.Management.Automation v7.4.0

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().AddScript("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 ref class PowerShell sealed : IDisposable

public sealed class PowerShell : IDisposable

type PowerShell = class
    interface IDisposable

Public NotInheritable Class PowerShell
Implements IDisposable

Inheritance

Object

PowerShell

Implements

IDisposable

Properties

Commands	Gets or sets current powershell command line.
HadErrors	If an error occurred while executing the pipeline, this will be set to true.
HistoryString	The history string to be used for displaying the history.
InstanceId	Get unique id for this instance of runspace pool. It is primarily used for logging purposes.
InvocationStateInfo	Gets the execution state of the current PowerShell instance.
IsNested	Gets the property which indicates if this PowerShell instance is nested.
IsRunspaceOwner	Indicates if this PowerShell object is the owner of the runspace or RunspacePool assigned to this object.
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	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 generated by PowerShell invocations.

Methods

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)	CommandInfo object for the command to add.
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");
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");
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");
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");
AddParameters(IDictionary)	Adds a set of parameters to the last added command.
AddParameters(IList)	Adds a set of parameters to the last added command.
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);
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);
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();
BeginInvoke()	Invoke the Command asynchronously. Use EndInvoke() to obtain the output of the command.
BeginInvoke<T>(PSDataCollection<T>, PSInvocationSettings, AsyncCallback, Object)	Invoke the Command asynchronously. Use EndInvoke() to obtain the output of the command.
BeginInvoke<T>(PSDataCollection<T>)	Invoke the Command asynchronously. Use EndInvoke() to obtain the output of the command.
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.
BeginInvoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>)	Invoke the Command asynchronously. When this method is used EndInvoke() returns a null buffer.
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()	Synchronously connects to a running command on a remote server.
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)	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()	Constructs an empty PowerShell instance; a script or command must be added before invoking this instance.
Create(InitialSessionState)	Constructs an empty PowerShell instance; a script or command must be added before invoking this instance.
Create(Runspace)	Constructs an empty PowerShell instance and associates it with the provided Runspace; a script or command must be added before invoking this instance.
Create(RunspaceMode)	Constructs an empty PowerShell instance; a script or command must be added before invoking this instance.
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 all managed resources. This will suppress finalizer on the object from getting called by calling System.GC.SuppressFinalize(this).
EndInvoke(IAsyncResult)	Waits for the pending asynchronous BeginInvoke to complete.
EndStop(IAsyncResult)	Waits for the pending asynchronous BeginStop to complete.
GetSteppablePipeline()	Get a steppable pipeline object.
Invoke()	Invoke the Command synchronously and return the output PSObject collection.
Invoke(IEnumerable, PSInvocationSettings)	Invoke the Command synchronously and return the output PSObject collection.
Invoke(IEnumerable)	Invoke the Command synchronously and return the output PSObject collection.
Invoke<T>()	Invoke the Command synchronously and return the output.
Invoke<T>(IEnumerable, IList<T>, PSInvocationSettings)	Invoke the Command synchronously and collect output data into the buffer output
Invoke<T>(IEnumerable, IList<T>)	Invoke the Command synchronously and collect output data into the buffer output
Invoke<T>(IEnumerable, PSInvocationSettings)	Invoke the Command synchronously and return the output.
Invoke<T>(IEnumerable)	Invoke the Command synchronously and return the output.
Invoke<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>, PSInvocationSettings)	Invoke the Command synchronously and stream output data into the buffer output
InvokeAsync()	Invoke a PowerShell command asynchronously. Use await to wait for the command to complete and obtain the output of the command.
InvokeAsync<T>(PSDataCollection<T>, PSInvocationSettings, AsyncCallback, Object)	Invoke a PowerShell command asynchronously. Use await to wait for the command to complete and obtain the output of the command.
InvokeAsync<T>(PSDataCollection<T>)	Invoke a PowerShell command asynchronously. Use await to wait for the command to complete and obtain the output of the command.
InvokeAsync<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>, PSInvocationSettings, AsyncCallback, Object)	Invoke a PowerShell command asynchronously and collect output data into the buffer output. Use await to wait for the command to complete and obtain the output of the command.
InvokeAsync<TInput,TOutput>(PSDataCollection<TInput>, PSDataCollection<TOutput>)	Invoke a PowerShell command asynchronously. Use await to wait for the command to complete and obtain the output of the command.
Stop()	Stop the currently running command synchronously.
StopAsync(AsyncCallback, Object)	Stop a PowerShell command asynchronously. Use await to wait for the command to stop.

Events

InvocationStateChanged

Event raised when PowerShell Execution State Changes.