Preliminary: (MS-PSRP) : Powershell Remoting Protocol Specification

[MS-PSRP]: PowerShell Remoting Protocol Specification
Intellectual Property Rights Notice for Open Specifications Documentation
Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you may make copies of it in order to develop implementations of the technologies described in the Open Specifications and may distribute portions of it in your implementations using these technologies or your documentation as necessary to properly document the implementation. You may also distribute in your implementation, with or without modification, any schema, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications. No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation. Patents. Microsoft has patents that may cover your implementations of the technologies described in the Open Specifications. Neither this notice nor Microsoft's delivery of the documentation grants any licenses under those or any other Microsoft patents. However, a given Open Specification may be covered by Microsoft's Open Specification Promise (available here: http://www.microsoft.com/interop/osp) or the Community Promise (available here: http://www.microsoft.com/interop/cp/default.mspx). If you would prefer a written license, or if the technologies described in the Open Specifications are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting iplg@microsoft.com.. Trademarks. The names of companies and products contained in this documentation may be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights.
PR
EL
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than specifically described above, whether by implication, estoppel, or otherwise. Tools. The Open Specifications do not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments you are free to take advantage of them. Certain Open Specifications are intended for use in conjunction with publicly available standard specifications and network programming art, and assumes that the reader either is familiar with the aforementioned material or has immediate access to it. Preliminary Documentation. This Open Specification is preliminary documentation for this technology. Since the documentation may change between this preliminary version and the final version, there are risks in relying on preliminary documentation. To the extent that you incur additional development obligations or any other costs as a result of relying on this preliminary documentation, you do so at your own risk.
IM
IN
[MS-PSRP] v20090521 PowerShell Remoting Protocol Specification Copyright 2009 Microsoft Corporation. Release: Thursday, May 21, 2009
AR
Technical Documentation. Microsoft publishes Open Specifications documentation for protocols, file formats, languages, standards as well as overviews of the interaction among each of these technologies.
Y
1 / 105
Revision Summary
Date 12/05/2008 01/16/2009 02/27/2009 04/10/2009 05/22/2009 Revision History 0.1 1.0 1.0.1 2.0 3.0 Revision Class Major Major Editorial Major Major Comments Initial Availability Updated and revised the technical content.
Updated and revised the technical content. Updated and revised the technical content.
PR
EL
IM
2 / 105 [MS-PSRP] v20090521 PowerShell Remoting Protocol Specification Copyright 2009 Microsoft Corporation. Release: Thursday, May 21, 2009
IN
AR
Revised and edited the technical content.
Contents
1 Introduction ............................................................................................................. 7 1.1 Glossary ............................................................................................................... 7 1.2 References ............................................................................................................ 8 1.2.1 Normative References ....................................................................................... 8 1.2.2 Informative References ..................................................................................... 9 1.3 Protocol Overview (Synopsis) .................................................................................. 9 1.4 Relationship to Other Protocols ................................................................................ 9 1.5 Prerequisites/Preconditions ................................................................................... 10 1.6 Applicability Statement ......................................................................................... 10 1.7 Versioning and Capability Negotiation ..................................................................... 10 1.8 Vendor-Extensible Fields ....................................................................................... 11 1.9 Standards Assignments ........................................................................................ 11 Messages................................................................................................................ 12 2.1 Transport............................................................................................................ 12 2.2 Message Syntax .................................................................................................. 12 2.2.1 PowerShell Remoting Protocol Message ............................................................. 12 2.2.2 Message Data ................................................................................................ 15 2.2.2.1 DataType: 0x00000001: Exception Wrapped in a PowerShell Error Record ....... 15 2.2.2.2 DataType: 0x00010002: Session Capability ................................................. 16 2.2.2.3 DataType: 0x00010003: Close Session........................................................ 17 2.2.2.4 DataType: 0x00010004: Create RunspacePool ............................................. 17 2.2.2.5 DataType: 0x00010005: Public Key ............................................................ 20 2.2.2.6 DataType: 0x00010006: Encrypted Session Key ........................................... 21 2.2.2.7 DataType: 0x00010007: Public Key Request ................................................ 21 2.2.2.8 DataType: 0x00021002: Set Maximum Runspaces in a RunspacePool ............. 21 2.2.2.9 DataType: 0x00021003: Set Minimum Runspaces in a RunspacePool .............. 22 2.2.2.10 DataType: 0x00021004: A Response to Setting Maximum or Minimum Runspaces in a RunspacePool .................................................................... 22 2.2.2.11 DataType: 0x00021005: State Information of a RunspacePool...................... 23 2.2.2.12 DataType: 0x00021006: Create a PowerShell Pipeline and Invoke It in the Specified RunspacePool ............................................................................ 23 2.2.2.13 DataType: 0x00021007: Get the Number of Available Runspaces in a RunspacePool .......................................................................................... 25 2.2.2.14 DataType: 0x00021008: Report a User-defined Event from Remote Runspace................................................................................................ 26 2.2.2.15 DataType: 0x00021009: Application Private Data ....................................... 27 2.2.2.16 DataType: 0x00021100: Method Call on the Host Associated with the RunspacePool .......................................................................................... 28 2.2.2.17 DataType: 0x00021101: Response from the Host Associated with the RunspacePool .......................................................................................... 29 2.2.2.18 DataType: 0x00041002: Input to a PowerShell Pipeline on the Server ........... 29 2.2.2.19 DataType: 0x00041003: Close the Input Collection for the PowerShell Pipeline on the Server .............................................................................. 30 2.2.2.20 DataType: 0x00041004: Output of a PowerShell Pipeline on the Server ......... 30 2.2.2.21 DataType: 0x00041005: Error Record from a PowerShell Pipeline on the Server .................................................................................................... 30 2.2.2.22 DataType: 0x00041006: State Information of a PowerShell Pipeline on the Server .................................................................................................... 33
PR
EL
IM
IN
AR
Y
3 / 105
PR
DataType: 0x00041007: Debug Record from a PowerShell Pipeline on the Server .................................................................................................... 34 2.2.2.24 DataType: 0x00041008: Verbose Record from a PowerShell Pipeline on the Server .................................................................................................... 36 2.2.2.25 DataType: 0x00041009: Warning Record from a PowerShell Pipeline on the Server .................................................................................................... 38 2.2.2.26 DataType: 0x00041010: Progress Record from a PowerShell Pipeline on the Server .................................................................................................... 40 2.2.2.27 DataType: 0x00041012: Stop a PowerShell Pipeline on the Server ................ 41 2.2.2.28 DataType: 0x00041100: Method Call on the Host Associated with the PowerShell Pipeline on the Server .............................................................. 41 2.2.2.29 DataType: 0x00041101: Response from the Host Associated with the PowerShell Pipeline on the Server .............................................................. 41 2.2.3 Other Object Types......................................................................................... 41 2.2.3.1 Coordinates ............................................................................................. 41 2.2.3.2 Size ........................................................................................................ 41 2.2.3.3 Color ....................................................................................................... 42 2.2.3.4 RunspacePoolState ................................................................................... 42 2.2.3.5 PSInvocationState .................................................................................... 43 2.2.3.6 PSThreadOptions ...................................................................................... 43 2.2.3.7 ApartmentState ........................................................................................ 43 2.2.3.8 RemoteStreamOptions .............................................................................. 44 2.2.3.9 ErrorCategory .......................................................................................... 44 2.2.3.10 TimeZone .............................................................................................. 45 2.2.3.11 PowerShell Pipeline ................................................................................. 45 2.2.3.12 Command .............................................................................................. 46 2.2.3.13 Command Parameter............................................................................... 46 2.2.3.14 Exception as ErrorRecord ......................................................................... 47 2.2.3.15 HostInfo ................................................................................................ 47 2.2.3.16 ErrorRecord............................................................................................ 48 2.2.3.17 InformationalRecord (DebugRecord, WarningRecord or VerboseRecord) ......... 50 2.2.3.18 Host Method Identifier ............................................................................. 51 2.2.3.19 Primitive Dictionary ................................................................................. 56 2.2.4 Packet Fragment ............................................................................................ 56 2.2.5 Serialization................................................................................................... 57 2.2.5.1 Serialization of Primitive Types ................................................................... 57 2.2.5.1.1 String ................................................................................................ 58 2.2.5.1.2 Character ........................................................................................... 58 2.2.5.1.3 Boolean ............................................................................................. 58 2.2.5.1.4 Date/Time .......................................................................................... 58 2.2.5.1.5 Duration ............................................................................................ 59 2.2.5.1.6 Unsigned Byte .................................................................................... 59 2.2.5.1.7 Signed Byte ........................................................................................ 59 2.2.5.1.8 Unsigned Short ................................................................................... 59 2.2.5.1.9 Signed Short ...................................................................................... 59 2.2.5.1.10 Unsigned Int ..................................................................................... 60 2.2.5.1.11 Signed Int ........................................................................................ 60 2.2.5.1.12 Unsigned Long .................................................................................. 60 2.2.5.1.13 Signed Long...................................................................................... 60 2.2.5.1.14 Float ................................................................................................ 61 2.2.5.1.15 Double ............................................................................................. 61 2.2.5.1.16 Decimal ............................................................................................ 61 2.2.5.1.17 Array of Bytes ................................................................................... 61
2.2.2.23
EL
IM
IN
AR
Y
4 / 105
PR
EL
3
2.2.5.1.18 GUID ............................................................................................... 62 2.2.5.1.19 URI .................................................................................................. 62 2.2.5.1.20 Null Value ......................................................................................... 62 2.2.5.1.21 Version ............................................................................................ 62 2.2.5.1.22 XML Document .................................................................................. 63 2.2.5.1.23 ScriptBlock ....................................................................................... 63 2.2.5.1.24 Secure String .................................................................................... 63 2.2.5.1.25 Progress Record ................................................................................ 63 2.2.5.2 Serialization of Complex Objects ................................................................. 64 2.2.5.2.1 Referencing Earlier Objects................................................................... 65 2.2.5.2.1.1 RefId Attribute .............................................................................. 65 2.2.5.2.1.1.1 <Ref> Element ........................................................................ 65 2.2.5.2.2 Serialization As a String ....................................................................... 65 2.2.5.2.3 <Obj> Element ................................................................................... 66 2.2.5.2.4 Type Names ....................................................................................... 66 2.2.5.2.5 ToString ............................................................................................. 67 2.2.5.2.6 Contents of Primitive Types with Notes .................................................. 68 2.2.5.2.7 Contents of Known Containers .............................................................. 68 2.2.5.2.7.1 Stack ........................................................................................... 68 2.2.5.2.7.2 Queue .......................................................................................... 68 2.2.5.2.7.3 List .............................................................................................. 69 2.2.5.2.7.4 Dictionaries................................................................................... 69 2.2.5.2.8 Contents of Enums .............................................................................. 70 2.2.5.2.9 Contents of Other Complex Objects ....................................................... 70 2.2.5.2.10 Extended Properties ........................................................................... 71 2.2.5.3 Miscellaneous ........................................................................................... 71 2.2.5.3.1 Property Name.................................................................................... 71 2.2.5.3.2 Encoding Strings ................................................................................. 72 2.2.5.3.3 Lifetime of a Serializer/Deserializer Pair ................................................. 72 2.2.5.3.4 Structure of Complex Objects ............................................................... 72 2.2.5.3.4.1 Adapted Properties ........................................................................ 72 2.2.5.3.4.2 Extended Properties ....................................................................... 73 2.2.5.3.4.3 Property Sets ................................................................................ 73 2.2.5.3.4.4 ToString Value .............................................................................. 73 2.2.6 Encoding Host Parameters in Host Method Calls ................................................. 73 2.2.6.1 Encoding Individual Parameters .................................................................. 73 2.2.6.1.1 Any Serializable Type........................................................................... 73 2.2.6.1.2 CultureInfo ......................................................................................... 73 2.2.6.1.3 List .................................................................................................... 73 2.2.6.1.4 ArrayList ............................................................................................ 74 2.2.6.1.5 Collection ........................................................................................... 74 2.2.6.1.6 Dictionary .......................................................................................... 74 2.2.6.1.7 Object Dictionary ................................................................................ 74 2.2.6.1.8 Other Object Types Used in a Host Call .................................................. 75
Protocol Details ...................................................................................................... 76 3.1 Client Details....................................................................................................... 76 3.1.1 Abstract Data Model ....................................................................................... 76 3.1.2 Timers .......................................................................................................... 78 3.1.3 Initialization .................................................................................................. 78 3.1.4 Higher-Layer Triggered Events ......................................................................... 78 3.1.5 Message Processing Events and Sequencing Rules .............................................. 78 3.1.5.1 General Protocol Rules .............................................................................. 78
IM
IN
AR
Y
5 / 105
PR
EL
5 6 7 8
Security .................................................................................................................. 96 5.1 Security Considerations for Implementers ............................................................... 96 5.2 Index of Security Parameters ................................................................................ 96 Appendix A: Product Behavior ................................................................................ 97
Change Tracking..................................................................................................... 98
Index ................................................................................................................... 101
IM
Protocol Examples .................................................................................................. 92 4.1 Example Messages ............................................................................................... 92 4.1.1 Host Information Message ............................................................................... 92 4.1.2 Host Method Call Message ............................................................................... 92 4.1.3 Host Method Call Invocation Response Message ................................................. 93 4.1.4 Progress Record Serialization Example .............................................................. 93 4.2 Serialized Data Element ........................................................................................ 93 4.3 Transport Message Examples ................................................................................ 94 4.4 Client Server Communication Examples from the Client Perspective ........................... 94
IN
3.1.5.2 Protocol Sequence .................................................................................... 79 3.1.5.2.1 Sending Messages ............................................................................... 79 3.1.5.3 Transporting Using WS-MAN ...................................................................... 80 3.1.5.3.1 Creating a Shell on a PowerShell Server ................................................. 80 3.1.5.3.2 Client-Server Negotiation ..................................................................... 81 3.1.5.3.3 Executing a Command on a Remote Shell............................................... 82 3.1.5.3.4 Sending Input to Command/Shell .......................................................... 83 3.1.5.3.5 Receiving Output from a Command/Shell ............................................... 84 3.1.5.3.6 Signaling a Command .......................................................................... 85 3.1.5.3.7 Deleting a Shell on a PowerShell Server ................................................. 86 3.1.6 Timer Events ................................................................................................. 86 3.1.7 Other Local Events ......................................................................................... 86 3.2 Server Details ..................................................................................................... 86 3.2.1 Abstract Data Model ....................................................................................... 86 3.2.2 Timers .......................................................................................................... 88 3.2.3 Initialization .................................................................................................. 88 3.2.4 Higher-Layer Triggered Events ......................................................................... 88 3.2.5 Message Processing Events and Sequencing Rules .............................................. 88 3.2.5.1 General Protocol Rules .............................................................................. 88 3.2.5.2 Transporting Using WS-MAN ...................................................................... 88 3.2.5.2.1 Response to Create Shell Request ......................................................... 88 3.2.5.2.2 Response to Create Command Request .................................................. 89 3.2.5.2.3 Response to Send Request ................................................................... 89 3.2.5.2.4 Response to Receive Request................................................................ 89 3.2.5.2.5 Response to Signal Request .................................................................. 90 3.2.5.2.6 Response to Delete Request ................................................................. 90 3.2.5.3 Sequencing Rules ..................................................................................... 90 3.2.6 Timer Events ................................................................................................. 91 3.2.7 Other Local Events ......................................................................................... 91
AR
Y
6 / 105
Introduction
This document specifies the Windows PowerShell Remoting Protocol. The Windows PowerShell Remoting Protocol encodes messages prior to sending them over the Web Services Management Protocol Extensions for Windows Vista [MS-WSMV] layer.
1.1
Glossary
The following terms are defined in [MS-GLOS]: globally unique identifier (GUID) The following terms are specific to this document: Cmdlet: A PowerShell command.
Command: Any entity which can be executed in PowerShell.
Crypto API (CAPI): The Microsoft Cryptographic API library. For details, see [MSDN-CAPI].
Decoding: The reversal of the encoding process, used by a PowerShell client or PowerShell server to correctly interpret a received object. Defragmentation: The construction of a serialized representation of an object from fragments and metadata. Deserialization: The mechanism by which PowerShell constructs an object from its XML representation. Encoding: The annotation of an object with metadata so that it can be sent to a PowerShell client or PowerShell server. Fragmentation: The breaking down of a large serialized object into fragments, with additional metadata such that fragments can be sequenced and sent using WinRM send calls and reassembled at the receiving end. Host: An interface between a PowerShell runspace and a user capable of responding to the host method calls specified in section 2.2.3.18. For more details on host functionality, see sections 2.2.3.18 and 2.2.6. Nested Pipeline: A pipeline on a runspace that is created when another pipeline already exists.
PR
EL
Object: The base class of all classes in the .NET Framework; it is the root of the type hierarchy. For more information, see [ECMA-335].
Pipeline: An ordered collection of commands, with the output of one command passed as input to the next. PowerShell Client: Any process that tries to initiate PowerShell commands using PowerShell remoting. PowerShell Server: Any process that accepts commands from a PowerShell client process (via WinRM).
PSObject: An object encapsulated to allow for a consistent view within the PowerShell environment.
IM
IN
AR
Y
7 / 105
Runspace: An entity capable of running one (and only one) pipeline of commands. RunspacePool: A group of runspaces with the same characteristics which can be opened and closed as needed. Serialization: A mechanism by which PowerShell converts an object into an XML representation. Session: The operational environment in which the PowerShell shell and its cmdlets execute. ScriptBlock: Represents a block of PowerShell script.
WS-MAN: The Web Services Management Protocol, as specified in [MS-WSMV].
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as described in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2
References Normative References
1.2.1
[FIPS197] National Institute of Standards and Technology, "Federal Information Processing Standards Publication 197: Advanced Encryption Standard (AES)", November 2001, http://www.csrc.nist.gov/publications/fips/fips197/fips-197.pdf [IEEE754] Institute of Electrical and Electronics Engineers, "Standard for Binary Floating-Point Arithmetic", IEEE 754-1985, October 1985, http://ieeexplore.ieee.org/servlet/opac?punumber=2355. [MS-WSMV] Microsoft Corporation, "Web Services Management Protocol Extensions for Windows Vista", July 2007. [PKCS1] RSA Laboratories, "PKCS#1 Version 2.1: RSA Cryptography Standard", PKCS #1, June 2002, http://www.rsa.com/rsalabs/node.asp?id=2125
PR
EL
[RFC791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981, http://www.ietf.org/rfc/rfc791.txt [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, September 1981, http://www.ietf.org/rfc/rfc0793.txt
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, http://www.ietf.org/rfc/rfc2119.txt [RFC2616] Fielding, R., Gettys, J., Mogul, J., et al., "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999, http://www.ietf.org/rfc/rfc2616.txt [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000, http://www.ietf.org/rfc/rfc2818.txt
IM
IN
We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact dochelp@microsoft.com. We will assist you in finding the relevant information. Please check the archive site, http://msdn2.microsoft.com/en-us/library/E4BD6494-06AD-4aed-9823-445E921C9624, as an additional source.
AR
Y
8 / 105
WinRM: The Windows Remote Management (WinRM) is the Microsoft implementation of WSMAN protocol [MS-WSMV].
[SOAP1.2-1/2003] Gudgin, M., Hadley, M., Mendelsohn, N., Moreau, J., and Nielsen, H.F., "SOAP Version 1.2 Part 1: Messaging Framework", W3C Recommendation, June 2003, http://www.w3.org/TR/2003/REC-soap12-part1-20030624
1.2.2
Informative References
[ECMA-335] ECMA international, "Common Language Infrastructure (CLI) Partitions I to VI", ECMA 335, June 2006, http://www.ecma-international.org/publications/standards/Ecma-335.htm [MSDN-BinaryFormatter] Microsoft Corporation, "Binary Formatter Class", http://msdn.microsoft.com/enus/library/system.runtime.serialization.formatters.binary.binaryformatter.aspx
[MSDN-TIMEZONEINFO] Microsoft Corporation, "TIME_ZONE_INFORMATION structure", http://msdn.microsoft.com/en-us/library/ms725481.aspx
[RFC2396] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998, http://www.ietf.org/rfc/rfc2396.txt
[RFC3548] Josefsson, S., Ed., "The Base16, Base32, and Base64 Data Encodings", RFC 3548, July 2003, http://www.ietf.org/rfc/rfc3548.txt [RFC4122] Leach, P., Mealling, M., and Salz, R., "A Universally Unique Identifier (UUID) URN Namespace", RFC 4122, July 2005, http://www.ietf.org/rfc/rfc4122.txt [XML] World Wide Web Consortium, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", W3C Recommendation, November 2008, http://www.w3.org/TR/REC-xml [XML Namespaces1.0] Bray, T., Hollander, D., and Layman, A., "Namespaces in XML 1.0 (Second Edition)", August 2006, http://www.w3.org/TR/REC-xml-names [XMLSCHEMA2] Biron, P.V., Ed. and Malhotra, A., Ed., "XML Schema Part 2: Datatypes", W3C Recommendation, May 2001, http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/
1.3
Protocol Overview (Synopsis)
PR
EL
1.4
The PowerShell Remoting Protocol enables users to send PowerShell commands to servers hosting PowerShell 2.0 with remoting, whereupon these commands can be executed remotely. The PowerShell Remoting Protocol first encodes the message, then serializes the data portion of the encoded message as XML. The serialized XML is fragmented before the message is transported to the PowerShell server. The PowerShell server defragments a message upon receipt. This is followed by deserialization and decoding of the message. The PowerShell servers may send a response back using the method described in the preceding paragraph.
Relationship to Other Protocols
The PowerShell Remoting Protocol uses the Web Services Management Protocol Extensions for Windows Vista [MS-WSMV] to establish a connection and transfer data between the client and the server. [MS-WSMV] is built on top of the following protocols. SOAP (Version 1.2) [SOAP1.2/1]
IM
IN
AR
[MSDN-CAPI] Microsoft Corporation, "Cryptography", http://msdn.microsoft.com/enus/library/aa380255.aspx
Y
9 / 105
The Hypertext Transfer Protocol (HTTP/1.1) [RFC2616] or HTTP Over TLS [RFC2818] The Transmission Control Protocol [RFC793] The Internet Protocol [RFC791]
Figure 1: Relationship of PowerShell Remoting Protocol to other protocols
1.5
Prerequisites/Preconditions
The server must have Windows PowerShell 2.0 installed.
The server must have the necessary WS-MAN configurations which will enable it to launch PowerShell remotely. The Windows Remote Management listener must be configured to listen to PowerShell create shell requests, as specified in [MS-WSMV].
1.6
Applicability Statement
The PowerShell Remoting Protocol is required whenever a user wants to execute PowerShell commands on a server from a client.
1.7
Versioning and Capability Negotiation
PR
EL
Release: Thursday, May 21, 2009
The PowerShell Remoting Protocol is based on the Web Services Management Protocol Extensions for Windows Vista [MS-WSMV]. Supported Transports: The PowerShell Remoting Protocol is implemented on top of the WSWSMV protocol, as discussed in section 3.1.5.3 Protocol Versions: The PowerShell Remoting Protocol supports the following explicit dialects: WSMAN1.1. These dialects are defined in section 3.1.5.3.1 PowerShell Protocol Version: The PowerShell Remoting Protocol requires the option named protocolversion to be present in the OptionSet of the /Create message. This option is described in section 3.1.5.3.1 and is used by the server to send messages to the client in a format that client can understand.
IM
IN
For a client that uses the PowerShell Remoting Protocol to communicate with the server, the following must be true.
[MS-PSRP] v20090521 PowerShell Remoting Protocol Specification Copyright 2009 Microsoft Corporation.
AR
10 / 105
Capability Negotiation: The PowerShell Remoting Protocol does explicit capability negotiation as specified in section 3.1.5.3.2
1.8
Vendor-Extensible Fields
None.
1.9
Standards Assignments
None.
PR
EL
IM
IN
AR
2
2.1
Messages
Transport
PowerShell Remoting Protocol messages MUST be sent as WS-MAN packets and transported over an MS-WSMV transport layer. The Windows PowerShell Remoting Protocol MUST fragment the data into payload packets that can fit into the WS-MAN SOAP message (as specified in [MS-WSMV]) and transport these messages using WS-MAN.
1. Construct the protocol message as described in section 2.2.1.
The PowerShell Remoting Protocol MUST use the following steps to interpret the data packets when receiving data. 1. The server will send data in the form of fragments, as described in section 2.2.4. The PowerShell Remoting Protocol SHOULD collect all the fragments until it receives a fragment that is marked as End fragment. The first fragment shall be identified by using Start fragment marker specified in the fragment header. 2. All the fragments MUST be combined in ascending order identified by the FragmentId field. While assembling the fragments make sure the Object Id is same for all the fragments. The Fragement header MUST NOT be assembled. Once all the fragments are combined, the result is a serialized object. 3. The serialized object MUST be deserialized.
The deserialized Object represents a PowerShell protocol message and MUST be interpreted as described in section 2.2.1.
2.2
Message Syntax
2.2.1
PowerShell Remoting Protocol Message
The structure of a PowerShell Remoting Protocol Message is as follows.
EL
1 0
IM
5 6 7 8 9 1 2 3 4 5 ...
IN
6 7 8 9 2 0 1 2 Destination RPID
AR
3 4 5 6 7 8 9 3 0
2. Fragment the message into several packets, as specified in section 2.2.4. Each fragmented packet is added as payload to a WS-Management SOAP message and transported using WSManagement.
PR
Y
1 12 / 105
The PowerShell Remoting Protocol MUST use the following steps to construct its pay load data packets when sending data.
... ... PID ... ... ... DataType Data (variable) ...
Destination (4 bytes): The destination of this message. Possible values.

Value 0x00000000 0x00000001 0x00000002 0x00000004
RPID (16 bytes): A globally unique identifier (GUID) specifying the instance ID of the RunspacePool on the PowerShell client.
PR
EL
Possible values.
Value Meaning 0x00000001 0x00010002 0x00010003 Close session. Release: Thursday, May 21, 2009
PID (16 bytes): A GUID specifying the instance ID of the Pipeline on the PowerShell client. DataType (4 bytes): The type of message. The value of this field specifies what action MUST be taken by the PowerShell client or PowerShell server upon receipt.
IM
Session capability.
Exception wrapped in a PowerShell error record.
IN
Meaning InvalidDestination Client Server Listener 13 / 105
AR
Value 0x00010004 0x00010005 0x00010006 0x00010007 0x00021002 0x00021003 0x00021004
Meaning Create RunspacePool. Public key. Encrypted session key. Public key request.
Set minimum runspaces in a RunspacePool.
0x00021005 0x00021006 0x00021007 0x00021008 0x00021009
State information of a RunspacePool.
Create a PowerShell and invoke it in the specified RunspacePool. Get the number of available runspaces in a RunspacePool. Report a user-defined event from remote runspace.
0x00021100 0x00021101 0x00041002 0x00041003 0x00041004 0x00041005 0x00041006 0x00041007 0x00041008 0x00041009 0x00041010 0x00041012 0x00041100
Method call on the host associated with the RunspacePool on the server. Response from a host call executed on the PowerShell client RunspacePool's host. Input to a PowerShell on the server.
PR
EL
0x00041101 Release: Thursday, May 21, 2009
IM
Stop a pipeline on the server.
Close the input collection for the PowerShell on the server. Output of a PowerShell on the server. Error record from a PowerShell on the server. State information of a Powershell on the server. Debug record from a PowerShell on the server. Verbose record from a PowerShell on the server. Warning record from a PowerShell on the server. Progress record from a PowerShell on the server.
Method call on the host associated with the pipeline invocation settings on the server. Response from a host call executed on the PowerShell client's host.
IN
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.
AR
14 / 105
A response to either set maximum runspaces or set minimum runspaces in a RunspacePool or request for available runspaces in a RunspacePool.
Set maximum runspaces in a RunspacePool.
Data (variable): The contents of this field are determined by the DataType field, and are fully specified in section 2.2.2.
2.2.2
Message Data DataType: 0x00000001: Exception Wrapped in a PowerShell Error Record
2.2.2.1
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an exception as an error record (see section 2.2.3.13).
PR
<Obj RefId="1"> <TN RefId="0"> <T>System.Management.Automation.ErrorRecord</T> <T>System.Object</T> </TN> <ToString>The pipeline has been stopped.</ToString> <MS> <Obj N="Exception" RefId="2"> <TN RefId="1"> <T>System.Management.Automation.PipelineStoppedException</T> <T>System.Management.Automation.RuntimeException</T> <T>System.SystemException</T> <T>System.Exception</T> <T>System.Object</T> </TN> <ToString>System.Management.Automation.PipelineStoppedException: The pipeline has been stopped._x000D__x000A_ at System.Management.Automation.Internal.PipelineProcessor.SynchronousExecuteEnumerate(Object input, Hashtable errorResults, Boolean enumerate) in c:\e\win7_powershell\admin\monad\src\engine\pipeline.cs:line 586</ToString> <Props> <S N="ErrorRecord">The pipeline has been stopped.</S> <S N="StackTrace"> at System.Management.Automation.Internal.PipelineProcessor.SynchronousExecuteEnumerate(Object input, Hashtable errorResults, Boolean enumerate) in c:\e\win7_powershell\admin\monad\src\engine\pipeline.cs:line 586</S> <S N="Message">The pipeline has been stopped.</S> <Obj N="Data" RefId="3"> <TN RefId="2"> <T>System.Collections.ListDictionaryInternal</T> <T>System.Object</T> </TN> <DCT /> </Obj> <Nil N="InnerException" /> <S N="TargetSite">System.Array SynchronousExecuteEnumerate(System.Object, System.Collections.Hashtable, Boolean)</S> <Nil N="HelpLink" /> <S N="Source">System.Management.Automation</S> </Props> </Obj> <Nil N="TargetObject" /> <S N="FullyQualifiedErrorId">PipelineStopped</S> <Nil N="InvocationInfo" /> <I32 N="ErrorCategory_Category">14</I32> <S N="ErrorCategory_Activity"></S> <S N="ErrorCategory_Reason">PipelineStoppedException</S>
EL
IM
IN
AR
Y
15 / 105
Example:
<S N="ErrorCategory_TargetName"></S> <S N="ErrorCategory_TargetType"></S> <S N="ErrorCategory_Message">OperationStopped: (:) [], PipelineStoppedException</S> false </MS> </Obj>
2.2.2.2
DataType: 0x00010002: Session Capability
Version of PowerShell Property name: PSVersion. Property type: String (see section 2.2.5.1.1).
Version of the PowerShell remoting protocol (see section 3.1.5.3.1) Property name: protocolversion. Property type: String (see section 2.2.5.1.1). Version of PowerShell serialization
Property name: SerializationVersion.
Property type: String (see section 2.2.5.1.1). Time zone of the client Property name: TimeZone.
Property type: TimeZone (see section 2.2.3.10) or Null value (see section 2.2.5.1.20). This property is optional.
If server must comply with the capabilities implied by the version Property name: MustComply.
PR
EL
Example:
Property type: Boolean (see section 2.2.5.1.3).
<Obj RefId="0"> <MS> <Version N="protocolversion">2.0</Version> <Version N="PSVersion">2.0</Version> <Version N="SerializationVersion">1.1.0.1</Version> <BA N="TimeZone">AAEAAAD/////AQAAAAAAAAAEAQAAABxTeXN0ZW0uQ3VycmVudFN5c3RlbVRpbWVab25lBAAAABdtX0Nh Y2hlZERheWxpZ2h0Q2hhbmdlcw1tX3RpY2tzT2Zmc2V0Dm1fc3RhbmRhcmROYW1lDm1fZGF5bGlnaHROYW1lAwABARxTe XN0ZW0uQ29sbGVjdGlvbnMuSGFzaHRhYmxlCQkCAAAAAMDc8bz///8KCgQCAAAAHFN5c3RlbS5Db2xsZWN0aW9ucy5IYX NodGFibGUHAAAACkxvYWRGYWN0b3IHVmVyc2lvbghDb21wYXJlchBIYXNoQ29kZVByb3ZpZGVyCEhhc2hTaXplBEtleXM GVmFsdWVzAAADAwAFBQsIHFN5c3RlbS5Db2xsZWN0aW9ucy5JQ29tcGFyZXIkU3lzdGVtLkNvbGxlY3Rpb25zLklIYXNo Q29kZVByb3ZpZGVyCOxROD8BAAAACgoLAAAACQMAAAAJBAAAABADAAAAAQAAAAgI2QcAABAEAAAAAQAAAAkFAAAABAUAA
IM
IN
16 / 105
AR
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10):
AAhU3lzdGVtLkdsb2JhbGl6YXRpb24uRGF5bGlnaHRUaW1lAwAAAAdtX3N0YXJ0BW1fZW5kB21fZGVsdGEAAAANDQwAkO q4qG3LiAAQOyeuKMyIAGjEYQgAAAAL</BA> </MS> </Obj>
2.2.2.3
DataType: 0x00010003: Close Session
In messages of this data type, the data field is empty (has a length of zero bytes).
Property name: MinRunspaces. Property type: Signed int (see section 2.2.5.1.11). Maximum number of runspaces in the RunspacePool Property name: MaxRunspaces. Property type: Signed int (see section 2.2.5.1.11). Thread options
Property name: PSThreadOptions.
Property type: PSThreadOptions (see section 2.2.3.6). Apartment state
Property name: ApartmentState.
Property type: ApartmentState (see section 2.2.3.7). Host information
Property name: HostInfo.
Property type: HostInfo (see section 2.2.3.14)
PR
EL
Application arguments Example:
Property name: ApplicationArguments Property type: Primitive Dictionary (see section2.2.3.19) or Null Value (see section 2.2.5.1.20)
<Obj RefId="1"> <MS> <I32 N="MinRunspaces">1</I32> <I32 N="MaxRunspaces">1</I32> <Obj N="PSThreadOptions" RefId="2">
IM
IN
17 / 105
AR
Minimum number of runspaces in the RunspacePool.
2.2.2.4
DataType: 0x00010004: Create RunspacePool
PR
<TN RefId="0"> <T>System.Management.Automation.Runspaces.PSThreadOptions</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Default</ToString> <I32>0</I32> </Obj> <Obj N="ApartmentState" RefId="3"> <TN RefId="1"> <T>System.Threading.ApartmentState</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>MTA</ToString> <I32>1</I32> </Obj> <Obj N="HostInfo" RefId="4"> <MS> <Obj N="_hostDefaultData" RefId="5"> <MS> <Obj N="data" RefId="6"> <TN RefId="2"> <T>System.Collections.Hashtable</T> <T>System.Object</T> </TN> <DCT> <En> <I32 N="Key">9</I32> <Obj N="Value" RefId="7"> <MS> <S N="T">System.String</S> <S N="V">Windows PowerShell V2 (MS Internal Only)</S> </MS> </Obj> </En> <En> <I32 N="Key">8</I32> <Obj N="Value" RefId="8"> <MS> <S N="T">System.Management.Automation.Host.Size</S> <Obj N="V" RefId="9"> <MS> <I32 N="width">181</I32> <I32 N="height">98</I32> </MS> </Obj> </MS> </Obj> </En> <En> <I32 N="Key">7</I32> <Obj N="Value" RefId="10"> <MS> <S N="T">System.Management.Automation.Host.Size</S> <Obj N="V" RefId="11"> <MS>
EL
IM
IN
AR
18 / 105
PR
<I32 N="width">120</I32> <I32 N="height">98</I32> </MS> </Obj> </MS> </Obj> </En> <En> <I32 N="Key">6</I32> <Obj N="Value" RefId="12"> <MS> <S N="T">System.Management.Automation.Host.Size</S> <Obj N="V" RefId="13"> <MS> <I32 N="width">120</I32> <I32 N="height">79</I32> </MS> </Obj> </MS> </Obj> </En> <En> <I32 N="Key">5</I32> <Obj N="Value" RefId="14"> <MS> <S N="T">System.Management.Automation.Host.Size</S> <Obj N="V" RefId="15"> <MS> <I32 N="width">120</I32> <I32 N="height">3000</I32> </MS> </Obj> </MS> </Obj> </En> <En> <I32 N="Key">4</I32> <Obj="" N="Value" RefId="16"> <MS> <S N="T">System.Int32</S> <I32 N="V">25</I32> </MS> </Obj> </En> <En> <I32 N="Key">3</I32> <Obj N="Value" RefId="17"> <MS> <S N="T">System.Management.Automation.Host.Coordinates</S> <Obj N="V" RefId="18"> <MS> <I32 N="x">0</I32> <I32 N="y">0</I32> </MS> </Obj> </MS> </Obj> </En> <En>
EL
IM
IN
AR
19 / 105
PR
EL
2.2.2.5
Property name: PublicKey.
<I32 N="Key">2</I32> <Obj N="Value" RefId="19"> <MS> <S N="T"> System.Management.Automation.Host.Coordinates </S> <Obj N="V" RefId="20"> <MS> <I32 N="x">0</I32> <I32 N="y">4</I32> </MS> </Obj> </MS> </Obj> </En> <En> <I32 N="Key">1</I32> <Obj N="Value" RefId="21"> <MS> <S N="T">System.ConsoleColor</S> <I32 N="V">5</I32> </MS> </Obj> </En> <En> <I32 N="Key">0</I32> <Obj N="Value" RefId="22"> <MS> <S N="T">System.ConsoleColor</S> <I32 N="V">6</I32> </MS> </Obj> </En> </DCT> </Obj> </MS> </Obj> false false false false </MS> </Obj> <Nil N="ApplicationArguments /> </MS> </Obj>
DataType: 0x00010005: Public Key
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10).
2048-bit public key of a RSA public key pair [PKCS1], encoded as XML using rules outlined by the Crypto API (CAPI) and encoded in Base64 format.
IM
IN
AR
20 / 105
Property type: String (see section 2.2.5.1.1). Example:

