共用方式為

使用 SOAP 標頭

  • 發行項

使用 SOAP 與 XML Web Service 方法通訊時需要遵循標準格式，這種格式部分是 XML 文件中編碼的資料。XML 文件是由根目錄 Envelope 標記構成，而它又是以必須的 Body 項目和選擇性的 Header 項目構成。Body 項目中包含與訊息專屬的資料，而選擇性的 Header 項目可包含與特定訊息沒有直接關聯的其他資訊。Header 項目的每個子項目都稱為 SOAP 標頭。

雖然 SOAP 標頭可包含與訊息相關的資訊，但因為 SOAP 規格不嚴格定義 SOAP 標頭的內容，所以通常包含 Web 伺服器中由基礎架構處理的資訊，例如如何使用 SOAP 標頭提供路由資訊給 SOAP 標頭中的 SOAP 訊息。

定義和處理 SOAP 標頭

使用 ASP.NET 建立的 XML Web Service 可定義和管理 SOAP 標頭。SOAP 標頭定義的方式，是定義類別來表示特定 SOAP 標頭內的資料，並從 SoapHeader 類別衍生出標頭。

若要定義代表 SOAP 標頭的類別

  1. 建立從 SoapHeader 類別衍生出的類別，且名稱符合 SOAP 標頭的根目錄項目。

    public class MyHeader : SoapHeader
[Visual Basic]
Public Class MyHeader : Inherits SoapHeader

  2. 加入公用欄位或屬性，並與 SOAP 標頭中每個項目的名稱和相對的資料型別相符。

    以下列SOAP 標頭為例，後續的類別定義了表示 SOAP 標頭的類別。

    public class MyHeader : SoapHeader
{
   public DateTime Created;
   public long Expires;
} 
[Visual Basic]
Public Class MyHeader
  Inherits SoapHeader
    Public Created As DateTime
    Public Expires As Long
End Class

若要在 XML Web Service 中處理 SOAP 標頭

  1. 將 Public 成員加入實作 XML Web Service 的類別，且服務的型別表示 SOAP 標頭。

    [WebService(Namespace="https://www.contoso.com")]
public class MyWebService 
{
    // Add a member variable of the type deriving from SoapHeader.
    public MyHeader timeStamp;
[Visual Basic]
<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService
    ' Add a member variable of the type deriving from SoapHeader.
    Public TimeStamp As MyHeader

  2. 將 SoapHeader 屬性套用至每個用來處理 SOAP 標頭的 XML Web Service 方法。將 SoapHeader 屬性的 MemberName 屬性設定為第一個步驟中，成員變數 (Member Variable) 的名稱。

    [WebMethod]
[SoapHeader("timeStamp")]
public void MyWebMethod()
[Visual Basic]
<WebMethod, SoapHeader("TimeStamp")> _ 
Public Sub MyWebMethod()

  3. 在每個套用 SoapHeader 屬性的 XML Web Service 方法中，存取第一個步驟建立的成員變數，來處理傳入 SOAP 標頭的資料。

    [WebMethod]
[SoapHeader("timeStamp",            Direction=SoapHeaderDirection.InOut)]
public string MyWebMethod() 
{
  // Verify that the client sent the SOAP Header.
  if (timeStamp == null)
  {
     timeStamp = new MyHeader();
  }
  // Set the value of the SoapHeader returned
  // to the client.
  timeStamp.Expires = 60000;
  timeStamp.Created = DateTime.UtcNow;

  return "Hello World";
}
[Visual Basic]
<WebMethod,SoapHeader("TimeStamp", _                      Direction:=SoapHeaderDirection.InOut)> _ 
Public Function MyWebMethod() As String
   ' Verify that the client sent the SOAP Header. 
   If (TimeStamp Is Nothing) Then
      TimeStamp = New MyHeader
   End If

   ' Set the value of the SoapHeader returned
   ' to the client.
   TimeStamp.Expires = 60000
   TimeStamp.Created = DateTime.UtcNow

