建立 XML Web Service Proxy

發行項
02/28/2011

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

根據定義，可以使用產業標準通訊協定 (包括 SOAP)，透過網路與 Web 服務進行通訊。也就是說，用戶端和 Web 服務可以使用將 in 和 out 參數封裝成 XML 的 SOAP 訊息相互通訊。幸虧 Proxy 類別可以替 Web 服務用戶端處理由參數至 XML 項目的對應工作，再透過網路傳送 SOAP 訊息。

所以只要服務描述存在，且這項服務描述符合 Web 服務描述語言 (WSDL)，就可以產生 Proxy 類別。服務描述會定義與 Web 服務進行通訊的方式。有了服務描述，您將可以使用 Wsdl.exe 工具來建立 Proxy 類別。接下來，Web 服務用戶端便可以叫用 Proxy 類別的方法，這些方法會處理往返於 Web 服務傳送的 SOAP 訊息，以便透過網路與 Web 服務通訊。因為 Proxy 類別可以跨越網際網路與 Web 服務進行通訊，所以最好要確認 Proxy 類別的 Url 屬性是否參考受信任的目的端。

根據預設，Proxy 類別會使用 SOAP over HTTP 與 Web 服務進行通訊。不過，Wsdl.exe 也可以產生 Proxy 類別，以便使用 HTTP-GET 通訊協定或 HTTP-POST 通訊協定與 Web 服務進行通訊。若要指定 Proxy 類別應使用 HTTP-GET 或 HTTP-POST，請提供 /protocol 參數給 Wsdl.exe 工具，如下表中所述。

使用 Wsdl.exe 產生 XML Web Service Proxy 類別

您可以從命令提示字元使用 Web 服務描述語言工具 (Wsdl.exe) 來建立 Proxy 類別，並至少指定 Web 服務或服務描述的 URL 或已儲存之服務描述的路徑。

Wsdl /language:language /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>

注意：
這裡列出的引數是一些常用於 Wsdl.exe 的引數。如需 Wsdl.exe 的完整語法，請參閱 Web 服務描述語言工具 (Wsdl.exe)。

參數	值
<URL 或路徑>	服務描述 (使用 Web 服務描述語言描述 Web 服務的檔案) 的 URL 或路徑。如果您指定檔案，請提供包含服務描述的檔案。例如： mywebservice.wsdl 如果指定的是 URL，這個 URL 必須參考 .asmx 頁面，或傳回服務描述。對於使用 ASP.NET 所建立的 Web 服務，您可以在 Web 服務的 URL 中附加 ?WSDL，表示要傳回服務描述。例如： https://www.contoso.com/MyWebService.asmx?WSDL。
/language:language	產生 Proxy 類別所使用的語言。可用的選項包括 CS、VB 和 JS，分別代表 C#、Visual Basic .NET 和 JScript .NET。預設語言為 C#。(選擇項)
/protocol:protocol	用來和 Web 服務方法進行通訊的通訊協定。可用的選項包括 SOAP、HTTP-GET 和 HTTP-POST。預設通訊協定為 SOAP。(選擇項)
/namespace:myNameSpace	產生之 Proxy 的命名空間。預設值為全域命名空間。(選擇項)
/out:filename	要建立之檔案的名稱，該檔案將包含 Proxy 類別。預設名稱是根據實作 Web 服務之類別的名稱。(選擇項)
/username:username	連接到要求驗證的 Web 伺服器時要使用的使用者名稱。(選擇項)
/password:password	連接到要求驗證的 Web 伺服器時要使用的密碼。(選擇項)
/domain:domain	連接到要求驗證的 Web 伺服器時要使用的網域。(選擇項)

產生的 Proxy 類別詳細資訊

