Runspace Class

 

Updated: April 27, 2016

Applies To: Windows PowerShell

Represents the runspace that is the operating environment for command pipelines. This class provides methods for opening the runspace, creating single and nested pipelines for the runspace, and closing the runspace.

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

System.Object
  System.Management.Automation.Runspaces.Runspace

public abstract class Runspace : IDisposable

NameDescription
System_CAPS_pubpropertyApartmentState

Gets the apartment state of the thread used to run commands in the runspace. This property must be set before the runspace is opened.This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertySystem_CAPS_staticCanUseDefaultRunspace

Returns true if Runspace.DefaultRunspace can be used to create an instance of the PowerShell class with 'UseCurrentRunspace = true'. Introduced in Windows PowerShell 4.0.

System_CAPS_pubpropertyConnectionInfo

Gets information about the connection used to open a runspace on a computer. Typically this is a connection to a remote computer; however it can also be a connection to the local computer. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyDebugger

Gets the debugger instance for the current runspace. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertySystem_CAPS_staticDefaultRunspace

Gets and sets the default runspace used to evaluate scripts.

System_CAPS_pubpropertyDisconnectedOn

DisconnectedOn property applies to remote runspaces that have been disconnected. Introduced in Windows PowerShell 4.0.

System_CAPS_pubpropertyEvents

Gets the event manager who handles subscribing to and receiving events that are raised by Windows PowerShell. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyExpiresOn

ExpiresOn property applies to remote runspaces that have been disconnected. Introduced in Windows PowerShell 4.0.

System_CAPS_pubpropertyId

Gets the Runspace Id.

This element is introduced in Windows PowerShell 5.0.

System_CAPS_pubpropertyInitialSessionState

Gets configuration information about the session state used when the runspace is opened. The configuration information includes the different types of commands, providers, and variables that are accessible to the runspace when the runspace is opened. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyInstanceId

Gets the unique identifier for this instance of the runspace. This identifier is typically used when logging individual instances of the runspace.

System_CAPS_pubpropertyJobManager

Gets the manager of the job source adapters registered in this runspace. Introduced in Windows PowerShell 3.0.

System_CAPS_pubpropertyName

Gets and sets a friendly name for the Runspace.

This element is introduced in Windows PowerShell 5.0.

System_CAPS_pubpropertyOriginalConnectionInfo

Gets the connection information that was originally supplied by the user. Introduced in Windows PowerShell 3.0.

System_CAPS_pubpropertyRunspaceAvailability

Gets a constant that identifies whether the runspace is available or busy. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyRunspaceConfiguration

Gets and sets the configuration information that describes the capabilities of the runspace.

System_CAPS_pubpropertyRunspaceIsRemote

Describes whether the Runspace is Remote.

System_CAPS_pubpropertyRunspaceStateInfo

Gets the current state of the runspace.

System_CAPS_pubpropertySessionStateProxy

Gets access to methods that are used to get and set variables in the session state.

System_CAPS_pubpropertyThreadOptions

Gets and sets information about how threads are created and used when a command is run within the runspace. This property must be set before the runspace is opened. This property is introduced in Windows PowerShell 2.0.

System_CAPS_pubpropertyVersion

Gets the version of the assembly in which the runspace class is implemented.

NameDescription
System_CAPS_pubmethodClearBaseTransaction()

Clears the base transaction that is used by all transactions that are performed on this runspace. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodClose()

Closes the runspace and makes it unavailable for use.

System_CAPS_pubmethodCloseAsync()

Closes the runspace asynchronously, and makes it unavailable for use. This method returns control immediately, and then, in a separate thread, closes the runspace and stops all its associated pipelines.

System_CAPS_pubmethodConnect()

Synchronously connects the remote runspace to the remote server and sets the runspace state to Opened. If the object is a local runspace, a not supported exception is thrown. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodConnectAsync()

Asynchronously connects the remote runspace to the remote server and sets the runspace state to Opened. If the object is a local runspace, a not supported exception is thrown. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodCreateDisconnectedPipeline()

Creates a Pipeline object in the Disconnected state for the currently disconnected remote running command associated with this runspace. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodCreateDisconnectedPowerShell()

Creates a PowerShell object in the Disconnected state for the currently disconnected remote running command associated with this runspace. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodCreateNestedPipeline()

Creates a pipeline for the runspace while an existing pipeline is executing.

System_CAPS_pubmethodCreateNestedPipeline(String, Boolean)

Creates a pipeline for the runspace while an existing pipeline is executing. This method also specifies the commands, such as cmdlets and scripts, that can be executed by the pipeline and specifies a Boolean value that indicates that pipeline execution is added to the history of the runspace.

System_CAPS_pubmethodCreatePipeline()

Creates a pipeline for the runspace.

System_CAPS_pubmethodCreatePipeline(String)

Creates a pipeline for the runspace. This method also specifies commands, such as cmdlets and scripts, that can be executed by the pipeline.

System_CAPS_pubmethodCreatePipeline(String, Boolean)

Creates a pipeline for the runspace. This method also specifies the commands, such as cmdlets and scripts, that can be executed by the pipeline and a Boolean value that indicates that pipeline execution is added to the history of the runspace.

System_CAPS_pubmethodDisconnect()

Synchronously disconnects the remote runspace from the remote server and sets the runspace state to Disconnected. If the object is a local runspace, a not supported exception is thrown. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodDisconnectAsync()