   Return "Hello World"
End Function

下列程式碼範例說明如何在 XML Web Service (使用 ASP.NET 建立) 中定義和處理 SOAP 標頭。MyWebService XML Web Service 具有名為 timeStamp 的成員變數，它是從 SoapHeader (MyHeader) 衍生而來的型別，並且設定為 SoapHeader 屬性 (Attribute) 的 MemberName 屬性 (Property)。接著將 SoapHeader 屬性套用至指定 myHeaderMemberVariable 的 MyWebMethod XML Web Service 方法。在 MyWebMethod XML Web Service 方法中，會存取 myHeaderMemberVariable 以設定 Created 的值和 SOAP 標頭的 Expires XML 項目。

<%@ WebService Language="C#" Class="MyWebService" %>
using System;
using System.Web.Services;
using System.Web.Services.Protocols;

// Define a SOAP header by deriving from the SoapHeader class.
public class MyHeader : SoapHeader
{
   public DateTime Created;
   public long Expires;
}

[WebService(Namespace="https://www.contoso.com")]
public class MyWebService : System.Web.Services.WebService
{
   // Add a member variable of the type deriving from SoapHeader.
   public MyHeader timeStamp;

   // Apply a SoapHeader attribute.
   [WebMethod]
   [SoapHeader("timeStamp", Direction=SoapHeaderDirection.InOut)]
   public string HelloWorld()
   {
      if (timeStamp == null)
         timeStamp = new MyHeader();
         
      timeStamp.Expires = 60000;
      timeStamp.Created = DateTime.UtcNow;
         
      return "Hello World";
   }
} 
[Visual Basic]
<%@ WebService Language="VB" Class="MyWebService" %>
Imports System
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader class.
Public Class MyHeader
    Inherits SoapHeader
    Public Created As DateTime
    Public Expires As Long
End Class

<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService
    Inherits System.Web.Services.WebService

    ' Add a member variable of the type deriving from SoapHeader.
    Public timeStamp As MyHeader

    ' Apply a SoapHeader attribute.
    <WebMethod(), _
     SoapHeader("timeStamp", Direction:=SoapHeaderDirection.InOut)> _
    Public Function HelloWorld() As String

        If (timeStamp Is Nothing) Then
            timeStamp = New MyHeader
        End If

        timeStamp.Expires = 60000
        timeStamp.Created = DateTime.UtcNow

        Return "Hello World"
    End Function
End Class

上一個範例會有 SOAP 回應傳回用戶端，其中 Expires 項目設為 60000 (亦即每分鐘的毫秒數)，Created 項目設為 Coordinated Universal Time 時制所表示的目前時間，也就是說下列 SOAP 回應會傳回用戶端：

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <MyHeader xmlns="https://www.contoso.com">
      <Created>dateTime</Created>
      <Expires>long</Expires>
    </MyHeader>
  </soap:Header>
  <soap:Body>
    <MyWebMethod xmlns="https://www.contoso.com" />
  </soap:Body>
</soap:Envelope>

建置能處理 SOAP 標頭的用戶端

XML Web Service 用戶端與 XML Web Service 通訊時能傳送與接收 SOAP 標頭。使用 Wsdl.exe 公用程式產生的 Proxy 類別是針對預期或傳回 SOAP 標頭的 XML Web Service 時，Proxy 類別會包含 SOAP 標頭的資訊。Proxy 類別中表示 SOAP 標頭的成員變數，又和 XML Web Service 的成員變數有相互關係。Proxy 類別也具有表示 SOAP 標頭對應類別的定義。例如，針對先前 XML Web Service 產生的 Proxy 類別將具有型別為 MyHeader 的成員變數，以及 MyHeader 類別的定義。如需建立 Proxy 類別的詳細資訊，請參閱建立 XML Web Service Proxy。

注意：如果 XML Web Service 定義的成員變數，是表示型別 SoapHeader 或 SoapUnknownHeader 的 SOAP 標頭，而非從 SoapHeader 衍生的型別，則 Proxy 類別不會有任何關於 SOAP 標頭的資訊。

若要在 XML Web Service 用戶端中處理 SOAP 標頭

  1. 針對表示 SOAP 標頭的型別建立新執行個體。