使用 Wsdl.exe 產生 Proxy 類別時，會以指定的語言來產生單一原始程式檔。這個檔案包含的 Proxy 類別會公開 Web 服務中每一個 Web 服務方法的同步及非同步方法。例如，如果 Web 服務包含名為 Add 的 Web 服務方法，則 Proxy 類別有下列方法可用來呼叫 Add Web 服務方法：Add、BeginAdd, 和 EndAdd。Proxy 類別的 Add 方法是用來與 Add Web 服務方法進行同步通訊，而 BeginAdd 和 EndAdd 方法則是用來與 Web 服務方法進行非同步通訊。如需詳細資訊與 Web 服務方法進行非同步通訊，請參閱與 XML Web 服務進行非同步通訊。

產生之 Proxy 類別的每個方法都會包含可以和 Web 服務方法通訊的適當程式碼。如果在與 Web 服務及 Proxy 類別通訊時發生錯誤，就會擲回例外狀況。如需詳細資訊處理例外狀況，請參閱在 XML Web Service 中處理和擲回例外狀況。

在 Web 服務方法與相關聯的 Proxy 類別方法中定義的參數，可能在順序上有差異。在大多數情況下，參數順序會相符。不過，如果 Web 服務需要 Document 格式化的 SOAP 訊息，就會發生參數順序不相符的情況。如果 Web 服務方法在 in 參數之前定義了 out 參數，out 參數便會在 Proxy 類別中置於所有 in 參數之後。例如，在下列程式碼範例中，Web 服務方法 MyWebMethod 在 in 參數 inStr 之前宣告了 out 參數 outStr。然而在 Proxy 類別中，inStr 參數則是宣告於 outStr 之前。

' Declare MyWebMethod in the Web service.
MyWebMethod(ByRef outStr As String, inStr As String)

' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)

// Declare MyWebMethod in the Web service.
MyWebMethod(out string outStr, string inStr)

// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).

在某些情況下，由 Wsdl.exe 產生的 Proxy 類別會使用最小公分母的方式將物件轉換為服務描述中指定的型別。因此，Proxy 類別中產生的型別可能會和開發人員想要或預期的不同。例如，當 Wsdl.exe 在服務描述中遇到 ArrayList 型別時，它會在產生的 Proxy 類別中建立 Object 陣列。若要確定正確的物件型別轉換 (Type Cast)，請開啟包含產生之 Proxy 類別的檔案，並將所有不正確的物件型別變更為預期的物件型別。

Wsdl.exe 擲回的警告

為 Wsdl.exe 提供多個服務描述時，可能會引發以下兩個錯誤訊息：

警告: 將忽略 <結構描述 URI> 內 TargetNamespace=<結構描述命名空間> 的重複服務描述。

表示兩個以上提供的服務描述的 TargetNamespace 完全相同。由於 TargetNamespace 原本就應該是特定 XML 文件 (在此例中是服務描述) 的唯一識別項，所以 Wsdl.exe 會假設兩個服務描述完全相同。這樣做時，Wsdl.exe 只會為其中一個服務描述建置一個 Proxy 類別。如果這不是您要的結果，您可以變更這種做法。如果服務描述表示的是使用 ASP.NET 所建立的 Web 服務，您可以套用 WebService 屬性，將唯一的 Namespace 屬性指定給實作 Web 服務的類別。這個 Namespace 屬性便會在服務描述中當做 TargetNamespace 用來唯一識別 Web 服務。
警告: 將忽略 <結構描述 URI> 內 TargetNamespace=<結構描述命名空間> 的重複結構描述。

表示提供的服務描述中有兩個以上 XML 結構描述的 TargetNamespace 完全相同。因為 TargetNamespace 原本就應該是特定 XML 文件 (在此例中是 XML 結構描述) 的唯一識別項，所以 Wsdl.exe 會假設兩個 XML 結構描述完全相同。這樣做時，Wsdl.exe 只會為其中一個結構描述建置一個類別。如果這不是您要的結果，就必須將每個 XML 結構描述的 TargetNamespace 變更為唯一的 URI。修改 TargetNamespace 的確切方式應取決於特定 XML 結構描述的來源。

另請參閱