逐步解說：使用 SOAP 擴充功能更改 SOAP 訊息

發行項
02/28/2011

本主題專門說明舊有技術。應該使用下列建立 XML Web Service 及 XML Web Service 用戶端： Windows Communication Foundation.

您可以將 SOAP 擴充功能插入 .NET Framework SOAP 訊息處理管線中，以便在 Web 服務或用戶端序列化或還原序列化 SOAP 要求或回應訊息時，加以修改或檢查。這個逐步說明主題會示範如何建置和執行 SOAP 擴充功能。如需有關 SOAP 擴充功能運作方式的圖片，以及在訊息處理管線中呼叫 SOAP 擴充方法的順序，請參閱使用 SOAP 擴充功能修改 SOAP 訊息。

在這個逐步解說過程中，您將學習如何：

從 SoapExtension 衍生類別。
儲存 Stream 物件的參考，這些物件代表未來在 SOAP 擴充功能完成其處理之前和之後的 SOAP 訊息。
初始化 SOAP 擴充功能的特定資料。
在適當的 SoapMessageStage 期間或階段處理 SOAP 訊息。

將 SOAP 擴充功能設定為與特定 Web 服務方法一起執行。

必要條件

從 SoapExtension 衍生類別。

衍生自 SoapExtension 的類別是會執行 SOAP 擴充功能的類別。也就是，如果 SOAP 擴充功能是具有加密功能的 SOAP 擴充，那麼衍生自 SoapExtension 類別的類別就會執行加密和對應的解密作業。

儲存代表未來 SOAP 訊息之資料流物件的參考

若要修改 SOAP 訊息，您必須取得可用以取得未來 SOAP 訊息內容之資料流的參考。您要取得這個參考，就只有覆寫 ChainStream 方法一途。

若要儲存代表未來 SOAP 訊息之資料流物件的參考

覆寫 ChainStream 方法。

ChainStream 方法具有下列簽章：

public virtual Stream ChainStream(Stream stream)

Public Overridable Function ChainStream(ByVal stream As Stream) As Stream

在 ChainStream 實作中，指派當做參數傳遞的 Stream 執行個體。

在進行任何 SoapMessageStage 之前，都會將 Stream 的參考傳入至 ChainStream 一次。在優先權較低的 SOAP 擴充功能已執行，並且已對 SOAP 訊息進行變更之後，這個 Stream 會參考 SOAP 訊息的 XML (如需 SOAP 擴充功能優先權的詳細資訊，請參閱＜將 SOAP 擴充功能設定為與 Web 服務方法一起執行＞)。當 SOAP 擴充功能檢查或修改 SOAP 訊息時，SOAP 擴充功能必須將這個參考指派給成員變數，以便稍後於 SoapMessageStage 期間存取。

不過，傳入 ChainStream 中的 Stream 並不是 SOAP 擴充功能應該修改的 Stream。
在 ChainStream 實作中，產生新的 Stream，並將其參考儲存至私用成員變數，然後傳回該參考。

下列範例示範 ChainStream 方法的通用實作。

如需 ChainStream 方法的通用實作範例，請參閱 HOW TO：實作 ChainStream 方法來儲存資料流物件的參考。

初始化 SOAP 擴充功能的特定資料

衍生自 SoapExtension 的類別具有兩個用於初始化資料的方法：GetInitializer 和 Initialize。

