[MC-NETCEX]:
.NET Context Exchange Protocol
Intellectual Property Rights Notice for Open Specifications Documentation
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.
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, IDL's, 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 Open Specification Promise or the Community Promise. 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 .
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. For a list of Microsoft trademarks, visit
Fictitious Names. The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.
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.
Revision Summary
Date / Revision History / Revision Class / Comments4/8/2008 / 0.1 / Version 0.1 release
5/16/2008 / 0.1.1 / Editorial / Changed language and formatting in the technical content.
6/20/2008 / 0.1.2 / Editorial / Changed language and formatting in the technical content.
7/25/2008 / 0.1.3 / Editorial / Changed language and formatting in the technical content.
8/29/2008 / 0.1.4 / Editorial / Changed language and formatting in the technical content.
10/24/2008 / 0.1.5 / Editorial / Changed language and formatting in the technical content.
12/5/2008 / 0.1.6 / Editorial / Changed language and formatting in the technical content.
1/16/2009 / 0.1.7 / Editorial / Changed language and formatting in the technical content.
2/27/2009 / 1.0 / Major / Updated and revised the technical content.
4/10/2009 / 1.0.1 / Editorial / Changed language and formatting in the technical content.
5/22/2009 / 1.0.2 / Editorial / Changed language and formatting in the technical content.
7/2/2009 / 1.0.3 / Editorial / Changed language and formatting in the technical content.
8/14/2009 / 1.0.4 / Editorial / Changed language and formatting in the technical content.
9/25/2009 / 1.1 / Minor / Clarified the meaning of the technical content.
11/6/2009 / 1.1.1 / Editorial / Changed language and formatting in the technical content.
12/18/2009 / 1.1.2 / Editorial / Changed language and formatting in the technical content.
1/29/2010 / 1.2 / Minor / Clarified the meaning of the technical content.
3/12/2010 / 1.2.1 / Editorial / Changed language and formatting in the technical content.
4/23/2010 / 1.2.2 / Editorial / Changed language and formatting in the technical content.
6/4/2010 / 1.2.3 / Editorial / Changed language and formatting in the technical content.
7/16/2010 / 2.0 / Major / Updated and revised the technical content.
8/27/2010 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
10/8/2010 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
11/19/2010 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
1/7/2011 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
2/11/2011 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
3/25/2011 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
5/6/2011 / 2.0 / None / No changes to the meaning, language, or formatting of the technical content.
6/17/2011 / 2.1 / Minor / Clarified the meaning of the technical content.
9/23/2011 / 2.1 / None / No changes to the meaning, language, or formatting of the technical content.
12/16/2011 / 3.0 / Major / Updated and revised the technical content.
3/30/2012 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
7/12/2012 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
10/25/2012 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
1/31/2013 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
8/8/2013 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
11/14/2013 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
2/13/2014 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
5/15/2014 / 3.0 / None / No changes to the meaning, language, or formatting of the technical content.
6/30/2015 / 4.0 / Major / Significantly changed the technical content.
10/16/2015 / 4.0 / No Change / No changes to the meaning, language, or formatting of the technical content.
Table of Contents
1Introduction
1.1Glossary
1.2References
1.2.1Normative References
1.2.2Informative References
1.3Overview
1.4Relationship to Other Protocols
1.5Prerequisites/Preconditions
1.6Applicability Statement
1.7Versioning and Capability Negotiation
1.8Vendor-Extensible Fields
1.9Standards Assignments
2Messages
2.1Transport
2.2Message Syntax
2.2.1CONTEXT_XML
2.2.2CALLBACK_CONTEXT_XML
2.2.3CONTEXT_NV
2.2.4HTTP Client Message Header
2.2.5HTTP Server Message Header
2.2.6Server Context Establishing Message
2.2.7Context Participating Message
3Protocol Details
3.1Context Exchange Client Role Details
3.1.1Abstract Data Model
3.1.1.1IDLE State
3.1.1.2WAIT_CORRELATED_SM State
3.1.1.3WAIT_SM State
3.1.1.4ENDED State
3.1.2Timers
3.1.3Initialization
3.1.4Higher-Layer Triggered Events
3.1.4.1SEND_CM
3.1.4.2TERMINATE
3.1.5Message Processing Events and Sequencing Rules
3.1.5.1RECEIVE_SM
3.1.6Timer Events
3.1.7Other Local Events
3.2Context Exchange Server Role Details
3.2.1Abstract Data Model
3.2.1.1WAIT_CM State
3.2.1.2ENDED State
3.2.2Timers
3.2.3Initialization
3.2.4Higher-Layer Triggered Events
3.2.4.1TERMINATE
3.2.5Message Processing Events and Sequencing Rules
3.2.5.1RECEIVE_CM
3.2.6Timer Events
3.2.7Other Local Events
3.3Callback Context Exchange Client Role Details
3.3.1Abstract Data Model
3.3.1.1WAIT_SM State
3.3.1.2ENDED State
3.3.2Timers
3.3.3Initialization
3.3.4Higher-Layer Triggered Events
3.3.4.1TERMINATE
3.3.5Message Processing Events and Sequencing Rules
3.3.5.1SEND_CM
3.3.5.2RECEIVE_SM
3.3.6Timer Events
3.3.7Other Local Events
3.4Callback Context Exchange Server Role Details
3.4.1Abstract Data Model
3.4.1.1WAIT_CM State
3.4.1.2ENDED State
3.4.2Timers
3.4.3Initialization
3.4.4Higher-Layer Triggered Events
3.4.4.1TERMINATE
3.4.5Message Processing Events and Sequencing Rules
3.4.5.1RECEIVE_CM
3.4.5.2SEND_SM
3.4.6Timer Events
3.4.7Other Local Events
4Protocol Examples
4.1Using the .NET Context Exchange Protocol with SOAP 1.2
4.1.1Establishing Context Using SOAP 1.2
4.1.2Subsequent Context Participating Messages Using SOAP 1.2
4.1.3Continue Using Context Using SOAP 1.2
4.1.4Establish a Callback Context
4.1.5Subsequent Callback Messages
4.2Using the .NET Context Exchange Protocol with HTTP
4.2.1Establishing Context Using HTTP
4.2.2Subsequent Context Participating Messages Using HTTP
4.2.3Continue Using the Context Using HTTP
4.3Processing an Unrecognized Context Using SOAP 1.2
4.4Processing an Unrecognized Context Using HTTP
5Security
5.1Security Considerations for Implementers
5.2Index of Security Parameters
6Appendix A: Product Behavior
7Change Tracking
8Index
1Introduction
This document specifies the .NET Context Exchange Protocol, which specifies a message syntax for identifying context that is shared between a client and a server, and a protocol for establishing that context.
Sections 1.8, 2, and 3 of this specification are normative and can contain the terms MAY, SHOULD, MUST, MUST NOT, and SHOULD NOT as defined in [RFC2119]. Sections 1.5 and 1.9 are also normative but do not contain those terms. All other sections and examples in this specification are informative.
1.1Glossary
The following terms are specific to this document:
base64 encoding: A binary-to-text encoding scheme whereby an arbitrary sequence of bytes is converted to a sequence of printable ASCII characters, as described in [RFC4648].
callback context: The context that is required for a server to make callbacks to a client. A callback context consists of an endpoint reference for a clientendpoint with an optional context identifier.
client: A computer on which the remote procedure call (RPC) client is executing.
Client Context Initiating Message: A client message that requests a server to establish a context.
client message: A message that is sent from a client to a server.
connection: A time-bounded association between two endpoints that allows the two endpoints to exchange messages.
context: An abstract concept that represents an association between a resource and a set of messages that are exchanged between a client and a server. A context is uniquely identified by a context identifier.
context identifier: A GUID that identifies a context.
Context Participating Message: A client message or a server message that is one of a set of messages associated with a context.
endpoint: A communication port that is exposed by an application server for a specific shared service and to which messages can be addressed.
endpoint reference (EPR): A resource that conveys the information that is needed to address an endpoint.
server: A computer on which the remote procedure call (RPC) server is executing.
Server Context Establishing Message: A server message that establishes a new context and is correlated to a Client Context Initiating Message.
server message: A message that is sent from a server to a client.
SOAP: A lightweight protocol for exchanging structured information in a decentralized, distributed environment. SOAP uses XML technologies to define an extensible messaging framework, which provides a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation-specific semantics. SOAP 1.2 supersedes SOAP 1.1. See [SOAP1.2-1/2003].
SOAP envelope: A container for SOAP message information and the root element of a SOAP document. See [SOAP1.2-1/2007] section 5.1 for more information.
SOAP fault: A container for error and status information within a SOAP message. See [SOAP1.2-1/2007] section 5.4 for more information.
SOAP header: A mechanism for implementing extensions to a SOAP message in a decentralized manner without prior agreement between the communicating parties. See [SOAP1.2-1/2007] section 5.2 for more information.
SOAP message: An XML document consisting of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body. See [SOAP1.2-1/2007] section 5 for more information.
UTF-8: A byte-oriented standard for encoding Unicode characters, defined in the Unicode standard. Unless specified otherwise, this term refers to the UTF-8 encoding form specified in [UNICODE5.0.0/2007] section 3.9.
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2References
Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.
1.2.1Normative References
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 . We will assist you in finding the relevant information.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997,
[RFC2234] Crocker, D. and Overell, P., "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997,
[RFC2616] Fielding, R., Gettys, J., Mogul, J., et al., "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999,
[RFC3548] Josefsson, S., Ed., "The Base16, Base32, and Base64 Data Encodings", RFC 3548, July 2003,
[RFC3629] Yergeau, F., "UTF-8, A Transformation Format of ISO 10646", STD 63, RFC 3629, November 2003,
[SOAP1.1] Box, D., Ehnebuske, D., Kakivaya, G., et al., "Simple Object Access Protocol (SOAP) 1.1", May 2000,
[SOAP1.2-1/2007] Gudgin, M., Hadley, M., Mendelsohn, N., et al., "SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)", W3C Recommendation 27, April 2007,
[W3C-XSD] World Wide Web Consortium, "XML Schema Part 2: Datatypes Second Edition", October 2004,
[WSA] Gudgin, M., Hadley, M., and Rogers, T., "Web Services Addressing 1.0 - Core", W3C Recommendation, May 2006,
[XML1.0] Bray, T., Paoli, J., Sperberg-McQueen, C.M., and Maler, E., "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C Recommendation, October 2000,
1.2.2Informative References
[RFC2109] Kristol, D., and Montulli, L., "HTTP State Management Mechanism", RFC 2109, February 1997,
[RFC2965] Kristol, D. and Montulli, L., "HTTP State Management Mechanism", RFC 2965, October 2000,
[RFC4346] Dierks, T., and Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006,
[WSS1] Nadalin, A., Kaler, C., Hallam-Baker, P., et al., "Web Services Security: SOAP Message Security 1.0 (WS-Security 2004)", March 2004,
1.3Overview
The .NET Context Exchange Protocol specifies a message syntax for identifying context that is shared between a client and a server independent of connection usage, and a protocol for establishing that context. For example, in some scenarios, the connection between a client and a server is sufficient for the server to relate the client messages to specific resources; a chat application can define a conversation resource and relate chat messages to a conversation by associatingthe conversation with chat messages that arrive over a particular connection.
It is typical, however, for a set of client messages to be associated with a resource that is independent of a connection. For example, a SOAP-based shopping application can define a shopping cart resource and relate client messages to the shopping cart even if the first few messages arrive on one connection and the remaining messages arrive on a different connection. The .NET Context Exchange Protocol facilitates this more general connection-independent case.
The .NET Context Exchange Protocol can be used in one of two modes: stateless or stateful. In stateless mode, a client and server use the message syntax specified in section 2.2; however, the interpretation of this syntax is defined by the client and server implementations. In stateful mode the client and server must interpret the message syntax as specified in section 3. Unless explicitly mentioned, this document discusses the .NET Context Exchange Protocol in stateful mode.
This protocol specifies two roles for context exchange: a client role and a server role. The server role is responsible for creating context identifiers in response to client requests and associating context identifiers with resources. For example, a shopping service may create a context identifier with the following (property name, property value) pair.
Property name / Property valueshoppingCartId / 1a1913b1-cb24-4d94-91d2-cf414a569481
It may then store a shopping cart resource by using the value of the shoppingCartId as a key.
The client role initiates communication with the server role, captures the context identifier that is sent from the server role, and attaches the context identifier to all subsequent client messages that are related to the resources in question. For example, a client shopping application may use the previously mentioned shopping service to create a shopping cart resource using the .NET Context Exchange Protocol. The client stores the context identifier that is generated by the server and attaches it to each message that is intended to manipulate the shopping cart.
The protocol also specifies two roles for callback context exchange: a client role and a server role.<1> The initial communication of the client role with the server role may specify a callback context to enable duplex communication. The callback context consists of an endpoint reference that specifies the address of the client endpoint. The endpoint reference may optionally contain a context identifier that is associated with resources by the client. For example, a customer of a shopping service may create a context identifier with the following (property name, property value) pair.
Property name / Property valuecustomerId / 9b0e43f0-e783-4cb9-8343-106d677c4ed7
Note that the roles for context exchange and callback context exchange compose. For example, the entity acting as the client role for context exchange may also act as the client role for callback context exchange.
The following figure describes the typical use of the .NET Context Exchange Protocol.
Figure 1: Typical use of the .NET Context Exchange Protocol
Each message that is exchanged between client and server is an application-specific message. This protocol is a header-based protocol that composes into client and server messages:
- The client sends a Client Context Initiating Message to the server. The server recognizes this message as a Client Context Initiating Message because it does not have a context identifier attached.
- The server creates a resource (for example, a shopping cart) and a new context identifier. It then associates the resource with the new context identifier.
- The server returns a Server Context Establishing Message to the client with the newly created context identifier attached.
- The client stores the attached context identifier so that it can be retrieved even if the client process is restarted.
- The client sends the server a Context Participating Message with the context identifier attached. This message is intended to manipulate the resource that is created in step 2. For example, it may be intended to add an item to the shopping cart.
- The server dereferences the resource using the context identifier. For example, it may use the property value of the property named "shoppingCartId" in the predicate of a database query to retrieve the shopping cart. It may then act on the resource according to the message it received.
- The server sends a response back to the client.
- At some point later on a different connection, the client retrieves the context identifier that it stored earlier in step 4.
- The client then sends the server a Context Participating Message that has the context identifier attached. This message is intended to manipulate the resource that was created in step 2. For example, it may be intended to purchase the items in the shopping cart.
The message that is sent by the client is also a Callback Context Establishing Message that has a callback context attached. This allows the server to engage in a duplex conversation with the client. For example, it allows the server to notify the client when the purchased items have shipped.