    Dim mySoapHeader As MyHeader = New MyHeader()
[C#]
MyHeader mySoapHeader = new MyHeader();

  2. 填入 SOAP 標頭的值。

    header.Expires = 60000
header.Created = DateTime.UtcNow
[C#]
header.Expires = 60000;
header.Created = DateTime.UtcNow;

  3. 建立 Proxy 類別的新執行個體。

    Dim proxy As MyWebService = New MyWebService()
[C#]
MyWebService proxy = new MyWebService();

  4. 將 SOAP 標頭物件指派給表示 SOAP 標頭的 Proxy 類別成員變數。

    proxy.MyHeaderValue = mySoapHeader
[C#]
proxy.MyHeaderValue = mySoapHeader

  5. 呼叫 Proxy 類別上與 XML Web Service 方法進行通訊的方法。

    傳送給 XML Web Service 的 SOAP 要求中的SOAP 標頭，將會包含 SOAP 標頭物件中儲存的資料內容。

    Dim results as String = proxy.MyWebMethod()
[C#]
string results = proxy.MyWebMethod();

下列程式碼範例示範如何將 SOAP 標頭從用戶端傳遞給 XML Web Service。

<%@ Page Language="VB" %>

<asp:Label id="ReturnValue" runat="server" />
<script runat=server language=VB>

 Sub Page_Load(o As Object, e As EventArgs)

  Dim header As MyHeader = New MyHeader()  ' Populate the values of the SOAP header.   header.Expires = 60000   header.Created = DateTime.UtcNow

  ' Create a new instance of the proxy class.
  Dim proxy As MyWebService = New MyWebService()
  
  ' Add the MyHeader SOAP header to the SOAP request.  proxy.MyHeaderValue = header

  ' Call the method on the proxy class that communicates
  ' with your XML Web service method.
  Dim results as String = proxy.MyWebMethod()

  ' Display the results of the method in a label.
  ReturnValue.Text = results

 End Sub
</script>
[C#]
<%@ Page Language="C#" %>

<asp:Label id="ReturnValue" runat="server" />
<script runat=server language=c#>

 void Page_Load(Object o, EventArgs e)
 {

  MyHeader header = new MyHeader();  // Populate the values of the SOAP header.  header.Expires = 60000;  header.Created = DateTime.UtcNow;

  // Create a new instance of the proxy class.
  MyWebService proxy = new MyWebService();
  
  // Add the MyHeader SOAP header to the SOAP request.  proxy.MyHeaderValue = header;

  // Call the method on the proxy class that communicates 
  // with your XML Web service method.
  string results = proxy.MyWebMethod();

  // Display the results of the method in a label.
  ReturnValue.Text = results;
 }
</script>

變更 SOAP 標頭接收者

根據預設，SOAP 標頭會在 SoapHeader 屬性套用至 XML Web Service 方法後，由 XML Web Service 用戶端傳送給 XML Web Service 方法。SOAP 標頭也可以由 XML Web Service 方法回傳給 XML Web Service 用戶端，也就是可以來回傳送。您可以將套用至 XML Web Service 方法的 SoapHeader 屬性中之 Direction 屬性加以設定，來控制 SOAP 標頭的接收者。Direction 屬性屬於 SoapHeaderDirection 型別，具有四個值：In、Out、InOut 和 Fault。這些值分別表示接收者 (無論是否為 XML Web Service 伺服器)、用戶端，或 XML Web Service 伺服器和用戶端兩者，以及 XML Web Service 擲回例外狀況時 SOAP 標頭是否傳送到用戶端。

注意：.NET Framework SDK 1.0 版不支援 Fault 值。

若要變更 SOAP 標頭接收者

  1. 定義 SOAP 標頭。

    public class MyHeader : SoapHeader
{
   public DateTime Created;
   public long Expires;
} 
[Visual Basic]
Public Class MyHeader
  Inherits SoapHeader
    Public Created As DateTime
    Public Expires As Long
End Class

  2. 將成員變數加入實作 XML Web Service 的類別。

    [WebService(Namespace="https://www.contoso.com")]
public class MyWebService : WebService
{
    public MyHeader myOutHeader;
[Visual Basic]
<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService  
  Inherits WebService
    Public myOutHeader As MyHeader

  3. 將 SoapHeader 屬性套用至每個用來處理 SOAP 標頭的 XML Web Service 方法。使用 SoapHeaderDirection 列舉型別 (Enumeration)，將 Direction 屬性設定為每個想要的接收者。下列範例透過將 Direction 設定為 SoapHeaderDirection.Out，來將 XML Web Service 用戶端設定為接收者。

        [WebMethod]
    [SoapHeader("myOutHeader",Direction=SoapHeaderDirection.Out)]
[Visual Basic]
    <WebMethod, _
     SoapHeader("myOutHeader",Direction:=SoapHeaderDirection.Out)>

  4. 視接收者不同來處理或設定 SOAP 標頭。下列程式碼範例設定 SOAP 標頭的值，而接收者為 XML Web Service 用戶端。

    // Set the Time the SOAP message expires.
myOutHeader.Expires = 60000;
myOutHeader.Created = DateTime.UtcNow;
[Visual Basic]
' Set the Time the SOAP message expires.
myOutHeader.Expires = 60000
myOutHeader.Created = DateTime.UtcNow

下列程式碼範例定義的 MyHeader SOAP 標頭會從 XML Web Service 方法傳送至用戶端。

<%@ WebService Language="C#" Class="MyWebService" %>
using System;
using System.Web.Services;
using System.Web.Services.Protocols;

// Define a SOAP header by deriving from the SoapHeader class.
public class MyHeader : SoapHeader
{
   public DateTime Created;
   public long Expires;
} 

[WebService(Namespace="https://www.contoso.com")]
public class MyWebService : WebService
{
    public MyHeader myOutHeader;
 
    [WebMethod]
    [SoapHeader("myOutHeader",Direction=SoapHeaderDirection.Out)]
    public void MyOutHeaderMethod() 
    {
      // Set the time the SOAP message expires.
      myOutHeader.Expires = 60000;
      myOutHeader.Created = DateTime.UtcNow;
    }
}
[Visual Basic]
<%@ WebService Language="VB" Class="MyWebService" %>
Imports System
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader class.
Public Class MyHeader
  Inherits SoapHeader
    Public Created As DateTime
    Public Expires As Long
End Class

<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService 
  Inherits WebService
    Public myOutHeader As MyHeader 
    
    <WebMethod, _
     SoapHeader("myOutHeader",Direction:=SoapHeaderDirection.Out)> _
    Public Sub MyOutHeaderMethod()
         ' Set the time the SOAP message expires.
         myOutHeader.Expires = 60000
         myOutHeader.Created = DateTime.UtcNow
    End Sub
End Class

處理未知的 SOAP 標頭

XML Web Service 用戶端可將具 SOAP 標頭的 SOAP 要求傳送給 XML Web Service 方法，且 XML Web Service 可能未明確定義預期接收項目為何。這種情形下，有一點很重要。您必須判斷 SOAP 標頭的語意已經過瞭解並處理，根據 SOAP 規格，SOAP 標頭的 mustUnderstand 屬性設定為 true 時會擲回例外況狀。如需處理用戶端要求 SOAP 標頭的詳細資訊，請參閱處理 XML Web Service 用戶端要求的 SOAP 標頭。

若要處理來自 XML Web Service 用戶端的未知 SOAP 標頭

  1. 將成員變數加入實作 XML Web Service 的類別，類別中具有型別 SoapUnknownHeader、SoapHeader 或這兩個其中一個陣列，以處理多個未知的 SOAP 標頭。

    將型別宣告為 SoapUnknownHeader 的陣列或單一執行個體有附帶好處，能使 SoapUnknownHeader 具有 Element 屬性。Element 屬性的型別為 XmlElement，表示 SOAP 要求或 SOAP 回應之 Header 項目的 XML 文件。這樣一來，XML Web Service 方法即可質詢 Element 屬性，來判斷 SOAP 標頭名稱及 SOAP 標頭所傳遞的資料。

    public class MyWebService {
    public SoapUnknownHeader[] unknownHeaders;
[Visual Basic]
Public Class MyWebService
    Public unknownHeaders() As SoapUnknownHeader

  2. 將 SoapHeader 屬性套用至用來處理各個未知 SOAP 標頭的每個 XML Web Service 方法。

        [WebMethod]
    [SoapHeader("unknownHeaders")]
    public string MyWebMethod()
[Visual Basic]
    <WebMethod, _
     SoapHeader("unknownHeaders") > _
    Public Function MyWebMethod() As String

  3. 加入程式碼以判斷是否能處理任何未知的 SOAP 標頭。

    如果成員變數的型別為 SoapUnknownHeader，XML Web Service 方法即可質詢 Element 屬性，來判斷 SOAP 標頭名稱及 SOAP 標頭所傳遞的資料。Element 屬性的 Name 屬性用於識別 SOAP 標頭的名稱。

           foreach (SoapUnknownHeader header in unknownHeaders) 
       {
         // Check to see if this a known header.
         if (header.Element.Name == "MyKnownHeader")
[Visual Basic]
       Dim header As SoapUnknownHeader       
       For Each header In unknownHeaders
         ' Check to see if this is a known header.
         If (header.Element.Name = "MyKnownHeader") Then

  4. 如果已知表示未知 SOAP 標頭成員變數的 DidUnderstand 屬性能處理特定 SOAP 標頭，請將其設定為 true。

    如果 XML Web Service 方法能處理未知的 SOAP 標頭，但未將 DidUnderstand 屬性設定為 true，則可能會擲回 SoapHeaderException。如需詳細資訊，請參閱處理 XML Web Service 用戶端要求的 SOAP 標頭。

             // Check to see if this is a known header.
         if (header.Element.Name == "MyKnownHeader")
               header.DidUnderstand = true;
         else
             // For those headers that cannot be 
             // processed, set DidUnderstand to false.
             header.DidUnderstand = false;
         }
[Visual Basic]
         ' Check to see if this a known header.
         If (header.Element.Name = "MyKnownHeader") Then
               header.DidUnderstand = True
         Else
             ' For those headers that cannot be 
             ' processed, set DidUnderstand to false.
             header.DidUnderstand = False
         End If

    ****注意   DidUnderstand 屬性的用途是供使用 ASP.NET 建立的 XML Web Service 與 XML Web Service 方法進行通訊。它並不屬於 SOAP 規格，且其值不會出現在 SOAP 要求或 SOAP 回應中。

    **注意   **XML Web Service 用戶端使用 Web 服務描述語言工具 (Wsdl.exe) 建置 Proxy 類別，且 XML Web Service 使用 SoapUnknownHeader 型別來定義表示 SOAP 標頭的成員變數時，連至 SOAP 標頭的參考不會加入 Proxy 類別。如果 XML Web Service 用戶端決定將 SOAP 標頭加入 SOAP 要求，就必須修改 Proxy 類別。方法是加入成員變數，並將 SoapHeader 屬性套用至呼叫相關 XML Web Service 方法的方法。

處理 XML Web Service 用戶端要求的 SOAP 標頭

用戶端可要求 XML Web Service 方法正確解譯 SOAP 標頭的語意，然後處理語意以便 SOAP 要求能成功執行。若要這麼做，用戶端必須將 SOAP 標頭的 mustUnderstand 屬性設定為 1。例如，下列SOAP 要求會讓 SOAP 要求接收者處理 MyCustomSoapHeader SOAP 標頭。

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" >
  <soap:Header>
    <MyCustomSoapHeader soap:mustUnderstand="1" xmlns="https://www.contoso.com">
      <custom>Keith</custom>
    </MyCustomSoapHeader>
  </soap:Header>
  <soap:Body>
    <MyUnknownHeaders xmlns="https://www.contoso.com" />
  </soap:Body>
</soap:Envelope>

XML Web Service 是否定義 SOAP 標頭，決定了 XML Web Service 如何處理用戶端要求的 SOAP 標頭。由 XML Web Service 定義 SOAP 標頭時，多數工作由 ASP.NET 處理。您可以透過下列程序，瞭解如何處理這兩個案例的方法。

若要處理未經 XML Web Service 定義，並且由 XML Web Service 用戶端要求的 SOAP 標頭

  • 請遵照步驟，從 XML Web Service 用戶端處理未知的 SOAP 標頭，特別注意 SOAP 標頭的 DidUnderstand 屬性。

    如果 SOAP 標頭未經 XML Web Service 定義，則 DidUnderstand 的初始值為 false。如果 XML Web Service 方法傳回後，ASP.NET 偵測到 SOAP 標頭的 DidUnderstand 屬性設定為 false，SoapHeaderException 會自動擲回。

若要處理經 XML Web Service 定義，並且由 XML Web Service 用戶端要求的 SOAP 標頭

  • 請遵照步驟處理每個 XML Web Service 方法中，使用 ASP.NET 所建立的 XML Web Service 內的 SOAP 標頭。

    如果 SOAP 標頭經過 XML Web Service 定義，且在接收 SOAP 標頭的 XML Web Service 方法中處理過，ASP.NET 會假設 XML Web Service 已瞭解 SOAP 標頭，所以將 DidUnderstand 的初始值設定為 true。

下列 MyWebService XML Web Service 定義 MyHeader SOAP 標頭，並要求將其與傳至 MyWebMethod XML Web Service 方法的任何呼叫一塊傳送。此外，MyWebMethod 會處理任何未知的 SOAP 標頭。若要處理 SOAP 標頭的 MyWebMethod，需將 DidUnderstand 設定為 true。

<%@ WebService Language="C#" Class="MyWebService" %>
using System.Web.Services;
using System.Web.Services.Protocols;

// Define a SOAP header by deriving from the SoapHeader base class.
public class MyHeader : SoapHeader {
    public string MyValue;
}
public class MyWebService {
    public MyHeader myHeader;

    // Receive all SOAP headers other than the MyHeader SOAP header.
    public SoapUnknownHeader[] unknownHeaders;
 
    [WebMethod]
    [SoapHeader("myHeader")]
    //Receive any SOAP headers other than MyHeader.
    [SoapHeader("unknownHeaders")]
    public string MyWebMethod() 
    {
       foreach (SoapUnknownHeader header in unknownHeaders) 
       {
         // Perform some processing on the header.
         if (header.Element.Name == "MyKnownHeader")
               header.DidUnderstand = true;
         else
                // For those headers that cannot be 
                // processed, set DidUnderstand to false.
                header.DidUnderstand = false;
       }
       return "Hello";
    }
}
[Visual Basic]
<%@ WebService Language="VB" Class="MyWebService" %>
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader base class.
Public Class MyHeader : Inherits SoapHeader
    Public MyValue As String
End Class

Public Class MyWebService
    Public myHeader As MyHeader
    
    ' Receive all SOAP headers other than the MyHeader SOAP header.
    Public unknownHeaders() As SoapUnknownHeader    
    
    <WebMethod, _
     SoapHeader("myHeader"), _
     SoapHeader("unknownHeaders")> _
    Public Function MyWebMethod() As String
        'Receive any SOAP headers other than MyHeader.
        Dim header As SoapUnknownHeader        For Each header In unknownHeaders
            ' Perform some processing on the header.
            If header.Element.Name = "MyKnownHeader" Then
                header.DidUnderstand = True
            ' For those headers that cannot be 
            ' processed, set DidUnderstand to false.
            Else
                header.DidUnderstand = False
            End If
        Next header
        Return "Hello"
    End Function
End Class

****注意   DidUnderstand 屬性的用途是供 ASP.NET 與 XML Web Service 方法進行通訊。它並不屬於 SOAP 規格，且其值不會出現在 SOAP 要求或 SOAP 回應中。

如果 XML Web Service 轉送 SOAP 標頭，一定要按照 SOAP 規格的規則，尤其該特別注意與 Actor 相關的值。如需詳細資訊，請參閱 W3C 網站 (http://www.w3.org/TR/SOAP/)。

因應 SOAP 標頭處理期間發生的錯誤

當 XML Web Service 偵測到標頭處理的特定錯誤時，應該會擲回 SoapHeaderException。 XML Web Service 可使用這個 Exception 類別，以一定格式正確回應。如果用戶端是使用 .NET Framework 建立的，則會收到 SoapHeaderException，而 SoapHeaderException 的內容和 InnerException 屬性會放在 Message 屬性中。用戶端攔截的 SoapHeaderException 之 InnerException 屬性將為 Null。.NET Framework 支援這種程式撰寫模型 (Programming Model)，會按照 SOAP 規格所規定，將例外況狀以 SOAP <Fault> XML 項目透過網路傳送。如需例外況狀的詳細資訊，請參閱在 XML Web Service 中處理和擲回例外狀況。

在下列程式碼範例中，如果用戶端對 MyWebMethod XML Web Service 方法提出 SOAP 要求，但是其 Expires 屬性所設定的時間和日期卻超過 SOAP 要求傳到 XML WEB Service 的時間和日期，便會擲回 SoapHeaderException。

<%@ WebService Language="C#" Class="MyWebService" %>
using System.Web.Services;
using System.Web.Services.Protocols;

// Define a SOAP header by deriving from the SoapHeader class.
public class MyHeader : SoapHeader
{
  public DateTime Created;
  public DateTime Expires;
  public DateTime Received;
} 

[WebService(Namespace="https://www.contoso.com")]
public class MyWebService 
{
    // Add a member variable of the type deriving from SoapHeader.
    public MyHeader myHeaderMemberVariable;
 
    // Apply a SoapHeader attribute.
    [WebMethod]
    [SoapHeader("myHeaderMemberVariable")]
    public void MyWebMethod() 
    {
       if (timeStamp == null)
          timeStamp = new MyHeader();
       else
       {
          // Check whether the SOAP message is expired.
          if ((timeStamp.Expires.CompareTo(DateTime.UtcNow)) <= 0)
          {
             // The SOAP message is expired, so throw a SOAP header
             // exception indicating that.
             SoapHeaderException se = new SoapHeaderException(
               "SOAP message expired before reaching this node.",
               SoapException.ClientFaultCode, 
               this.Context.Request.Url.ToString());
             throw se;
          }
       }
    }
}
[Visual Basic]
<%@ WebService Language="VB" Class="MyWebService" %>
Imports System.Web.Services
Imports System.Web.Services.Protocols

' Define a SOAP header by deriving from the SoapHeader class.
Public Class MyHeader 
  Inherits SoapHeader
    Public Created As DateTime
    Public Expires As DateTime
    Public Received As DateTime
End Class

<WebService(Namespace:="https://www.contoso.com")> _
Public Class MyWebService
    ' Add a member variable of the type deriving from SoapHeader.
    Public myHeaderMemberVariable As MyHeader    
    
    ' Apply a SoapHeader attribute.
    <WebMethod, _
     SoapHeader("myHeaderMemberVariable")> _
    Public Sub MyWebMethod()
       If (TimeStamp Is Nothing) Then
          TimeStamp = New MyHeader
       Else
           ' Check whether the SOAP message is expired.
           If ((TimeStamp.Expires.CompareTo(DateTime.UtcNow)) <= 0) Then
             ' The SOAP message is expired, so throw a SOAP header
             ' exception indicating that.
             Dim se As New SoapHeaderException( _
                "SOAP message expired before reaching this node.", _
                SoapException.ClientFaultCode, _
                Me.Context.Request.Url.ToString())
             Throw se    
           End If
       End If
    End Sub
End Class

注意：.NET Framework 1.0 版包含 SoapHeaderAttribute.Required 屬性，會讓 XML Web Service 在該屬性設定為 true 時，要求客戶傳送特定的 SOAP 標頭。ASP.NET 將 soap:header 項目上的 wsdl:required 屬性設定為**「true」**，指示產生的 WSDL 文件必須包含 SOAP 標頭。從 WSDL 文件建置之 XML Web Service 的 .NET Framework 用戶端，如果在其他用戶端收到 SOAP 錯誤而卻沒有傳送必要的 SOAP 標頭，則會收到 SoapHeaderException。為了與其他的 SOAP 實作進行溝通，之後的版本會移除這項功能。

Required 屬性在 1.1 版已經過時，而 Web 服務描述語言工具 (Wsdl.exe) 則會忽略 WSDL 文件中 soap:header 項目的 wsdl:required 屬性。因為不再需要 SOAP 標頭，所以 XML Web Service 在存取 SOAP 標頭前，應該先驗證代表標頭的欄位或屬性不是 null。

請參閱

SoapHeader | SoapHeaderAttribute | SoapHeaderException | SoapUnknownHeader | 使用 ASP.NET 建置 XML Web Service | 建置 XML Web Service 用戶端