MessageHeaderAttribute 類別

定義

指定某個資料成員為 SOAP 訊息標頭。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, Inherited=false)]
public class MessageHeaderAttribute : System.ServiceModel.MessageContractMemberAttribute
type MessageHeaderAttribute = class
    inherit MessageContractMemberAttribute
Public Class MessageHeaderAttribute
Inherits MessageContractMemberAttribute
繼承
衍生
屬性

範例

下列程式碼範例示範如何使用 MessageHeaderAttribute 為回應訊息建立 SOAP 標頭,此回應訊息的 NameNamespaceMustUnderstand 屬性已設定為適用於這個標頭的值。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

備註

MessageHeaderAttribute 屬性 (Attribute) 可讓您將含有 MessageContractAttribute 屬性 (Attribute) 標記之型別的欄位和屬性 (Property),對應至 SOAP 訊息標頭。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.

如需控制 SOAP 本文內容的序列化而不修改預設 SOAP 封套本身的詳細資訊,請參閱 System.Runtime.Serialization.DataContractAttribute在服務合約中指定資料傳輸使用資料合約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.

SOAP 標準會定義下列可存在於標頭的屬性:The SOAP standard defines the following attributes that can exist on a header:

  • ActorRole (在 SOAP 1.1 中為 Actor,在 SOAP 1.2 中為 Role)Actor or Role (Actor in SOAP 1.1, Role in SOAP 1.2)

  • MustUnderstand

  • Relay

ActorRole 屬性會指定節點的 URI,即為指定的標頭所指向的節點。The Actor or Role attribute specifies the URI of the node for which a given header is intended. MustUnderstand 屬性會指定標頭是否能夠解讀節點處理。The MustUnderstand attribute specifies whether the header understands the node processing. Relay 屬性會指定標頭是否要轉送至下游節點。The Relay attribute specifies whether the header is to be relayed to downstream nodes. Windows Communication Foundation (WCF)不會對傳入訊息上的這些屬性執行任何處理,但 MustUnderstand 屬性除外。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. 首先,您可以變更 Actor 上的 MustUnderstandRelayMessageHeaderAttribute 屬性First, you can change the Actor, MustUnderstand and Relay properties on the MessageHeaderAttribute. (沒有 Role 屬性-設定 Actor 屬性,並在使用 SOAP 1.2 時傳遞 Role)。(There is no Role property - set the Actor property and Role is passed if SOAP 1.2 is used). 例如:For example:

控制這些屬性的另一種方式,是將需要的標頭型別變成 MessageHeader<T> 類別的型別參數,並將結果型別搭配 MessageHeaderAttribute 一起使用。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. 然後,以程式設計的方式使用 MessageHeader<T> 屬性 (Property),來設定 SOAP 屬性 (Attribute)。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[];  

在接收端,只能使用泛型 MessageHeader<T> 類別來讀取這些 SOAP 屬性。On the receiving side, reading these SOAP attributes can only be done if the generic MessageHeader<T> class is used. 您可以檢查 Actor 型別標頭的 RelayMustUnderstandMessageHeader<T> 屬性,探索接收到的訊息上的屬性設定。Examine the Actor, Relay or MustUnderstand properties of a header of the MessageHeader<T> type to discover the attribute settings on the received message.

接收到訊息並傳回訊息時,SOAP 屬性設定只會為 MessageHeader<T> 型別的標頭而往返。When a message is received and then sent back, the SOAP attribute settings only roundtrip for headers of the MessageHeader<T> type.

建構函式

MessageHeaderAttribute()

MessageHeaderAttribute 類別的新執行個體初始化。Initializes a new instance of the MessageHeaderAttribute class.

屬性

Actor

取得或設定 URI,這個 URI 表示此標頭的目標節點。Gets or sets a URI that indicates the node at which this header is targeted. 使用 SOAP 1.2 時,會對應到 role 標頭屬性,而使用 SOAP 1.1 則會對應到 actor 標頭屬性。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.

(繼承來源 MessageContractMemberAttribute)
MustUnderstand

指定扮演 Actor 角色的節點是否必須解讀這個標頭。Specifies whether the node acting in the Actor role must understand this header. 這會對應到 mustUnderstand SOAP 標頭屬性。This is mapped to the mustUnderstand SOAP header attribute.

Name

指定對應於這個成員的項目名稱。Specifies the name of the element that corresponds to this member.

(繼承來源 MessageContractMemberAttribute)
Namespace

指定對應於這個成員的項目命名空間。Specifies the namespace of the element that corresponds to this member.

(繼承來源 MessageContractMemberAttribute)
ProtectionLevel

指定成員要依現狀加以傳輸、簽署,或者加以簽署並加密。Specifies whether the member is to be transmitted as-is, signed, or signed and encrypted.

(繼承來源 MessageContractMemberAttribute)
Relay

指定這個標頭是否要轉送至下游節點。Specifies whether this header is to be relayed to downstream nodes. 這會對應到 relay SOAP 標頭屬性。This is mapped to the relay SOAP header attribute.

TypeId

在衍生類別中實作時,取得這個 Attribute 的唯一識別碼。When implemented in a derived class, gets a unique identifier for this Attribute.

(繼承來源 Attribute)

方法

Equals(Object)

傳回值,這個值指出此執行個體是否與指定的物件相等。Returns a value that indicates whether this instance is equal to a specified object.

(繼承來源 Attribute)
GetHashCode()

傳回此執行個體的雜湊碼。Returns the hash code for this instance.

(繼承來源 Attribute)
GetType()

取得目前執行個體的 TypeGets the Type of the current instance.

(繼承來源 Object)
IsDefaultAttribute()

在衍生類別中覆寫時,表示這個執行個體的值是衍生類別的預設值。When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(繼承來源 Attribute)
Match(Object)

在衍生類別中覆寫時,會傳回值,表示這個執行個體是否等於指定物件。When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(繼承來源 Attribute)
MemberwiseClone()

建立目前 Object 的淺層複製。Creates a shallow copy of the current Object.

(繼承來源 Object)
ToString()

傳回代表目前物件的字串。Returns a string that represents the current object.

(繼承來源 Object)

明確介面實作

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

將一組名稱對應至一組對應的分派識別項 (Dispatch Identifier)。Maps a set of names to a corresponding set of dispatch identifiers.

(繼承來源 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.

(繼承來源 Attribute)
_Attribute.GetTypeInfoCount(UInt32)

擷取物件提供的類型資訊介面數目 (0 或 1)。Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(繼承來源 Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

提供物件所公開的屬性和方法的存取權。Provides access to properties and methods exposed by an object.

(繼承來源 Attribute)

適用於