ASP.NET 基礎結構會在何時呼叫 GetInitializer 方法，以及傳遞何種參數至方法，均取決於設定 SOAP 擴充功能的方式。(請參閱＜使用 SOAP 擴充功能修改 SOAP 訊息＞和＜將 SOAP 擴充功能設定為與 Web 服務方法一起執行＞。

若要在使用屬性設定 SOAP 擴充功能時初始化資料

使用下列簽章來實作 GetInitializer 方法：

public override object GetInitializer(LogicalMethodInfo methodInfo, SoapExtensionAttribute attribute)

Public Overloads Overrides Function GetInitializer(methodInfo As _
   LogicalMethodInfo, attribute As SoapExtensionAttribute) As Object

LogicalMethodInfo 會提供 Web 服務方法的原型詳細資訊，例如參數的數目及其資料型別。

必要時，您可以呼叫 Initialize 方法，並傳遞 GetInitializer 所傳回的物件。對許多 SoapExtension 實作來說，Initialize 方法可以是空的。

若要在組態檔中設定 SOAP 擴充功能時初始化資料

使用下列簽章來實作 GetInitializer 方法：

public override object GetInitializer(Type WebServiceType)

Public Overloads Overrides Function GetInitializer(WebServiceType As Type) As Object

Type 參數是實作 Web 服務類別之類別的型別。

必要時，您可以呼叫 Initialize 方法，並傳遞 GetInitializer 所傳回的物件。對許多 SoapExtension 實作來說，Initialize 方法可以是空的。

如需如何在設定 SOAP 擴充功能時初始化快取資料的範例，請參閱 HOW TO：在設定 SOAP 擴充功能時初始化快取的資料。

處理 SOAP 訊息

在衍生自 SoapExtension 的類別中，實作的核心部分即是 ProcessMessage 方法。在定義於 SoapMessageStage 列舉型別 (Enumeration) 中的每個階段上，ASP.NET 會數次呼叫這個方法。

若要處理 SOAP 訊息

實作抽象的 ProcessMessage 方法。

ProcessMessage 方法的下列實作會追蹤對 Web 服務的呼叫。在追蹤期間，如果 SoapMessageStage 指示參數已序列化為 XML，就會將 XML 寫入檔案。

public override void ProcessMessage(SoapMessage message) 
{
   switch (message.Stage) 
   {
   case SoapMessageStage.BeforeSerialize:
       break;
   case SoapMessageStage.AfterSerialize:
       // Write the SOAP message out to a file.
       WriteOutput( message );
       break;
   case SoapMessageStage.BeforeDeserialize:
       // Write the SOAP message out to a file.
       WriteInput( message );
       break;
   case SoapMessageStage.AfterDeserialize:
       break;
   default:
       throw new Exception("invalid stage");
   }
}

Public Overrides Sub ProcessMessage(message As SoapMessage)
    Select Case message.Stage
      Case SoapMessageStage.BeforeSerialize
      Case SoapMessageStage.AfterSerialize
        ' Write the SOAP message out to a file.
        WriteOutput(message)
      Case SoapMessageStage.BeforeDeserialize
        ' Write the SOAP messae out to a file.
        WriteInput(message)
      Case SoapMessageStage.AfterDeserialize
      Case Else
        Throw New Exception("invalid stage")
    End Select
End Sub

將 SOAP 擴充功能設定為與 Web 服務方法一起執行

您可以使用自訂屬性或修改組態檔，設定 SOAP 擴充功能的執行方式。自訂屬性便會套用至 Web 服務方法。如果是使用組態檔，SOAP 擴充功能將會與組態檔範圍內的所有 Web 服務一起執行。如需組態檔運作方式的詳細資訊，請參閱Configuring Applications。

若要使用自訂屬性設定 SOAP 擴充功能

從 SoapExtensionAttribute 衍生類別。
實作 SoapExtensionAttribute 的兩個屬性：ExtensionType 和 Priority。SOAP 擴充功能應該會傳回 ExtensionType 屬性中的 SOAP 擴充的型別。Priority 屬性表示 SOAP 擴充功能的相對優先權，如＜使用 SOAP 擴充功能修改 SOAP 訊息＞中的＜套用優先權群組＞所述。
將自訂屬性套用至您要搭配 SOAP 擴充功能一起執行的每個 Web 服務方法。

若要在組態檔中設定 SOAP 擴充功能

如果它尚不存在，請將 soapExtensionTypes XML 項目新增至適當的 App.config 或 Web.config 檔案的 webServices 區段。
在 soapExtensionTypes XML 項目中，針對您要搭配組態檔範圍內所有 Web 服務一起執行的每個 SOAP 擴充功能，新增其 add XML 項目。

add XML 項目具有下列屬性。
- Type：指定 SOAP 擴充功能及其所在之組件的型別。
- Priority：指定其群組內 SOAP 擴充功能的相對優先權。
- Group：指定 SOAP 擴充功能所屬的群組。

另請參閱

共用方式為