The MessageHeaderAttribute attribute allows you to map fields and properties of a type marked with the MessageContractAttribute attribute to SOAP message headers. The field or property can be of a simple type or a composite type that can be serialized.

For information on controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see System.Runtime.Serialization..::.DataContractAttribute, Specifying Data Transfer in Service Contracts, and Data Contracts Overview.

For more information about creating message contracts, see Using Message Contracts.

The SOAP standard defines the following attributes that can exist on a header:

• Actor or Role (Actor in SOAP 1.1, Role in SOAP 1.2)

• MustUnderstand

• Relay

The Actor or Role attribute specifies the URI of the node for which a given header is intended. The MustUnderstand attribute specifies whether the header understands the node processing. The Relay attribute specifies whether the header is to be relayed to downstream nodes. Windows Communication Foundation (WCF) does not perform any processing of these attributes on incoming messages, except for the MustUnderstand attribute.

You can, however, read and write these attributes, even though they are not sent by default. You can set the attribute values in two ways. First, you can change the Actor, MustUnderstand and Relay properties on the MessageHeaderAttribute. (There is no Role property – set the Actor property and Role is passed if SOAP 1.2 is used). For example:

The second way to control these attributes is by making the desired header type the type parameter of the MessageHeader<(Of <(T>)>) class and using the resulting type together with the MessageHeaderAttribute. Then use the MessageHeader<(Of <(T>)>) properties programmatically to set the SOAP attributes. For example:

If both the dynamic and the static control mechanisms are used, the static settings are the default but can be overridden using the dynamic mechanism. For example:

Creating repeated headers with dynamic attribute control is allowed. For example:

[MessageHeaderArray] public MessageHeader<Person> documentApprovers[];

On the receiving side, reading these SOAP attributes can only be done if the generic MessageHeader<(Of <(T>)>) class is used. Examine the Actor, Relay or MustUnderstand properties of a header of the MessageHeader<(Of <(T>)>) type to discover the attribute settings on the received message.

When a message is received and then sent back, the SOAP attribute settings only roundtrip for headers of the MessageHeader<(Of <(T>)>) type.

The following code example shows the use of the MessageHeaderAttribute to create a SOAP header for the response message with the Name, Namespace and MustUnderstand properties set to values appropriate for this header. The code example is followed by an example of the message when sent.

 [MessageContract]
 public class HelloResponseMessage
 {
   private string localResponse = String.Empty;
   private string extra = String.Empty;

   [MessageBodyMember(
     Name = "ResponseToGreeting",
     Namespace = "http://www.examples.com")]
   public string Response
   {
     get { return localResponse; }
     set { localResponse = value; }
   }

   [MessageHeader(
     Name = "OutOfBandData",
     Namespace = "http://www.examples.com",
     MustUnderstand=true
   )]
   public string ExtraValues
   {
     get { return extra; }
     set { this.extra = value; }
  }

  /*
   The following is the response message, edited for clarity.

   <s:Envelope>
     <s:Header>
       <a:Action s:mustUnderstand="1">http://HelloResponseMessage/Action</a:Action>
       <h:OutOfBandData s:mustUnderstand="1" xmlns:h="http://www.examples.com">Served by object 13804354.</h:OutOfBandData>
     </s:Header>
     <s:Body>
       <HelloResponseMessage xmlns="Microsoft.WCF.Documentation">
         <ResponseToGreeting xmlns="http://www.examples.com">Service received: Hello.</ResponseToGreeting>
       </HelloResponseMessage>
     </s:Body>    
   </s:Envelope>
   */
}

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003

.NET Framework

Reference