Export (0) Print
Expand All

MessageHeaderAttribute Class

Specifies that a data member is a SOAP message header.

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

'Declaration
<AttributeUsageAttribute(AttributeTargets.Property Or AttributeTargets.Field, AllowMultiple := False,  _
	Inherited := False)> _
Public Class MessageHeaderAttribute _
	Inherits MessageContractMemberAttribute

The MessageHeaderAttribute type exposes the following members.

  NameDescription
Public methodMessageHeaderAttributeInitializes a new instance of the MessageHeaderAttribute class.
Top

  NameDescription
Public propertyActorGets 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.
Public propertyHasProtectionLevelWhen overridden in a derived class, gets a value that indicates whether the member has a protection level assigned. (Inherited from MessageContractMemberAttribute.)
Public propertyMustUnderstandSpecifies whether the node acting in the Actor role must understand this header. This is mapped to the mustUnderstand SOAP header attribute.
Public propertyNameSpecifies the name of the element that corresponds to this member. (Inherited from MessageContractMemberAttribute.)
Public propertyNamespaceSpecifies the namespace of the element that corresponds to this member. (Inherited from MessageContractMemberAttribute.)
Public propertyProtectionLevelSpecifies whether the member is to be transmitted as-is, signed, or signed and encrypted. (Inherited from MessageContractMemberAttribute.)
Public propertyRelaySpecifies whether this header is to be relayed to downstream nodes. This is mapped to the relay SOAP header attribute.
Public propertyTypeIdWhen implemented in a derived class, gets a unique identifier for this Attribute. (Inherited from Attribute.)
Top

  NameDescription
Public methodEqualsInfrastructure. Returns a value that indicates whether this instance is equal to a specified object. (Inherited from Attribute.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeReturns the hash code for this instance. (Inherited from Attribute.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodIsDefaultAttributeWhen overridden in a derived class, indicates whether the value of this instance is the default value for the derived class. (Inherited from Attribute.)
Public methodMatchWhen overridden in a derived class, returns a value that indicates whether this instance equals a specified object. (Inherited from Attribute.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

  NameDescription
Explicit interface implemetationPrivate method_Attribute.GetIDsOfNamesMaps a set of names to a corresponding set of dispatch identifiers. (Inherited from Attribute.)
Explicit interface implemetationPrivate method_Attribute.GetTypeInfoRetrieves the type information for an object, which can be used to get the type information for an interface. (Inherited from Attribute.)
Explicit interface implemetationPrivate method_Attribute.GetTypeInfoCountRetrieves the number of type information interfaces that an object provides (either 0 or 1). (Inherited from Attribute.)
Explicit interface implemetationPrivate method_Attribute.InvokeProvides access to properties and methods exposed by an object. (Inherited from Attribute.)
Top

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

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

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