1.3 Overview

Client applications use the PowerShell Remoting Protocol (PSRP) to send pipelines of commands to a server system over a network for execution by the server.

PSRP is a stateful protocol where clients establish a session with a server and use that session to send structured pipelines of abstract commands to the server for execution. PSRP imposes state to maintain an authentication context and cryptographic operations as well as give higher layers on the server a way to preserve session state associated with the commands being executed on the server across multiple pipeline executions. The state associated with commands is contained in an abstraction informally called a "runspace".

Only one pipeline can be executed in a runspace at a time. A server allows the client to execute multiple pipelines concurrently by providing a bounded pool of runspaces formally called a RunspacePool. The RunspacePool bounds are specified by the client at session initiation time.

Note that the PSRP provides no mechanism for specifying which runspace in a pool is to be used when executing a pipeline. The only addressable construct is the RunspacePool. As a consequence, scenarios where pipelines depend on the runspace containing a specific state established by previous pipelines need to use a RunspacePool size of 1.

The PSRP pipeline is similar to the UNIX concept of a pipeline with the difference that PSRP represents pipeline commands and parameters in an abstract structured way, independent of any higher-layer syntax or semantics using an XML representation. A pipeline contains an ordered sequence of commands as well as parameters and arguments associated with each command. Other than classifying pipeline elements as commands, parameters, and typed arguments, PSRP leaves all other semantic command interpretation to the higher layer responsible for actually executing the pipeline. For example, an implementation of the higher layer can translate the PSRP pipeline representation into UNIX syntax to be executed by the UNIX shell. An alternate implementation might translate the pipeline into a series of web service requests orchestrated by the server higher layers.

After the client submits a pipeline for execution, it optionally can send a sequence of input objects to the pipeline on the server. The server passes this input to the higher layer to be used as input to the first command in the pipeline. The higher layers orchestrate the execution of commands such that the output of one command in the pipeline becomes the input of the next command in an implementation-dependent way. Any objects emitted by the final command in the pipeline are sent from the server back to the client.

In addition, PSRP provides for the following capabilities:

  • A mechanism for the client to request that a pipeline currently executing on the server be stopped.

  • An "error" stream that contains error objects generated by commands in the pipeline during execution.

  • A set of messages that the server can send to the client allowing the server to request or display additional information such as progress messages, warnings, requests for confirmation of an operation, or requests for additional information. These messages are called the host methods. The client implementation can honor these messages by taking appropriate actions (displaying messages, sending the requested information). It is also acceptable for the client to ignore all display requests and fail all information requests from the server.

  • A mechanism for the client to discover the set of available commands that can be executed on the server. The information returned by this mechanism is sufficient for the client to create structurally valid pipelines. This information is not guaranteed to remain valid after it has been retrieved because the set of commands exposed by the server is allowed to change at any time.