2009-01-16 19:09:15艾爾文

[轉] 建立 XML Web Service Proxy

翻了好久的 msdn 才找到的..
==

建立 XML Web Service Proxy

依照定義,Web 服務可使用工業標準通訊協定 (包括 SOAP) 透過網路通訊。也就是說,用戶端和 Web 服務可使用 SOAP訊息通訊,此訊息會將 in 和 out 的參數以 XML 格式封裝。幸好對 Web 服務的用戶端而言,Proxy 類別可處理將參數對應到XML 項目,並接著透過網路傳送 SOAP 訊息的工作。

如果服務描述存在並且符合 Web 服務描述語言(WSDL),就可以產生 Proxy 類別。服務描述定義了如何與 Web 服務通訊。透過服務描述,可使用 Wsdl.exe 工具建立Proxy 類別。接著 Web 服務用戶端可以叫用 Proxy 類別的方法,藉由處理與 Web 服務來往傳送的 SOAP 訊息,以透過網路與Web 服務通訊。因為 Proxy 類別在網際網路上與 Web 服務通訊,所以建議您確認該 Proxy 類別的 Url 屬性是參考信任的目的地。

依預設,Proxy 類別會使用 SOAP over HTTP 與 Web 服務通訊。不過,透過 HTTP-GET 或 HTTP-POST通訊協定,Wsdl.exe 可產生 Proxy 類別與 Web 服務通訊。若要指定 Proxy 類別應使用 HTTP-GET 還是HTTP-POST,您可以將 /protocol 參數提供給 Wsdl.exe 工具,如下表所述。

使用 Wsdl.exe 來產生

XML Web Service Proxy

類別

您可以在命令提示字元中使用 Web 服務描述語言工具 (Wsdl.exe),至少要指定 Web 服務或服務描述的 URL,或指定已儲存之服務描述的路徑。

Wsdl /language:language  /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain 
Note注意事項

此處所列的引數為 Wsdl.exe 常用引數。如需 Wsdl.exe 的完整語法,請參閲 Web 服務描述語言工具 (Wsdl.exe)

參數 Value

連往服務描述 (以 Web 服務描述語言描述 Web 服務的檔案) 的 URL 或路徑。

如果您要指定檔案,請提供包含服務描述的檔案。例如:

mywebservice.wsdl

如果您要指定 URL,則該 URL 必須參考 .asmx 網頁或傳回服務描述。對於使用 ASP.NET 建立的 Web 服務,您可以在 Web 服務的 URL 之後加上 ?WSDL 來傳回服務描述。例如:

http://www.contoso.com/MyWebService.asmx?WSDL

/language:language

用於產生 Proxy 類別的語言。可用選項包括 CSVB 以及 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 服務方法:AddBeginAdd 以及 EndAdd。Proxy 類別的 Add 方法用於與 Add Web 服務方法同步通訊,而 BeginAddEndAdd 方法則用於與 Web 服務方法非同步通訊。如需與 Web 服務方法非同步通訊的詳細資訊,請參閱與 XML Web Service 進行非同步通訊

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

Web 服務方法與相關 Proxy 類別方法中所定義的參數順序可能不同。多數情況下,參數順序是相符的。但如果 Web 服務需要 Document 格式的 SOAP 訊息,則有一種狀況參數順序會不同。如果 Web 服務方法的 out 參數定義於 in 參數之前,那麼 out 參數會放在 Proxy 類別中所有 in 參數之後。以下列程式碼範例為例,Web 服務方法 MyWebMethodoutStr out 參數就宣告於 inStr in 參數之前。而在 Proxy 類別中,inStr 參數是宣告於 outStr 之前。

Visual Basic
' 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).

在某些情況下,由 WDSL.exe 產生的 Proxy 類別會使用最小公分母方式來將物件轉型為服務描述中指定的型別。因此,Proxy 類別中產生的型別可能不符開發人員所想或預期的。例如,WSDL.exe 在服務描述中遇到 ArrayList 型別時,會在產生的 Proxy 類別中建立 Object 陣列。為確保轉型成正確的物件型別,請開啟包含產生之 Proxy 類別的檔案,並將任何不正確的物件型別變更為應有的物件型別。

Wsdl.exe 擲回的警告

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

  • 警告: 忽略 位置內具有 TargetNamespace= 的重複服務描述。

    表示提供之兩個以上服務描述的 TargetNamespace 是相同的。因為 TargetNamespace應為特定 XML 文件 (在本例中為服務描述) 的唯一識別項,Wsdl.exe 會假設這兩個服務描述是相同的。在這種情況下,Wsdl.exe只會為其中一個服務描述建立一個 Proxy 類別。如果這不是您要的結果,可以加以變更。對於表示使用 ASP.NET 建立之 Web服務的服務描述,您可以套用 WebService 屬性,並指定唯一 Namespace 屬性給實作 Web 服務的類別。該 Namespace 屬性接著會在服務描述中當做 TargetNamespace 使用,以唯一識別 Web 服務。如需設定 Namespace 屬性的詳細資訊,請參閱套用 WebService 屬性。

  • 警告: 忽略 位置內具有 TargetNamespace= 的重複結構描述。

    表示在提供的服務描述中,有兩個以上 XML 結構描述的 TargetNamespace 是相同的。因為 TargetNamespace 應為特定 XML 文件 (在本例中為 XML 結構描述) 的唯一識別碼,Wsdl.exe 會假設這兩個 XML 結構描述是相同的。在這種情況下,Wsdl.exe 只會為其中一個結構描述建置類別。如果這不是您要的結果,那麼每個 XML 結構描述的 TargetNamespace 就必須改為唯一 URI。要如何修改 TargetNamespace,視特定 XML 結構描述的來源而定。

請參閱

工作

如何探索使用 ASP.NET 建立的現有 XML Web Service

參考

如何從瀏覽器存取 XML Web Service

概念

建置 XML Web Service 用戶端
Web 服務探索
與 XML Web Service 進行非同步通訊

其他資源

建立 XML Web Service 的用戶端