ASP.Net WebAPI經驗分享

大綱• REST• WebAPI• Debug WebAPI• Async/Await• HttpClient• Help Page

REST

• REST 全名為 : REpresentational State Transfer• 意思為不斷的進行資源呈現的狀態轉移• REST 探討的是 : 如何正確的使用網頁標準• RESTfull 指的是該服務滿足所有 REST 規範

REST 的由來Roy Thomas Fielding

• 在 2000 年提出的Architectural Styles and the Design of Network-based Software Architecture 博士論文第五章提出 REST 的概念。

Http 動詞• 動詞一共有 :

• Head 、 Get 、 Post 、 Put 、 Delete 、 Patch 、 Option

• 而資料庫操作與 Http 動詞的對應如下表 :動詞 Http中的動作 資料庫中對應的動作Get 取得資源 Select

Post 新增資源 Insert

Put 修改資源 Update

Delete 刪除資源 Delete

Patch 修改資源 Update 部份欄位

資源 (Resource)

1. 網址列輸入網址2. 伺服器接收到請求 , 回應請求的資源內容3. 使用者對某個鏈結有興趣並點擊4. 伺服器收到請求 , 回應請求的內容

請求某個資源 http://localhost/Products/1

回應首頁資源請求首頁資源 http://localhost/

回應產品編號為 1 的資源

網際網路 (Internet) 上擁有著無數的資源 ; 任何資訊或圖片都是資源 , 每個資源都以一個 Uri 識別

資源與 Http 方法Http方法 資源”

/api/values資源 :/api/values/1

Get 取得所有資源 取得指定資源Put 更新所有資源 更新指定資源Post 新增一組資源 新增一組資源Delete 刪除所有資源 刪除指定資源

資源的呈現• 資源 : Get http://localhost/api/values• Firefox, Chrome -> 以 XML 呈現• IE 10 -> 以 JSon 呈現

Http Status Code

• Http 服務不是一個網頁 , 並無 UI 存在 , 故需要 Http Status Code告知用戶端本次的請求執行狀況。

大綱• REST• WebAPI• Debug WebAPI• Async/Await• HttpClient• Help Page

WebAPI

• 提供網頁應用程式介面的功能就稱之為 WebAPI 。• 常見的 WebAPI:

• Google Maps API• MediaWiki API• Bing API• Facebook API

• 開發人員僅需遵守 API 規範就能夠開發自己所需要的應用程式。

ASP.Net WebAPI

• ASP.Net Web API 從 WCF Web API 改良而來。• 集 ASP.Net MVC 與 WCF 精華於一身。• ASP.Net WebAPI 是一組 Framework ，建置在 Http 服務之上。

ASP.Net WebAPI 整合功能整合 ASP.Net MVC的功能 整合WCF Web API的功能ASP.Net Routing Modern HTTP Programming ModelModel Binding HttpClientValidation Task-based asyncFilters FormattingLink Generation Server-side Query CompositionTestability Create custom help pagesIoC Integration Self-HostVisual Studio Template TracingScaffolding Content Negotiation

ASP.Net WebAPI 能否取代 WCF

• ASP.Net WebAPI 的通訊協定僅有 Http 。• WCF 是針對企業級 SOA(Service-Oriented Architecture) 打造的 , 具備一切企業級服務設計所需的能力和功能。• 如何選擇 :

• Http 服務選擇 ASP.Net WebAPI• 其它通訊協定選擇 WCF

ASP.Net WebAPI 的 Routing 定義

• Get /api/values• Get /api/values/1

ASP.Net WebAPI 的慣例• API 方法命名 : Http 方法 +ActionName• API 方法呼叫 : Http 方法 +Uri

• Create 資源 : Post api/values• Update 資源 : PUT api/values• Read 資源 : Get api/values 與 Get api/values/5• Delete 資源 : Delete api/values/5

ASP.Net WebAPI 與 Entity Framework

DatabaseClientASP.Net

MVC

ASP.Net WebAPI

Entity Framework

HTML 會員管理認證

JSon CRUD 請求 CRUD

Visual Studio 的範本

ASP.Net WebAPI- 以 Northwind 為例

Get 範例

PUT 範例

POST 範例

Delete 範例

Patch