Asynchronously disconnects the remote runspace from the remote server and sets the runspace state to Disconnected. If the object is a local runspace, a not supported exception is thrown. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodDispose()

Releases the resources used by the Runspace object.

System_CAPS_protmethodDispose(Boolean)

Disposes this instance of the runspace, and defines a Boolean value that specifies whether the call is made by the cmdlet or by the runtime.

System_CAPS_pubmethodEquals(Object)

(Inherited from Object.)

System_CAPS_protmethodFinalize()

(Inherited from Object.)

System_CAPS_pubmethodGetApplicationPrivateData()

Retrieves private application data from the server that can be used by the runspace. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodGetCapabilities()

Retrieves the capabilities of this runspace.

System_CAPS_pubmethodGetHashCode()

(Inherited from Object.)

System_CAPS_pubmethodSystem_CAPS_staticGetRunspace(RunspaceConnectionInfo, Guid, Nullable<Guid>, PSHost, TypeTable)

Returns a single disconnected Runspace object targeted to the remote computer and remote session as specified by the connection, session Id, and command Id parameters.

This element is introduced in Windows PowerShell 5.0.

System_CAPS_pubmethodSystem_CAPS_staticGetRunspaces(RunspaceConnectionInfo)

Queries the server for disconnected runspaces, using connection information, and creates an array of runspace objects associated with each disconnected runspace on the server. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodSystem_CAPS_staticGetRunspaces(RunspaceConnectionInfo, PSHost)

Queries the server for disconnected runspaces, using connection information and the client host, and creates an array of runspace objects associated with each disconnected runspace on the server. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodSystem_CAPS_staticGetRunspaces(RunspaceConnectionInfo, PSHost, TypeTable)

Queries the server for disconnected runspaces, using connection information, the client host, and the type table, and creates an array of runspace objects associated with each disconnected runspace on the server. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodGetType()

(Inherited from Object.)

System_CAPS_protmethodMemberwiseClone()

(Inherited from Object.)

System_CAPS_protmethodOnAvailabilityChanged(RunspaceAvailabilityEventArgs)

Raises the AvailabilityChanged event when the state of the currently invoked pipeline changes. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodOpen()

Opens the runspace synchronously, creating a Windows PowerShell execution environment.

System_CAPS_pubmethodOpenAsync()

Opens the runspace asynchronously, creating a Windows PowerShell execution environment. This method returns control immediately, and then, in a separate thread, opens the runspace.

System_CAPS_pubmethodResetRunspaceState()

Resets the variable table for the runspace to the default state. Introduced in Windows PowerShell 3.0.

System_CAPS_pubmethodSetBaseTransaction(CommittableTransaction)

Sets the base transaction that is used by all transactions performed on this runspace. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodSetBaseTransaction(CommittableTransaction, RollbackSeverity)

Sets the base transaction that is used by all transactions performed on this runspace and specifies the error condition that will cause the transaction to be automatically rolled back. This method is introduced in Windows PowerShell 2.0.

System_CAPS_pubmethodToString()

(Inherited from Object.)

System_CAPS_protmethodUpdateRunspaceAvailability(RunspaceState, Boolean)

Raises the AvailabilityChanged event when the state of the currently invoked pipeline changes to the specified state. This method is introduced in Windows PowerShell 2.0.

NameDescription
System_CAPS_pubeventAvailabilityChanged

Occurs when the availability of the runspace changes, such as when the runspace becomes available and when it is busy. This event is introduced in Windows PowerShell 2.0.

System_CAPS_pubeventStateChanged

Occurs when the state of the runspace changes.

For more information about runspaces and runspace pools, see Writing a Windows PowerShell Host Application.

System_CAPS_noteNote

The user at the command line may not necessarily realize that the commands that Windows PowerShell runs are being processed within a runspace. From the command-line user’s point of view, commands are run in a Windows PowerShell session. From a host application’s point of view, commands are run within a runspace.

After a runspace is opened, Windows PowerShell host applications can run startup scripts that include the profiles and initialization scripts in the runspace configuration. For more information about runspace configuration, see the RunspaceConfiguration class.

The runspace does not provide output. Data is returned to the host application through the pipelines executing within the runspace. For more information about pipeline output, see the Pipeline class.

It is permitted to derive from this class. However, there is no established scenario for doing this, nor has deriving from this class been tested.

The following code example, pulled from the ps_runspace10 sample in the Windows SDK, uses a RunspaceFactory to create a runspace.

private static void Main(string[] args)    
{
      InitialSessionState iss = InitialSessionState.CreateDefault();
      SessionStateCmdletEntry ssce = new SessionStateCmdletEntry("get-proc", typeof(GetProcCommand), null);
      iss.Commands.Add(ssce);
      using (Runspace myRunSpace = RunspaceFactory.CreateRunspace(iss))
      {
          myRunSpace.Open();
        		using (PowerShell powershell = PowerShell.Create())
           {
              powershell.Runspace = myRunSpace;
              powershell.AddCommand("get-proc");
             Collection<PSObject> results = powershell.Invoke();
             Console.WriteLine("Process              HandleCount");
             Console.WriteLine("--------------------------------");
             foreach (PSObject result in results)
             {
                Console.WriteLine(
                               "{0,-20} {1}",
                               result.Members["ProcessName"].Value,
                               result.Members["HandleCount"].Value);
             }
           }
         myRunSpace.Close();
      }
      System.Console.WriteLine("Hit any key to exit...");
      System.Console.ReadKey();
}

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

Community Additions

ADD
Show: