Summary

ASP.NET Web Service 方法（ WebMethods ）怎樣為建立 Web 服務提供一種高效的解決方案呢。 WebMethods 使傳統的 Microsoft.NET 方法成為 Web 服務操作，它支援 HTTP 、 XML 、 XML Schema 、 SOAP 和 WSDL 。 WebMethods（ .asmx ）控制代碼將到來的 SOAP 訊息派送給適當的方法，並將到來的 XML 元素序列化為對應的 .NET 物件。

Introduction

當今在 Microsoft.NET 中實現基於 HTTP 的 Web 服務有兩種根本不同的方法。第一種也是較低階的一種技術是編寫一個定製的 IhttpHandler 類並把它嵌入到 HTTP 管道中。這種方法要求你使用 System.web API 處理到來的 HTTP 訊息，用 System.Xml API 處理 HTTP 訊息體中的 SOAP 封裝（ envelope ）。編寫一個定製的控制代碼同樣也需要你手工編寫WSDL 文件，準確的描述實現過程。做到這一切要求對 XML 、 XSD 、 SOAP 和 WSDL 規範有深入的瞭解，但這對大多數人來講都是讓人望而卻步的先決條件。

實現 Web 服務的一種更高效的方法是使用 Microsoft ASP.NET 的 WebMethods 框架。 ASP.NET 為 .asmx 終節點（叫作 WebServiceHandler ）裝載了一個專門的 IhttpHandler 類，它為你的需要提供了 XML 、 XSD 、 SOAP 和 WSDL的功能性樣板。因為 WebMethod 框架使你從底層 XML 技術的複雜性中解脫出來，可以將精力集中到一些緊要的業務問題。

選擇一種實現技術涉及到在靈活性和高效性之間的權衡，如圖 1 所示。一個定製的 IhttpHandler 有很大的靈活性，但卻要花費大量的時間來編寫、測試和除錯程式碼。 WebMethods 框架使構建和執行 Web 服務變得異常輕鬆，不過很明顯你將被限制在框架的界線裡。不過，如果 WebMethods 框架不能正確的滿足你的需要，也可通過填加你自己的功能來擴充套件框架。

總的來講，除非你已經掌握了 XML 、 XSD 、 SOAP 和 WSDL 並且願意承受直接處理它們的負擔，最好還是使用WebMethods 框架來實現你的 Web 服務需要。它提供了大多數 Web 服務終點需要的基本服務，還有一些擴充套件屬性使構架更適合你的具體需要。基於此假設，文章的餘下部分我們將討論 WebMethods 的內部工作機制。

WebMethods 框架

WebMethods 框架通過在方法開始處標記 [WebMethods] 屬性，將 SOAP 訊息對映到一個 .NET 類的方法，[WebMethods] 可以在 System.Web.Service 名稱空間中找到。比如下面的 .NET 類包括四個方法，其中的兩個被標註了[WebMethods] 屬性。

using System.Web.Services;

public class MathService

{

   [WebMethod]

   public double Add(double x, double y) {

      return x + y;

   }

   [WebMethod]

   public double Subtract(double x, double y) {

      return x - y;

   }

   public double Multiply(double x, double y) {

      return x * y;

   }

   public double Divide(double x, double y) {

      return x / y;

   }

}

要在 WebMethods 框架中使用這個類，需要把它編譯成一個 assembly 並拷貝到虛擬目錄的 bin 子目錄下。在這個例子中， Add 和 Subtract 方法被作為 Web 服務操作，而 Multiply 和 Divide 卻不能。（因為它們沒有被標記為[WebMethods] ）

你可以通過一個 .asmx 終節點來訪問 Add 和 Subtract Web 服務操作：建立一個文字檔案 Math.asmx ，它包含下面的簡單宣告，然後把它放到包含 assembly 的同一個虛擬目錄下（注這裡是虛擬目錄本身，而不是它的 bin 子目錄）

<%@ WebService class="MathService"%>

這個宣告告訴 .asmx 控制代碼去哪個類中查詢 WebMethods ，餘下的就由控制代碼全全處理。比如，假設虛擬目錄叫作“math ”，它包含了 Math.asmx ，它的 bin 子目錄下包含了 assembly ，瀏覽 http://localhost/math/math.asmx 時 .asmx控制代碼將生成 文件。

關於 .asmx 控制代碼如何工作有一個主要的變化。 .asmx 檔案通常只包含了 WebService 的宣告，根據名字引用相應的Web 服務類。因此，在這種情況下， assembly 必須已經被編譯並且部署到虛擬目錄的 bin 子目錄中。 .asmx 控制代碼也提供了對 .asmx 檔案原始碼的即時編譯（ just-in-time compilation ），比如下面的檔案就既包括了 WebService 宣告，也包括了引用類的原始碼。

<@% WebService class="MathServiceJit" language="C#"%>

using System.Web.Services;

public class MathServiceJit

{

   [WebMethod]

   public double Add(double x, double y) {

      return x + y;

   }

   [WebMethod]

   public double Subtract(double x, double y) {

      return x - y;

   }

   public double Multiply(double x, double y) {

      return x * y;

   }

   public double Divide(double x, double y) {

      return x / y;

   }

}

當此檔案通過 HTTP 被第一次訪問時， .asmx 控制代碼編譯原始碼並將 assembly 部署到相應位置。注意 WebService 宣告必須提供語言以使 .asmx 控制代碼在執行時能選擇正確的編譯器。這種方法明顯的劣勢就是直到第一次訪問這個檔案的時候你才會發現它的編譯錯誤。

       當你在 Visual Studio.NET 中建立一個新的 Web Service 專案時，通常使用“雙檔案”技術，即類的原始檔和引用它的 .asmx 檔案是分開的。 IDE 會盡量遮蔽這些，如果你在 Solution Explorer 工具欄中點選 Show All Files ，你會注意到專案中 Web Service 類都有兩個檔案。事實上 Visual Studio.NET 不支援 .asmx 檔案的 syntax highlighting or IntelliSense® 。對於 Web 專案， Visual Studio.NET 也負責建立一個虛擬目錄，自動地將編譯好的 assembly 放到虛擬目錄的 bin 子目錄下。

在我們詳細討論 .asmx 控制代碼如何工作之前，先來簡單的看一下訊息是怎樣從 IIS 傳遞到 .asmx 控制代碼的。當一個HTTP 訊息到達 80 埠後， IIS 用在 IIS 元資料庫中找到的資訊決定由哪個 ISAPI.DLL 來處理訊息。 .NET 安裝時將.asmx 副檔名對映到 Aspnet_isapi.dll 。

Aspnet_isapi.dll 是 .NET 框架提供的標準的 ISAPI 副檔名，它只是簡單的將 HTTP 請求傳遞到一個單獨的工作者程序 Aspnet_wp.exe 。 Aspnet_wp.exe hosts CLR （通用語言執行時）和 HTTP 管道。訊息一旦進入了 HTTP 管道，管道就查詢配置檔案看哪個 IhttpHandler 類用來處理給定的副檔名。如果你檢視你的 machine.config 檔案，會看到它包含了一個對映到 .asmx 檔案的 httphandler ，如下所示：

<configuration>

  <system.web>

    <httpHandlers>  

        <add verb="*" path="*.asmx" type="System.Web.Services.Protocols.WebServiceHandlerFactory, 

System.Web.Services, Version=1.0.3300.0, Culture=neutral, 

PublicKeyToken=b03f5f7f11d50a3a" validate="false"/>

當一個訪問 .asmx 檔案的訊息進入 .NET HTTP 管道時，管道就會呼叫 WebServiceHandlerFactory 類來例項化一個新的 WebServiceHandler 物件，用它來處理請求（通過呼叫 IhttpHandlerProcessRequest 方法）。 WebServiceHandler 物件開啟物理的 .asmx 檔案來決定包含你的 WebMethods 的類名。

HTTP管道一旦呼叫了.asmx控制代碼，便開始了XML、XSD、SOAP和WSDL的處理。.asmx控制代碼提供的餘下的功能被分為三個領域：
訊息分派

當.asmx控制代碼被HTTP管道呼叫時，通過檢視.asmx檔案中的WebService宣告，確定檢查哪個.NET類。然後它觀察到來的HTTP訊息中的資訊，確定呼叫引用類中的哪個方法。為了呼叫前面例子中的Add方法，HTTP請求訊息應像下面一樣：

POST /math/math.asmx HTTP/1.1

Host: localhost

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://tempuri.org/Add"

 

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <Add xmlns="http://tempuri.org/">

      <x>33</x>

      <y>66</y>

    </Add>

  </soap:Body>

</soap:Envelope>

上面的HTTP請求訊息中有兩條資訊可以用來確定呼叫類中的哪個方法：SOAPAction頭或soap體中請求元素的名字。在這個例子中，每種方法都指出了傳送者想呼叫的方法名。

.asmx控制代碼使用SOAPAction頭的值來實現訊息的分派。因此，.asmx控制代碼檢視訊息中的SOAPAction頭，使用.NET對映檢查引用類中的方法。它只考慮標記了[WebMethod]屬性的方法，但通過檢視每種方法的SOAPAction值再具體確定呼叫哪個方法。因為我們在類中並沒有明確的指定SOAPAction的值，.asmx控制代碼認為SOAPAction的值是Web服務的名稱空間加上方法名。而且我們也沒有指定名稱空間，所以控制代碼就把http://tempuri.org作為預設值。這樣Add方法的預設SOAPAction值就是http://tempuri.org/Add。

可以按如下方法定製Web服務的名稱空間。把類標記上[WebService]屬性，用[SoapDocumentMethod]屬性標記WebMethods來指定具體的SOAPAction值。示例如下：

using System.Web.Services;

using System.Web.Services.Protocols;

 

[WebService(Namespace="http://example.org/math")]

public class MathService

{

   [WebMethod]

   public double Add(double x, double y) {

      return x + y;

   }

   [WebMethod]

   [SoapDocumentMethod(Action="urn:math:subtract")]

   public double Subtract(double x, double y) {

      return x - y;

   }

   ...

}

現在.asmx控制代碼認為Add方法的SOAPAction值是http://example.org/math/Add，SubTract的值是urn:math:subtract（因為我們在類中明確定義了）。比如下面的HTTP請求訊息呼叫Subtract：
POST /math/math.asmx HTTP/1.1

Host: localhost

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "urn:math:subtract"

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <Subtract xmlns="http://example.org/math">

      <x>33</x>

      <y>66</y>

    </Subtract>

  </soap:Body>

</soap:Envelope>

如果.asmx 控制代碼沒為HTTP請求訊息找到一個SOAPAction匹配，將會丟擲一個異常。如果你不想依賴SOAPAction頭來分派訊息，可以引導.asmx控制代碼使用請求元素名稱。採用這種方法需要為類標記上[SoapDocumentService]屬性的RoutingStyle特性，同時也應該指出 WebMethods不需要SOAPAction值（在類中設定其值為空）。如下所示：

using System.Web.Services;

using System.Web.Services.Protocols;

 

[WebService(Namespace="http://example.org/math")]

[SoapDocumentService(

  RoutingStyle=SoapServiceRoutingStyle.RequestElement)]

public class MathService

{

   [WebMethod]

   [SoapDocumentMethod(Action="")]

   public double Add(double x, double y) {

      return x + y;

   }

   [WebMethod]

   [SoapDocumentMethod(Action="")]

   public double Subtract(double x, double y) {

      return x - y;

   }

    ...

}

在這種情況下，控制代碼甚至不關心SOAPAction的值，它使用請求元素的名字確定呼叫方法。比如，在下面的HTTP請求訊息中，它希望呼叫Add方法的請求元素的名字是Add：

POST /math/math.asmx HTTP/1.1

Host: localhost

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: ""

<soap:Envelope  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <Add xmlns="http://example.org/math">

      <x>33</x>

      <y>66</y>

    </Add>

  </soap:Body>

</soap:Envelope>

所以當.asmx控制代碼接收到HTTP訊息時它要做的第一件事情就是決定如何分派訊息到對應的WebMethod。在它真正呼叫方法之前，還需要將到來的XML對映到.NET物件。
將XML對映到物件

一旦WebMethod控制代碼決定了呼叫哪個方法，它就會將XML訊息反序列化為.NET物件。隨著訊息分派，控制代碼通過reflection檢查類，然後決定怎樣處理XML訊息。XmlSerializer類自動完成XML和System.Xml.Serialization名稱空間中類的對映。

XmlSerializer能實現任何.NET公共型別到XML Schema型別的對映，有了這個適當的對映，它能自動的實現.NET物件和XML例項文件的對映（見圖4）。XmlSerializer受XML Schema所支援功能的限制，雖不能處理所有複雜的現代物件模型（如非樹型的物件圖），卻能處理開發者常用的複雜型別。

再看前面Add的例子，XmlSerializer將把x和y元素對映為.NET的double值（呼叫Add方法時必須提供的）。Add方法返回一個double型別值給呼叫者，這也需要被序列化為SOAP應答訊息中的一個XML元素。

Figure 4. Mapping XML to objects

XmlSerializer也能自動處理一些複雜型別（除了上面說到的一些限制）。比如，下面的WebMethod計算兩個點結構之間的距離。

using System;

using System.Web.Services;

public class Point {

  public double x; 

  public double y;

}

[WebService(Namespace="urn:geometry")]

public class Geometry {

  [WebMethod]

  public double Distance(Point orig, Point dest) {

    return Math.Sqrt(Math.Pow(orig.x-dest.x, 2) +

                     Math.Pow(orig.y-dest.y, 2));

  }

}

請求此操作的SOAP訊息將包含一個Distance元素，它包含了兩個子元素，一個稱作orig，另一個是dest，每一個都包括了x和y元素，如下所示：

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <Distance xmlns="urn:geometry">

      <orig>

        <x>0</x>

        <y>0</y>

      </orig>

      <dest>

        <x>3</x>

        <y>4</y>

      </dest>

    </Distance>

  </soap:Body>

</soap:Envelope>

這種情況下SOAP應答訊息將包含一個DistanceResponse元素，它包含一個double 型別的DistanceResult子元素。

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <DistanceResponse 

      xmlns="urn:geometry">

      <DistanceResult>5</DistanceResult> 

    </DistanceResponse>

  </soap:Body>

</soap:Envelope>

預設的XML對映使用方法名作為請求元素名，引數名作為子元素名。每個引數的結構依賴於型別的結構。公共欄位和屬性的名字簡單對映為子元素，如Point類中的x和y。應答元素的名字預設為請求元素的名字後面附加上“Response”,應答元素也包含一個子元素，是請求元素名字後面附加“Result”。也有可能使用一些固定的對映屬性來打破標準的XML對映。比如，你可以使用[XmlType]屬性來定製型別的名字和名稱空間，使用[XmlElement]和[XmlAttribute]屬性來控制如何將引數或類成員分別對映為元素或屬性，也可以使用[SoapDocumentMethod]屬性控制怎樣把方法本身對映為請求/響應訊息中的元素名。比如，檢查下面重新定義的Distance。

using System;

using System.Web.Services;

using System.Web.Services.Protocols;

using System.Xml.Serialization;

 

public class Point {

  [XmlAttribute]

  public double x;

  [XmlAttribute] 

  public double y;

}

[WebService(Namespace="urn:geometry")]

public class Geometry {

  [WebMethod]

  [SoapDocumentMethod(RequestElementName="CalcDistance",

     ResponseElementName="CalculatedDistance")]

  [return: XmlElement("result")]

  public double Distance(

    [XmlElement("o")]Point orig, [XmlElement("d")]Point dest) {

    return Math.Sqrt(Math.Pow(orig.x-dest.x, 2) +

                     Math.Pow(orig.y-dest.y, 2));

  }

}

它所期望的SOAP請求訊息如下：

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <CalcDistance xmlns="urn:geometry">

      <o x="0" y="0" />

      <d x="3" y="4" />

    </CalcDistance>

  </soap:Body>

</soap:Envelope>

並將產生下面的應答訊息：

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <CalculatedDistance xmlns="urn:geometry">

      <result>5</result>

    </CalculatedDistance>

  </soap:Body>

</soap:Envelope>

.asmx控制代碼使用SOAP document/literal風格來實現和描述上面顯示的預設對映。意思上說WSDL定義將包含literal XML schema定義，它描述了SOAP訊息中用到的請求和響應元素。

.asmx控制代碼也能使用SOAP rpc/encoded風格。這意味著SOAP體中包含一個RPC呼叫的XML代表（representation），引數用SOAP編碼規則來序列化。實現這些僅需將[SoapDocumentService] and [SoapDocumentMethod]替換為[SoapRpcService] and [SoapRpcMethod]屬性。

正如你所看到的，我們可能完全定製一個從給定方法到SOAP訊息的對映。XmlSerializer提供了一個強大的序列化引擎。

除了處理引數的反序列化，.asmx控制代碼也能序列化/反序列化SOAP頭。SOAP頭的處理不同於引數，因為它們被認為是典型的無法控制的資訊，和具體的方法沒有直接的聯絡。由於這些，頭處理主要是通過中間層（interception layers），完全為WebMethods遮蔽了頭處理。

然而如果想涉足於WebMethod中的頭資訊，你必須提供一個.NET類，從SoapHeader派生而來，它代表了頭的XML schema型別。然後定義一個此型別的成員變數作為每一個頭例項的佔位符。最後標記每個要訪問頭的WebMethod，指定你想要到達的域名。

比如，下面的SOAP請求包括一個用來進行身份驗證的UsernameToken頭。

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Header>

    <x:UsernameToken xmlns:x="http://example.org/security">

      <username>Mary</username>

      <password>yraM</password>

    </x:UsernameToken>

  </soap:Header>

  <soap:Body>

    <CalcDistance xmlns="urn:geometry">

  為了使.asmx控制代碼有可能反序列化SOAP頭，首先你需要定義一個.NET類，它代表了暗含的XML Schema類。在此例中相應的類如下：

[XmlType(Namespace="http://example.org/security")]

[XmlRoot(Namespace="http://example.org/security")]

public class UsernameToken : SoapHeader {

   public string username;

   public string password;

}

然後你需要在WebMethod類中定義一個成員變數來控制一個頭類的例項，同樣要為WebMethods標記[SoapHeader]屬性。見如下：

using System;

using System.Web.Services;

using System.Web.Services.Protocols;

 [WebService(Namespace="urn:geometry")]

public class Geometry {

  public UsernameToken Token;

  [WebMethod]

  [SoapHeader("Token")]

  public double Distance(Point orig, Point dest) {

    if (!Token.username.Equals(Reverse(Token.password)))

       throw new Exception("access denied");
    return Math.Sqrt(Math.Pow(orig.x-dest.x, 2) +
                     Math.Pow(orig.y-dest.y, 2));
  }
}

這樣，在WebMethod中你可以訪問Token域，並提取SOAP頭提供的資訊。你也可以使用同樣的技術將頭資訊送回客戶端——你需要在[SoapHeader]屬性宣告中指定頭的方向。

.asmx控制代碼也提供了.NET異常的自動序列化。任何被.asmx控制代碼劫獲的未處理的異常都會被自動序列化為應答訊息中的SOAP Fault元素。比如，在前面的例子中，假如使用者名稱與反轉的口令不匹配，我們的程式碼將會丟擲一個.NET異常。.asmx控制代碼劫獲這個異常，將它序列化為下面的SOAP應答：

<soap:Envelope  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

  <soap:Body>

    <soap:Fault>

      <faultcode>soap:Server</faultcode>    

      <faultstring>Server was unable to process request. --&gt; access denied</faultstring>

      <detail />

    </soap:Fault>

  </soap:Body>

</soap:Envelope>

如果你想更多的控制SOAP Fault元素，也可以通過指定所有SOAP Fault元素細節來明確丟擲一個SOAP異常物件。比如：faultcode, faulstring, faultactor, detail元素。

    領會WebMethods如何工作需要理解根本的序列化引擎和它的各種選項。序列化引擎的好處就是它隱藏了定製控制代碼中底層的XML API程式碼。然而儘管許多開發人員認為這樣很好，一些人也認為這也是它的缺陷，因為他們想親手來處理WebMethod中未經加工的SOAP訊息。
自動生成WSDL文件

寫好並部署了一個WebMethod後，客戶需要明確知道和它成功通訊SOAP訊息應該是個什麼樣子。提供Web服務描述的標準方法是通過WSDL（和嵌入的XSD定義）。.asmx控制代碼自動的生成了人性化的可讀文件和WSDL定義，它準確的反映了WebMethod介面。如果在你的WebMethods中應用了一些對映屬性，它們將都被反映在生成的文件中。

       假如你瀏覽這個.asmx檔案，你將看到一個人性化的可讀文件頁面就像圖2中顯示的那樣。這個文件頁是由DefaultWsdlHelpGenerator.aspx (在 C:/windows/Microsoft.NET/Framework/v1.0.3705/config中)生成的。開啟這個檔案你會看到它就是一個標準的ASP.NET頁面，它使用.NET reflection生成那個文件。這個特點使文件一直與程式碼同步，可以通過簡單的修改這個檔案來定製你的生成文件。

       也可以在Web.config檔案中指定一個不同的文件檔案來繞過基於虛擬目錄文件生成器：

<configuration>

  <system.web>

    <webServices>

      <wsdlHelpGenerator href="MyDocumentation.aspx"/>

    </webServices>

    ...

如果客戶端發出請求.asmx終點，且請求字串後加“？wsdl”，.asmx控制代碼將生成一個WSDL定義而不是一個人性化的可讀文件。客戶端可以使用WSDL定義生成代理類，它自動的知道怎樣和Web服務通訊。

       要定製WSDL生成過程，你可以寫一個SoapExtensionReflector類並在你的Web.config檔案中註冊到WebMethods框架。然後當.asmx控制代碼生成WSDL定義時，它將會呼叫你的反映類（reflector）使你有機會定製提供給使用者的最後定義。

       同樣你也可以採用兩種技術來繞過WSDL生成過程。首先，可以在你的虛擬目錄下提供一個靜態的WSDL文件供客戶訪問，然後從Web.config檔案中除去文件生成器（如下所示）。

<configuration>

  <system.web>

    <webServices>

      <protocols>

        <remove name="Documentation"/>

      </protocols>

      ...

另外一個比較自動化的技術是使用[WebServiceBinding]屬性來指定WebMethod類實現的靜態WSDL文件在虛擬目錄中的位置，也要用[SoapDocumentMethod]屬性為每一個實現的WebMethod指定WSDL繫結的名字。這樣做以後，自動WSDL生成過程將會匯入你的靜態WSDL檔案，生成一個新的服務描述。

手工編寫WSDL是極端困難的，因為現在沒有很多WSDL編輯器。因此自動文件/WSDL生成是WebMethod框架中有價值的一部分。沒有它，許多開發者的日子會很難過的。
總結

ASP.NET WebMethods框架為建立WEB服務提供了高效的方法。WebMethods使得傳統的.NET方法能夠成為支援HTTP、XML、XML Schema和WSDL的Web服務操作。WebMethod（.asmx）控制代碼自動決定怎樣將到來的SOAP請求訊息分派到適當的方法，然後又將請求訊息中的XML元素序列化為相應的.NET物件。為簡化整合客戶端，.asmx控制代碼也支援可讀文件和WSDL的生成。

和自己定製的IhttpHandlers相比，儘管WebMethods框架有點受限，它還是提供了稱為SOAP擴充套件框架的強大擴充套件模型。SOAP擴充套件允許你引入我們上面沒有討論到的額外功能來滿足你的具體需要。比如，微軟釋出了Web Serivices Enhancements1.0，它提供了SoapExtension類，為WebMethods框架引入了幾個GXA規範的支援。