• 當需要提供更新實體中部份成員屬性 (Property) 時 , 不該使用 Put;使用 Put 會造成其它非修改欄位被設定為 Null 。• 使用 Patch 需在 Action 上加上屬性標籤 : [HttpPatch], 並且在輸入參數上加上過濾標籤 : [Bind]

Patch 範例

大綱• REST• WebAPI• Debug WebAPI• Async/Await• HttpClient• Help Page

如何 Debug ASP.Net WebAPI

• ASP.Net WebAPI 僅是服務 , 因此不具有任何 UI 畫面 , 因此在偵錯上比較困難。• Visual Studio 2010/2012 都有提供 IISExpress, 可利用

IISExpress 觀察 Log 。

POSTMan

可在 Chrome 的 App Store 上找到 POSTMan

POSTMan 的 icon

嘗試用 Postman 取得 Order 資料

發生錯誤

造成錯誤的原因

修改 POCO

再次執行

成功 !

IISExpress

• Visual Studio 2010免費提供 IISExpress 7.5 。亦可在微軟官網上下載 IISExpress獨立安裝包 , 可安裝在 Windows XP 以上作業系統版本。• Visual Studio 2012亦提供 IISExpress 8.0 。但 IISExpress

8.0 不能安裝在 Windows XP 。

IISExpress 的 config檔• 位置 : C:\Users\{帳戶名稱 }\Documents\IISExpress\config\applicationhost.config• 每個編譯過的網站都會記錄在這個 config檔中的 <sites>…</

sites> 標籤內。

以命令提示字元執行

啟動指定的網站

使用者 Request紀錄

Fiddler

http://www.fiddlertool.com/fiddler2/version.asp

Fiddler 觀察當前 IE 開啟的網頁

Fiddler 取得 ASP.Net WebAPI 資料

Fiddler 的 Post

Fiddler 的 Patch

大綱• REST• WebAPI• Debug WebAPI• Async/Await• HttpClient• Help Page

過去的非同步呼叫

Async/Await

• .Net Framework 4.5 在非同步程式提供兩個關鍵字 :• Async: 用來標示這個方法內部使用非同步呼叫• Await: 等待某個非同步呼叫完成

• 一個方法以 Async 標示 , 內部會含 0 ~ 多個 Await 。• 只要是標示了 Async 的方法 , 回傳型別都要是 : Task<T> 。• 使用 Await 會讓方法執行以一條新的 IO Thread去等待該方法呼叫完成 , 而原本的 Worker Thread則暫時先釋放。

Async/Await帶來的優缺點• 優點 :

• 提升網站效率。• 缺點 :

• 若用錯 Await 到非需要長久等待的方法 ,反而會增加執行成本。

範例

大綱• REST• WebAPI• Debug WebAPI• Async/Await• HttpClient• Help Page

Nuget安裝

加入參考

介面

HttpClientRepositoryBase

屬性 :Client

取得所有物件

依識別碼取得物件

新增物件

更新物件

刪除物件

子類別 :Order

大綱• REST• WebAPI• Debug WebAPI• Async/Await• HttpClient• Help Page

WebAPI 的 Help Page

• 任何 API 都會需要提供其 API 的使用說明與範例。• 為了便利性 API 的使用說明 (Help Page)尤其以線上文件的方式最為適合。• 網路牛人已有提供一個完整的套件解決這個問題。• 安裝Microsoft ASP.NET Web API Help Page這個 Nuget套件。

仿 Castle 的做法• 使用 Microsoft ASP.NET Web API Help Page套件仍有一些需要自行組態的動作。• Castle 是過去常被用於自動化產生 .Net 應用程式的 API 文件。• Visual Studio 提供註解以 XML 資料格式匯出。 Castle便是藉由產生出來的 XML 文件產製 API 文件。

第一步 :讓 VS將註解匯出

勾選填入匯出 XML 的路徑 :App_Data\XmlDocument.xml

第二步 : 解開 Help Page 組態的註解

取消此行註解

步驟 3: 為方法寫上完整註解

執行

Help Page 的真面目• 其實 Help Page 是在 WebAPI專案中提供一個子網站。• 若需要客製化或是美化均可自行修改。

大綱• REST• WebAPI• Debug WebAPI• Async/Await• HttpClient• Help Page

CORS

• CORS 是 HTML5 所提出的一種解決跨站呼叫的解決方案。• 可以安裝套件 :