Remoting & Runspaces
Relevant source files
The following files were used as context for generating this wiki page:
- src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs
- src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs
- src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs
- test/powershell/Modules/Microsoft.PowerShell.Utility/Implicit.Remoting.Tests.ps1
- test/powershell/engine/Api/BasicEngine.Tests.ps1
- src/System.Management.Automation/cimSupport/cmdletization/ScriptWriter.cs
PowerShell remoting provides a robust framework for executing commands on remote computers and managing remote resources as if they were local. This system is built upon the concept of Runspaces, which are isolated environments where PowerShell code executes, and the PowerShell Remoting Protocol (PSRP), which facilitates communication between client and server endpoints. Sources: src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs:122-132, src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:51-60
The infrastructure supports various connection types, including WS-Management (WSMan), Hyper-V sockets (VMConnection), and Container-based sessions. By utilizing Runspace Pools and serialized data exchange, PowerShell enables complex scenarios such as implicit remoting, where remote commands are exported as local proxy functions to provide a seamless user experience. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:830-845, src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs:405-415
Implicit Remoting Architecture
Implicit remoting allows users to import a session from a remote computer into their local session. This process creates proxy functions that wrap the Invoke-Command cmdlet, targeting the remote runspace. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:1150-1170
Proxy Module Generation
When a session is exported via Export-PSSession or imported via Import-PSSession, the system generates a temporary or permanent module containing proxy functions. These functions include metadata that maps local parameters to remote command arguments. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:1250-1270
The diagram above illustrates the workflow of generating a proxy module to represent remote commands locally. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:130-150, src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:1150-1165
Core Components of Proxy Modules
| Component | Purpose |
|---|---|
| Header | Checks script generator version and initializes cmdlet references. |
| Helper Functions | Manages session state, options, and parameter modification. |
| Command Proxies | Script blocks that serialize arguments and call the remote endpoint. |
| Cleanup Script | Unregisters events and removes temporary files when the session closes. |
Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:910-950, src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:1150-1180
Runspace Management
A Runspace is the operating environment for a PowerShell pipeline. In remoting, the lifecycle of a runspace is managed by the client to ensure connectivity and resource availability. Sources: test/powershell/engine/Api/BasicEngine.Tests.ps1:34-45
Connection Types
The system supports multiple RunspaceConnectionInfo implementations:
- WSManConnectionInfo: Uses standard WS-Management protocols for network-based remoting.
- VMConnectionInfo: Uses Hyper-V VMBus for host-to-guest communication.
- ContainerConnectionInfo: Specifically for Windows and Linux container remoting.
Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:830-848
Runspace State Transitions
Runspaces transition through states such as BeforeOpen, Opened, Disconnected, and Closed. Implicit remoting specifically handles Disconnected states by attempting to reconnect before creating a new session. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:1005-1020, src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs:1280-1285
The state machine for a remote runspace ensures that resources are properly cleaned up upon termination or failure. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:1000-1030, src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs:405-410
Wire Data Format & Serialization
PowerShell Remoting Protocol (PSRP) uses a specific wire format to exchange data between the client and server. This involves serializing complex objects into a format that can be transmitted over transports like HTTP or Named Pipes. Sources: src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs:122-132
Remoting Data Objects
The RemoteDataObject class encapsulates the payload, destination, and data type. Key data types include:
- SessionCapability: Exchange of protocol and serialization versions.
- CreateRunspacePool: Instructions to initialize a pool of runspaces.
- PowerShellInput/Output: Streams of objects for execution.
- RemoteHostCall: Requests for the client host to perform UI actions (e.g.,
Read-Host).
Sources: src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs:175-215
Sequence of a Remote Call
The following sequence diagram shows the interaction between the client ClientRemotePowerShell and the server-side host during a command execution. Sources: src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs:640-670
Security & Constraints
Remoting involves strict security checks, especially when dealing with script execution and module loading.
Language Modes and Lockdown
The system enforces ConstrainedLanguage mode in locked-down environments. Script modules must match the language mode of the manifest that loaded them to prevent security bypasses. Sources: src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs:610-630
Signature Verification
Implicit remoting modules can be signed using certificates. If the system's ExecutionPolicy is set to AllSigned, the Export-PSSession cmdlet will fail if a valid certificate is not provided for the generated .psm1 and .format.ps1xml files. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:1260-1285, test/powershell/Modules/Microsoft.PowerShell.Utility/Implicit.Remoting.Tests.ps1:60-75
Summary
The Remoting and Runspace infrastructure in PowerShell provides the necessary isolation and communication channels for distributed task execution. Through the use of RemoteDataObject for structured communication and proxy modules for user-facing integration, PowerShell masks the complexity of remote execution. Robust state management and security policy enforcement ensure that these remote operations remain stable and secure across diverse environments. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ImplicitRemotingCommands.cs:20-40, src/System.Management.Automation/engine/remoting/common/WireDataFormat/EncodeAndDecode.cs:122-140