1/29/2010 9.0 Major Updated and revised the technical content. 3/12/2010 9.0.1 Editorial Changed language and formatting in the technical content. 4/23/2010 9.0.2 Editorial Changed language and formatting in the technical content. 6/4/2010 9.1 Minor Clarified the meaning of the technical content. 7/16/2010 9.1 None No changes to the meaning, language, or formatting of the technical content. 8/27/2010 9.1 None No changes to the meaning, language, or formatting of the technical content. 10/8/2010 9.1 None No changes to the meaning, language, or formatting of the technical content. 11/19/2010 9.1 None No changes to the meaning, language,
or formatting of the technical content. 1/7/2011 9.1 None No changes to the meaning, language, or formatting of the technical content. 2/11/2011 9.1 None No changes to the meaning, language, or formatting of the technical content. 3/25/2011 9.1 None No changes to the meaning, language, or formatting of the technical content. 5/6/2011 9.1 None No changes to the meaning, language, or formatting of the technical content. 6/17/2011 9.2 Minor Clarified the meaning of the technical content. 9/23/2011 10.0 Major Updated and revised the technical content. 12/16/2011 11.0 Major Updated and revised the
technical content. 3/30/2012 11.1 Minor Clarified the meaning of the technical content. 7/12/2012 11.1 None No changes to the meaning, language, or formatting of the technical content. 10/25/2012 12.0 Major Updated and revised the technical content. 1/31/2013 12.0 None No changes to the meaning, language, or formatting of the technical content. 8/8/2013 13.0 Updated and revised the technical content. 11/14/2013 13.0 None No changes to the meaning, language, or formatting of the technical content. 2/13/2014 14.0 Major Updated and revised the technical content. 5/15/2014 14.0 None No changes to the meaning, language, or
formatting of the technical content. 6/30/2015 15.0 Major Significantly changed the technical content. 10/16/2015 15.0 None No changes to the meaning, language, or formatting of the technical content. 7/14/2016 16.0 Major Significantly changed the technical content. 6/1/2017 16.0 None No changes to the meaning, language, or formatting of the technical content. 9/15/2017 17.0 Major Significantly changed the technical content. 12/1/2017 17.0 None No changes to the meaning, language, or formatting of the technical content.
Target: RunspacePool. GET_AVAILABLE_RUNSPACES 0x00021007 Get the number of available runspaces in a RunspacePool. Direction: Client to server. Target: RunspacePool. USER_EVENT 0x00021008 Report a user-defined from a remote runspace. Direction: Server to client. Target: RunspacePool. APPLICATION_PRIVATE_DATA 0x00021009 Application private data: data private to the application using the PowerShell Remoting Protocol on the server and client, which is passed by the protocol without interpretation. Direction: Server to client. Target: RunspacePool. GET_COMMAND_METADATA 0x0002100A Get metadata for commands available in a RunspacePool. Direction: Client to server. Target: RunspacePool. RUNSPACEPOOL_HOST_CALL 0x00021100 Method call on the associated with the RunspacePool on the server. Direction: Server to client. Target: RunspacePool. RUNSPACEPOOL_HOST_RESPONSE 0x00021101 Response from a host call executed on the client RunspacePool's host. Direction: Client to server. Target: RunspacePool. PIPELINE_INPUT 0x00041002 Input to a command pipeline on the server. Direction: Client to server. Target: . END_OF_PIPELINE_INPUT 0x00041003 Close the input collection for the command pipeline on the server. Direction: Client to server. Target: pipeline. PIPELINE_OUTPUT 0x00041004 Output of a command pipeline on the server. Direction: Server to client. Target: pipeline. ERROR_RECORD 0x00041005 Error record from a command pipeline on the server. Direction: Server to client. Target: pipeline. PIPELINE_STATE 0x00041006 State information of a command pipeline on the server. Direction: Server to client. Target: pipeline or RunspacePool. DEBUG_RECORD 0x00041007 Debug record from a command pipeline on the server. Direction: Server to client. Target: pipeline. VERBOSE_RECORD 0x00041008 Verbose record from a command pipeline on the server. Direction: Server to client.
ErrorCategory This data type represents a category of an error. This data type is a signed Int (section ), which can have the following values: Value Meaning 0 NotSpecified The error category is unspecified. 1 OpenError The error occurred while trying to perform an open. 2 CloseError The error occurred while trying to perform a close. 3 DeviceError The error originated with the device. 4 DeadlockDetected A deadlock was detected. 5 InvalidArgument An argument was invalid. 6 InvalidData The data was invalid. 7 InvalidOperation An operation was invalid. 8 InvalidResult A result was invalid. 9 InvalidType A type was invalid. 10 MetadataError There is an error with the metadata. 11 NotImplemented The operation is not implemented. 12 NotInstalled The specified resource was not installed. 13 ObjectNotFound The object was not found. 14 OperationStopped The operation was stopped. 15 OperationTimeout The operation timed out. 16 SyntaxError There was an error with the syntax.
types and options. PromptForChoice 26 Signed int (section 2.2.5.1.11 SHOULD display a list of choices to the user and MUST return the of the selected option. Host RawUI Read/Write Properties Name of method/property Method identifier Return value Method details GetForegroundColor 27 Color (section ) SHOULD return the foreground color of the hosting application. SetForegroundColor 28 None. SHOULD set the foreground color of the hosting application. GetBackgroundColor 29 Color (section 2.2.3.3) SHOULD return the background color of the hosting application. SetBackgroundColor 30 None. SHOULD set the background of the hosting application. GetCursorPosition 31 Coordinates (section ) SHOULD return the current cursor position in the hosting application. SetCursorPosition 32 None. SHOULD set the current cursor position in the hosting application.
return an of buffer cells. ScrollBufferContents 51 None. SHOULD scroll a region on the screen buffer. IHostSupportsInteractiveSession Methods Name of method/property Method identifier Return Method details PushRunspace 52 None. SHOULD store the current working runspace in a stack and replace it with the new specified runspace. PopRunspace 53 None. SHOULD retrieve the last stored runspace from the stack and make it the current active runspace. IHostSupportsInteractiveSession Read Only Properties Name of method/property Method identifier Return value Method details GetIsRunspacePushed 54 Boolean (section 2.2.5.1.3) SHOULD validate if is a runspace currently pushed on a stack in the host, returning true if so and false otherwise.
For details about how a pipeline state transitions from NotStarted to Running, see section . The server can change the pipeline state from Running to Failed at any time if it determines that there is something wrong with the pipeline (such as a network connection getting lost, a corrupted RunspacePool is in bad state, or a pipeline failed while executing). After changing the pipeline state to Failed, the server MUST send a PIPELINE_STATE message (section ) with a Failed state to the client. When the pipeline state is changed to Completed, Stopped, or Failed, the server MUST NOT send any PSRP messages to the client targeted to that particular pipeline. Figure 5: Server pipeline states and transitions Defragmentation Data The current state of (see sections and for PSRP messages (section ) sent by the PSRP server and targeted at the . Server-side defragmentation data for a pipeline includes exactly the same type information as defragmentation data (section ). Queue of Outgoing Messages The server MUST maintain a first in, first out (FIFO) queue of messages (see section ) ready to be sent to the particular on the client. The element at the beginning of the queue can be a whole message or a suffix of a message (when the prefix has already been fragmented and sent to the client); all other elements of the queue are whole messages. See section for details on how the queue is used. The queue is initialized to be empty. HostInfo The server MUST store the HostInfo received in the CREATE_PIPELINE message (see section ) and make it available to commands executed in pipelines that use a separate host associated with a pipeline, instead of using a host associated with a RunspacePool. Host CI Table The server MUST maintain a table associating an integer identifier with outstanding PIPELINE_HOST_CALL message (section ) originating from the higher layer. The table is used to map the server requests to corresponding client responses by the "c" property of PIPELINE_HOST_RESPONSE messages (see section ). Runspace Data Runspace State A runspace in a RunspacePool can be in any of the following states: available: to run new pipelines. busy: already running a pipeline. Runspace state is initialized to "available" in newly created runspaces. Currently Running Pipeline
Step Client Direction Server 1 The is in the Opened state on the client (section ). The client constructs a CREATE_PIPELINE message (section ). The client fragments the message into multiple fragments as needed (section ). The client initializes the pipeline state (section ) to Running. The client sends the first fragment to the server using a wxf:Command message (section ). > The server extracts the PID from the message (section ) and stores this value as the pipeline's (section ). The server initializes the pipeline state (section ) to NotStarted. The server processes and validates the message. 2 < The server sends a success message (section ) if validation is successful. 3 If the pipeline message is fragmented into multiple fragments, the rest of the fragments (starting from second fragment) are sent individually using a wxf:Send message (section ). > < The server collects all the fragments until the end fragment (section 2.2.4) is received. For each wxf:Send message received from the client, the server sends a wxf:SendResponse message (see section ) to the client. The server processes all the fragments and understands the pipeline to execute. If a in the RunspacePool is available (section ), the RunspacePool assigns the runspace to the pipeline for execution. 4 < The server changes the pipeline state (section 3.2.1.3.2) to Running. Note this state change information is not sent to the client.
using a wxf:Send message (section ) targeted to the RunspacePool. The client starts Session Key Transfer timer (section ). The server generates a Session Key (section ), if not already generated. 3 The client a wxf:Receive message (see section ) to the server, if none is pending for this RunspacePool. > 4 < For each wxf:Send message received from the client, the server sends a wxf:SendResponse message (see section ) to the client. 5 The client processes the ENCRYPTED_SESSION_KEY message (section 2.2.2.4), cancels the Session Key Transfer timer (section ) and stores the Session Key (section ) for future use. < The server constructs an Encrypted Session Key (section 2.2.2.4) and sends it to the client using wxf:ReceiveResponse (section ). 6 From this point on, the client uses the stored Session Key (section 3.1.1.2.7) for sending secure data (section ) to the server. From this on, the server uses the Session Key (section 3.1.1.2.7) for sending secure data (section 2.2.5.1.24) to the client. Server-Initiated Transfer of Session Key The PowerShell Remoting Protocol allows the client and the server to exchange a session key (section ). The typical PSRP sequence for transferring a session key (section 2.2.2.4) from the server to the client, when the server initiates the transfer, is described in the following table: Step Client Direction Server 1 The is in the Opened state on the client. The RunspacePool is in the Opened state on the server (section ). The Public Key (section ) is empty. 2 The client a wxf:Receive message (section ) to the server, if none is pending for this RunspacePool. >
3 < The server constructs a PUBLIC_KEY_REQUEST message (section ) and it to the client using wxf:ReceiveResponse (section ). 4 The client constructs a PUBLIC_KEY message (section ) and it using wxf:Send message (section ) targeted to the RunspacePool. The client starts Session Key Transfer timer (section ). > The server stores the Public Key (section 3.2.1.2.8). The server generates a Session Key (section ), if not already generated. 5 The client a wxf:Receive message (section 3.1.5.3.7) to the server, if none is pending for this RunspacePool. > 6 < For each wxf:Send message received from the client, the server sends a wxf:SendResponse message (see section ) to the client. 7 The client processes the ENCRYPTED_SESSION_KEY message (section 2.2.2.4), cancels the Session Key Transfer timer (section 3.1.2) and stores the Session Key (section ) for future use. < The server constructs an Encrypted Session Key (section 2.2.2.4) and sends it to the client using wxf:ReceiveResponse (section 3.2.5.3.8). 8 From this point on, the client uses the stored Session Key (section 3.1.1.2.7) for sending secure data (section ) to the server. From this point on, the server uses the Session Key (section 3.2.1.2.7) for sending secure data (section 2.2.5.1.24) to the client. Changing Maximum Runspaces Count of the Server's RunspacePool The typical PSRP sequence for changing the maximum runspaces count of the server's is described in the following table: Step Client Direction Server
higher layer. While interacting with the higher layer, the server extracts the extended properties Name, CommandType, Namespace and ArgumentList from the GET_COMMAND_METADATA message (section 2.2.2.14) message and passes them to the higher layer. The higher layer interprets the values of these properties as per the guidelines specified in section 2.2.2.14. 5 The client sends a wxf:Receive message to start receiving data from the server. > 6 < Once all the commands metadata is collected, the server constructs a CommandMetadataCount (section ) object using the collected number of commands metadata and sends it to the client. For each and every command metadata collected, the server constructs a CommandMetadata (section ) object and sends it to the client. 7 The client sends a wxf:Receive message to start receiving data from the server. This step is repeated server indicates that the Getting command metadata is completed (step 8). > 8 < Once all CommandMetadata (see section 2.2.3.22) objects have been sent, the server sends the Completed PIPELINE_STATE message (section ). 9 The client changes the pipeline (section 3.1.1.3.2) to Completed and notifies the higher layer.
Index A Abstract data model 100 130 56 15 76 98 B 79 79 C 15 178 157 157 Client 100 104 104 129 message processing 111 122 112 113 129 sequencing 122 112 113 129 103 155 99 53 60 62 73 73 80 72 Complex objects - serialization of 95 94 contents of known containers 94 94 93 93 93 95 91 90 referencing earlier objects 90 90 92 91 152 78 51 153 151 98 D Data model - abstract 100 130 99 E 98 56 63 Examples 157 157 155 152 153 151 158 159 159 156 154 160 F 16 G 158 159 11 H Higher-layer triggered events 104 134 159 67 Host parameters - encoding in host method calls 98 99 99 98 99 98 99 98 98
62 I 162 162 67 14 Initialization 104 134 11 153 K 77 L 98 events 129 150 M Message processing client 111 122 112 113 server general rules ( 135, 136) 137 20 Messages data types 20 21 27 28 28 29 29 32 32 36 37 38 38 38 38 41 42 44 46 48 49 49 56 76 79 79 53 60 62 73 73 80 72 78 51 56 63 67 62 67 77 75 80 72 76 55 55 56 54 52 58 73 98 20 51 81 17 82 syntax 20 98 51 17 82 17 N 12 O 99 local events 129 150 51 14 P 81 81 162 75 162 80 17 PPSRP messages - processing rules ERROR_RECORD 127
15 15 72 Primitive types - serialization of 86 83 83 83 86 86 83 85 86 87 82 88 88 88 84 85 85 84 83 84 85 85 84 87 87 87 176 76 55 PSRP messages - processing APPLICATION_PRIVATE_DATA 125 146 CONNECT_RUNSPACEPOOL 129 150 CREATE_PIPELINE 125 146 DEBUG_RECORD 127 148 ENCRYPTED_SESSION_KEY 124 144 END_OF_PIPELINE_INPUT 126 148 ERROR_RECORD 148 GET_AVAILABLE_RUNSPACES 125 146 GET_COMMAND_METADATA 125 147 INIT_RUNSPACEPOOL 123 144 PIPELINE_HOST_CALL 128 149 PIPELINE_HOST_RESPONSE 128 149 PIPELINE_INPUT 126 148 PIPELINE_OUTPUT 127 148 PIPELINE_STATE 127 148 PROGRESS_RECORD 128 149 PUBLIC_KEY 123 144 PUBLIC_KEY_REQUEST 124 144 RUNSPACE_AVAILABILITY 124 145 RUNSPACEPOOL_HOST_CALL 126 147 RUNSPACEPOOL_HOST_RESPONSE 126 147 RUNSPACEPOOL_INIT_DATA 129 150 RUNSPACEPOOL_STATE 125 145 SESSION_CAPABILITY 122 143 SET_MAX_RUNSPACES 124 145 SET_MIN_RUNSPACES 124 145 USER_EVENT 125 146 VERBOSE_RECORD 128 149 WARNING_RECORD 128 149 55 R 12 14 12 15 56 54
S Security 162 162 Sequencing rules client 122 112 113 server 136 137 Serialization 90 96 97 82 primitive 86 83 83 83 86 86 83 85 86 87 82 88 88 88 84 85 85 84 83 84 85 85 84 87 87 87 96 structure of complex objects 97 97 97 97 97 82 Server 130 134 134 150 message processing general ( 135, 136) 137 150 sequencing rules 136 137 150 134 156 52 16 154 Syntax 20 data 20 21 27 28 28 29 29 32 32 36 37 38 38 38 38 41 42 44 46 48 49 49 56 76 79 79 53 60 62 73 73 80 72 78 51 56 63 67 62 67 77 75 80 72 76 55 55 56 54 52 58 73 encoding host parameters in host method calls 98 99
99 98 99 98 99 98 98 51 17 serialization 90 82 82 T Timer events 129 150 Timers 103 134 58 178 17 160 Triggered events - higher-layer 104 134 V 16 15 W 73 WS-MAN messages - processing rules wxf:Command 114 138 wxf:CommandResponse 115 139 wxf:Connect 119 141 wxf:ConnectResponse 120 141 wxf:Create 113 137 wxf:Delete 118 141 wxf:DeleteResponse 119 141 wxf:Disconnect 121 142 wxf:DisconnectResponse 121 142 wxf:Fault 119 141 wxf:Receive 116 139 wxf:ReceiveResponse 117 139 wxf:Reconnect 121 142 wxf:ReconnectResponse 122 143 wxf:ResourceCreated 114 138 wxf:Send 115 139 wxf:SendResponse 116 139 wxf:Signal 118 140 wxf:SignalResponse 118 141