共用方式為

建立 XML Web Service Proxy

  • 發行項

XML Web Service 依定義可透過業界標準通訊協定 (包括 SOAP)，在網路上進行通訊。也就是說，用戶端和 XML Web Service 透過 SOAP 訊息進行通訊，訊息中將 in 和 out 參數封裝為 XML。XML Web Service 用戶端有一點相當方便，Proxy 類別會負責將參數對應至 XML 項目，並將 SOAP 訊息透過網路傳送。

只要有服務描述存在，且服務描述格式符合 Web 服務描述語言 (WSDL)，即可產生 Proxy 類別。服務描述定義與 XML Web Service 通訊的方式。有了服務描述，就可以使用 Wsdl.exe 工具建立 Proxy 類別。然後 XML Web Service 用戶端就能叫用 Proxy 類別的方法，這些方法會處理 XML Web Service 傳出或收到的 SOAP 訊息，來和 XML Web Service 透過網路進行通訊。由於 Proxy 類別透過 Internet 與 XML Web Service 進行通訊，因此驗證 Proxy 類別的 Url 屬性是否參考了受信任的目的端是不錯的想法。

根據預設，Proxy 類別在 HTTP 上使用 SOAP，來和 XML Web Service 進行通訊。但是，Wsdl.exe 可以使用 HTTP-GET 通訊協定或 HTTP-POST 通訊協定，產生 Proxy 類別來和 XML Web Service 進行通訊。這時，若要指定 Proxy 類別該使用 HTTP-GET 或 HTTP-POST，請提供 /protocol 參數給 Wsdl.exe 工具，如下表所述。

若要產生 XML Web Service Proxy 類別

  • 在命令提示字元處，使用 Wsdl.exe 來建立 Proxy 類別，(至少) 指定連至 XML Web Service 或服務描述，或是儲存服務描述路徑的 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 or path> 指定連至服務描述的 URL 或路徑 (以Web 服務描述語言撰寫，描述 XML Web Service 的檔案)。

    如果您指定檔案，請提供包含服務描述的檔案。例如：

    mywebservice.wsdl

    如果您指定 URL，URL 必須參考 .asmx 網頁或傳回服務描述。至於使用 ASP.NET 建立的 XML Web Service，您可以將 ?WSDL 附加到 XML Web Service 的 URL，來傳回服務描述。例如：

    https://www.contoso.com/MyWebService.asmx?WSDL
    /language:language 指定產生 Proxy 類別的語言，可用選項包括 CS、VB 和 JS；分別代表 C#、Visual Basic .NET 和 JScript .NET。預設語言為 C#。(選擇性)
    /protocol:protocol 指定與 XML Web Service 方法通訊使用的通訊協定，可用選項包括 SOAP、HTTP-GET 和 HTTP-POST。預設通訊協定為 SOAP。(選擇性)
    /namespace:myNameSpace 指定所產生 Proxy 的命名空間，預設值為全域命名空間。(選擇性)
    /out:filename 指定用來建立包含 Proxy 類別的檔名，預設名稱是根據實作 XML Web Service 的類別名稱。(選擇性)
    /username:username 指定在連接至要求驗證的 Web 伺服器時，所要使用的使用者名稱。(選擇性)
    /password:password 指定在連接至要求驗證的 Web 伺服器時，所要使用的密碼。(選擇性)
    /domain:domain 指定在連接至要求驗證的 Web 伺服器時，所要使用的網域。(選擇性)

產生的 Proxy 類別詳細資訊

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

所產生之 Proxy 類別的每個方法中包含適用程式碼，可與 XML Web Service 方法進行通訊。與 XML Web Service 和 Proxy 類別通訊期間若發生錯誤，會擲回例外狀況。如需處理例外狀況的詳細資訊，請參閱在 XML Web Service 中處理和擲回例外狀況。

XML Web Service 方法定義的順序，可能和 Proxy 類別關聯方法的的參數順序不同。多數情況下，參數順序應該會相符。但是，如果 XML Web Service 預期 Document 格式化 SOAP 訊息，這時參數順序有可能不相符。如果 XML Web Service 方法具有的 in 參數比 out 參數早定義，Proxy 類別中的 out 參數會放在所有的 in 參數之後。例如，以下列程式碼為例，XML Web Service 方法 MyWebMethod 的 outStr out 參數比 inStr in 參數先宣告，但是 Proxy 類別中的 inStr 參數比 outStr 早宣告。

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

' Declare MyWebMethod in the XML 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)
[C#]
// Declare MyWebMethod in the XML 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 類別會使用最小公分母，將物件轉換 (Cast) 為服務描述中指定的型別。因此，Proxy 類別中產生的型別可能會和開發人員想要或預期的不同。例如，當 WSDL.exe 在服務描述中碰到 ArrayList 型別，會在產生的 Proxy 類別中建立 Object 陣列。若要確定正確的物件型別轉換 (Type Cast)，請開啟包含產生之 Proxy 類別的檔案，並將所有不正確的物件型別變更為預期的物件型別。

Wsdl.exe 擲回的警告

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

  • 警告：忽略 <schema URI> 內具有 TargetNamespace=<schema namespace> 的重複服務描述。

    表示兩個或多個提供的服務描述具有相同的 TargetNamespace。由於 TargetNamespace 必須為特定 XML 文件的唯一識別碼 (本例為服務描述)，Wsdl.exe 會假設這兩個服務描述相同。所以，Wsdl.exe 只會為其中一個服務描述建置一個 Proxy 類別。如果這不是您想要的結果，可以加以變更。您可以將 WebService 屬性套用至 (表示使用 ASP.NET 建立之 XML Web Service) 的服務描述，將唯一 Namespace 屬性指定給實作 XML Web Service 的類別。這樣 Namespace 屬性就可以在服務描述中當成 TargetNamespace 使用，成為 XML Web Service 的唯一識別。如需設定 Namespace 屬性的詳細資訊，請參閱設定 WebService 屬性。

  • 警告：忽略 <schema URI> 內具有 TargetNamespace=<schema Namespace> 的重複結構描述。

    表示所提供之服務描述中的兩個或多個 XML 結構描述具有相同的 TargetNamespace。由於 TargetNamespace 必須為特定 XML 文件的唯一識別碼 (本例為 XML 結構描述)，Wsdl.exe 會假設這兩個 XML 結構描述相同。所以，Wsdl.exe 只會為其中一個結構描述建置一個 Proxy 類別。如果這不是您想要的結果，必須將每個 XML 結構描述的 TargetNamespace 改成唯一的 URI。至於 TargetNamespace 該如何修改，則視特定 XML 結構描述的來源而定。

請參閱

建置 XML Web Service 用戶端 | 探索 XML Web Service | 建立 XML Web Service 的用戶端 | 瀏覽現有使用 ASP.NET 建立的 XML Web Service | 與 XML Web Service 進行非同步通訊 | 從瀏覽器存取 XML Web Service