WebService 項目實踐筆記

註：筆記內容本來就這麼多，其他都應該屬於商業機密。

要點

1. WebService 類，如 Syc.asmx.cs 中的 class Syc ，即擁有 WebMethod 的類。
2. WebService 類，要繼承自 System.Web.Services.WebService。
3. WebService 類，要引用 System.Web.Services 命名空間
4. WebService 類，不需要每個方法都標為 [WebMethod] ，只是公開的介面方法需要。
5. 可序列化的實體物件，即作為 WebMethod 返回的對象實體類
6. 可序列化的實體物件，必須有 [Serializable] 標記
7. 可序列化的實體物件，要引用 System.Xml.Serialization 命名空間
8. 可序列化的實體物件，在經過 WebService 傳遞後，仍可按類執行個體使用它的屬性和方法
9. 可序列化的實體物件，可以擁有一對針對有價值內容的 getter / setter 方法
10. 壓縮除了為了節省傳輸資料量，也為了在一定程度上的資料保密
11. KEY 密鑰 和 Auth 驗證碼產生方法是為了通訊前的安全驗證。
12. 實體物件的編號 ID 屬性 通常是 32位 GUID。不僅保證唯一，也為了支援資料的分布式 Insert。
13. Web 服務提供端（響應端）僅僅需要編寫 *.asmx (.cs)  和 可序列化的實體物件。wsdl 文檔、SOAP 代理程式使用 Microsoft ASP.NET 工具自動產生。
14. 請求端在獲得包括了 WebService 代理類和可序列化對象實體類的 SOAP 代理程式檔案後，可以像調用本地類庫一樣使用這些代碼。
15. 對於不同版本的 ASP.NET 或者完全不同的運行環境，例如 Mono，交換的介面檔案應是 WSDL 文檔。

參考閱讀

Microsoft ASP.NET QuickStart 快速入門教程 Web 服務章節（xxxClient 即為服務要求端）
http://chs.gotdotnet.com/quickstart/aspplus/doc/writingservices.aspx 

Web Service 類聲明

[WebService(Namespace="http://www.abc123.com/WebService/")]
public class Syc
{
......
}

注意：不加標註也是可以的，加標註僅僅是為了聲明命名空間。

Web Service 方法聲明

[WebMethod(Description=".....")]
public  傳回值 方法名 ( 參數表 )
{

返回的對象必須是 序列化對象
對象有效資料可以是 DataSet ，
如果需要壓縮，則資料應該是 XML 或者常值內容 （位元組數組）

}

[Serializable]
對象實體類

（與 UI 同級）
WebService \ UsersEntity.cs

主要屬性：
屬性 Users － 位元組數組
int result
string ErrorString
string CRC
public void SetUserData (ds) —— ( ds --> xml --> ZIP 壓縮 )
public void SetResult ( resultCode)

同步介面
WebService \ Syc.asmx.cs  － 公用 WebService 方法 [WebMethod]

主要方法：
public string CreateAuth( string entityID, string entityName, string key  ) － 產生驗證碼

public bool CheckAuth( string auth ) － 檢查驗證碼

[WebMethod]
public UsersEntity GetOrgUsers (string  orgID, string auth )
方法主要流程：
checkAuth ( orgID, auth )
SetResult ( resultCode )
調用 DataProvider 做 select 返回 ds
調用 UsersEntity 設定資料 (ds)
返回 UsersEntity

資料介面（做 select 返回 ds）
類庫 \ Data \ DataProvider.cs

主要方法：
public DataSet GetOrgUsersRequest (string orgID)
{
DataSet ds = new DataSet();
dataHelper.FillDataSet ( ...., sql, ds, dtName );
return ds;
}

測試案例

1.
string key = "  n 位密鑰 ";  // 公開金鑰
Syc syc = new Syc(); // 載入同步介面
string auth = syc.CreateAuth (entityID, entityName, key);  // 產生驗證碼

2. Console.WriteLine( auth );  // 得到驗證碼（公開金鑰）

3.
WebService / UsersEntity res = syc.GetOrgUsers ("1", auth); // 調用同步介面的 WebMethod
byte[] r = Zip.DecompressData ( res.Users ); // 解壓 XML（DS）資料

4. Console.WriteLine (System.Text.Encoding.UTF8.GetString ( r ));  // 用 UTF8 輸出使用者結果資料（XML文本）

測試案例流程

1. 驗證碼：對公開金鑰 KEY  用目前時間 SHA1 加密
（請求方提供 明文要素 和 加密結果 給回應程式，回應程式看看用明文要素能不能產生發過來的加密結果）

2. 用同步介面 [WebMethod] 取資料（調用資料介面）

（返回）得到一個序列化的實體物件（.NET對象）

3. 從序列化對象方法取得位元組數組

4. 解壓（ZIP）

5. 得到（XML）文本

為服務要求端作準備－1. 產生 WSDL 介面文檔 （XML 格式介面 API）

