A runspace is the operating environment where commands are processed. These commands can be entered interactively at the command line or programmatically by a host application. From the view of the user at the command line, cmdlets such as Invoke-Command and New-PSSession create a session, which in turn has an associated runspace that is used by Windows PowerShell to process the commands entered at the command line. Notice that from the command line perspective, the user is operating within the session and is not necessarily aware of the runspace.
From the view of a host application, including the default host application powershell.exe, the runspace is created and opened by the host application and then commands are invoked within the opened runspace. When creating a runspace, host applications can specify the initial session-state of the runspace and the optional host interfaces that are used for communications.
Elements of a Runspace
Runspaces define the commands, providers, variables, functions, and other language elements that are available to the command line user or to the host application.
Constrained Runspaces
Windows PowerShell 2.0 introduces the concept of a restricted, or constrained, runspace, where the host application can explicitly restrict some of the elements that would be normally available to the user or host application.
Communications
However, even though the runspace separates the hosting application from the pipeline execution, communications between the hosting application user and the underlying pipeline execution may occur in two ways. First, the execution may return results that may be displayed by the hosting application. Second, the elements of the pipeline may communicate directly with the host through one of two optional host interfaces that can be specified when the runspace is configured.
Creating a Runspace
Runspaces are created using the RunspaceFactory class. This class provides the CreateRunspace method for defining a single runspace, and the CreateRunspacePool method (introduced by Windows PowerShell 2.0) for defining a group of runspaces.
Here is an example of how the runspace is created, opened, and then used by the PowerShell API (introduced by Windows PowerShell 2.0) to invoke the command pipeline
using System;
using System.Management.Automation; // Windows PowerShell namespace.
using System.Management.Automation.Runspaces; // Windows PowerShell namespace.
namespace HostPS4
{
class HostPS4
{
static void Main(string[] args)
{
// Call the CreateRunspace() method to create the
// runspace. This call does not specify any
// configuration information such as a custom host
// or initial session state information.
Runspace rs = RunspaceFactory.CreateRunspace();
rs.Open();
// Call the Create() method to create the PowerShell
// object, and then specify the runspace and
// create the pipeline.
PowerShell ps = PowerShell.Create();
ps.Runspace = rs;
ps.AddCommand("Get-Process").AddArgument("wmi*");
Console.WriteLine("Process Id");
Console.WriteLine("------------------------");
// Using the PowerShell object, invoke the pipeline
// synchronously.
foreach (PSObject result in ps.Invoke())
{
Console.WriteLine("{0,-20}{1}",
result.Members["ProcessName"].Value,
result.Members["Id"].Value);
} // End foreach.
} // End Main.
} // End HostPS4.
}
See Also