PowerShell Class

 

Updated: April 27, 2016

Applies To: Windows PowerShell

Provides methods that are used to create a pipeline of commands and invoke those commands either synchronously or asynchronously within a runspace. This class also provides access to the output streams that contain data that is generated when the commands are invoked. This class is primarily intended for host applications that programmatically use Windows PowerShell to perform tasks. This class is introduced in Windows PowerShell 2.0.

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

System.Object
  System.Management.Automation.PowerShell

public sealed class PowerShell : IDisposable

NameDescription
System_CAPS_pubpropertyCommands

Gets or sets the commands of the pipeline invoked by the PowerShell object. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyHadErrors

Gets a value that indicates whether an error occurred while executing the pipeline. Introduced in Windows PowerShell 3.0.

System_CAPS_pubpropertyHistoryString

Gets or sets the history string to be used for displaying the history. Introduced in Windows PowerShell 3.0.

System_CAPS_pubpropertyInstanceId

Gets the global identifier for this instance of the PowerShell object. This identifier is primarily used for logging purposes. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyInvocationStateInfo

Gets information about the current state of the invocation of the pipeline, such as whether it is running, completed, or failed. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyIsNested

Gets a value that indicates whether the current PowerShell object is nested within a parent PowerShell object. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyIsRunspaceOwner

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

System_CAPS_pubpropertyRunspace

Gets or sets the runspace that is used when the pipeline is invoked. The runspace is the operating environment that defines which commands, variables, and other elements are available. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyRunspacePool

Gets or sets the runspace pool used by the PowerShell object. A runspace from this pool is used whenever the PowerShell object pipeline is invoked. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyStreams

Gets the data streams that contain any messages and error reports that were generated when the pipeline of the PowerShell object is invoked.

NameDescription
System_CAPS_pubmethodAddArgument(Object)

Adds an argument for a positional parameter of a command without specifying the parameter name. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddCommand(CommandInfo)

Adds a cmdlet to the end of the pipeline of the PowerShell object by specifying a CommandInfo object. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodAddCommand(String)

Adds a command to the end of the pipeline of the PowerShell object by specifying the command name. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddCommand(String, Boolean)

Adds a cmdlet to the end of the pipeline of the PowerShell object, and specifies whether the cmdlet should be run within a new local scope. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddParameter(String)

Adds a switch parameter to the last command added to the pipeline. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddParameter(String, Object)

Adds a parameter and value to the last command added to the pipeline. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddParameters(IDictionary)

Adds a set of parameters to the last command of the pipeline. The parameter names and values are taken from the keys and values of the dictionary. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddParameters(IList)

Adds a set of parameters to the last command of the pipeline. The parameter values are taken from the values in a list. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddScript(String)

Adds a script to the end of the pipeline of the PowerShell object. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddScript(String, Boolean)

Adds a script to the end of the pipeline of the PowerShell object, and indicates whether the script should be run in local scope. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodAddStatement()

Adds an additional statement to the end of the pipeline of the PowerShell object.

System_CAPS_pubmethodAsJobProxy()

Retrieves a Windows PowerShell job proxy, which can be used to control the invocation of the command with the -AsJob parameter (to run a cmdlet in the background). Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodBeginInvoke()

Asynchronously runs the commands of the PowerShell object pipeline. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodBeginInvoke<T>(PSDataCollection<T>)

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

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

Asynchronously runs the commands of the PowerShell object by using a specified input buffer for the first command of the pipeline, specified invocation options, and a specified callback method to use when the invocation is complete. This method is introduced in Windows PowerShell 2.0.

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

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.

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

Asynchronously runs the commands of the PowerShell object pipeline by using a specified input buffer, invocation settings, callback method, and output buffer. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodBeginStop(AsyncCallback, Object)

Asynchronously stops the currently running execution of the pipeline.

System_CAPS_pubmethodConnect()

Connects synchronously to a running command on a remote server. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodConnectAsync()

Connects asynchronously to a running command on a remote server.

System_CAPS_pubmethodConnectAsync(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.

System_CAPS_pubmethodSystem_CAPS_staticCreate()

Initializes a new instance of the PowerShell class with an empty pipeline. You must call this method to create a PowerShell object. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodSystem_CAPS_staticCreate(InitialSessionState)

Initializes a new instance of the PowerShell class with an empty pipeline and an initial session state; a script or command must be added before invoking this instance. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodSystem_CAPS_staticCreate(RunspaceMode)

Initializes a new instance of the PowerShell class with an empty pipeline and a specific runspace mode; a script or command must be added before invoking this instance. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodCreateNestedPowerShell()

Creates a nested PowerShell object within the current object.

System_CAPS_pubmethodDispose()

Releases all resources used by the PowerShell object. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodEndInvoke(IAsyncResult)

Waits for the pending asynchronous BeginInvoke call to be completed and then returns the results of the call. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodEndStop(IAsyncResult)

Waits for the pending asynchronous BeginStop call to be completed. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodEquals(Object)

(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

(Inherited from Object.)

System_CAPS_pubmethodGetType()

(Inherited from Object.)

System_CAPS_pubmethodInvoke()

Synchronously runs the commands of the PowerShell object pipeline. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodInvoke(IEnumerable)

Synchronously runs the pipeline of the PowerShell object by using the supplied input data for the first command of the pipeline. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodInvoke(IEnumerable, PSInvocationSettings)

Synchronously runs the pipeline of the PowerShell object by using the supplied input data and invocation settings. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodInvoke<T>()

Synchronously runs the pipeline of the PowerShell object. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodInvoke<T>(IEnumerable)

Synchronously runs the pipeline of the PowerShell object by using the supplied input data. This method is introduced in Windows PowerShell 2.0.

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

Synchronously starts running the commands of the PowerShell object pipeline by using the specified input buffer, and returns the results of the call to the specified output buffer. This method is introduced in Windows PowerShell 2.0.

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

Synchronously runs the pipeline of the PowerShell object by using the supplied input data and invocation settings, and returns the output of the call to a specified output buffer. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodInvoke<T>(IEnumerable, PSInvocationSettings)

Synchronously runs the pipeline of the PowerShell object by using the supplied input data and invocation settings, and returns the output of the call. This method is introduced in Windows PowerShell 2.0.

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

Invokes the Command synchronously, and streams output data into the output buffer. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodStop()

Synchronously stops the currently running execution of the pipeline. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodToString()

(Inherited from Object.)

NameDescription
System_CAPS_pubeventInvocationStateChanged

Occurs when the state of the pipeline of the PowerShell object changes. This event is introduced in Windows PowerShell 2.0.

Host applications can use the PowerShell object to run any combination of cmdlets and scripts that can be invoked at the command line. By using this object, the host application can create a pipeline, add commands and scripts to the pipeline, specify the runspace where the commands are run, and then invoke the pipeline synchronously or asynchronously. For more information about host applications, see Writing a Windows PowerShell Host Application.

For more sample code, see Host Application Samples.

The following example shows how to synchronously invoke a pipeline that contains a single command.

using System;
using System.Management.Automation;  // Windows PowerShell namespace.


namespace HostPS1
{
  class HostPS1
  {
    static void Main(string[] args)
    {

      // Call the PowerShell.Create() method to create an 
      // empty pipeline.
      PowerShell ps = PowerShell.Create();

      // Call the PowerShell.AddCommand(string) method, add 
      // the Get-Process cmdlet to the pipeline. Do 
      // not include spaces before or after the cmdlet name 
      // because that will cause the command to fail.
      ps.AddCommand("Get-Process");

      Console.WriteLine("Process                 Id");
      Console.WriteLine("----------------------------");


      // Call the PowerShell.Invoke() method to run the 
      // commands of the pipeline in the default runspace.
        foreach (PSObject result in ps.Invoke())
      {
        Console.WriteLine("{0,-24}{1}",
                result.Members["ProcessName"].Value,
                result.Members["Id"].Value);
      } // End foreach.
    } // End Main.
  } // End HostPs1.
}

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

Return to top
Show: