MessageHeaderAttribute Class

Definition

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
Derived
Attributes

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

Actor

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.

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)
Relay

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

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)

Explicit Interface Implementations

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

Maps a set of names to a corresponding set of dispatch identifiers.

(Inherited from Attribute)
_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)
_Attribute.GetTypeInfoCount(UInt32)

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

(Inherited from Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Provides access to properties and methods exposed by an object.

(Inherited from Attribute)

Applies to