塵世打雜工: [ASP.NET] Creating Web APIs Note

筆記

文章區塊會以大段落為主，而每個段落之間的分枝，就直接寫在一起，只保留關鍵字。

1. Getting Started

關於試作 WebAPI 的部份，這邊算是入門教學，照著做就對了。所以，並不會有什麼不一樣的地方 Http Request Life Cycle 反倒是意外發現這張圖，解說從 Client 端發出送請求到訊息回應的流程圖。

2. Creating Web APIs

名詞解說 CRUD stands for "Create, Read, Update, and Delete"。這四個動作是基於與資料庫做溝通時，通常會使用到的動作，也是多數網頁請求會使用到的行為。基本上選擇空白具可讀取的選項，都會自動幫使用者建立出這四個函式。路徑與函式之間的概念，可能會需要去了解 MVC Routes 才會懂這邊想表達的意思。當收到Client端的請求時，預設是以請求的形態來做 map 的動作。

$(function () {
 $.ajax({
  type: "Get",
  url: ""
 });
});

對收到的對像來說，會先至 Routes 找尋對應規則，再預設當中，如 type Get 則會優先尋找開頭為 Get 且不需攜帶引數的函式。

Request.CreateResponse<T>(HttpStatusCode.Created, new T());

Http StatusCode 允許使用者定義回應狀態。

Entity Framework 設計

Database-first
Model-first
Code-first

Entity Framework 會使用 ID 屬性來當 primary key 並自動 map 到資料庫的欄位，所以 DB 會自動產生這個值。POCOs (plain-old CLR objects) [ScaffoldColumn(false)] 告訴 MVC 產生表單編輯時，請略過這個屬性，或者說不用編輯。 [Required] 對當前 Model 對言，必需是有效值且不能為空白字串。修改預設回應 xml 為 json 格式， Response 物件就會被序列化成 json 格式。建好這部份的關聯，可以在伺服器管理員 -> 資料連接當中發現 DbContext(EF) 物件。

var json = config.Formatters.JsonFormatter;
json.SerializerSettings.PreserveReferencesHandling = Newtonsoft.Json.PreserveReferencesHandling.Objects;

config.Formatters.Remove(config.Formatters.XmlFormatter);

自定義測試這邊，DropCreateDatabaseIfModelChanges 一直無法觸發到 Seed 這函式，看了一些討論文章，大家的做法不差異不會很大，也有人在討論觸發的時機點，感覺是個有問題的功能。暫時先不理會這段，之後再來深入。後面就只剩下畫面呈現的部份，就不在紀錄。

WebAPI Doc 對應 XML 註解樣式經由 Package Manager Console Install-Package Microsoft.AspNet.WebApi.HelpPage，對於相同名稱的函式，ApiExplorer 也會自動做區分，讓每個函式都是唯一的，不顯示的函式，[ApiExplorerSettings(IgnoreApi=true)] 直接加上標籤就會略過了。

3. Web API Clients

Console 及 WPF Application 模式，則是使用 HttpClient 就可以處理完畢。HTTP Message Handlers 等五章節再來研究。

4. Web API Routing and Actions

關於 HTTP Methods，使用者可以指定當前的 Mathod 所提示的支援，HttpGet, HttpPut, HttpPost, or HttpDelete，同時，也可以使用 [AcceptVerbs("GET", "HEAD")]，同樣的，也可使用 [ActionName("youwant")] 來讓 Template 對應至這個位置。對應的 tag 則為 [NonAction]

5. Working with HTTP

在測試狀態，可以使用System.Diagnostics.Debug.WriteLine("輸出至(輸出視窗)"); 將需要測試的內容輸出到視窗，不見得一定要下中斷點，經由圖解可以知道 Message Handlers 的流程，所以再收到 Request 到 Response 的過程，如果想要額外處理訊息，就會需要委派到別的訊息處理。比較需要留意的是當自行定義 task 回應之後，流程是無法到達 ctrl ，而純修改 Response ，只需要重新設定關係鏈結仍可以到 ctrl。如範例的 ApiKey，就可讓某些頁面必需有 ApiKey才能使用，這類型的工作就可以委派出去。

DelegatingHandler[] handlers = new DelegatingHandler[] {
 new MessageHandler3()
};

//需自行定義結束點，讓流程可以進行到 ctrl 。
var routeHandlers = HttpClientFactory.CreatePipeline(
 new HttpControllerDispatcher(config), handlers);

config.Routes.MapHttpRoute(
 name: "Route2",
 routeTemplate: "api2/{controller}/{id}",
 defaults: new { id = RouteParameter.Optional },
 constraints: null,
 handler: routeHandlers
);

6. Formats and Model Binding

MIME type 的結構解說，通常會有主(次)描述用來描述訊息內容的規格，如 text/html。所以，使用者可以自行定義所要描述訊息內容，再做序列化的處理。最後，對應不同平台做註冊的動作。Asp.Net 直接註冊再 WebApiConfig 裡面。

不使用第三方 Json

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.UseDataContractJsonSerializer = true;

以類別來說，預設會將所包含的屬性欄位，全序列化為 Json 格式，但可能有些屬性是不需要輸出，這時就可以使用 Newtonsoft.Json.JsonIgnore; [JsonIgnore]來做修飾。另一種則是使用 [DataContract]，則有使用到 [DataMember]，才會認定做序列化處理。XML 產生序列化的開關，仍是使用 [DataContract] 及 [DataMember]，而當 A 有 B 物件，B 有 A 物件的環狀結構。則需額外設定。

var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter;
json.SerializerSettings.PreserveReferencesHandling = Newtonsoft.Json.PreserveReferencesHandling.All;

最後的這隻類別，還滿不錯用的…連泛型都直接寫好了。收起來...

Content Negotiation

Accept: Which media types are acceptable for the response, such as “application/json,” “application/xml,” or a custom media type such as "application/vnd.example+xml"
Accept-Charset: Which character sets are acceptable, such as UTF-8 or ISO 8859-1.
Accept-Encoding: Which content encodings are acceptable, such as gzip.
Accept-Language: The preferred natural language, such as “en-us”.

Model 屬性驗證，簡單的來說，這類別裡面的屬性都可以拿來做驗證，例 PhoneAttribute 則為 [Phone] ，最後對應 ModelState.IsValid，而當驗證失敗時，針對錯誤的欄位做失敗處理。

7. OData

Install-Package Microsoft.AspNet.WebApi.OData
System.Web.Http.OData
EntitySetController<TEntity, TKey>
在 API 函式上增加 [Queryable] ，就有基本功能可支援。暫時還想不出硬要擴充出來的功能。

本來想繼續做些 Data Develop 部份的筆記，但看了一下，多到讓人完全動力不足阿...先小記吧!!

Data Developer Center

塵世打雜工

[ASP.NET] Creating Web APIs Note