1. 在瀏覽器地址欄輸入：

http://localhost/.........../Syc.asmx?WSDL

2. 把網頁另存新檔 XML 格式的 Syc.wsdl 檔案，在下一節會用到。

為服務要求端作準備－ 2. 產生 SOAP  代理（提供給服務要求端的 C# 程式）

1. 開啟命令列方式

2. Microsoft WSDL 轉換工具的使用方法：

Microsoft (R) Web 服務描述語言工具 + 生產力
[Microsoft (R) .NET Framework，版本 1.1.4322.573]
Copyright (C) Microsoft Corporation 1998-2002. All rights reserved.


wsdl.exe -
    用於從 WSDL 協定檔案、XSD 架構和 .discomap 發現文檔，
    為使用 ASP.NET 的 Xml Web service 用戶端和 Xml Web services 產生代碼的實用工
具。
    此工具可以與 disco.exe 一起使用。

wsdl.exe <選項> <URL 或路徑> <URL 或路徑> 

     - 選項 -

<url or path> -
    WSDL 協定、XSD 架構或 .discomap 文檔的 URL 或路徑。

/nologo
    取消顯示著作權標誌。

/language:<language>
    用於產生的代理類的語言。從“CS”、
    “VB”、“JS”、“VJS”中選擇，或者為實現
    System.CodeDom.Compiler.CodeDomProvider 的類提供完整名稱。預設為“CS”

(CSharp)。縮寫為“/l:”。

/server
    基於協定，為使用 ASP.NET 的 Xml Web service 實現產生抽象類別。
    預設為產生用戶端代理類。

/namespace:<namespace>
    產生的代理或模板的命名空間。預設命名空間
    為全域命名空間。縮寫為“/n:”。

/out:<fileName>
    產生的代理代碼的檔案名稱。預設名稱是從
    服務名派生的。縮寫為“/o:”。

/protocol:<protocol>
    重寫要實現的預設協議。從“SOAP”、“SOAP12”、
“HttpGet”、“HttpPost”或設定檔中指定的自訂協議中選擇。

/username:<username>
/password:<password>
/domain:<domain>
    串連到要求身分識別驗證的
    伺服器時使用的憑據。縮寫為“/u:”、“/p:”和“/d:”。

/proxy:<url>
    用於 HTTP 請求的Proxy 伺服器的 URL。
    預設為使用系統代理程式設定。

/proxyusername:<username>
/proxypassword:<password>
/proxydomain:<domain>
    串連到要求身分識別驗證的Proxy 伺服器時使用的憑據。
    縮寫為“/pu:”、“/pp:”和“/pd:”。

/appsettingurlkey:<key>
    在代碼產生中用來讀取 URL 屬性的預設值的配置項。預設為不從配置
    檔案中讀取。縮寫為“/urlkey:”。

/appsettingbaseurl:<baseurl>
    計算 URL 段時使用的基 URL。
    還必須指定 appsettingurlkey 選項。URL 段是
    從 appsettingbaseurl 計算
     WSDL 文檔中的 URL 的相對 URL 的結果。縮寫為“/baseurl:”。

/parsableerrors
    輸出錯誤，其格式與編譯器報告的格式類似。

3. 在命令列執行 wsdl.exe 命令：

F:\WorkPlace\MyProject\WebService>"C:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin\wsdl.exe" /l:CS /n:SOAP代理類的命名空間 /out:SOAP代理類的C#檔案名稱.cs WSDL源檔案.wsdl

例如：

F:\WorkPlace\MyProject\WebService>"C:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin\wsdl.exe" /l:CS /n:StephenCat.WebService.SycService /out:SycService.cs syc.wsdl

執行後的螢幕輸出內容：

Microsoft (R) Web 服務描述語言工具 + 生產力
[Microsoft (R) .NET Framework，版本 1.1.4322.573]
Copyright (C) Microsoft Corporation 1998-2002. All rights reserved.

正在寫入檔案“SycService.cs”。

所成生的 SOAP 代理檔案包含以下內容：

1. 與 WebService 類同名、擁有相同方法的代理類，如 class Syc
2. WebService 類中使用到的所有可序列化對象實體類，如 class UsersEntity
3. 以上所有類被包含在同一個命名空間中，該命名空間在命令列執行 wsdl 的參數中指定。

服務要求端調用 Syc 同步介面

參見《微軟 ASP.NET 快速入門教程 Web服務樣本》：
http://chs.gotdotnet.com/quickstart/util/srcview.aspx?path=/quickstart/aspplus/samples/services/DataTypes/DataTypesClient.src&file=CS\DataTypesClient.aspx&font=3

由 WDSL 產生的SOAP代理檔案：
http://chs.gotdotnet.com/quickstart/util/srcview.aspx?path=/quickstart/aspplus/samples/services/DataTypes/DataTypesClient.src&file=CS\DataTypes.cs&font=3

其中：
DataTypes 是 SOAP 代理類
Order 是對象實體類