MessageHeaderAttribute Class
Collapse the table of content
Expand the table of content

MessageHeaderAttribute Class


Specifies that a data member is a SOAP message header.

Namespace:   System.ServiceModel
Assembly:  System.ServiceModel (in System.ServiceModel.dll)


[AttributeUsageAttribute(AttributeTargets.Property | AttributeTargets.Field, 
	AllowMultiple = false, Inherited = false)]
public class MessageHeaderAttribute : MessageContractMemberAttribute


Initializes a new instance of the MessageHeaderAttribute class.


Gets or sets a URI that indicates the node at which this header is targeted. Maps to the role header attribute when SOAP 1.2 is used and the actor header attribute when SOAP 1.1 is used.


When overridden in a derived class, gets a value that indicates whether the member has a protection level assigned. (Inherited from MessageContractMemberAttribute.)


Specifies whether the node acting in the Actor role must understand this header. This is mapped to the mustUnderstand SOAP header attribute.


Specifies the name of the element that corresponds to this member. (Inherited from MessageContractMemberAttribute.)


Specifies the namespace of the element that corresponds to this member. (Inherited from MessageContractMemberAttribute.)


Specifies whether the member is to be transmitted as-is, signed, or signed and encrypted. (Inherited from MessageContractMemberAttribute.)


Specifies whether this header is to be relayed to downstream nodes. This is mapped to the relay SOAP header attribute.


When implemented in a derived class, gets a unique identifier for this Attribute.(Inherited from Attribute.)


This API supports the product infrastructure and is not intended to be used directly from your code. Returns a value that indicates whether this instance is equal to a specified object.(Inherited from Attribute.)


Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)


Returns the hash code for this instance.(Inherited from Attribute.)


Gets the Type of the current instance.(Inherited from Object.)


When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.(Inherited from Attribute.)


When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.(Inherited from Attribute.)


Creates a shallow copy of the current Object.(Inherited from Object.)


Returns a string that represents the current object.(Inherited from Object.)

System_CAPS_pubinterfaceSystem_CAPS_privmethod_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)

Maps a set of names to a corresponding set of dispatch identifiers.(Inherited from Attribute.)

System_CAPS_pubinterfaceSystem_CAPS_privmethod_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Retrieves the type information for an object, which can be used to get the type information for an interface.(Inherited from Attribute.)


Retrieves the number of type information interfaces that an object provides (either 0 or 1).(Inherited from Attribute.)

System_CAPS_pubinterfaceSystem_CAPS_privmethod_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Provides access to properties and methods exposed by an object.(Inherited from Attribute.)

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 Using Data Contracts.

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<T> class and using the resulting type together with the MessageHeaderAttribute. Then use the MessageHeader<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<T> class is used. Examine the Actor, Relay or MustUnderstand properties of a header of the MessageHeader<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<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.

 public class HelloResponseMessage
   private string localResponse = String.Empty;
   private string extra = String.Empty;

     Name = "ResponseToGreeting",
     Namespace = "")]
   public string Response
     get { return localResponse; }
     set { localResponse = value; }

     Name = "OutOfBandData",
     Namespace = "",
   public string ExtraValues
     get { return extra; }
     set { this.extra = value; }

   The following is the response message, edited for clarity.

       <a:Action s:mustUnderstand="1">http://HelloResponseMessage/Action</a:Action>
       <h:OutOfBandData s:mustUnderstand="1" xmlns:h="">Served by object 13804354.</h:OutOfBandData>
       <HelloResponseMessage xmlns="Microsoft.WCF.Documentation">
         <ResponseToGreeting xmlns="">Service received: Hello.</ResponseToGreeting>

.NET Framework
Available since 3.0

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
© 2015 Microsoft