<Obj RefId="0"> <MS> <S N="PublicKey"> BgIAAACkAABSU0ExAAgAAAEAAQBxLtiI7U4s5gkx4zzFaRyhCgTwSYWBdxx6MfjJMXcuLewnq7RvIo6yfgcN2s8FXrelH s8y34S0fdvM/fbSXjaacKOQoLVvOgyVf1x7EODpDADW2Tj9RIz52hcsVzNFfkfT4EhMvcJbDIqtEwIF6BmjHc5yNPsywT FD6QU50BIySeV7IT3qhjxihQEbMt/shf0DcFX07JIs37FPPZpesaviyG3RZjhQbfCbJ66vlea+1ocVYgqM7W98ZIeHlRT 2XhrPSD+hwriUcfG3oOJIILpo2acpAxcz8KCEOkpocH4wA/IgF+9UcaeanOkBXqK3xc9LPtVuQ7otZYa+zvrTZXe4 </S> </MS> </Obj>
2.2.2.6
DataType: 0x00010006: Encrypted Session Key
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10). 256-bit symmetric key for AES encryption scheme [FIPS197] encrypted using PKCS #1 standard [PKCS1] with the public key from DataType 0x00010005 (see section 2.2.2.5) and encoded as XML using rules outlined by the Crypto API (CAPI) and encoded in Base64 format.
Property type: String (see section 2.2.5.1.1). Example:
PR
EL
Example:
<S></S>
2.2.2.7
DataType: 0x00010007: Public Key Request
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an empty String (see section 2.2.5.1.1); that is, a string containing zero characters.
2.2.2.8
DataType: 0x00021002: Set Maximum Runspaces in a RunspacePool
IM
<Obj RefId="0"> <MS> <S N="EncryptedSessionKey"> AQIAABBmAAAApAAAgY6iLhsPXjMGza6Rc6JeEfezwTaZjJhm+gj55YRVzv6QTyRkl3j9XuESv5WhNwHHZD0pAwDC5iZcx FCKtZ4PSuBIy6EULAuvxUCvREZ2NueMLUzbOaLviFc4Y2Qf9rPEBfjK/iKyudKTiF4bY92RTZxoxVECaT4Z9EJI4QyigC IUfjY7oXzcntkc09Its+v9HgoQY50qXCtqB+r1Npdx3gYPvtuTPsRGGPlmKnns6gVALeh8Tw/FPo8EMk+oGpfAUZjhxcN pmrniujs8UTlDzV8JWa/sEjrpewEGTBRWs0AQ3yEj2ALZzpwDa+bHhSp8TtJV+V6ZN7MvTX2igcAwQA== </S> </MS> </Obj>
IN
Property name: EncryptedSessionKey.
AR
Y
21 / 105
Maximum number of runspaces in the RunspacePool Property name: MaxRunspaces. Property type: Signed int (see section 2.2.5.1.11) Example:
<Obj RefId="5"> <MS> <I32 N="MaxRunspaces">3</I32> <I64 N="ci">1</I64> </MS> </Obj>
2.2.2.9
DataType: 0x00021003: Set Minimum Runspaces in a RunspacePool
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10): Minimum number of runspaces in the RunspacePool. Property name: MinRunspaces. Property type: Signed int (see section 2.2.5.1.11) Example:
<Obj RefId="6"> <MS> <I32 N="MinRunspaces">2</I32> <I64 N="ci">2</I64> </MS> </Obj>
2.2.2.10 DataType: 0x00021004: A Response to Setting Maximum or Minimum Runspaces in a RunspacePool

