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 Model Model Binding HttpClient Validation Task-based async Filters Formatting Link Generation Server-side Query Composition Testability Create custom help pages IoC Integration Self-Host Visual Studio Template Tracing Scaffolding 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 DatabaseClient ASP.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{帳戶名稱}DocumentsIISExpressconfigapplicationhost.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_DataXmlDocument.xml
第二步: 解開Help Page組態的註解 取消此行註解
步驟3:為方法寫上完整註解
執行
Help Page的真面目 • 其實Help Page是在WebAPI專案中提供一個子網站。 • 若需要客製化或是美化均可自行修改。
大綱 • REST • WebAPI • Debug WebAPI • Async/Await • HttpClient • Help Page
CORS • CORS是HTML5所提出的一種解決跨站呼叫的解決方案。 • 可以安裝套件:

ASP.Net WebAPI經驗分享