MessageHeaderAttribute Class

Definition

Namespace:

System.ServiceModel

Assembly:

System.ServiceModel.Primitives.dll

Package:

System.ServiceModel.Primitives v8.0.0

Source:

MessageHeaderAttribute.cs

Specifies that a data member is a SOAP message header.

public ref class MessageHeaderAttribute : System::ServiceModel::MessageContractMemberAttribute

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

[<System.AttributeUsage(System.AttributeTargets.Field | System.AttributeTargets.Property, AllowMultiple=false, Inherited=false)>]
type MessageHeaderAttribute = class
    inherit MessageContractMemberAttribute

Public Class MessageHeaderAttribute
Inherits MessageContractMemberAttribute

Inheritance

Object

Attribute

MessageContractMemberAttribute

MessageHeaderAttribute

Derived

System.ServiceModel.MessageHeaderArrayAttribute

System.ServiceModel.PeerHopCountAttribute

Attributes

AttributeUsageAttribute

Examples

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>
   */
}

  <MessageContract> _
  Public Class HelloResponseMessage
    Private localResponse As String = String.Empty
    Private extra As String = String.Empty

    <MessageBodyMember(Name := "ResponseToGreeting", Namespace := "http://www.examples.com")> _
    Public Property Response() As String
      Get
          Return localResponse
      End Get
      Set(ByVal value As String)
          localResponse = value
      End Set
    End Property

    <MessageHeader(Name := "OutOfBandData", Namespace := "http://www.examples.com", MustUnderstand:=True)> _
    Public Property ExtraValues() As String
      Get
          Return extra
      End Get
      Set(ByVal value As String)
          Me.extra = value
      End Set
    End Property

'   
'    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>
'      </s:Body>    
'    </s:Envelope>
'    
  End Class

Remarks

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.

Constructors

MessageHeaderAttribute()

Initializes a new instance of the MessageHeaderAttribute class.

Properties

HasProtectionLevel	When overridden in a derived class, gets a value that indicates whether the member has a protection level assigned. (Inherited from MessageContractMemberAttribute)
MustUnderstand	Specifies whether the node acting in the Actor role must understand this header. This is mapped to the mustUnderstand SOAP header attribute.
Name	Specifies the name of the element that corresponds to this member. (Inherited from MessageContractMemberAttribute)
Namespace	Specifies the namespace of the element that corresponds to this member. (Inherited from MessageContractMemberAttribute)
ProtectionLevel	Specifies whether the member is to be transmitted as-is, signed, or signed and encrypted. (Inherited from MessageContractMemberAttribute)
TypeId	When implemented in a derived class, gets a unique identifier for this Attribute. (Inherited from Attribute)

Methods

Equals(Object)	Returns a value that indicates whether this instance is equal to a specified object. (Inherited from Attribute)
GetHashCode()	Returns the hash code for this instance. (Inherited from Attribute)
GetType()	Gets the Type of the current instance. (Inherited from Object)
IsDefaultAttribute()	When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class. (Inherited from Attribute)
Match(Object)	When overridden in a derived class, returns a value that indicates whether this instance equals a specified object. (Inherited from Attribute)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
ToString()	Returns a string that represents the current object. (Inherited from Object)