PR
EL
Call ID Property name: ci. Response Property type: any type Example:
Property type: Signed long (see section 2.2.5.1.13).
Property name: SetMinMaxRunspacesResponse.
IM
IN
22 / 105
AR
<Obj RefId="2"> <MS> true <I64 N="ci">1</I64> </MS> </Obj>
2.2.2.11
DataType: 0x00021005: State Information of a RunspacePool
RunspacePool state information Property name: RunspaceState.
Property type: RunspacePoolState (see section 2.2.3.4).
Optional error information (included only if this message is triggered by an error). Property name: ExceptionAsErrorRecord.
Property type: Exception as ErrorRecord (see section 2.2.3.13). Example:
<Obj RefId="1"> <MS> <I32 N="RunspaceState">2</I32> </MS> </Obj>
2.2.2.12 DataType: 0x00021006: Create a PowerShell Pipeline and Invoke It in the Specified RunspacePool
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10). Whether the PowerShell pipeline will take input
PR
EL
Apartment state
Property name: NoInput.
Property name: ApartmentState. Property type: ApartmentState (see section 2.2.3.7).
Stream options that indicate how PowerShell MUST treat messages from debug, verbose, warning and error streams in the remote invocation scenario Property name: RemoteStreamOptions. Property type: RemoteStreamOptions (see section 2.2.3.8).
23 / 105
IM
IN
AR
Boolean indicating if PowerShell MUST add the command being executed to the history field of the runspace. Property name: AddToHistory. Property type: Boolean (see section 2.2.5.1.3). Host information Property name: HostInfo.
Description of the PowerShell pipeline to create Property name: PowerShell. Property type: PowerShell (see section 2.2.3.11) Example:
PR
<Obj RefId="0"> <MS> <Obj N="PowerShell" RefId="1"> <MS> <Obj N="Cmds" RefId="2"> <TN RefId="0"> <T>System.Collections.Generic.List`1[[System.Management.Automation.PSObject, System.Management.Automation, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]</T> <T>System.Object</T> </TN> <LST> <Obj RefId="3"> <MS> <S N="Cmd">123 </S> true <Nil N="UseLocalScope" /> <Obj N="MergeMyResult" RefId="4"> <TN RefId="1"> <T>System.Management.Automation.Runspaces.PipelineResultTypes</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>None</ToString> <I32>0</I32> </Obj> <Obj N="MergeToResult" RefId="5"> <TNRef RefId="1" /> <ToString>None</ToString> <I32>0</I32> </Obj> <Obj N="MergePreviousResults" RefId="6"> <TNRef RefId="1" /> <ToString>None</ToString> <I32>0</I32> </Obj> <Obj N="Args" RefId="7">
EL
IM
IN
AR
24 / 105
Property type: HostInfo (see section 2.2.3.15).
PR
EL
Call ID
<TNRef RefId="0" /> <LST> <Obj RefId="8"> <MS> <Nil N="N" /> <S N="V">powershell.exe</S> </MS> </Obj> </LST> </Obj> </MS> </Obj> </LST> </Obj> false </MS> </Obj> true <Obj N="ApartmentState" RefId="8"> <TN RefId="2"> <T>System.Threading.ApartmentState</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>MTA</ToString> <I32>1</I32> </Obj> <Obj N="RemoteStreamOptions" RefId="9"> <TN RefId="3"> <T>System.Management.Automation.RemoteStreamOptions</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>AddInvocationInfo</ToString> <I32>15</I32> </Obj> false <Obj N="HostInfo" RefId="10"> <MS> true true true true </MS> </Obj> </MS> </Obj>
2.2.2.13 DataType: 0x00021007: Get the Number of Available Runspaces in a RunspacePool

IM
IN
25 / 105
AR
Property name: ci. Property type: Signed long (see section 2.2.5.1.13). Example:
<Obj RefId="7"> <MS> <I64 N="ci">3</I64> </MS> </Obj>
Messages of this type are sent when the PowerShell client requests that the remote runspace forward PowerShell events generated on the remote computer. When the PowerShell client receives this message, it adds the event to the local event queue. In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10). Event identifier Property name: PSEventArgs.EventIdentifier.
Property type: Signed int (see section 2.2.5.1.11). Source identifier
Property name: PSEventArgs.SourceIdentifier.
Time when event was generated
Property name: PSEventArgs.TimeGenerated.
Property type: Date/Time (see section 2.2.5.1.4). Sender of the event
PR
EL
Property type: any object Event arguments Property type: any object Message data Property type: any object
Property name: PSEventArgs.Sender.
Property name: PSEventArgs.SourceArgs.
Property name: PSEventArgs.MessageData.
IM
Property type: String (see section 2.2.5.1.1).
IN
26 / 105
AR
2.2.2.14 DataType: 0x00021008: Report a User-defined Event from Remote Runspace
Name of the computer where the event was fired. Property name: PSEventArgs.ComputerName. Property type: String (see section 2.2.5.1.1). ID of the runspace. Property name: PSEventArgs.RunspaceId. Property type: GUID (see section 2.2.5.1.18). Example:
2.2.2.15
DataType: 0x00021009: Application Private Data
PR
EL
Application private data Example:
Property name: ApplicationPrivateData Property type: A Primitive Dictionary (see section 2.2.3.19) or Null Value (see section 2.2.5.1.20).
<Obj RefId="0"> <MS> <Nil N="ApplicationPrivateData" /> </MS>
IM
<Obj RefId="15"> <MS> <I32 N="PSEventArgs.EventIdentifier">5</I32> <S N="PSEventArgs.SourceIdentifier">SourceIdentifier</S> <DT N="PSEventArgs.TimeGenerated">2008-10-01T14:07:10.5219404-07:00</DT> <Ref N="PSEventArgs.Sender" RefId="3" /> <Obj N="PSEventArgs.SourceArgs" RefId="16"> <TNRef RefId="1" /> <LST> <Ref RefId="3" /> <Obj RefId="17"> <TNRef RefId="2" /> <ToString>System.Timers.ElapsedEventArgs</ToString> <Props> <DT N="SignalTime">2008-10-01T14:07:10.5219404-07:00</DT> </Props> </Obj> </LST> </Obj> <S N="PSEventArgs.MessageData">MessageData</S> <Nil N="PSEventArgs.ComputerName" /> <G N="PSEventArgs.RunspaceId">9b817325-ee22-4612-a6a8-7b54070084ed</G> </MS> </Obj>
IN
AR
27 / 105
</Obj>
2.2.2.16 DataType: 0x00021100: Method Call on the Host Associated with the RunspacePool
Property name: ci. Property type: Signed long (see section 2.2.5.1.13). Host method identifier Property name: mi.
Property type: Host Method Identifier (see section 2.2.3.17). Parameters for the method Property name: mp.
Property type: Host Parameters Encoded (see section 2.2.6). Example:
PR
<Obj RefId="0"> <MS> <I64 N="ci">1</I64> <Obj N="mi" RefId="1"> <TN RefId="0"> <T>System.Management.Automation.Remoting.RemoteHostMethodId</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>ReadLine</ToString> <I32>11</I32> </Obj> <Obj N="mp" RefId="2"> <TN RefId="1"> <T>System.Collections.ArrayList</T> <T>System.Object</T> </TN> <LST /> </Obj> </MS> </Obj>
EL
IM
IN
AR
28 / 105
Call ID
2.2.2.17 DataType: 0x00021101: Response from the Host Associated with the RunspacePool
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10). Call ID Property name: ci.
ID of the host method that the response is coming from Property name: mi. Property type: Host Method Identifier (see section 2.2.3.17). Return value of the method Property name: mr.
Property type: Host Parameter Encoding in Host Method Calls (see section 2.2.6). Exception thrown by a host method invocation Property name: me.
Property type: Exception as ErrorRecord (see section 2.2.3.13)
Note that if either the mr property or the mi property is present, the other may be omitted. Example:
PR
EL
2.2.2.18
<Obj RefId="11"> <MS> <S N="mr">Line read from the host</S> <I64 N="ci">1</I64> <Obj N="mi" RefId="12"> <TN RefId="4"> <T>System.Management.Automation.Remoting.RemoteHostMethodId</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>ReadLine</ToString> <I32>11</I32> </Obj> </MS> </Obj>
DataType: 0x00041002: Input to a PowerShell Pipeline on the Server
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing the input object. The object can be of any type.
IM
IN
AR
29 / 105
Property type: Signed long (see section 2.2.5.1.13).
2.2.2.19 DataType: 0x00041003: Close the Input Collection for the PowerShell Pipeline on the Server
2.2.2.20
DataType: 0x00041004: Output of a PowerShell Pipeline on the Server
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing the output object. The object can be of any type.
Example:
PR
<Obj RefId="0"> <TN RefId="0"> <T>System.Management.Automation.ErrorRecord</T> <T>System.Object</T> </TN> <ToString>Can't open file</ToString> <MS> <Obj N="Exception" RefId="1"> <TN RefId="1"> <T>System.IO.IOException</T> <T>System.SystemException</T> <T>System.Exception</T> <T>System.Object</T> </TN> <ToString>System.IO.IOException: Can't open file</ToString> <Props> <SN="Message"> Can't open file</S><Obj N="Data" RefId="2"> <TN RefId="2"> <T>System.Collections.ListDictionaryInternal</T> <T>System.Object</T> </TN> <DCT /> </Obj><Nil N="InnerException" /><Nil N="TargetSite" /><Nil N="StackTrace" /><Nil N="HelpLink" /><Nil N="Source" /> </Props> </Obj> <Nil N="TargetObject" /> <S N="FullyQualifiedErrorId">System.IO.IOException</S> <Obj N="InvocationInfo" RefId="3"> <TN RefId="3"> <T>System.Management.Automation.InvocationInfo</T> <T>System.Object</T> </TN> <ToString>System.Management.Automation.InvocationInfo</ToString> <Props> <Obj N="MyCommand" RefId="4"> <TN RefId="4"> <T>System.Management.Automation.ScriptInfo</T>
EL
IM
IN
AR
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing the ErrorRecord (see section 2.2.3.15).
Y
30 / 105
2.2.2.21 Server
DataType: 0x00041005: Error Record from a PowerShell Pipeline on the
PR
<T>System.Collections.ObjectModel.ReadOnlyCollection`1[[System.Management.Automation.CommandP arameterSetInfo, System.Management.Automation, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]</T> <T>System.Object</T> </TN> <LST> <S></S> </LST> </Obj> </Props> </Obj> <Obj N="BoundParameters" RefId="6"> <TN RefId="6"> <T>System.Collections.Generic.Dictionary`2[[System.String, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089],[System.Object, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <DCT /> </Obj> <Obj N="UnboundArguments" RefId="7"> <TN RefId="7"> <T>System.Collections.Generic.List`1[[System. Object, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <LST/> </Obj> <I32 N="ScriptLineNumber">0</I32> <I32 N="OffsetInLine">0</I32> <S N="ScriptName"></S> <S N="Line"></S> <S N="PositionMessage"></S> <S N="InvocationName"></S> <I32 N="PipelineLength">1</I32> <I32 N="PipelinePosition">1</I32> false <S N="CommandOrigin">Runspace</S> </Props> </Obj> <I32 N="ErrorCategory_Category">1</I32> <S N="ErrorCategory_Activity">Write-Error</S> <S N="ErrorCategory_Reason">IOException</S> <S N="ErrorCategory_TargetName"></S> <S N="ErrorCategory_TargetType"></S> <S N="ErrorCategory_Message">OpenError: (:) [Write-Error], IOException</S>
EL
IM
IN
AR
Y
31 / 105
<T>System.Management.Automation.CommandInfo</T> <T>System.Object</T> </TN> <ToString>write-error -category OpenError -exception (new-object io.ioexception "Can't open file") </ToString> <Props> <SBKN="ScriptBlock"> write-error -category OpenError -exception (new-object io.ioexception "Can't open file") </SBK><S N="Definition">write-error -category OpenError -exception (new-object io.ioexception "Can't open file") </S><S N="Name"></S><S N="CommandType">Script</S><S N="Visibility">Public</S><S N="ModuleName"></S><Nil N="Module" /><Obj N="ParameterSets"RefId="5"> <TN RefId="5">
PR
true <Ref N="InvocationInfo_BoundParameters" RefId="6" /> <Obj N="InvocationInfo_CommandOrigin" RefId="8"> <TN RefId="8"> <T>System.Management.Automation.CommandOrigin</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Runspace</ToString> <I32>0</I32> </Obj> false <S N="InvocationInfo_InvocationName"></S> <S N="InvocationInfo_Line"></S> <I32 N="InvocationInfo_OffsetInLine">0</I32> <Obj N="InvocationInfo_PipelineIterationInfo" RefId="9"> <TN RefId="9"> <T>System.Int32[]</T> <T>System.Array</T> <T>System.Object</T> </TN> <LST> <I32>0</I32> <I32>0</I32> </LST> </Obj> <I32 N="InvocationInfo_PipelineLength">1</I32> <I32 N="InvocationInfo_PipelinePosition">1</I32> <S N="InvocationInfo_PositionMessage"></S> <I32 N="InvocationInfo_ScriptLineNumber">0</I32> <S N="InvocationInfo_ScriptName"></S> <Ref N="InvocationInfo_UnboundArguments" RefId="7" /> <Obj N="CommandInfo_CommandType" RefId="10"> <TN RefId="10"> <T>System.Management.Automation.CommandTypes</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Script</ToString> <I32>64</I32> </Obj> <S N="CommandInfo_Definition">write-error -category OpenError -exception (new-object io.ioexception "Can't open file") </S> <S N="CommandInfo_Name"></S> <Obj N="CommandInfo_Visibility" RefId="11"> <TN RefId="11"> <T>System.Management.Automation.SessionStateEntryVisibility</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Public</ToString> <I32>0</I32> </Obj> <Obj N="PipelineIterationInfo" RefId="12"> <TN RefId="12">
EL
IM
IN
AR
32 / 105
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10). State information of PowerShell Property name: PipelineState.
Property type: PSInvocationState (see section 2.2.3.5).
Optional error information (included only if this message is triggered by an error). Property name: ExceptionAsErrorRecord.
Property type: Exception as ErrorRecord (see section 2.2.3.13) Example:
PR
<Obj RefId="0"> <MS> <I32 N="PipelineState">3</I32> <Obj N="ExceptionAsErrorRecord" RefId="1"> <TN RefId="0"> <T>System.Management.Automation.ErrorRecord</T> <T>System.Object</T> </TN> <ToString>The pipeline has been stopped.</ToString> <MS> <Obj N="Exception" RefId="2"> <TN RefId="1"> <T>System.Management.Automation.PipelineStoppedException</T> <T>System.Management.Automation.RuntimeException</T> <T>System.SystemException</T> <T>System.Exception</T> <T>System.Object</T> </TN> <ToString>System.Management.Automation.PipelineStoppedException: The pipeline has been stopped._x000D__x000A_ at System.Management.Automation.Internal.PipelineProcessor.SynchronousExecuteEnumerate(Object input, Hashtable errorResults, Boolean enumerate) in c:\e\win7_powershell\admin\monad\src\engine\pipeline.cs:line 586</ToString> <Props>
EL
IM
IN
AR
2.2.2.22 DataType: 0x00041006: State Information of a PowerShell Pipeline on the Server
Y
33 / 105
<T>System.Collections.ObjectModel.ReadOnlyCollection`1[[System.Int32, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <LST> <I32>0</I32> <I32>0</I32> </LST> </Obj> <Nil N="PSMessageDetails" /> </MS> </Obj>
2.2.2.23 Server
DataType: 0x00041007: Debug Record from a PowerShell Pipeline on the
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing the debug record (see section 2.2.3.16). Example:
PR
EL
<Obj RefId="0"> <TN RefId="0"> <T>System.Management.Automation.DebugRecord</T> <T>System.Management.Automation.InformationalRecord</T> <T>System.Object</T> </TN> <ToString>Debug message</ToString> <MS> <S N="InformationalRecord_Message">Debug message</S> true <Obj N="InvocationInfo_BoundParameters" RefId="1"> <TN RefId="1">
IM
IN
<S N="ErrorRecord">The pipeline has been stopped.</S> <S N="StackTrace"> at System.Management.Automation.Internal.PipelineProcessor.SynchronousExecuteEnumerate(Object input, Hashtable errorResults, Boolean enumerate) in c:\e\win7_powershell\admin\monad\src\engine\pipeline.cs:line 586</S> <S N="Message">The pipeline has been stopped.</S> <Obj N="Data" RefId="3"> <TN RefId="2"> <T>System.Collections.ListDictionaryInternal</T> <T>System.Object</T> </TN> <DCT /> </Obj> <Nil N="InnerException" /> <S N="TargetSite">System.Array SynchronousExecuteEnumerate(System.Object, System.Collections.Hashtable, Boolean)</S> <Nil N="HelpLink" /> <S N="Source">System.Management.Automation</S> </Props> </Obj> <Nil N="TargetObject" /> <S N="FullyQualifiedErrorId">PipelineStopped</S> <Nil N="InvocationInfo" /> <I32 N="ErrorCategory_Category">14</I32> <S N="ErrorCategory_Activity"></S> <S N="ErrorCategory_Reason">PipelineStoppedException</S> <S N="ErrorCategory_TargetName"></S> <S N="ErrorCategory_TargetType"></S> <S N="ErrorCategory_Message">OperationStopped: (:) [], PipelineStoppedException</S> false </MS> </Obj> </MS> </Obj>
AR
Y
34 / 105
PR
<T>System.Collections.Generic.Dictionary`2[[System.String, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089],[System.Object, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <DCT> <En> <S N="Key">Debug</S> <Obj N="Value" RefId="2"> <TN RefId="2"> <T>System.Management.Automation.SwitchParameter</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>True</ToString> <Props> true </Props> </Obj> </En> <En> <S N="Key">Message</S> <S N="Value">Debug message</S> </En> </DCT> </Obj> <Obj N="InvocationInfo_CommandOrigin" RefId="3"> <TN RefId="3"> <T>System.Management.Automation.CommandOrigin</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Runspace</ToString> <I32>0</I32> </Obj> false <S N="InvocationInfo_InvocationName">write-debug</S> <S N="InvocationInfo_Line"></S> <I32 N="InvocationInfo_OffsetInLine">0</I32> <Obj N="InvocationInfo_PipelineIterationInfo" RefId="4"> <TN RefId="4"> <T>System.Int32[]</T> <T>System.Array</T> <T>System.Object</T> </TN> <LST> <I32>0</I32> <I32>1</I32> </LST> </Obj> <I32 N="InvocationInfo_PipelineLength">1</I32> <I32 N="InvocationInfo_PipelinePosition">1</I32> <S N="InvocationInfo_PositionMessage"></S> <I32 N="InvocationInfo_ScriptLineNumber">0</I32> <S N="InvocationInfo_ScriptName"></S> <Obj N="InvocationInfo_UnboundArguments" RefId="5"> <TN RefId="5">
EL
IM
IN
AR
Y
35 / 105
PR
EL
Example:
2.2.2.24 DataType: 0x00041008: Verbose Record from a PowerShell Pipeline on the Server
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing the verbose record (see section 2.2.3.16).
<Obj RefId="0"> <TN RefId="0"> <T>System.Management.Automation.VerboseRecord</T> <T>System.Management.Automation.InformationalRecord</T>
IM
<T>System.Collections.Generic.List`1[[System.Object, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <LST /> </Obj> <Obj N="CommandInfo_CommandType" RefId="6"> <TN RefId="6"> <T>System.Management.Automation.CommandTypes</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Cmdlet</ToString> <I32>8</I32> </Obj> <S N="CommandInfo_Definition">Write-Debug [-Message] <String> [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]_x000D__x000A_</S> <S N="CommandInfo_Name">Write-Debug</S> <Obj N="CommandInfo_Visibility" RefId="7"> <TN RefId="7"> <T>System.Management.Automation.SessionStateEntryVisibility</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Public</ToString> <I32>0</I32> </Obj> <Obj N="InformationalRecord_PipelineIterationInfo" RefId="8"> <TN RefId="8"> <T>System.Collections.ObjectModel.ReadOnlyCollection`1[[System.Int32, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <LST> <I32>0</I32> <I32>1</I32> </LST> </Obj> </MS> </Obj>
IN
AR
Y
36 / 105
PR
<T>System.Object</T> </TN> <ToString>Verbose message</ToString> <MS> <S N="InformationalRecord_Message">Verbose message</S> true <Obj N="InvocationInfo_BoundParameters" RefId="1"> <TN RefId="1"> <T>System.Collections.Generic.Dictionary`2[[System.String, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089],[System.Object, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <DCT> <En> <S N="Key">Verbose</S> <Obj N="Value" RefId="2"> <TN RefId="2"> <T>System.Management.Automation.SwitchParameter</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>True</ToString> <Props> true </Props> </Obj> </En> <En> <S N="Key">Message</S> <S N="Value">Verbose message</S> </En> </DCT> </Obj> <Obj N="InvocationInfo_CommandOrigin" RefId="3"> <TN RefId="3"> <T>System.Management.Automation.CommandOrigin</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Runspace</ToString> <I32>0</I32> </Obj> false <S N="InvocationInfo_InvocationName">write-verbose</S> <S N="InvocationInfo_Line"></S> <I32 N="InvocationInfo_OffsetInLine">0</I32> <Obj N="InvocationInfo_PipelineIterationInfo" RefId="4"> <TN RefId="4"> <T>System.Int32[]</T> <T>System.Array</T> <T>System.Object</T> </TN> <LST> <I32>0</I32> <I32>1</I32> </LST> </Obj>
EL
IM
IN
AR
Y
37 / 105
PR
EL
<I32 N="InvocationInfo_PipelineLength">1</I32> <I32 N="InvocationInfo_PipelinePosition">1</I32> <S N="InvocationInfo_PositionMessage"></S> <I32 N="InvocationInfo_ScriptLineNumber">0</I32> <S N="InvocationInfo_ScriptName"></S> <Obj N="InvocationInfo_UnboundArguments" RefId="5"> <TN RefId="5"> <T>System.Collections.Generic.List`1[[System.Object, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <LST /> </Obj> <Obj N="CommandInfo_CommandType" RefId="6"> <TN RefId="6"> <T>System.Management.Automation.CommandTypes</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System. Object</T> </TN> <ToString>Cmdlet</ToString> <I32>8</I32> </Obj> <S N="CommandInfo_Definition">Write-Verbose [-Message] <String> [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]_x000D__x000A_</S> <S N="CommandInfo_Name">Write-Verbose</S> <Obj N="CommandInfo_Visibility" RefId="7"> <TN RefId="7"> <T>System.Management.Automation.SessionStateEntryVisibility</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Public</ToString> <I32>0</I32> </Obj> <Obj N="InformationalRecord_PipelineIterationInfo" RefId="8"> <TN RefId="8"> <T>System.Collections.ObjectModel.ReadOnlyCollection`1[[System.Int32, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <LST> <I32>0</I32> <I32>1</I32> </LST> </Obj> </MS> </Obj>
2.2.2.25 DataType: 0x00041009: Warning Record from a PowerShell Pipeline on the Server
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing the warning record (see section 2.2.3.16).
IM
IN
AR
Y
38 / 105
Example:
<Obj RefId="0"> <TN RefId="0"> <T>System.Management.Automation.WarningRecord</T> <T>System.Management.Automation.InformationalRecord</T> <T>System.Object</T> </TN> <ToString>Warning message</ToString> <MS> <S N="InformationalRecord_Message">Warning message</S> true <Obj N="InvocationInfo_BoundParameters" RefId="1"> <TN RefId="1"> <T>System.Collections.Generic.Dictionary`2[[System.String, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089],[System.Object, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <DCT> <En> <S N="Key">Message</S> <S N="Value">Warning message</S> </En> </DCT> </Obj> <Obj N="InvocationInfo_CommandOrigin" RefId="2"> <TN RefId="2"> <T>System.Management.Automation.CommandOrigin</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Runspace</ToString> <I32>0</I32> </Obj> false <S N="InvocationInfo_InvocationName">write-warning</S> <S N="InvocationInfo_Line"></S> <I32 N="InvocationInfo_OffsetInLine">0</I32> <Obj N="InvocationInfo_PipelineIterationInfo" RefId="3"> <TN RefId="3"> <T>System.Int32[]</T> <T>System.Array</T> <T>System.Object</T> </TN> <LST> <I32>0</I32> <I32>1</I32> </LST> </Obj> <I32 N="InvocationInfo_PipelineLength">1</I32> <I32 N="InvocationInfo_PipelinePosition">1</I32> <S N="InvocationInfo_PositionMessage"></S> <I32N="InvocationInfo_ScriptLineNumber"> 0</I32><S N="InvocationInfo_ScriptName"></S><Obj N="InvocationInfo_UnboundArguments" RefId="4"> <TN RefId="4">
PR
EL
IM
IN
AR
Y
39 / 105
PR
EL
Example:
2.2.2.26 DataType: 0x00041010: Progress Record from a PowerShell Pipeline on the Server
In messages of this data type, the data field is UTF-8 encoded XML, equivalent to the XML created by serializing the progress record (see section 2.2.5.1.25).
<PR> <AV>activity description</AV> <AI>1</AI> <Nil /> <PI>-1</PI> <PC>-1</PC> <T>Processing</T> <SR>-1</SR>
IM
<T>System.Collections.Generic.List`1[[System.Object, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <LST /> </Obj><Obj N="CommandInfo_CommandType" RefId="5"> <TN RefId="5"> <T>System.Management.Automation.CommandTypes</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Cmdlet</ToString> <I32>8</I32> </Obj><S N="CommandInfo_Definition">Write-Warning [-Message] <String> [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]_x000D__x000A_</S><S N="CommandInfo_Name">Write-Warning</S><Obj N="CommandInfo_Visibility" RefId="6"> <TN RefId="6"> <T>System.Management.Automation.SessionStateEntryVisibility</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Public</ToString> <I32>0</I32> </Obj><Obj N="InformationalRecord_PipelineIterationInfo" RefId="7"> <TN RefId="7"> <T>System.Collections.ObjectModel.ReadOnlyCollection`1[[System.Int32, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]]</T> <T>System.Object</T> </TN> <LST> <I32>0</I32> <I32>1</I32> </LST> </Obj> </MS> </Obj>
IN
AR
Y
40 / 105
<SD>status description</SD> </PR>
2.2.2.27
DataType: 0x00041012: Stop a PowerShell Pipeline on the Server
In messages of this data type, the data field is formatted the same way as it is for messages of the DataType: 0x00021100: Method call on the host associated with the runspacepool.
In messages of this data type, the data field is formatted the same way as it is for messages of the DataType: 0x00021101: Response from the host associated with the RunspacePool data type (see section 2.2.2.16).
2.2.3
Other Object Types
2.2.3.1
Coordinates
This data type represents a position in the screen buffer of a user interface. This data type is a complex object (see section 2.2.5.2 and 2.2.5.2.9) with the following adapted properties (see section 2.2.5.3.4.1): X coordinate (0 is the left-most column). Property name: X.
Property type: Signed int (see section 2.2.5.1.11). Y coordinate (0 is the topmost row). Property name: Y.
PR
EL
2.2.3.2 Size
Width of an area. Property name: Width.
Property type: Signed int (see section 2.2.5.1.11).
This data type represents a size of a screen buffer area of a user interface.
This data type is a complex object (see section 2.2.5.2 and 2.2.5.2.9) with the following adapted properties (see section 2.2.5.3.5.1):
Property type: Signed int (see section 2.2.5.1.11).
IM
IN
The following sections specify other object types used by the PowerShell Remoting Protocol.
AR
2.2.2.29 DataType: 0x00041101: Response from the Host Associated with the PowerShell Pipeline on the Server
Y
41 / 105
2.2.2.28 DataType: 0x00041100: Method Call on the Host Associated with the PowerShell Pipeline on the Server
Height of an area. Property name: Height. Property type: Signed int (see section 2.2.5.1.11).
2.2.3.3
Color
This data type represents a color used in a user interface.
Value 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Meaning DarkBlue DarkGreen DarkCyan DarkRed DarkMagenta DarkYellow Gray
EL
2.2.3.4 RunspacePoolState
Value 0 1 2 Release: Thursday, May 21, 2009
This data type represents the state of a RunspacePool. This data type is a signed int (see section 2.2.5.1.11) with the following allowed values.
Meaning BeforeOpen Opening Opened
PR
IM
Cyan Red Magenta Yellow White 42 / 105
IN
DarkGray Blue Green
AR
This data type is an enum (see section 2.2.5.2.8) based on the default underlying type (signed int; see section 2.2.5.1.11) that defines the following named constants.
Value 3 4 5
Meaning Closed Closing Broken
2.2.3.5
PSInvocationState
This data type is a signed int (see section 2.2.5.1.11) with the following allowed values.
Value 0 1 2 3 4 5 Meaning Not started Running Stopping Stopped Completed Failed
2.2.3.6
PSThreadOptions
This data type represents threading options for the server.
Value 0 1 2 3
PR
EL
2.2.3.7 ApartmentState
Value 0 Meaning Release: Thursday, May 21, 2009
This data type represents the state of a COM apartment.
IM
Meaning Default UseNewThread ReuseThread UseCurrentThread
This data type is an enum (see section Contents of enums) based on the default underlying type (signed int; see section 2.2.5.1.11) that defines the following named constants.
Single threaded apartment (STA)
IN
AR
43 / 105
This data type represents a state of a pipeline invocation.
Value 1 2
Meaning Multi threaded apartment (MTA) Unknown
2.2.3.8
RemoteStreamOptions
This data type represents options of a remote stream. This data type is an enum (see section 2.2.5.2.8) based on the default underlying type (signed int; see section 2.2.5.1.11) that defines the following named constants (which can be combined by adding the associated values).
Value 0x01 0x02 0x04 0x08 Meaning
Add invocation information to ErrorRecord objects
Add invocation information to WarningRecord objects Add invocation information to DebugRecord objects
Add invocation information to VerboseRecord objects
2.2.3.9
ErrorCategory
This data type represents a category of an error.
Value NotSpecified OpenError CloseError DeviceError Meaning 0 1 2 3 4 5 6 7 8 9 10 11
PR
EL
InvalidArgument InvalidData InvalidOperation InvalidResult InvalidType MetadataError NotImplemented [MS-PSRP] v20090521 PowerShell Remoting Protocol Specification Copyright 2009 Microsoft Corporation. Release: Thursday, May 21, 2009
DeadlockDetected
IM
IN
AR
44 / 105
Value NotInstalled ObjectNotFound OperationStopped OperationTimeout SyntaxError ParserError PermissionDenied ResourceBusy ResourceExists ResourceUnavailable ReadError SecurityError
Meaning 12 13 14 15
17 18 19 20 21 22 25
2.2.3.10
TimeZone
This data type represents a time zone.
This data type is an array of bytes (see section 2.2.5.1.17) built using the algorithm that follows. Construct a TimeZone object as described in the MSDN documentation at [MSDN-TZCLASS].
2.2.3.11
PowerShell Pipeline
This data type represents a pipeline of Commands to be executed. A PowerShell pipeline is an object with the following extended properties (see section 2.2.5.2.10).
PR
EL
Property name: IsNested. Commands in the pipeline. Property name: Commands.
Boolean, indicating if this is a nested pipeline.
Property type: List (see section List) of individual command objects (see section 2.2.3.12) in the order they appear in the pipeline.
IM
Once a TimeZone object is constructed, serialize the object using a BinaryFormatter specified in [MSDN-BinaryFormatter].
IN
AR
45 / 105
16
2.2.3.12
Command
This data type represents a command in a pipeline. Command is an object with the following extended properties (see section 2.2.5.2.10). The name of command or text of script to execute. (The format of a script is unspecified, as the PowerShell Remoting Protocol directly passes the script to the remote runspace, which in turn parses and executes the script.)
Property type: String (see section 2.2.5.1.1). A Boolean indicating if command to execute is a script. Property name: IsScript. Property type: Boolean (see section 2.2.5.1.3).
A Boolean indicating if PowerShell MUST use local scope or global scope to invoke the commands. Property name: UseLocalScope.
Property type: Boolean (see section 2.2.5.1.3) or Null value (see section 2.2.5.1.20).
A Boolean indicating if error and output streams MUST be merged on command invocation. This property SHOULD have the same value as MergeToResults. Property name: MergeMyResults.
Property name: MergeToResults.
Property type: Boolean (see section 2.2.5.1.3). A Boolean indicating if execution MUST merge error and output streams coming from previous commands in the pipeline.
PR
EL
Arguments of the command. Property name: Args.
Property name: MergePreviousResults.
Property type: List (see section 2.2.5.2.7.3) of individual command parameter objects (see section 2.2.3.12) in the order they appear in the command invocation.
2.2.3.13
Command Parameter
This data type represents a parameter of a command. A command parameter is an object with the following extended properties (see section 2.2.5.2.10).
46 / 105
IM
A Boolean indicating if error and output streams MUST be merged on command invocation. This property SHOULD have the same value as MergeMyResults.
IN
AR
Property name: CommandText.
Name of the parameter. Property name: N. Property type: String (see section 2.2.5.1.1) if the parameter has a name; otherwise a Null value (see section 2.2.5.1.20). Parameter value. Property name: V.
2.2.3.14
Exception as ErrorRecord
An exception is encoded in the following way and the resulting object is substituted in the remote data object's data field. 1. If the exception implements the interface System.Management.Automation.IContainsErrorRecord as defined in the PowerShell public API, then the error record is extracted directly. 2. If the exception does not implement the interface, then a new error record is constructed (as described in section 2.2.3.15) with an error ID and category defined from the following table.
ErrorId
RemotePSInvocationStateInfoReason RemoteRunspaceStateInfoReason
RemoteHostExecutionException
IM
Description
2.2.3.15
HostInfo
This data type represents host information.
PR
EL
Element _hostDefaultData _isHostNull _isHostUINull _isHostRawUINull Release: Thursday, May 21, 2009
The HostInfo message is used by a PowerShell client to specify information about the host. An example of this message is provided in section 4.1.1.
The following table describes each element in the preceding XML element.
A dictionary of elements with host related information - see PowerShell serialization, section 2.2.5.1, on how to serialize dictionaries. True or False. If the host object associated with the runspace/RunspacePool is null. True or False. If the UI implementation of the host interface is null. True or False. If the RawUI implementation of the host interface is null.
IN
Category (as specified in section ErrorCategory ) NotSpecified NotSpecified NotSpecified
AR
Comments Created for Pipeline state information. Created for runspace state information. Created for host execution exception.
This data type represents an exception encoded as an ErrorRecord type (see section 2.2.3.15).
Y
47 / 105
Property type: any type (depends on the command).
Element _useRunspaceHost
Description True or False. Whether a PowerShell invocation MUST use the host associated with its associated RunspacePool.
The following are the elements which MUST be included in the _hostDefaultData dictionary.
Data ForegroundColor BackgroundColor CursorPosition WindowPosition CursorSize BufferSize WindowSize MaxWindowSize MaxPhysicalWindowSize WindowTitle Host data type Color - see section 2.2.3.3 Color - see section 2.2.3.3 Coordinates - see section 2.2.3.1 Coordinates - see section 2.2.3.1 Int32 - see section 2.2.5.1.11 Size - see section 2.2.3.2 Size - see section 2.2.3.2 Size - see section 2.2.3.2 Size - see section 2.2.3.2 Key (for Dictionary
1 2 3 4 5 6 7 8 9
String - see section 2.2.5.1.1
2.2.3.16
ErrorRecord
This data type represents information about an error.
Property name Exception
TargetObject
EL
FullyQualifiedErrorId InvocationInfo String ErrorCategory_Category ErrorCategory_Activity ErrorCategory_Reason String String Release: Thursday, May 21, 2009
PR
IM
Property type Complex object Arbitrary object Complex object Signed int
ErrorRecord is an object with the following extended properties (see section 2.2.5.2.10).
IN
Property value A text description of the error.
An object derived from System.Exception that describes the error. The object against which the error occurred.
A String which uniquely identifies this error condition. An object of type System.Management.Automation.InvocationInfo, which identifies the cmdlet, script, or other command which caused the error. ErrorCategory (see section 2.2.3.9). A text description of the operation which encountered the error.
AR
48 / 105
Property name ErrorCategory_TargetName ErrorCategory_TargetType ErrorCategory_Message ErrorDetails_Message ErrorDetails_ RecommendedAction SerializeExtendedInfo
Property type String String String String String
Property value A text description of the target object. A text description of the type of the target object. A concise string which categorizes the error. A detailed error message. (this property is not included if there are no error details associated with the ErrorRecord).
A text describing the recommended action in the event that this error occurs. (this property is not included if there are no error details associated with the ErrorRecord). A Boolean value which is set to True if InvocationInfo and PipelineIterationInfo are serialized.
Boolean
< InvocationInfo-specific properties (see the following in the same section) if SerializeExtendedInfo = true > PipelineIterationInfo List of signed ints
The status of the pipeline when this record was created. Included only if SerializedExtendedInfo is true
InvocationInfo-specific extended properties that are included when serializing ErrorRecord and when SerializeExtendedInfo property is set to true.
Property name Property type The property value. The command line parameters grouped by parameter name. Whether the command was being invoked inside the runspace or if it was an external request. There are two possible values: Runspace=0, Internal=1). A Boolean value set to True if this command is expecting input. The command name used to invoke this command; if invoked through an alias, then this is the alias name. The text of the line that contained this command invocation. The command's character offset in the InvocationInfo_Line. If the command was executed directly through the host interfaces, this is 1. The index of the ProcessRecord iteration for each of the commands
InvocationInfo_CommandLineParameters
InvocationInfo_CommandOrigin
InvocationInfo_ExpectingInput
EL
InvocationInfo_InvocationName InvocationInfo_Line InvocationInfo_OffsetInLine InvocationInfo_PipelineIterationInfo [MS-PSRP] v20090521 PowerShell Remoting Protocol Specification Copyright 2009 Microsoft Corporation. Release: Thursday, May 21, 2009
PR
IM
Boolean String String Signed int
IN
Dictionary from strings to arbitrary objects. CommandOrigin enum (see section 2.2.5.2.8 for serialization of enums). List of signed ints
AR
49 / 105
Property name
Property type
The property value. in the pipeline. All the commands in a given pipeline share the same PipelineIterationInfo.
InvocationInfo_PipelineLength
Signed int
The number of elements in the pipeline. Which element this command was in the containing pipeline. A formatted message indicating where the cmdlet appeared in the command line.
InvocationInfo_PipelinePosition
Signed int
InvocationInfo_PositionMessage
String
InvocationInfo_ScriptLineNumber
Signed int
InvocationInfo_ScriptName
String
InvocationInfo_UnboundArguments
List of arbitrary objects
InformationalRecord (that is, DebugRecord, WarningRecord or VerboseRecord) is a structure that contains additional information that a cmdlet or script can output in addition to the regular data output. When serializing an InformationalRecord (DebugRecord, WarningRecord or VerboseRecord), the following extended properties (see section 2.2.5.2.10) are added to the object.
Property name
IM
String Boolean
InformationalRecord_Message
InformationalRecord_SerializeInvocationInfo
EL
Property name Release: Thursday, May 21, 2009
< InvocationInfo-specific properties (see below in the same section) if InformationalRecord_SerializeInvocationInfo = true > InformationalRecord_PipelineIterationInfo List of signed ints The status of the pipeline when this record was created. Included only if InvocationInfo is serialized as well.
PR
InvocationInfo-specific extended properties that are included when serializing InformationalRecord (DebugRecord, WarningRecord, VerboseRecord) and when InformationalRecord_SerializeInvocationInfo property is set to true.
Property type Dictionary from strings The property value. The command line parameters
InvocationInfo_CommandLineParameters
IN
Property type
2.2.3.17
InformationalRecord (DebugRecord, WarningRecord or VerboseRecord)
AR
The name of the script containing invocation of the command. A list of the arguments that were not bound to any parameter. Property value The message associated with the informational record. A Boolean value set to True if InvocationInfo is serialized.
The line number in the executing script that contained this command.
Y
50 / 105
Property name
Property type to arbitrary objects
The property value. grouped by parameter name. Whether the command was being invoked inside the runspace or if it was an external request. There are two possible values: Runspace=0, Internal=1). A Boolean value set to True if this command is expecting input.
InvocationInfo_CommandOrigin
CommandOrigin enum (see section Contents of enums for serialization of enums). Boolean
InvocationInfo_ExpectingInput
InvocationInfo_InvocationName
String
InvocationInfo_Line InvocationInfo_OffsetInLine
String Signed int
InvocationInfo_PipelineIterationInfo
InvocationInfo_PipelineLength
InvocationInfo_PipelinePosition
IM
Signed int String Signed int String List of arbitrary objects
InvocationInfo_PositionMessage
InvocationInfo_ScriptLineNumber
EL
InvocationInfo_ScriptName InvocationInfo_UnboundArguments
2.2.3.18
Host Method Identifier
PR
This data type represents a method to be executed on a host. This data type is an enum (as specified in section 2.2.5.2.8) based on the default underlying type (signed int, as specified in section 2.2.5.1.11) that defines the named constants listed in the following tables.
IN
List of signed ints Signed int
AR
The text of the line that contained this command invocation. The number of elements in the pipeline. Which element this command was in the containing pipeline. A formatted message indicating where the cmdlet appeared in the command line. The name of the script containing invocation of the command. A list of the arguments that were not bound to any parameter.
The command name used to invoke this command; if invoked through an alias, then this is the alias name.
The command's character offset in the InvocationInfo_Line. If the command was executed directly through the host interfaces, this is 1. The index of the ProcessRecord iteration for each of the commands in the pipeline. All the commands in a given pipeline share the same PipelineIterationInfo.
The line number in the executing script that contained this command.
Y
51 / 105
The following table lists the possible values for method identifiers when a PowerShell server invokes a host method on the client. What the host methods SHOULD or MUST do is also defined in the table. Host Read Only Properties
Name of Method/Property GetName GetVersion Method Identifier 1 2
Method Details MUST return a string identifying the hosting application in a user friendly way. MUST return the version number (System.Version as specified in [ECMA-335] and serialized as specified in 2.2.5) of the hosting application. MUST return a GUID that uniquely identifies the hosting application.
GetInstanceId GetCurrentCulture
3 4
MUST return the host's culture (System.Globalization.CultureInfo as specified in [ECMA-335] and serialized as specified in 2.2.5). MUST return the host's UI culture (System.Globalization.CultureInfo as specified in [ECMA-335] and serialized as specified in 2.2.5).
GetCurrentUICulture
Host Methods
An example of this message is provided in section 4.1.2.

Name of Method/Property SetShouldExit Method Identifier 6
EnterNestedPrompt ExitNestedPrompt
EL
NotifyEndApplication 10
NotifyBeginApplication
Host UI Methods
PR
Name of Method/Property ReadLine
ReadLineAsSecureString
IM
7 8 9 Method Identifier 11 12
IN
Method Details Method Details
SHOULD shut down the hosting application and close the current PowerShell runspace. SHOULD interrupt the current pipeline and start a nested pipeline. SHOULD stop the nested pipeline and resume the current pipeline. Called by PowerShell to indicate that it is executing a command line application. Called by PowerShell to indicate that it has finished executing a command line application.
SHOULD read a line of characters from a user and MUST return a string. SHOULD read a line of characters from a user, with the user
AR
52 / 105
Name of Method/Property
Method Identifier
Method Details input not echoed and MUST return a SecureString object (as specified in [ECMA-335] and serialized as specified in section 2.2.5).
Write1 Write2
13 14
SHOULD write specified characters on the hosting application. SHOULD write the specified characters with the specified foreground and background color on the hosting application. SHOULD write a carriage return on the hosting application. SHOULD write the specified line on the hosting application.
WriteLine1 WriteLine2 WriteLine3 WriteErrorLine
15 16 17 18
SHOULD write the specified line with the specified foreground and background color on the hosting application. SHOULD write a line to the error display of the hosting application.
WriteDebugLine
19
SHOULD write a line to the debug display of the hosting application.
WriteProgress WriteVerboseLine
20 21
SHOULD display a progress record on the hosting application.
WriteWarningLine
22
Prompt PromptForCredential1
23 24
PromptForCredential2
EL
PromptForChoice 26 Name of Method/Property Method Identifier 27 GetForegroundColor Release: Thursday, May 21, 2009
Host RawUI Read/Write Properties
An example of this message is provided in section 4.1.3.
PR
IM
25
IN
Method Details
SHOULD write a line on the verbose display of the hosting application. SHOULD write a line on the warning display of the hosting application. SHOULD prompt the user with a set of choices and MUST return a dictionary (serialized as specified in section 2.2.5). SHOULD prompt the user for entering credentials with the specified caption, message, user name and target name and MUST return a PSCredential object (serialized as specified in section 2.2.5). SHOULD prompt the user for entering credentials with the specified caption, message, username, target name, allowed credential types and options, and MUST return a PSCredential object (serialized as specified in section 2.2.5). SHOULD display a list of choices to the user and MUST return the selected option.
SHOULD return the foreground color of the hosting application and MUST return Color (as specified in section 2.2.3.3).
AR
53 / 105
Name of Method/Property SetForegroundColor GetBackgroundColor
Method Identifier 28 29
Method Details SHOULD set the foreground color of the hosting application. SHOULD return the background color of the hosting application and MUST return Color (as specified in section 2.2.3.3). SHOULD set the background color of the hosting application.
SetBackgroundColor GetCursorPosition
30 31
SetCursorPosition
32
GetWindowPosition
33
SHOULD return the position of the view window relative to the screen buffer and MUST return as Coordinates (as specified in section 2.2.3.1). SHOULD set the position of the view window relative to the screen buffer. SHOULD return the cursor size as a percentage and MUST return an integer.
SetWindowPosition
34
GetCursorSize SetCursorSize
35 36
GetBufferSize
37
SetBufferSize GetWindowSize
38 39
SetWindowSize GetWindowTitle SetWindowTitle
EL
42 Name of Method/Property GetMaxWindowSize 43 GetMaxPhysicalWindowSize 44 Release: Thursday, May 21, 2009
Host RawUI Read Only Properties

Method Identifier
PR
IM
40 41
IN
Method Details
SHOULD set the cursor size based on the percentage value specified. SHOULD return the current size of the screen buffer, measured in character cells and MUST return Size (as specified in section 2.2.3.2). SHOULD set the size of the screen buffer with the specified size in character cells. SHOULD return the current view window size and MUST return Size (as specified in section 2.2.3.2). SHOULD set the view window size based on the size specified. SHOULD return the title of the hosting application's window and MUST return a string. SHOULD set the title of the hosting application's window.
SHOULD return the maximum window size possible for the current buffer, current font, and current display hardware, and MUST return Size (as specified in section 2.2.3.2). SHOULD return the maximum window size possible for the current font and current display hardware, ignoring the current buffer size, and MUST return Size (as specified in
AR
SHOULD set the current cursor position in the hosting application.
Y
54 / 105
SHOULD return the current cursor position in the hosting application and MUST return as Coordinates (as specified in section 2.2.3.1).
Method Identifier
Method Details section 2.2.3.2).
GetKeyAvailable
45
SHOULD examine if a keystroke is waiting on the input and MUST return Boolean.
Host RawUI Methods
Method Details
ReadKey FlushInputBuffer SetBufferContents1
46 47 48
SHOULD reset the keyboard input buffer.
SHOULD copy the specified buffer cell array into the screen buffer at the specified coordinates (as specified in section 2.2.3.1).
SetBufferContents2 GetBufferContents
49 50
SHOULD copy the specified buffer cell into all the cells within the specified rectangle.
ScrollBufferContents
51
IHostSupportsInteractiveSession Methods
Name of Method/Property PushRunspace Method Identifier 52
PopRunspace
EL
Name of Method/Property GetIsRunspacePushed 54 GetRunspace 55 Release: Thursday, May 21, 2009
IHostSupportsInteractiveSession Read Only Properties

Method Identifier
PR
IHostSupportsMultipleChoiceSelect Methods
IM
53
IN
Method Details Method Details
SHOULD return the contents in a specified rectangular region of the hosting application's window and MUST return an array of buffer cells. SHOULD scroll a region on the screen buffer.
SHOULD store the current working runspace in a stack and replace it with the new specified runspace. SHOULD retrieve the last stored runspace from the stack and make it the current active runspace.
SHOULD validate if there is a runspace currently pushed on a stack in the host MUST return a Boolean. SHOULD return the currently active runspace and MUST return a runspace object.
AR
SHOULD read a key stroke from the keyboard, blocking until a key is typed .MUST return a KeyInfo.
Y
55 / 105
Method Identifier
Name of Method/Property PromptForChoiceMultipleSelection
Method Identifier 56
Method Details SHOULD display a list of choices to the user and return a list of options selected by the user and MUST return a collection (serialized as specified in section 2.2.5.2.7.3).
2.2.3.19
Primitive Dictionary
This data type represents a dictionary which contains only objects that are primitive types.
This data type is a dictionary complex object (see section 2.2.5.2.7.4) with the restriction that keys are strings (see section 2.2.5.1.1) and values are any of the following: Any primitive type from the Serialization of Primitive Types section 2.2.5.1 except ScriptBlock. An array of primitive types (except ScriptBlock). Another primitive dictionary.
2.2.4
Packet Fragment
Each message SHOULD be fragmented into one or more fragments with the fragment structure as described in the following section. Each fragment MUST fit into the payload of a WS-MAN message.
1 0 2 0 3 0
EL
Reserved
IM
... ... E S ...
IN
2 3 4 5 6 7 8 9 1 2 ObjectId FragmentId BlobLength Blob (variable)
A WS-MAN packet can carry only a fixed amount of data and serialization. The PowerShell Remoting Protocol may produce large amounts of data that may not fit into a single WS-MAN packet. To overcome this, PowerShell fragments messages before sending.
AR
3 4 5 6 7 8 9
...
PR
ObjectId (8 bytes): The ID of the object to which the packet belongs. As a deserialized object may be sent as multiple packets. the receiver will use the ObjectId to map them to the same object. MUST be greater than 0. The value is in the network-byte order.
56 / 105
Y
1
FragmentId (8 bytes): A numerical value that identifies where in the sequence of object fragments this fragment falls. The FragmentId values determine the order in which different fragments are combined to construct the PowerShell Remoting Protocol message on the receiver's end. The value is in the network-byte order. MUST start with 0. Reserved (6 bits): Reserved for future use. MUST be set to 0 and ignored upon receipt. E (1 bit): Specifies if the packet represents the End fragment. This will be used by the receiver to combine different packets for the same deserialized object. A value of 1 means the packet is End fragment. If a deserialized object fits into 1 packet, then both the E field and the S field MUST be 1
Value 0 1 Meaning Not an End fragment. End fragment.
S (1 bit): Specifies if the packet represents the Start fragment. A value of 1 means the packet is Start fragment. If a deserialized object fits into 1 packet, then both the E field and the S field MUST be 1. The Start fragment MUST have a FragmentId of 0.
Value 0 1 Meaning Not a Start fragment. Start fragment.
BlobLength (4 bytes): The length, in bytes, of actual data this packet is carrying. This field MUST be set to a value greater than or equal to 0 and less than or equal to 32768.
2.2.5
Serialization
Any object can be serialized by the PowerShell Remoting Protocol into an XML document. The resulting XML document MAY have an XML declaration, as specified in [XML] section 2.8. All XML elements and attributes described in section 2.2.5 belong to the following XML namespace:
PR
EL
2.2.5.1
http://schemas.microsoft.com/powershell/2004/04
Serialization MAY indicate the XML namespace [XML Namespaces1.0] using the xmlns attribute.
The name of the root XML element depends on the type of the element being serialized. Serialization of Primitive Types (section 2.2.5.1) and Serialization of Complex Objects (section 2.2.5.2) describe in detail serialization of different types of objects.
Serialization of Primitive Types
This section describes how to serialize primitive type objects that do not possess extended properties. See section 2.2.5.3.4 for definition of extended properties.
IM
Blob (variable): Actual data. This will fill up the rest of the packet.
IN
AR
Y
57 / 105
2.2.5.1.1
String
Represents a string of characters. XML Element: <S> XML Content: follows the XML schema specification [XMLSCHEMA2] for the string data type. Contents of the string MUST be encoded as described in the following section Encoding strings. Example:
<S>This is a string</S>
Represents a single Unicode character. XML Element: <C>
XML Content: 16-bit unsigned integer equivalent to the specified Unicode character, serialized as described in XML schema specification [XMLSCHEMA2] for the unsignedShort data type. Example:
 <C>97</C>
2.2.5.1.3
Boolean
Represents a Boolean (TRUE/FALSE) value. XML Element: 
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the boolean data type. Example:
true
PR
EL
Represents a date and time. XML Element: <DT> Example:
2.2.5.1.4
Date/Time
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the dateTime data type with the exception of making timezone information mandatory.
<DT>2008-04-11T10:42:32.2731993-07:00</DT>
IM
IN
58 / 105
AR
2.2.5.1.2
Character
2.2.5.1.5
Duration
Represents a length of time. XML Element: <TS> XML Content: Follows the XML schema specification [XMLSCHEMA2] for the duration data type. Example:
Represents an unsigned byte (8 bits). XML Element: <By>
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the unsignedByte data type. Example:
<By>254</By>
2.2.5.1.7
Signed Byte
Represents a signed byte (8 bits). XML Element: <SB>
Example:
<SB>-127</SB>
2.2.5.1.8
Unsigned Short
PR
EL
XML Element: <U16> Example:
<U16>65535</U16>
Represents an unsigned short (16 bits).
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the unsignedShort data type.
2.2.5.1.9
Signed Short
Represents a signed short (16 bits).

59 / 105
IM
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the byte data type.
IN
AR
2.2.5.1.6
Unsigned Byte
 <TS>PT9.0269026S</TS>
XML Element: <I16> XML Content: Follows the XML schema specification [XMLSCHEMA2] for the short data type. Example:
<I16>-32767</I16>
2.2.5.1.10
Unsigned Int
Represents an unsigned integer (32 bits). XML Element: <U32>
Example:
<U32>4294967295</U32>
2.2.5.1.11
Signed Int
XML Element: <I32>
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the int data type. Example:
<I32>-2147483648</I32>
2.2.5.1.12
Unsigned Long
Represents an unsigned long (64 bits). XML Element: <U64>
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the unsignedLong data type.
PR
EL
Example:
<U64>18446744073709551615</U64>
2.2.5.1.13
Signed Long
Represents an unsigned long (64 bits). XML Element: <I64> XML Content: Follows the XML schema specification [XMLSCHEMA2] for the long data type.
Example:
IM
IN
Represents an signed integer (32 bits).
AR
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the unsignedInt data type.
Y
60 / 105
<I64>-9223372036854775808</I64>
2.2.5.1.14
Float
Represents IEEE single-precision 32-bit floating point type [IEEE754]. XML Element: <Sg> XML Content: Follows the XML schema specification [XMLSCHEMA2] for the float data type. Example:
<Sg>12.34</Sg>
2.2.5.1.15
Double
Represents IEEE double-precision 64-bit floating point type [IEEE 754-1985]. XML Element: <Db>
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the float data type.
<Db>12.34</Db>
2.2.5.1.16
Decimal
Represents arbitrary precision decimal numbers as defined in [ECMA-335]. XML Element: <D>
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the decimal data type. Example:
<D>12.34</D>
PR
EL
2.2.5.1.17 Array of Bytes
Represents an array of bytes. XML Element: <BA> Example:
XML Content: contents of the byte array represented as a string in base64-encoding [RFC3548]
 <BA>AQIDBA==</BA>
IM
IN
Example:
AR
61 / 105
2.2.5.1.18
GUID
Represents a 16-byte (128-bit) number which is assumed to be unique in any context as defined in [RFC4122]. XML Element: <G> XML Content: UUID string representation defined by [RFC4122]. Example:
<G>792e5b37-4505-47ef-b7d2-8711bb7affa8</G>
Represents a Uniform Resource Identifier (URI) reference as defined in Section 4 of [RFC2396], as amended by [RFC2732]. XML Element: <URI>
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the uriReference data type. Contents of the URI MUST be encoded as described in section 2.2.5.3.2 below.
<URI>http://www.microsoft.com/</URI>
2.2.5.1.20
Null Value
Represents a NULL value. XML Element: <Nil>
XML Content: Empty element Example:

<Nil />
PR
EL
XML Element: <Version> Example:
2.2.5.1.21
Version
Represents a version number that consist of two to four components: major, minor, build, and revision.
XML Contents: Version is represented as a string and serialized using XML schema specification for string data type. String representation of a version is "major.minor[.build[.revision]]" (optional components are shown in square brackets). All defined components MUST be integers greater than or equal to 0. For example, if the major number is 6, the minor number is 2, the build number is 1, and the revision number is 3, then string representation of the version would be "6.2.1.3".
IM
62 / 105
IN
Example:
AR
2.2.5.1.19
URI
<Version>6.2.1.3</Version>
2.2.5.1.22
XML Document
Represents an XML document as defined in [XML]. XML Element: <XD> XML Content: XML document represented as a string, serialized using XML schema specification for string data type. String representation of the XML document MUST be encoded as described in the following section 2.2.5.3.2. Example:
<XD><name attribute="value">Content</name></XD>
2.2.5.1.23
ScriptBlock
Represents a block of PowerShell script. XML Element: <SBK>
Example:
<SBK>get-command -type cmdlet</SBK>
2.2.5.1.24
Secure String
Represents a string that SHOULD be protected from eavesdropping and modification (that is, a password). XML Element: <SS>
PR
EL
Example:
XML Content: The contents of the SecureString encrypted using the session key from DataType 0x00010006 (see section 2.2.2.6) and encoded in Base64 format. The key exchange MUST take place before sending a message containing a SecureString.
<SS> bs7MU5rXWiJF7UZcgbJtYUAX55zJJFuCyDsFx2AOgb0BwFjmZso6+0dZj9dU9JfhyE9TQqi4hFTX6INJYOb54lW12eN6l yHBXCS9EwsfCkOpfpSEnDhGZd0gxCDHmUvM5+fy5zlwL+5m3FtxSWsye/OgCZwlyPoa2EwUaq8uCE4ymuDeQ5vt1nMJEl RFre8/paddAqHHGebGEepwW6coLdoiG2EuIwk0n+cmXyNzYJNnn/CEMpDTDsFNnkrp4CyIVfOEsn4cFjGhDkpj3qHMubV Wy29F2f1n3ztJDNf4IX07q+xJeX8ncmFn70FNiFSONizkLD3APKFl9zSIBF6AzQ== </SS>
2.2.5.1.25 Progress Record

Represents the status of an ongoing operation at a point in time.
63 / 105
IM
IN
XML Content: The contents of the ScriptBlock represented as a string, serialized using XML schema specification for string data type. String representation of the ScriptBlock MUST be encoded as described in the following section 2.2.5.3.2.
AR
XML Element: <PR> XML Content: The following data is included (all strings MUST be encoded as described in section 2.2.5.3.2; elements containing integers follow XML schema [XMLSCHEMA2] specification for int data type). Activity: An <AV> XML element with a string describing the activity for which progress is being reported. ActivityId: An <AI> XML element with an integer identifying the activity for which progress is being reported.
CurrentOperation: An <CO> XML element with a string describing the current operation of the many required to accomplish the activity (such as copying sample.txt).
PercentComplete: An <PC> XML element with an integer with an estimate of the percentage of total work that is completed for the activity RecordType: An <T> XML element with a string indicating if the activity is in progress (Processing string) or complete (Completed string).
StatusDescription: An <SD> XML element with a string containing the current status of the operation; for example., 35 of 50 items copied, 95% completed, or 100 files purged. Example:
<PR> <AV>activity description</AV> <AI>1</AI> <Nil /> <PI>-1</PI> <PC>-1</PC> <T>Processing</T> <SR>-1</SR> <SD>status description</SD> </PR>
PR
EL
2.2.5.2
Serialization of Complex Objects
This section describes how to serialize: Non-primitive type objects (objects not covered in the section 2.2.5.1). Primitive type objects (see section 2.2.5.1) with instance properties (see section 2.2.5.2.6 and 2.2.5.2.10 below for definition of instance properties).
A complex object can be serialized using one of the following methods. As a reference to an earlier object (section 2.2.5.2.1).
IM
64 / 105
IN
SecondsRemaining: An <SR> XML element with an integer estimating of time needed to complete the activity for which progress is being reported
AR
ParentActivityId: An <PI> XML element with an integer identifying the parent activity for which this record is a subordinate; a negative value indicates that the activity for which progress is being reported has no parent
As a string (section 2.2.5.2.2). As an <Obj> element (section 2.2.5.2.3).
2.2.5.2.1
Referencing Earlier Objects RefId Attribute
2.2.5.2.1.1
2.2.5.2.1.1.1
<Ref> Element
When a particular object has been already serialized by a given instance of the serializer (see the following section 2.2.5.3.3 for details of serializer lifetime), the serializer MAY choose to output only <Ref> element (instead of <Obj> element with full object data). Example:
2.2.5.2.2
Serialization As a String
PR
EL
Example:
The serializer SHOULD limit depth of serialization in order to prevent infinite recursion. The PowerShell Remoting Protocol requires that the serializer MUST calculate the depth in such a way that the structure of the PowerShell Remoting Protocol messages is preserved. The PowerShell Remoting Protocol places no requirements on depth of serialization of user data (that is, contents of DataType: 0x00041004: Output of a PowerShell on the server, described in section 2.2.2.20).
Objects serialized at a depth of 0 are serialized as a primitive string. The serializer can choose any method for converting an object to a primitive string, and can use the same string as would be used in a ToString element (see sections 2.2.5.2.5 and 2.2.5.3.4.4).
<Obj RefId="RefId-0"> <-- object serialized at depth 2 --> <TN RefId="RefId-0">
IM
 <Obj><LST> <Obj RefId="RefId-0"> <TN RefId="RefId-0"> <T>System.Drawing.Point</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>{X=12,Y=34}</ToString> <Props> false <I32 N="X">12</I32> <I32 N="Y">34</I32> </Props> </Obj> <Ref RefId="RefId-0" /> </LST></Obj>
IN
AR
Y
65 / 105
All <Obj> elements representing complex objects (see section 2.2.5.2.3) SHOULD have an optional RefId attribute that identifies the object so that it can be referenced later. The object identifier used MUST be unique during the lifetime of a serializer/deserializer pair (see the following section for details). The identifier can be any string that is valid in an XML attribute.
2.2.5.2.3
<Obj> Element
The <Obj> element can include the following subelements in any order. Type names (section 2.2.5.2.4). ToString (section 2.2.5.2.5).
Element generated by one of the following:
Contents of primitive types with notes (section 2.2.5.2.6). Contents of known containers (section 2.2.5.2.7). Contents of enums (section 2.2.5.2.8).
Contents of other complex objects (section 2.2.5.2.9). Extended properties (section 2.2.5.2.10).
2.2.5.2.4
Type Names
The <Obj> element MAY specify a description of the type of the serialized object. The serializer MAY choose not to serialize type information.
PR
EL
If the type information has been already serialized earlier in the same instance of the serializer, this information can be referenced using the <TNRef> element with the RefId attribute set to the identity of the earlier result of serializing type information. If type information has not been serialized earlier, a <TN> element is written. The <TN> element contains <T> elements, each of which contains the name of a type associated with the object being serialized. <T> elements MUST be ordered from the most specific (that is, point) to least specific (that is, object). Type names MUST be encoded as described in the following section 2.2.5.3.2 . Mapping type names to concrete types is outside the scope of the protocol and is an implementation detail. The <TN> element always has a RefId attribute which identifies the type information; the <TN> element may be referenced later by <TNRef> elements. The type identifier used MUST be unique
IM
IN
66 / 105
AR
<T>LinkedListNode</T> <T>System.Object</T> </TN> <ToString>LinkedListNode</ToString> <Props> <Nil N="Value" /> <Obj N="Next" RefId="RefId-1"> <-- object serialized at depth 1--> <TNRef RefId="RefId-0" /> <ToString>LinkedListNode</ToString> <Props> <Nil N="Value" /> <!-object serialized as a string at depth 0 --> <S N="Next">LinkedListNode</S> </Props> </Obj> </Props> </Obj>
during the lifetime of a serializer/deserializer pair (see the following section 2.2.5.3.3 for details). The identifier can be any string that is valid in an XML attribute. Example:
<Obj><LST> <Obj RefId="RefId-0"> <TN RefId="RefId-0"> <T>System.Drawing.Point</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>{X=12,Y=34}</ToString> <Props> false <I32 N="X">12</I32> <I32 N="Y">34</I32> </Props> </Obj> <Obj RefId="RefId-1"> <TNRef RefId="RefId-0" /> <ToString>{X=56,Y=78}</ToString> <Props> false <I32 N="X">56</I32> <I32 N="Y">78</I32> </Props> </Obj> </LST></Obj>
2.2.5.2.5
ToString
XML Element: <ToString>
XML Content: Follows the XML schema specification [XMLSCHEMA2] for the "string" data type. Contents of the string MUST be encoded as described in section 2.2.5.3.2. Example:
PR
EL
<Obj RefId="RefId-0"> <TN RefId="RefId-0"> <T>System.Drawing.Point</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>{X=12,Y=34}</ToString> <Props> false <I32 N="X">12</I32> <I32 N="Y">34</I32> </Props> </Obj>
IM
Serialization of complex objects MAY include a string that represents the object. The serializer MAY choose not to serialize ToString information
IN
AR
67 / 105
2.2.5.2.6
Contents of Primitive Types with Notes
If the complex object being serialized is a primitive type with notes, then the contents of the primitive type are serialized as described in section 2.2.5.1. Example (compare with the serialization of a string without notes in section 2.2.5.1.1):
<Obj RefId="RefId-0"> <S>This is a string</S> <MS> <S N="Note1">My note</S> </MS> </Obj>
2.2.5.2.7.1
Stack
The Stack container specifies a data structure for accessing a collection of elements based on a lastin, first-out order. XML Element: <STK>
Example:
PR
EL
2.2.5.2.7.2 Queue
XML Element: <QUE> Example:
The Queue container specifies a data structure for accessing a collection of elements based on a first-in, first-out order.
XML Contents: Results of serializing all elements of the queue, starting with the first element.
 <Obj RefId="RefId-0">
IM
 <Obj RefId="RefId-0"> <TN RefId="RefId-0"> <T>System.Collections.Stack</T> <T>System.Object</T> </TN> <STK> <I32>3</I32> <I32>2</I32> <I32>1</I32> </STK> </Obj>
IN
XML Contents: Results of serializing all elements of the stack, starting with the topmost element.
AR
2.2.5.2.7
Contents of Known Containers
Y
68 / 105
<TN RefId="RefId-0"> <T>System.Collections.Queue</T> <T>System.Object</T> </TN> <QUE> <I32>1</I32> <I32>2</I32> <I32>3</I32> </QUE> </Obj>
2.2.5.2.7.3
List
XML Element: <LST> (an alternative element may be also used: <IE>).
XML Contents: Results of serializing all elements of the collection (starting with the first element). Example:
2.2.5.2.7.4
Dictionaries
The Dictionaries container specifies an associative array; that is, a collection of keys and a collection of values in which every key is associated with one value.
PR
EL
XML Element: <DCT> Example:
XML Contents: For each (key, value) pair, write <En>"key" "associated value"</Value></En>, replacing "key" with results of serializing the key with name attribute (see section 2.2.5.3.1) set to "Key" and replacing "associated value" with results of serializing the associated value with name attribute (see section 2.2.5.3.1) set to "Value". Pairs can be processed and written in any order.
 <Obj RefId="RefId-0"> <TN RefId="RefId-0"> <T>System.Object[]</T> <T>System.Array</T> <T>System.Object</T> </TN> <LST> <I32>1</I32> <I32>2</I32> <I32>3</I32> </LST> </Obj>
IN
AR
The List container specifies an ordered collection of elements.
Y
69 / 105
<T>System.Object</T> </TN> <DCT> <En><S N="Key">key2</S><I32 N="Value">2</I32></En> <En><S N="Key">key1</S><I32 N="Value">1</I32></En> </DCT> </Obj>
2.2.5.2.8
Contents of Enums
XML Element: element corresponding to the primitive integer type (see section 2.2.5.1) that is underlying the enumeration type. XML Contents: value of the enumeration converted to the underlying type. Example:
<Obj RefId="0"> <TN RefId="0"> <T>System.ConsoleColor</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>Blue</ToString> <I32>9</I32> </Obj>
2.2.5.2.9
Contents of Other Complex Objects
This section describes how to serialize adapted properties (see section 2.2.5.3.4.1) of those complex objects that are not covered in sections Contents of primitive types with notes, Contents of known containers, or Contents of enums. XML Element: <Props>
PR
EL
Example:
XML Contents: Results of serializing adapted properties of the complex object. Properties can be serialized in any order. The serializer MAY choose to serialize only a subset of properties. Property names MUST be serialized using the attribute described in section 2.2.5.3.1.
 <Obj RefId="RefId-0"> <TN RefId="RefId-0"> <T>System.Drawing.Point</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>{X=10,Y=20}</ToString>
IM
IN
70 / 105
AR
Enums specifies a value of an enumeration. An enumeration is a distinct type consisting of a set of named constants. Every enumeration type has an underlying type, which can be any integral type. The default underlying type of the enumeration elements is a 32-bit integer (see section 2.2.5.1.11).
<Props> false <I32 N="X">10</I32> <I32 N="Y">20</I32> </Props> </Obj>
2.2.5.2.10
Extended Properties
XML Element: <MS>
XML Contents: Results of serializing values of extended properties and/or results of recursive serialization of property sets (resulting in a nested <MS> element). Properties and property sets can be serialized in any order. The serializer MAY choose to serialize only a subset of properties and property sets if all of them are not required by the remote command or cmdlet (see section 2.2.5.3.4 below for more information). Property names and property set names MUST be serialized using the property name attribute described in section 2.2.5.3.1. Example:
PR
EL
2.2.5.3 Miscellaneous 2.2.5.3.1 Property Name
<!-serialization of a point with 2 extended properties and with 1 property set that contains 2 other extended properties --> <Obj RefId="RefId-0"> <TN RefId="RefId-0"> <T>System.Drawing.Point</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>{X=10,Y=20}</ToString> <Props> false <I32 N="X">10</I32> <I32 N="Y">20</I32> </Props> <MS> <S N="Property1">This is an extended property</S> <S N="Property2">This is a second extended property</S> <MS N="PropertySet1"> <S N="Property3">This is a third extended property</S> <S N="Property4">This is a forth extended property</S> </MS> </MS> </Obj>
If the serialized object was associated with a property, then the XML element representing the serialized object will have an N attribute that represents the name of that property. Property names MUST be encoded as described in section 2.2.5.3.2.
IM
IN
AR
Y
71 / 105
This section describes how to serialize extended properties (see section 2.2.5.3.4.2) and property sets (see section 2.2.5.3.4.3) of all complex objects.
Example:
 <Obj RefId="RefId-0"> <TN RefId="RefId-0"> <T>System.Drawing.Point</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>{X=10,Y=20}</ToString> <Props> false <I32 N="X">10</I32> <I32 N="Y">20</I32> </Props> </Obj>
2.2.5.3.2
Encoding Strings
Some strings require encoding before they can be used in XML output, to remove invalid surrogate pairs for example. In the sections that follow, the descriptions of strings which require encoding will explicitly cite this section (2.2.5.3.2); strings with descriptions that lack such a citation can be serialized without encoding them first.
The escape character is "_". Control characters and surrogate characters are escaped as _xHHHH_, where HHHH string stands for the four-digit hexadecimal UCS-2 code for the character in most significant bit first order. For example, the "Order\nDetails" is encoded as:
Order_x000A_Details
The underscore character only requires escaping when it is followed by a character sequence that, together with the underscore, can be misinterpreted as an escape sequence when decoding the name. For example, Order_Details is not encoded, but Order_x0020_ is encoded as Order_x005f_x0020_. No short forms are allowed. For example, the forms _x20_ and __ are not generated.
PR
EL
2.2.5.3.4 2.2.5.3.4.1
2.2.5.3.3
Lifetime of a Serializer/Deserializer Pair
The serialization used in PowerShell remoting makes certain assumptions about lifetime of a serializer/deserializer pair. These assumptions are used in managing uniqueness of object identifiers (section 2.2.5.2.1) and type identifiers (section 2.2.5.2.4) used by the serializer. A new serializer/deserializer pair MUST be created and reused for each type of message data that is specified in section 2.2.2 and sent across the network.
Structure of Complex Objects Adapted Properties
Adapted properties are name/value pairs exposed by the core definition of an object.
IM
IN
This method translates some characters into escaped numeric entity encodings.
AR
Y
72 / 105
Example 1: A .NET object representing a point can have a property named X with an associated value equal to 123 and a property named Y with an associated value equal to 456. Example 2: A WMI object representing a computer system can have a property named Model with an associated value equal to HP Compaq dc7800 Convertible Minitower.
2.2.5.3.4.2
Extended Properties
Extended properties are name/value pairs added to an object outside of the core definition of an object. Example: A .NET object representing a point can have 2 adapted properties named X and Y. A command executing on a PowerShell server can add extended properties to some instances of this object, for example, a property named Label with a value of My Location.
2.2.5.3.4.3 Property Sets

A property set is a named collection of properties.
2.2.5.3.4.4
ToString Value
A string representation of the object. Each object SHOULD provide a method called ToString.
2.2.6
Encoding Host Parameters in Host Method Calls
The parameters of a host method call are encoded as follows: A list of parameters is constructed.
Each element of the list is encoded using the rules described specified in 2.2.6.1. This depends on the type of the parameter.
2.2.6.1
Encoding Individual Parameters
The following sections specify how individual parameters are encoded.
2.2.6.1.1
Any Serializable Type
PR
EL
2.2.6.1.2 CultureInfo 2.2.6.1.3 List
Property Name: T.
Any type which can be serialized as described in 2.2.5 is not encoded.
The CultureInfo parameter is encoded by calling the ToString() method on the object. See [ECMA335] for the definition of ToString() of CultureInfo.
The list parameter is encoded by constructing a new list with the elements being encoded in UTF-8 XML format which is equivalent to an XML obtained by serializing an object (see section 2.2.5) with the following extended properties (see section 2.2.5.2.10).
IM
The list is then converted into UTF-8 encoded XML, equivalent to the XML created by serializing an object with extended properties (see section 2.2.5.2.10).
IN
AR
73 / 105
Property Value: Type name of the element as defined in [ECMA-335] Property Type: String Property Name: V. Property Value: Element encoded using rules described in section 2.2.6.1 Property Type: List (encoded as defined in section 2.2.5.2.7.3).
An array list is encoded in UTF-8 encoded XML, which is equivalent to the XML obtained by serializing an object (see section 2.2.5) with the following extended properties (see section 2.2.5.2.10). Property Name: mae.
Property Value: Elements of the array list encoded similar to elements of a list (see section 2.2.6.1.3). Property Type: List (encoded as defined in section 2.2.5.2.7.3). Property Name: mal. Property Value: Length of the array Property Type: Integer
2.2.6.1.5
Collection
The collection parameter is encoded like a list as defined in section 2.2.6.1.3
The dictionary paramater is encoded by constructing a new hash table with the following key/value pairs: Key: Key in the dictionary, encoded using rules described in section 2.2.6.1 Value: Value corresponding to key in dictionary, encoded using rules described in section 2.2.6.1
PR
EL
Property Name: T. Property Type: String
2.2.6.1.7
Object Dictionary
The object dictionary parameter is encoded by constructing a new hash table with the following key/value pairs: Key: Key in the dictionary, encoded using rules described in section 2.2.6.1 Value: UTF-8 encoded XML that is equivalent to the XML created by serializing an object with the following extended properties (see section 2.2.5.2.10).
Property Value: Type name of the element as defined in [ECMA-335]
IM
2.2.6.1.6
Dictionary
IN
AR
74 / 105
2.2.6.1.4
ArrayList
Property Name: V. Property Value: Value corresponding to key in dictionary, encoded using rules described in section 2.2.6.1 Property Type: List (encoded as defined in section 2.2.5.2.7.3).
2.2.6.1.8
Other Object Types Used in a Host Call
Property Name: Name of the object's property
PR
EL
IM
IN
AR
Property Value: The value of the object's property encoded as described in section 2.2.6.1. and then encoded into UTF-8 XML as described in section 2.2.5
The non-null properties of any other object types used in a host call, as defined in section 2.2.3, are encoded as extended properties (see section 2.2.5.2.10) in the following manner.
3
3.1
Protocol Details
Client Details Abstract Data Model
3.1.1
A RunspacePool is modeled on a WinRM Shell. Any message targeted on a RunspacePool should be sent to the WinRM Shell.
As described in [MS-WSMV], a shell is created before commands are run in it.
Figure 2: Abstract Data Model
The state machine of a RunspacePool is described below.
PR
EL
IM
IN
AR
A pipeline is modeled on a WinRM command. Any message targeted on a pipeline should be sent to the WinRM command.
Figure 3: RunspacePool state machine
A RunspacePool is assumed to be in Opening state when a create shell message, along with the negotiation payload, has been sent to the PowerShell server. If the negotiation succeeds, then the PowerShell server will send back a RunspacePool State Information object. On receipt of this object, the RunspacePool is in Opened state. If the negotiation fails, the RunspacePool enters the Closed state. When WinRM loses the connection between the PowerShell server and PowerShell client, the RunspacePool enters the Broken state. Also, after entering the Opening state, any other WinRM error will result in the RunspacePool entering the Broken state.
PR
EL
When the PowerShell client initiates a Close Shell (as specified in section 3.1.5.3.7), the RunspacePool enters the Closing state. Once the WinRM client confirms that the shell on the PowerShell server is closed, the RunspacePool enters the Closed state The state machine of a pipeline is as follows.
IM
IN
AR
77 / 105
Figure 4: Pipeline state machine
The pipeline enters a Running state when a WinRM command is invoked.
If the pipeline completes, then it enters the Completed state. The pipeline state information is sent from the PowerShell server to the PowerShell client.
When the PowerShell client sends a message to stop the pipeline, it enters the Stopping state. On receiving the pipeline state information from the PowerShell server, it enters the Stopped state.
3.1.2
None.
Timers
3.1.3
None.
Initialization
3.1.4
Higher-Layer Triggered Events
PR
EL
3.1.5 3.1.5.1
Before the client shuts down, all RunspacePools created by that client on the server SHOULD be closed.
Message Processing Events and Sequencing Rules General Protocol Rules
Message Processing Rules for WinRM described in [MS-WSMV] section Message Processing are applicable here as well. 1. Any message targeted for a RunspacePool on the PowerShell server MUST be sent as input to the WinRM remote shell.
IM
IN
If the pipeline terminates by throwing an exception, it enters the Failed state. The pipeline state information which contains the exception is sent back to the PowerShell client from the PowerShell server.
AR
Y
78 / 105
2. Any message targeted for a Pipeline on the PowerShell server MUST be sent as input to the WinRM remote command. 3. If there are any messages which cannot be decoded at the server, then the corresponding WinRM command/shell will be closed. 4. If the PowerShell client cannot decode a message coming from the PowerShell server, then it SHOULD initiate a close on the corresponding Pipeline/RunspacePool on the PowerShell server. 5. The Pipeline or RunspacePool should be in a valid state to accept response messages from the PowerShell server. For instance, a Pipeline cannot accept output objects or state information after it has reached a terminal state - Completed, Failed, or Stopped.
3.1.5.2
Protocol Sequence
The following shows the sequence by which a command can be executed on the PowerShell server from the PowerShell client. 1. The PowerShell client creates a WS-MAN shell (as specified in section 3.1.5.3.1)
2. Once a shell is successfully created, the PowerShell client sends in the negotiation message. 3. If negotiation is successful, then the PowerShell client sends a message to create a RunspacePool.
5. Close the WS-MAN session in order to close the RunspacePool.
6. The Receive operation (as specified in section 3.1.5.3.5) will return messages sent by the server, which MUST be decoded as specified in section 2.2.4. 7. To get a session key (see section 2.2.2.6 and 2.2.5.1.24) the PowerShell client MUST send its public key to the server (see section 2.2.2.5). The client MUST send the public key to the server in response to the public key request (see section 2.2.2.7). The client SHOULD handle the first public key request and ignore all subsequent messages of that type. The client SHOULD handle the first session key response (see section 2.2.2.6) and ignore all subsequent messages of that type.
3.1.5.2.1
Sending Messages
PR
EL
The PowerShell client MUST do the following in order to run PowerShell commands on the server. 1. Construct a protocol message object (see section 2.2).
2. Fragment the message object (see section 2.1). 3. Send the resulting fragmented message using WS-MAN. When a receive call back is raised from WS-MAN, the client MUST perform the following steps to reconstruct the message so that it can be interpreted. 1. Defragment and construct the serialized representation of the message (see section 2.1). 2. Deserialize and reconstruct the message object.
IM
IN
4. If the RunspacePool is successfully opened, a RunspacePool state information message will be received by the client. Until the state changes to Closed or Broken, messages to create and invoke powershell can be sent to the server.
AR
Y
79 / 105
3. Decode the object. The process for creating RunspacePool is summarized in the following image.
3.1.5.3
Transporting Using WS-MAN
3.1.5.3.1
Creating a Shell on a PowerShell Server
PowerShell uses a wxf:Create message (as described in [MS-WSMV] section 3.4.1.1) to create a shell on the PowerShell server. The following information is supplied for the wxf:Create message.
PR
EL
Element Uri Value ResourceUri OptionSet Release: Thursday, May 21, 2009
The following information is supplied for the shell data type, as required by [MS-WSMV] section 2.2.3, in the wxf:Create message.
IM
Network URI to which to connect.
Figure 5: Creating a RunspacePool
http://schemas.microsoft.com/PowerShell/Microsoft.PowerShell An option set with the following options. Name = ProtocolVersion, MustComply=True, Value=2.0
IN
80 / 105
AR
Element ShellId
Value Valid PowerShell remoting connection string of the form. Proto://computername:port/applicationname
Where "proto" can be "http" or "https", "computername" is the name of the machine to which to connect, "port" is the port for connection, and "applicationna me" can be WS-MAN or any other application which hosts WS-MAN provider. Environment WorkingDirectory Lifetime IdleTimeout InputStreams 240000 "Stdin pr".
"stdin" is used to send regular data. "pr" is used to send priority data. OutputStreams <open content> stdout
<creationXml> is described in the following section.
<open content> is defined as follows in [MS-WSMV] section 2.2.3: "The open content model for the rsp:Shell body allows individual shells to have any additional XML content required for initialization". The PowerShell client uses <open content> to send additional data, called creationXml data, that assists in creating a shell on the server. This creationXml can contain any data that is destined to the shell. Without this creationXml data, clients MUST use Send messages, described in section 3.1.5.3.4. To avoid multiple network calls, it is encouraged to send additionally using "creationXml". A Capability Object must be the first data that is sent to a server from the client. The Capability Object is described in section 3.1.5.3.2. Typically this Capability Object is included in the creationXml. The creationXml should be of the following format.
<creationXml xmlns=http://schemas.microsoft.com/powershell> Base64-Encoded data </creationXml>
PR
EL
3.1.5.3.2
As described in the preceding section, all the data that is sent as part of creationXml must be base64-encoded as described in [RFC3548].
If the Create message is successfully received and processed by the server, the server may either send a success message or a failure. In either case a response is sent from the server. A CreateResponse message, described in [MS-WSMV] section 3.4.1.2, is sent to notify success. A Fault message, described in [MS-WSMV] section 2.2.1.1, is sent to notify failure. The value specified in the ShellID element of the CreateResponse message must be used for future communication with the shell, for instance when sending input data, signal data, or closing the shell.
Client-Server Negotiation
To establish a PowerShell connection, both server and client should know each other's PowerShell version. This is important for both backward compatibility and future extensibility.
81 / 105
IM
IN
AR
To create a shell on the server (described in section 3.1.5.3.1), the client MUST send the following capability instructions, identifying itself. An empty PSObject MUST be constructed with the following note properties added to it.
Name protocolversion Value A string indicating the client version of the PowerShell remoting protocol. The version's string SHOULD be of the format: x.y. (Currently both client and server have a version of 2.0). A string indicating the client version of PowerShell. The version's string SHOULD be of the format: x.y. (Currently both client and server have a version of 2.0). A string indicating the client version of the PowerShell serialization. The version's string SHOULD be of the format: x.y.z.t. (Currently both client and server have a version of 1.1.0.1). A serialized string representing the Client's TimeZone. This may be used by the commands on the server to generate command output in terms of Client's TimeZone rather than Server's TimeZone. TimeZone serialization is specified in section 2.2.3.10. This element is optional; a client need not specify this property.
PSVersion
SerializationVersion
TimeZone
See section 2.2.5.2.10 for details about serialization of note properties.
The PSObject is called the Capability Object for the purposes of this discussion. The serialized Capability Object MUST be the first data to be sent to the server. This data can be sent either as part of the <creationXml> discussed in section 3.1.5.3.1 or as part of input discussed in section 2.2.3.4. The server waits for this Capability Object immediately after it is created. It uses this object to determine client's capabilities. The server MUST be compatible with minor version changes in the protocol. For example, a server with PSVersion 2.0 MUST be compatible with a client even if the client's PSVersion was 2.1. The meaning of 2.1 for PSVersion will be defined at a later point, if and when there are any protocol additions. Currently both the client and server protocol versions are defined as specified in this document. Irrespective of whether a client and server's protocol versions (PSVersion, ProtocolVersion and SerializationVersion) match, the server MUST always respond with its capability object in response to client's capability object. A client SHOULD use this information when determining whether to fail or connect to the server again with appropriate protocol versions. <creationXml>,discussed in section 3.1.5.3.1, is an interesting concept wherein one can piggyback data along with creation. This potentially saves another network call to send data. So wherever possible use MustComply=True and piggy back client capabilities using <creationXml>. Because Capability Object is not huge, it can piggy back additional data in <creationXml>.
PR
EL
3.1.5.3.3
Executing a Command on a Remote Shell
The PowerShell Remoting Protocol executes a PowerShell/Pipeline on the remote runspace (created using a remote shell as described in 3.1.5.3.1) by executing a command message against the remote shell as specified in [MS-WSMV] section 3.4.1.5. The header for the command message should contain the following information.
IM
IN
AR
82 / 105
Element ResourceUri ShellId
Value http://schemas.microsoft.com/PowerShell/Microsoft.PowerShell Shell GUID returned as a response to the create message in 2.2.3.1
The body of the message should contain a command line complex type as described in [MS-WSMV] section 2.2.3.5. The following information is supplied for the required values in the command line complex type.
Element Command Arguments Value MUST be empty.
3.1.5.3.4
Sending Input to Command/Shell
Element ResourceUri ShellId
Value
The Resource URI of the shell this send is targeted to. The shell GUID returned in the create response message in 3.1.5.3.1, if this is targeted to shell. Otherwise, the Command GUID returned in the command create response message described in 3.1.5.3.3.
PR
EL
Element Stream Value Release: Thursday, May 21, 2009
The body of the send message MUST contain a send data type as described in [MS-WSMV] section 2.2.3.12. The data type MUST contain the following information.
Stdin - if messages are to be sent in the regular priority order. Pr - to send a high priority message (like a host call response). The Name attribute of the stream element must be accordingly stdin or pr.
A Send message can be sent to a shell or command. If the Send message is targeted to a command it MUST contain the following attribute in the received complex data type.
IM
The send message as described in [MS-WSMV] section 3.4.1.8 is used to send input to a command or a remote shell. Any message sent to the pipeline on the PowerShell server MUST be sent as an input to the command and any message to the runspace on the PowerShell server MUST be sent as an input to the shell resource. The following information is included in the message.
IN
If the Command message is successfully received and processed by the server, the server may either send a success message or a failure. In either case, a response is sent from the server. A CommandResponse message, described in [MS-WSMV] section 2.2.3.10, is sent to notify success. A Fault message, specified in [MS-WSMV] section 2.2.1.1, is sent to notify failure. The value specified in the CommandID element of the CreateResponse message must be used for future communication with the Command, that is, for sending input data, signal data, and so on.
AR
The first fragment of the serialized Pipeline/PowerShell. This first fragment MUST be Base64encoded before including the data in the Arguments element. The remaining fragments MUST be sent using the Send message to the command as described in [MS-WSMV] section 3.4.1.8
Y
83 / 105
Element DesiredStream
Attribute CommandId
Value This attribute MUST be the one that was returned in the command response for the execute command message in 3.1.5.3.3. This attribute should not be specified if the Send message is targeted to a shell.
3.1.5.3.5
Receiving Output from a Command/Shell
The receive message as described in [MS-WSMV] section 3.4.1.10 is used to send output from a command or a remote shell. Any message from the pipeline on PowerShell server MUST be sent as an output to the command and any message from the runspace on the PowerShell server MUST be sent as an output from the shell resource. The following information is included in the message.
Element ResourceUri ShellId Value
The Resource URI of the shell this receive is targeted to.
The shell GUID returned in the create response message in 3.1.5.3.1 if this is targeted to shell. Otherwise, the Command GUID returned in the command create response message described in 3.1.5.3.3.
The body of the receive message must contain receive complex data type, as described in [MSWSMV] section 2.2.3.14. The received complex data type MUST contain the following information.
Element DesiredStream Value
PR
EL
Element Attribute DesiredStream CommandId Release: Thursday, May 21, 2009
A Receive message can be sent to a shell or command. If the Receive message is targeted to a command it MUST contain the following attribute in the received complex data type.
Value This attribute MUST be the one that was returned in the command response for the execute command message in 3.1.5.3.3. This attribute should not be specified if the Receive message is targeted to shell.
A Receive message MUST be sent only once per shell session or per command. If the Receive message is successfully received and processed by the server, the server may either send a success message or a failure. In either case a response is sent from the server. A ReceiveResponse message, described in [MS-WSMV] section 2.2.3.15, is sent to notify success. A
IM
MUST contain a value of "stdout".
IN
AR
Once an input is sent using a Send message for a shell or a command, another input cannot be sent for the same shell or the command until a SendResponse is received for that shell or command. That means only 1 packet at a time can be sent to a shell or a command. However, packets can be sent concurrently to multiple shells or commands.
Y
84 / 105
If the Send message is successfully received and processed by the server, the server may either send a success message or a failure. In either case a response is sent from the server. A SendResponse message, described in [MS-WSMV] section 2.2.3.13, is sent to notify success. A Fault message, described in [MS-WSMV] section 2.2.1.1, is sent to notify failure.
Fault message, described in [MS-WSMV] section 2.2.1.1, is sent to notify failure. The ReceiveResponse message may contain data. The following table describes how to interpret this ReceiveResponse message.
Element Stream Attribute Name Value This attribute MUST be stdout. This is because PowerShell server can send data only in one stream. If another stream name is specified, then it should be discarded.
This element may or may not present in every ReceiveResponse packet. If present, the value in the State attribute identifies the Command State. CommandSta te State The CommandState element is present if the ReceiveResponse is meant for a command. The value of the attribute identifies the state of the command. This Element may or may not present in every ReceiveResponse packet. A value of "http://schemas.microsoft.com/wbem/wsman/1/windows/shell/CommandStat e/Done" specifies that this ReceiveResponse packet is the last ReceiveResponse packet from the server for that particular command (as identified by CommandId).
Finally the Stream element holds whatever data that the server sent. This data must first be interpreted as specified in [MS-WSMV] sections 2.2.3.15 and 3.4.1.1. Once the data is interpreted this way, the converted data should be interpreted as described in section 2.1.
3.1.5.3.6
Signaling a Command
A signal message can be sent either to a shell or a command as described in [MS-WSMV] section 3.4.1.12. The PowerShell client uses a signal to stop an executing pipeline on the server. The following information MUST be supplied to the message.
Element ResourceUri ShellId Value
PR
EL
Element Code Value Release: Thursday, May 21, 2009
The message requires a signal complex data type in the body of the message as defined in [MSWSMV] section 2.2.3.16. The following information is sent in the signal complex data type.
A Signal message can be sent to a shell or command. If the Signal message is targeted to a command it MUST contain the following attribute in the Signal complex data type.
IM
The Resource URI of the shell this signal is targeted to. Shell GUID returned in the create response message in 3.1.5.3.1.
The value MUST be "powershell/signal/ctrl_c".
IN
AR
CommandSta te
CommandI d
The CommandState element is present if the ReceiveResponse is meant for a command. The value of the attribute identifies the Command this ReceiveResponse is targeted to.
Y
85 / 105
Stream
CommandI d
This attribute is present if the ReceiveResponse is meant for a command in which case the value of the attribute identifies the Command this ReceiveResponse is targeted to. If CommandId is not specified, then the ReceiveResponse is targeted to a shell.
Element Signal
Attribute CommandId
Value This attribute MUST be the one that was returned in the command response for the execute command message in 0. This attribute should not be specified if the Signal message is targeted to the shell.
3.1.5.3.7
Deleting a Shell on a PowerShell Server
To close a runspace on the PowerShell server, PowerShell client MUST close the WS-MAN shell by sending a wxf:Delete message as specified in [MS-WSMV] section 3.4.1.3. This message can be sent asynchronously to any outstanding messages on the shell and so the shell and therefore the runspace will be forcibly closed. The following information is supplied in the delete message.
Element Uri ResourceUri ShellId Value Network Uri to connect to.
The shell GUID returned in the create response message in 3.1.5.3.1.
If the Delete message is successfully received and processed by the server, the server may either send a success message or a failure. In either case, a response is sent from the server. A DeleteResponse message, described in [MS-WSMV] section , is sent to notify success. A Fault message, described in [MS-WSMV] section 2.2.1.1, is sent to notify failure.
3.1.6
None.
Timer Events
3.1.7
None.
Other Local Events
PR
EL
3.2.1 Abstract Data Model
3.2
Server Details
A RunspacePool is mapped to a WinRM shell. Any PowerShell remoting message targeted to a RunspacePool on the PowerShell client will be sent as a WinRM shell response. An example of a PowerShell remoting message targeted to a RunspacePool is "DataType: 0x00010002: Session Capability" (as specified in section 2.2.2.2).
A pipeline is mapped to a WinRM command. A PowerShell remoting message targeted to a pipeline on the PowerShell client will be sent as a WinRM command response. An example of a PowerShell remoting message targeted to a pipeline is "DataType: 0x00041004: Output of a PowerShell on the Server" (as specified in section 2.2.2.20).
IM
86 / 105
IN
http://schemas.microsoft.com/PowerShell/Microsoft.PowerShell
AR
If the Signal message is successfully received and processed by the server, the server may either send a success message or a failure. In either case a response is sent from the server. A SignalResponse message, described in [MS-WSMV] section 3.4.1.13, is sent to notify success. A Fault message, described in [MS-WSMV] section 2.2.1.1, is sent to notify failure.
A RunspacePool is a pool of runspaces. In PowerShell, a runspace can execute only one command at any given point of time. However, the Web Services Management Protocol [MS-WSMV] supports executing multiple commands concurrently within the same shell. To take complete advantage of this, the PowerShell Remoting Protocol maps a WinRM shell to a RunspacePool. A single runspace can be represented as RunspacePool with both the maximum runspaces and the minimum runspaces set to 1. A shell is created before commands are run in it, as specified in [MS-WSMV].
Figure 6: The state machine of a RunspacePool
If the PowerShell server cannot comply with what is requested in the negotiation it initiates a WinRM close shell.The state machine of a pipeline is as defined in the preceding figure. If a pipeline completes successfully, then the PowerShell server sends a pipeline state information message (as specified in section 2.2.2.22) with the Completed state. If the PowerShell server stops a pipeline execution in response to a WinRM stop control signal, it sends a pipeline state information message with the Stopped state. If execution of the pipeline failed for some reason, the PowerShell server MUST send a state information message with the Failed state along with an exception encoded as error record (as specified in section 2.2.2.1) which describes the reason for the failure. To interact with the user, the PowerShell server sends one of the following messages to the PowerShell client. If UseRunspaceHost was true in HostInfo (as specified in section 2.2.3.15), then the PowerShell server sends a message as specified in section 2.2.2.16. If UserRunspaceHost was false in HostInfo (as specified in section 2.2.3.15), then the PowerShell server MUST send a message, as specified in 2.2.2.28.
PR
EL
IM
When a request for creating a RunspacePool is received as a WinRM create shell request, the PowerShell server evaluates the negotiation packet. If the negotiation packet complies with the negotiation, the PowerShell server sends a RunspacePool Opened state information message (as specified in section 2.2.2.11).
IN
AR
87 / 105
3.2.2
None.
Timers
3.2.3
None.
Initialization
3.2.4
Higher-Layer Triggered Events
3.2.5
Message Processing Events and Sequencing Rules General Protocol Rules
3.2.5.1
The message processing Rules for WinRM, specified in [MS-WSMV] section 3.1.5, are applicable here as well. 1. The PowerShell server MUST send a response message (as specified in 3.2.5.2) for every message it receives from a PowerShell client.
3. Any message targeted for a pipeline on the PowerShell client MUST be sent as output (using a ReceiveResponse message, as specified in section 3.2.5.2.4) to the WinRM remote command. 4. If there are any messages which cannot be decoded by the PowerShell server, then the corresponding WinRM command or shell will be closed.
3.2.5.2
Transporting Using WS-MAN
Transportation using WS-MAN is as specified in section 3.1.5.3. A PowerShell server SHOULD participate in this protocol sequence by sending response messages as described in the following subsections.
PR
EL
3.2.5.2.1
Response to Create Shell Request
A PowerShell client uses the wxf:Create message to create a shell on the PowerShell server, as specified in section 3.1.5.3.1. A PowerShell server implementation MUST process the wxf:Create message and send a response message (either success or failure) using the CreateResponse message specified in [MS-WSMV], section 3.4.1.2. The PowerShell server MUST use ReceiveResponse messages to send any data, as specified in section 3.2.5.2.4. The wxf:Create message sent by clients MUST contain an option with the name "protocolversion" and the value "2.0". If the server does not accept a client's protocol version, then the server MUST send an error message to the client using a WSManFault message as specified in [MS-WSMV], section 2.2.1.1.
The following information MUST be included in the WSManFault message.

88 / 105
IM
5. If the PowerShell client cannot decode a message coming from the PowerShell server, then it SHOULD initiate a close on the corresponding pipeline or RunspacePool on the PowerShell server.
IN
2. Any message targeted for a RunspacePool on the PowerShell client MUST be sent as output (using a ReceiveResponse message, as specified in section 3.2.5.2.4) to the WinRM remote shell.
AR
Before a server closes a RunspacePool (WinRM shell), it SHOULD stop all the pipelines currently executing inside that RunspacePool.
Element Code Machine Message
Value 2152991685 A string that SHOULD specify the machine name where this fault occurred. A string message in the following format. <PSProtocolVersionError ServerProtocolVersion="x.y" ServerBuildVersion="a.b.cdef.g">detailed error message </PSProtocolVersionError> Where "x.y" represents the server's ProtocolVersion (currently 2.0), and "a.b.cdef.g" represents the server's build number (such as 7.0.7000.0).
3.2.5.2.2
Response to Create Command Request
3.2.5.2.3
Response to Send Request
3.2.5.2.4
Response to Receive Request
When a PowerShell client is ready to receive output it sends a Receive request, as specified in section 3.1.5.3.5. A PowerShell server implementation MUST process this request packet and send a response packet using a ReceiveResponse message, as specified in [MS-WSMV], section 3.4.1.11. A PowerShell server implementation MUST send the ReceiveResponse message only after it receives a Receive request from the PowerShell client for the corresponding shell or command.
PR
EL
Element Name Value Stdout CommandId Release: Thursday, May 21, 2009
A PowerShell server implementation MUST use the stream name stdout to send output to the client. A PowerShell client expects output data from the PowerShell server in this stream only. The following information MUST be included in the Stream element of the message.
This attribute MUST be identical to that sent in the command response for the execute command message, as specified in 3.2.5.2.2. This attribute MUST NOT be specified if the Receive message is targeted to the shell.
IM
A PowerShell client sends data to a shell or a command instance on the server, as specified in section 3.1.5.3.4. A PowerShell server implementation MUST process this request packet and send a response packet (either success or failure) using SendResponse message, as specified in [MSWSMV] section 3.4.1.9. The PowerShell server MUST use ReceiveResponse messages to send data to PowerShell client, as specified in section 3.2.5.2.4.
IN
A PowerShell client initiates a command invocation using the message structure specified in section 3.1.5.3.2. A PowerShell server implementation MUST process this message and send a response message (either success or failure) using a CommandResponse message, as specified in [MSWSMV] section 2.2.3.10. The PowerShell server MUST use ReceiveResponse messages to send data to the PowerShell client, as specified in section 3.2.5.2.4.
AR
A server MUST be compatible with minor version changes; in other words, a server could accept a client's packet even if the protocolversion was specified as "2.1".
Y
89 / 105
The body of the Stream element must contain the actual data. The data MUST be in the form as described in Messages (section 2).The following information MAY be included in the CommandState element of the message if the message is meant for a command.
Element CommandId Value This attribute MUST be identical to that sent in the command response for the execute command message, as specified in section in 3.2.5.2.2. This element may or may not be present in every ReceiveResponse packet. If present, the value in the State attribute identifies the Command State. State The value of the attribute identifies the state of the command.
Unlike other Response messages, the ReceiveResponse message can be sent many times after the PowerShell server receives Receive Request packet from the PowerShell client. As described earlier, ReceiveResponse messages MUST NOT be sent for a particular shell or command once a CommandState/Done state message is sent.
3.2.5.2.5
Response to Signal Request
A PowerShell client sends a Signal request to stop an executing pipeline on the PowerShell server, as specified in section 3.1.5.3.6. A PowerShell server implementation MUST process this request packet and send a response packet (either success or failure) using SignalResponse message, as specified in [MS-WSMV] section 3.4.1.13.
3.2.5.2.6
Response to Delete Request
A PowerShell server implementation MUST process the Delete Request and send a response packet using DeleteResponse as described in [MS-WSMV] section 3.4.1.4.
3.2.5.3
Sequencing Rules
PR
EL
The following are the general rules for sequencing and processing messages by the PowerShell server. 1. A pipeline MUST be created and invoked on the PowerShell server (as specified in section 2.2.2.12) before input can be sent to the pipeline. 2. Input to a pipeline on the server (as specified in section 2.2.2.18), if any, MUST be sent to the PowerShell server before an end of input message (as specified in section 2.2.2.19) can be sent.
3. A PowerShell server MUST respond with a response to setting a maximum or minimum runspace message (as specified in section 2.2.2.10) when it receives a message to modify the number of runspaces in a RunspacePool (as specified in sections 2.2.2.8 and 2.2.2.10).
IM
A PowerShell client sends a Delete Request packet to close the associated pipeline and any active pipelines in the pipeline, as specified in section 3.1.5.3.7. After this request is sent, the PowerShell client will not send any additional requests (such as Send, Receive, Command, and Signal) for that particular shell.
IN
AR
This Element may or may not present in every ReceiveResponse packet. A value of http://schemas.microsoft.com/wbem/wsman/1/windows/shell/CommandState/Done specifies that this ReceiveResponse packet is the final ReceiveResponse packet from the PowerShell server for that particular command (as identified by CommandId).
Y
90 / 105
4. A PowerShell client SHOULD respond to a host method call message (as specified in sections 2.2.2.16 and 2.2.2.28) with the corresponding response message (as specified in sections 2.2.2.17 and 2.2.2.29) 5. A PowerShell client SHOULD not request any operation on a pipeline on the PowerShell server, after the PowerShell server sends a pipeline state information message (as specified in section 2.2.2.22) 6. A PowerShell server MUST send all output, error, debug, verbose, warning and progress messages (as specified in sections 2.2.2.20, 2.2.2.21, 2.2.2.23, 2.2.2.24, 2.2.2.25, and 2.2.2.26) before it can send a state information message (as specified in section 2.2.2.22)
8. After getting a public key from the client (see section 2.2.2.6), the PowerShell server MUST reply by sending back a session key to the client (see section 2.2.2.5). The server SHOULD send the session key only once. The server SHOULD handle only the first public key message (see section 2.2.2.6) and ignore all the subsequent messages of that type. 9. A PowerShell server MUST send application private data (see section 2.2.2.15) to the client after a RunspacePool is created on the server and before reporting that the RunspacePool is opened (see section 2.2.2.11).
3.2.6
None.
Timer Events
3.2.7
None.
Other Local Events
PR
EL
IM
IN
AR
7. If a server needs a session key (see section 2.2.2.6 and 2.2.5.1.24), but it did not get a client public key yet (see section 2.2.2.5) then the server MUST initiate key exchange by asking the client for its public key (see section 2.2.2.7). The server SHOULD initiate key exchange only once.
4
4.1
Protocol Examples
Example Messages Host Information Message
4.1.1
The following is an example of a message describing the host on the client.

<Obj N="HostInfo" RefId="2"> <MS> <Obj N="_hostDefaultData" RefId="3"> ... ... </Obj> false false false false </MS> </Obj>
The following is an example of a message invoking a host method call remotely.

<Obj RefId="0"> <MS> <I64 N="ci">-100</I64> <Obj N="mi" RefId="1"> <TN RefId="0"> <T>System.Management.Automation.Remoting.RemoteHostMethodId</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>WriteLine2</ToString> <I32>16</I32> </Obj> <Obj N="mp" RefId="2"> <TN RefId="1"> <T>System.Collections.ArrayList</T> <T>System.Object</T> </TN> <LST> <S>hello</S> </LST> </Obj> </MS> </Obj>
PR
EL
IM
IN
4.1.2
Host Method Call Message
AR
92 / 105
4.1.3
Host Method Call Invocation Response Message
The following is an example of a message which contains a response to a host method call invocation.
<Obj RefId="9"> <MS> <S N="mr">Test</S> <I64 N="ci">1</I64> <Obj N="mi" RefId="10"> <TN RefId="4"> <T>System.Management.Automation.Remoting.RemoteHostMethodId</T> <T>System.Enum</T> <T>System.ValueType</T> <T>System.Object</T> </TN> <ToString>ReadLine</ToString> <I32>11</I32> </Obj> </MS> </Obj>
4.1.4
Progress Record Serialization Example
The following represents a progress record serialization example.

<PR> <AV>File copy</AV> <AI>123</AI> <CO>Copying sample.txt</CO> <PI>-1</PI> <PC>60</PC> <T>Processing</T> <SR>5</SR> <SD>Copied 3 out of 5 files</SD> </PR>
4.2
Serialized Data Element
PR
EL
The following is a example of serialized data element of a Create RunspacePool protocol message.
<Obj RefId="1"> <MS> <I32 N="MinRunspaces">1</I32> <I32 N="MaxRunspaces">1</I32> <Obj N="HostInfo" RefId="2"> <MS> true true true false </MS> </Obj> </MS>
IM
IN
93 / 105
AR
</Obj>
4.3
Transport Message Examples
The following examples show how to represent transport-specific data blocks. ObjectId: A value of 1 is represented as follows.
Byte Byte Byte Byte Byte Byte Byte Byte 0: 1: 2: 3: 4: 5: 6: 7: 0 0 0 0 0 0 0 1
FragmentId: A value of 1 is represented as follows.

Byte Byte Byte Byte Byte Byte Byte Byte 0: 1: 2: 3: 4: 5: 6: 7: 0 0 0 0 0 0 0 1
The following steps describe the client/server communication from the client's perspective. 1. The client initiates a remote connection with the server by sending a Create Action message. The client includes all the necessary data as explained in the Create Action message. 2. The client receives a response from the server. Response can be either success or failure. See [MS-WSMV] to find out what constitutes a success or failure.
PR
EL
3. If the response represents a success message and if there is data available to send to the server, the client sends this data using a Send Action message.
4. The client sends a Receive Action message. This will enable server to send data to the client (as a server will not send data to the client without first receiving a Receive Action message). 5. The client receives response messages for the Send Action message and Receive Action message. 6. After a response for the Send Action message is received, client sends more data, if available, as specified in Step 3. This step can be performed many times as long as client has data to send to server. 7. The client starts a remote command by sending a Command Action SOAP xml message to the server. If the serialized pipeline does not fit in Command Action SOAP message, then only the
IM
4.4
Client Server Communication Examples from the Client Perspective
IN
AR
94 / 105
portion that fits in will be sent. The rest of the serialized pipeline will be sent using Send Action SOAP messages as described in Step 9 and Step 12. 8. The client receives a response from the server. Response can be either success or failure. See [MS-WSMV] to find out what constitutes a success or failure. 9. If the response represents a success message and if there is data available to send to command running on the server, the client sends this data using Send Action SOAP xml message. 10.Client sends a Receive Action SOAP xml message. This will enable command running on the server to send data to the client.
11.The client receives response messages for Send Action message and Receive Action message.
13.The client can stop the command any time by sending a Signal Action SOAP message.
14.Finally, the client deletes the remote shell session by sending a Delete Action SOAP message. In between these steps, the client can receive data at any time by a ReceiveResponse SOAP message. This ReceiveResponse message contains data like command output, command state, command errors, and so on.
PR
EL
IM
IN
AR
12.After a response for the Send Action message is received, the client sends more data, if available, as specified in Step 9. This step can be performed many times as long as the client has data to send to the server.
5
5.1
Security
Security Considerations for Implementers
None.
5.2
Index of Security Parameters
None.
PR
EL
IM
IN
AR
Appendix A: Product Behavior

The information in this specification is applicable to the following product versions: Windows 7 operating system Windows Server 2008 R2 operating system Exceptions, if any, are noted below. If a service pack number appears with the product version, behavior changed in that service pack. The new behavior also applies to subsequent service packs of the product unless otherwise specified. Unless otherwise specified, any statement of optional behavior in this specification prescribed using the terms SHOULD or SHOULD NOT implies Windows behavior in accordance with the SHOULD or SHOULD NOT prescription. Unless otherwise specified, the term MAY implies that Windows does not follow the prescription.
PR
EL
IM
IN
AR
Change Tracking
This section identifies changes made to [MS-PSRP] protocol documentation between April 2009 and May 2009 releases. Changes are classed as major, minor, or editorial. Major changes affect protocol interoperability or implementation. Examples of major changes are: A document revision that incorporates changes to interoperability requirements or functionality. An extensive rewrite, addition, or deletion of major portions of content. A protocol is deprecated. The removal of a document from the documentation set. Changes made for template compliance.
Minor changes do not affect protocol interoperability or implementation. Examples are updates to fix technical accuracy or ambiguity at the sentence, paragraph, or table level. Editorial changes apply to grammatical, formatting, and style issues. No changes means that the document is identical to its last release.
Major and minor changes can be described further using the following revision types: New content added. Content update. Content removed.
New product behavior note added. Product behavior note updated.
Product behavior note removed. New protocol syntax added. Protocol syntax updated.
Protocol syntax removed.
PR
EL
New content added due to protocol revision. Content updated due to protocol revision. Content removed due to protocol revision. New protocol syntax added due to protocol revision. Protocol syntax updated due to protocol revision. Protocol syntax removed due to protocol revision. New content added for template compliance. Content updated for template compliance.
IM
98 / 105
IN
AR
Content removed for template compliance. Obsolete document removed. Editorial changes always have the revision type "Editorially updated." Some important terms used in revision type descriptions are defined as follows: Protocol syntax refers to data elements (such as packets, structures, enumerations, and methods) as well as interfaces.
Section 1.1 Glossary 1.1 Glossary
Tracking number (if applicable) and description
28557 Revised definition of host.
1.2.1 Normative References
IN
30214 Removed [MS-WSMAN] reference, as it is no longer cited in the specification. Removed [MSDN-Runspace] reference, as it is no longer cited in the specification. 30214 Removed [MS-WSMAN] from list of protocols and figure. 28562 Replaced instances of PowerShell with PowerShell Pipeline. N Y N N 28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell N N N
28787 Removed the phrase "PowerShell engine" from specification and revised definition of unspace.
1.2.2 Informative References
IM
1.4 Relationship to Other Protocols
EL
2.2.2.18 DataType: 0x00041002: Input to a PowerShell Pipeline on the Server 2.2.2.19 DataType: 0x00041003: Close the Input Collection for the PowerShell Pipeline on the Server 2.2.2.20 DataType: 0x00041004: Output of a Copyright 2009 Microsoft Corporation. Release: Thursday, May 21, 2009
2.2.2.12 DataType: 0x00021006: Create a PowerShell Pipeline and Invoke It in the Specified RunspacePool
PR
[MS-PSRP] v20090521 PowerShell Remoting Protocol Specification
AR
Major change (Y or N) N N Revision Type Content update. Content update. Content update. Content update. Content update. Content update. Content update. Content update.
Changes are listed in the following table. If you need further information, please contact protocol@microsoft.com.
Y
Product behavior note updated. 99 / 105
Protocol revision refers to changes made to a protocol that affect the bits that are sent over the wire.
Section PowerShell Pipeline on the Server 2.2.2.21 DataType: 0x00041005: Error Record from a PowerShell Pipeline on the Server 2.2.2.22 DataType: 0x00041006: State Information of a PowerShell Pipeline on the Server 2.2.2.23 DataType: 0x00041007: Debug Record from a PowerShell Pipeline on the Server 2.2.2.24 DataType: 0x00041008: Verbose Record from a PowerShell Pipeline on the Server 2.2.2.25 DataType: 0x00041009: Warning Record from a PowerShell Pipeline on the Server 2.2.2.26 DataType: 0x00041010: Progress Record from a PowerShell Pipeline on the Server 2.2.2.27 DataType: 0x00041012: Stop a PowerShell Pipeline on the Server
Tracking number (if applicable) and description with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline.
Major change (Y or N)
Revision Type
Content update.
28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline.
IN
N N 28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline. 28562 Replaced instances of PowerShell with PowerShell Pipeline. Added Windows Server 2008 R2 to list of applicable product versions. N N N N Y
IM
EL
2.2.2.29 DataType: 0x00041101: Response from the Host Associated with the PowerShell Pipeline on the Server 2.2.3.11 PowerShell Pipeline 6 Appendix A: Product Behavior Copyright 2009 Microsoft Corporation. Release: Thursday, May 21, 2009
2.2.2.28 DataType: 0x00041100: Method Call on the Host Associated with the PowerShell Pipeline on the Server
PR
[MS-PSRP] v20090521 PowerShell Remoting Protocol Specification
AR
N Content update. N Content update. Content update. Content update. Content update. Content update. Content update. Content update. New content added due to protocol revision. 100 / 105
Y
Content update.
8
A
Index
D
Data model - abstract client server Dictionary parameter - encoding Abstract data model client server ApartmentState data type Applicability ArrayList parameter - encoding
C
Capability negotiation Change tracking Client abstract data model higher-layer triggered events initialization local events message processing general rules overview sequence of command execution transporting using WS-MAN overview sequencing rules overview sequence of command execution transporting messages using WS-MAN timer events timers Client/server communication examples from client's perspective Collection parameter - encoding Color data type Command data type Command Parameter data type Complex objects - serialization of as string contents of Enums contents of known containers Dictionaries List overview Queue Stack contents of other complex objects contents of primitive types with notes extended properties Obj Element overview referencing earlier objects overview RefId attribute ToString type names Coordinates data type CultureInfo parameter - encoding
IM
PR
EL
IN
F G
Glossary
ErrorCategory data type ErrorRecord data type Examples client/server communication from client's perspective messages host information host method call host method call invocation response overview progress record serialization overview serialized data element transport message Exception as ErrorRecord data type
Fields - vendor-extensible
H
Higher-layer triggered events client server Host Method Identifier data type Host parameters - encoding in host method calls ArrayList parameter as extended properties collection parameter CultureInfo parameter dictionary parameter list parameter object dictionary parameter overview serializable elements HostInfo data type
I
Implementer - security considerations Index of security parameters InformationalRecord data type Informative references
AR
101 / 105
Initialization client server Introduction
L
List parameter - overview Local events client server
M
Message processing client general rules overview sequence of command execution transporting messages using WS-MAN server general rules (section 3.2.5.1, section 3.2.5.3) overview transporting messages using WS-MAN Messages data types 0x00000001: exception wrapped in PowerShell error record 0x00010002: session capability 0x00010003: close session 0x00010004: create RunspacePool 0x00021002: set maximum runspaces in RunspacePool 0x00021003: set minimum runspaces in RunspacePool 0x00021004: response to setting maximum or minimum runspaces in RunspacePool 0x00021005: state information of RunspacePool 0x00021006: create PowerShell and call it in specified RunspacePool 0x00021007: get number of available runspaces in RunspacePool 0x00021008: report user-defined event from remote runspace 0x00021100: method call on host associated with RunspacePool 0x00021101: response from host associated with RunspacePool 0x00041002: input to PowerShell on server 0x00041003: close input collection for PowerShell on server 0x00041004: output of PowerShell on server 0x00041005: error record from PowerShell on server 0x00041006: state information of PowerShell on server 0x00041007: debug record from PowerShell on server 0x00041008: verbose record from PowerShell on server
IM
0x00041009: warning record from PowerShell on server 0x00041010: progress record from PowerShell on server 0x00041012: stop pipeline on server 0x00041100: method call on host associated with pipeline on server 0x00041101: response from host associated with pipeline on server ApartmentState Color Command Command Parameter Coordinates ErrorCategory ErrorRecord Exception as ErrorRecord Host Method Identifier HostInfo InformationalRecord PowerShell PSInvocationState PSThreadOptions RemoteStreamOptions RunspacePoolState Size TimeZone examples host information message host method call invocation response message host method call message overview progress record serialization overview syntax data encoding host parameters in host method calls other object types overview serialization transport
EL
PR
IN
N O P
Normative references
Object dictionary parameter - encoding Overview (synopsis)
Packet_Fragment packet Parameters - security index PowerShell data type PowerShell_Remoting_Protocol_Message packet Preconditions Prerequisites Primitive types - serialization of Array of Bytes Boolean 102 / 105
AR
R
References informative normative overview RefID attribute overview Ref element Relationship to other protocols RemoteStreamOptions data type RunspacePoolState data type
PR
Security implementer considerations overview parameter index Sending messages Sequencing rules client overview sequence of command execution transporting messages using WS-MAN server general rules overview transporting messages using WS-MAN Serialization complex objects contents of Enums contents of known containers contents of other complex objects
EL
IM
IN
Character Date/Time Decimal Double Duration Float GUID Null Value overview Progress Record ScriptBlock Secure String Signed Byte Signed Int Signed Long Signed Short String Unsigned Byte Unsigned Int Unsigned Long Unsigned Short URI Version XML Document Product behavior PSInvocationState data type PSThreadOptions data type
contents of primitive types with notes extended properties Obj Element overview referencing earlier objects serialized as string ToString type names encoding strings lifetime of serializer/deserializer pair overview primitive types Array of Bytes Boolean Character Date/Time Decimal Double Duration Float GUID Null Value overview Progress Record ScriptBlock Secure String Signed Byte Signed Int Signed Long Signed Short String Unsigned Byte Unsigned Int Unsigned Long Unsigned Short URI Version XML Document property name structure of complex objects adapted properties extended properties overview property sets ToString value Serialized data element example Server abstract data model higher-layer triggered events initialization local events message processing general rules (section 3.2.5.1, section 3.2.5.3) overview transporting using WS-MAN overview sequencing rules general rules overview transporting messages using WS-MAN timer events
AR
Y
103 / 105
PR
timers Size data type Standards assignments Syntax data types 0x00000001: exception wrapped in PowerShell error record 0x00010002: session capability 0x00010003: close session 0x00010004: create RunspacePool 0x00021002: set maximum runspaces in RunspacePool 0x00021003: set minimum runspaces in RunspacePool 0x00021004: response to setting maximum or minimum runspaces in RunspacePool 0x00021005: state information of RunspacePool 0x00021006: create PowerShell and call it in specified RunspacePool 0x00021007: get number of available runspaces in RunspacePool 0x00021008: report user-defined event from remote runspace 0x00021100: method call on host associated with RunspacePool 0x00021101: response from host associated with RunspacePool 0x00041002: input to PowerShell on server 0x00041003: close input collection for PowerShell on server 0x00041004: output of PowerShell on server 0x00041005: error record from PowerShell on server 0x00041006: state information of PowerShell on server 0x00041007: debug record from PowerShell on server 0x00041008: verbose record from PowerShell on server 0x00041009: warning record from PowerShell on server 0x00041010: progress record from PowerShell on server 0x00041012: stop pipeline on server 0x00041100: method call on host associated with pipeline on server 0x00041101: response from host associated with pipeline on server ApartmentState Color Command Command Parameter Coordinates ErrorCategory ErrorRecord Exception as ErrorRecord Host Method Identifier HostInfo InformationalRecord overview
IM
Timer events client server Timers client server TimeZone data type Tracking changes Transport Transport message examples Triggered events - higher-layer client server
EL
IN
V W
Vendor-extensible fields Versioning
WS-MAN - transporting messages using client creating shell on PowerShell server deleting shell on PowerShell server executing command on remote shell negotiating with server overview receiving output from command or shell sending input to command or shell signaling command server negotiating with client overview response to Create Command request response to Create Shell request 104 / 105
AR
PowerShell PSInvocationState PSThreadOptions RemoteStreamOptions RunspacePoolState Size TimeZone encoding host parameters in host method calls ArrayList parameter as extended properties collection parameter CultureInfo parameter dictionary parameter list parameter object dictionary parameter overview serializable elements other object types overview serialization complex objects overview primitive types
response response response response
to to to to
Delete request Receive request Send request Signal request
PR
EL
IM
IN
AR

Preliminary: (MS-PSRP) : Powershell Remoting Protocol Specification

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Preliminary: (MS-PSRP) : Powershell Remoting Protocol Specification

Uploaded by

Copyright:

Available Formats

[MS-PSRP]: PowerShell Remoting Protocol Specification

Intellectual Property Rights Notice for Open Specifications Documentation

Revised and edited the technical content.

Index ................................................................................................................... 101

Command: Any entity which can be executed in PowerShell.

WS-MAN: The Web Services Management Protocol, as specified in [MS-WSMV].

References Normative References

[MSDN-TIMEZONEINFO] Microsoft Corporation, "TIME_ZONE_INFORMATION structure", http://msdn.microsoft.com/en-us/library/ms725481.aspx

Protocol Overview (Synopsis)

Relationship to Other Protocols

[MSDN-CAPI] Microsoft Corporation, "Cryptography", http://msdn.microsoft.com/enus/library/aa380255.aspx

Figure 1: Relationship of PowerShell Remoting Protocol to other protocols

The server must have Windows PowerShell 2.0 installed.

Versioning and Capability Negotiation

1. Construct the protocol message as described in section 2.2.1.

PowerShell Remoting Protocol Message

The structure of a PowerShell Remoting Protocol Message is as follows.

Destination (4 bytes): The destination of this message. Possible values.

Exception wrapped in a PowerShell error record.

Value 0x00010004 0x00010005 0x00010006 0x00010007 0x00021002 0x00021003 0x00021004

Set minimum runspaces in a RunspacePool.

0x00021005 0x00021006 0x00021007 0x00021008 0x00021009

State information of a RunspacePool.

Set maximum runspaces in a RunspacePool.

Message Data DataType: 0x00000001: Exception Wrapped in a PowerShell Error Record

DataType: 0x00010002: Session Capability

Property name: SerializationVersion.

Property type: Boolean (see section 2.2.5.1.3).

AAhU3lzdGVtLkdsb2JhbGl6YXRpb24uRGF5bGlnaHRUaW1lAwAAAAdtX3N0YXJ0BW1fZW5kB21fZGVsdGEAAAANDQwAkO q4qG3LiAAQOyeuKMyIAGjEYQgAAAAL</BA> </MS> </Obj>

DataType: 0x00010003: Close Session

Property name: PSThreadOptions.

Property type: PSThreadOptions (see section 2.2.3.6). Apartment state

Property name: ApartmentState.

Property type: ApartmentState (see section 2.2.3.7). Host information

Property name: HostInfo.

Property type: HostInfo (see section 2.2.3.14)

Minimum number of runspaces in the RunspacePool.

DataType: 0x00010004: Create RunspacePool

DataType: 0x00010005: Public Key

Property type: String (see section 2.2.5.1.1). Example:

DataType: 0x00010006: Encrypted Session Key

Property type: String (see section 2.2.5.1.1). Example:

DataType: 0x00010007: Public Key Request

DataType: 0x00021002: Set Maximum Runspaces in a RunspacePool

Property name: EncryptedSessionKey.

DataType: 0x00021003: Set Minimum Runspaces in a RunspacePool

2.2.2.10 DataType: 0x00021004: A Response to Setting Maximum or Minimum Runspaces in a RunspacePool

Property type: Signed long (see section 2.2.5.1.13).

Property name: SetMinMaxRunspacesResponse.

<Obj RefId="2"> <MS> <B N="SetMinMaxRunspacesResponse">true</B> <I64 N="ci">1</I64> </MS> </Obj>

DataType: 0x00021005: State Information of a RunspacePool

RunspacePool state information Property name: RunspaceState.

Property type: RunspacePoolState (see section 2.2.3.4).

Property type: Exception as ErrorRecord (see section 2.2.3.13). Example:

<Obj RefId="1"> <MS> <I32 N="RunspaceState">2</I32> </MS> </Obj>

Property name: NoInput.

Property type: Boolean (see section 2.2.5.1.3).

Property name: ApartmentState. Property type: ApartmentState (see section 2.2.3.7).

Property type: HostInfo (see section 2.2.3.15).

2.2.2.13 DataType: 0x00021007: Get the Number of Available Runspaces in a RunspacePool

Property type: Signed int (see section 2.2.5.1.11). Source identifier

Property name: PSEventArgs.SourceIdentifier.