---

2018 年 3 月

第 33 卷，第 3 期

本文章是由機器翻譯。

技術最前線 - ASP.NET Core 中的 REST 與 Web API

由Dino Esposito |2018 年 3 月

從來風扇做獨立架構的 ASP.NET Web api，我無法難以想像專案我使用的位置。本身中的架構是無法或不必要的 not。我剛發現的商務價值，它會實際傳遞是，大部分的情況下，最少。相反地，我辨識它在某些清除 Microsoft 提供給更新 ASP.NET 執行階段管線基礎投入時間的符號。整體來說，我要將哪些今天已變成 ASP.NET Core 和 ASP.NET Core 的具體來說，新版執行階段環境的概念證明視為 ASP.NET Web API。

Web API 主要是用來進行建置 RESTful API 輕鬆且方便在 ASP.NET 中引進。這篇文章是關於如何達成相同結果 — 建立 rest 式 API，在 ASP.NET Core。

在典型的 ASP.NET Web API 的額外成本

ASP.NET Web API 建置周圍維持開啟 Web 介面的.NET (OWIN) 規格，它用來分離 Web 伺服器裝載的 Web 應用程式的原則。.NET 空間中引進的 OWIN 標示轉折點，其中的質疑 IIS 和 ASP.NET 的緊密整合。在 ASP.NET Core，已完全放棄該緊密結合。

使用 ASP.NET Web API framework 建置的任何網頁外觀會依賴基礎主機 Web 伺服器會使用標準 OWIN 介面對話方塊完全重新撰寫管線。棒的是，ASP.NET Web 應用程式開發介面不是獨立應用程式。若要變成可供呼叫端必須負責接聽某些主機環境設定連接埠、 擷取連入要求並將其分派到 Web API 管線。

在 Windows 服務，或在自訂的主控台應用程式中實作適當的 OWIN 介面，可裝載的 Web API 應用程式。它也可由裝載的傳統 ASP.NET 應用程式是否以 Web Form 或 ASP.NET MVC 為目標。過去幾年來，在傳統的 ASP.NET MVC 應用程式中裝載 Web API 證明很常見的案例，但其中一個最有效未經處理的效能和記憶體耗用量方面。

做為圖 1顯示，每當您排列 ASP.NET MVC 應用程式中的 Web API 外觀，三個架構最後住並存，每個單一的 Web API 要求的處理。ASP.NET MVC 應用程式主機會封裝在住之上 system.web—the 原始 ASP.NET 執行階段環境的 HTTP 處理常式。在該 — 佔用額外的記憶體 — 您有 Web API OWIN 管線。

圖 1 所涉及的傳統 ASP.NET Web API 應用程式的架構

在此情況下，導入的獨立伺服器的 Web 架構的願景，大幅放寬條件約束停留相容於現有的 ASP.NET 管線。因此，Web API 的全新和 REST 易記設計不會發揮完整潛能由於舊版 system.web 組件。純效能的觀點而言，只有某些邊緣實際使用情況下，以構成 Web API 的使用。

Web 應用程式開發介面的有效使用案例

Web API 是作用中的 OWIN 原則的最高設定檔範例。背後的伺服器應用程式會擷取並將內送要求轉送執行 Web 應用程式開發介面程式庫。此主機可以是 Microsoft 堆疊 (Web Form、 ASP.NET MVC) 上的傳統 Web 應用程式，或是它可以是主控台應用程式或 Windows 服務。

在任何情況下，必須先將被授與的程式碼能夠使用 Web 應用程式開發介面的接聽程式 dialoging 精簡圖層的應用程式。

System.web 組件的相依性的根目錄裝載 Web API Web 環境之外移除，因此神奇地發出要求管線為精實和表示為所需。

這會導致 ASP.NET Core 小組建置 ASP.NET Core 管線的關鍵點。Web API 的理想主控條件是幾乎任何 ASP.NET Core 應用程式的理想主控條件已重新撰寫。此內嵌 HTTP 伺服器公開的合約的介面啟用完全新的管線抹除 system.web 組件和可裝載背後的相依性 — IServer 介面。

OWIN 規格和 Katana，ASP.NET 環境中，它的實作 ASP.NET Core 扮演任何角色。但是，這些平台的體驗成熟的技術願景 （特別是使用 Web 應用程式開發介面的邊緣案例），其中固然透過 ASP.NET Core 眩目新管線。

有趣的事是，一旦已重新設計整個 ASP.NET 管線 — 深自治組織所導致的理想的裝載環境的 Web 應用程式開發介面，該相同的 Web API，為不同的架構不適用。在新的 ASP.NET Core 管線沒有需要一個應用程式模型-MVC 應用程式模型-根據控制器，而控制器類別是比傳統的 ASP.NET MVC，因此將舊的 ASP.NET 控制器和 Web 的函式中的位元豐富應用程式開發介面控制站。

擴充的 ASP.NET Core 控制站

在 ASP.NET Core，您使用控制器類別是否想要提供 HTML 或任何其他類型的回應，如 JSON 或 PDF。已加入新的動作結果型別一大堆進行建置 RESTful 簡單、 方便的介面。內容交涉完全支援任何控制器的類別，並在動作啟動程式基礎結構已經確定格式化的協助程式。如果您想要建立 HTTP 端點會公開 Web API，您所要做為建置一般控制器類別，如下所示：

public class ApiController : Controller
{
  // Your methods here
}

控制器類別的名稱是任意的。雖然在 URL 中的某處有 /api 需要為了清楚起見，則為方式不需要。您可以讓 /api 中叫用的兩個如果您使用傳統的路由 （ApiController 類別） 將 Url 對應至動作方法，或如果您使用屬性路由的 URL。在我的個人看來，屬性路由最好可能是因為它可讓您公開多個端點，其中包含相同的 /api 項目，在 URL 中，同時在不同、 任意命名控制器類別中所定義。

控制器類別中 ASP.NET Core 在傳統的 ASP.NET MVC 中，有更多的功能比類別以及其關聯到建置 RESTful Web API 的大部分的擴充功能。首先和最重要的所有 ASP.NET Core 控制站都支援內容交涉。內容交涉指的是無訊息的呼叫端和實際的格式傳回資料的相關的 API 之間進行交涉。

內容交涉也不會發生所有的時間，只要每個要求。只有當內送的要求含有通告呼叫者是能夠了解的 MIME 類型 Accept HTTP 標頭，它會發生。在此情況下，ASP.NET Core 基礎結構經歷列在標頭內容，直到其中一個格式器所存在的應用程式的目前組態中找到的類型。如果找到相符的格式器清單中的型別，則使用預設的 JSON 格式器時，就像這樣：

[HttpGet]
public ObjectResult Get(Guid id)
{
  // Do something here to retrieve the resource data
  var data = FindResourceDataInSomeWay(id);
  return Ok(data);
}

內容交涉的另一個值得注意的層面是，雖然它不會產生序列化程序沒有 Accept HTTP 標頭中的任何變更，技術上觸發時才傳送回由控制站的回應是型別 ObjectResult。最常見的方式，來傳回 ObjectResult 動作結果型別會序列化透過確定方法的回應。請務必注意，如果您序列化說，透過控制站回應，Json 方法中，沒有交涉會曾經發生不論傳送的標頭。可以透過 AddMvc 方法的選項以程式設計方式加入支援輸出格式器。以下為範例：

services.AddMvc(options =>
{
  options.OutputFormatters.Add(new PdfFormatter());
});

在此範例中，示範類別 PdfFormatter 內部包含支援的 MIME 類型，它可以處理的清單。

請注意，使用 [產生屬性您覆寫內容交涉，如下所示：

[Produces("application/json")]
public class ApiController : Controller
{
  // Action methods here
}

您可以在控制器或方法層級，套用的輸出 ObjectResult 一律要序列化的格式輸入的屬性，不論 Accept HTTP 標頭所指定的強制產生屬性。

如需有關如何格式化回應的控制器方法的詳細資訊，您可能想要查看在內容bit.ly/2klDgdY。

REST 導向的動作結果型別

Web API 是否比較好的方式設計的其餘部分是爭議高點。一般情況下，它是安全夠來電的其餘部分方法根據已知的一組規則，在這方面很多標準。基於這個理由，通常建議屬於企業商務的公用 api。API 是否僅為有限的數目的用戶端 — 大部分相同控制下的應用程式開發介面建立者 — 則沒有實際的商務差異之間使用 REST 設計路由或更加鬆散的遠端程序呼叫 (RPC) 方法不存在。

在 ASP.NET Core 沒有什麼不同且專用的 Web API 架構。不會只是控制器的動作結果和 helper 方法的其集合。如果您想要建立 Web API，恕不另行通知，您只傳回 JSON、 XML 或其他任何。如果您想要建立 rest 式 API，您只出現熟悉另一組動作結果和 helper 方法。圖 2呈現 ASP.NET Core 控制站可以傳回的新動作結果型別。在 ASP.NET Core 動作結果型別會是實作 IActionResult 介面的類型。 

圖 2 Web 應用程式開發介面相關的動作結果型別

類型	描述
AcceptedResult	傳回 202 狀態碼。此外，它會傳回要檢查的持續狀態要求的 URI。URI 會儲存在位置標頭。
BadRequestResult	會傳回 400 狀態碼。
CreatedResult	會傳回 201 狀態碼。此外，它會傳回建立的資源 URI，儲存在位置標頭。
NoContentResult	會傳回 204 狀態程式碼和 null 內容。
OkResult	傳回 200 狀態碼。
UnsupportedMediaTypeResult	傳回 415 狀態碼。

請注意一些索引中的型別圖 2來自朋友的類型，可提供相同的核心功能，但有些微的差異。例如，除了 AcceptedResult 和 CreatedResult，您會發現 xxxAtActionResult 和 xxxAtRouteResult 型別。差異在於型別如何 express 監視接受作業的狀態和剛才建立的資源位置的 URI。XxxAtActionResult 類型表示為控制器和動作的字串之成對的 URI，而 xxxAtRouteResult 類型則使用路由名稱。

OkObjectResult 和 BadRequestObjectResult，相反地，具有 xxxObjectResult 變化。差別在於，物件的結果類型也可讓您將物件附加至回應。因此 OkResult 只會將 200 狀態碼，但 OkObjectResult 200 狀態碼，並且附加您選擇的物件。使用這項功能的常見方式，就會傳回不正確的要求處理時，偵測到的錯誤以更新 ModelState 字典。

另一個有趣的差異並沒有 NoContentResult 和 EmptyResult 之間。兩者都傳回空的回應，但 NoContentResult 設定的狀態碼 204，而 EmptyResult 設定 200 狀態碼。這雖如此，建置 RESTful API 就是定義資源的所有正在執行作業和排列一組使用的 HTTP 動詞命令來執行一般的管理作業的呼叫。您使用 GET 讀取，PUT 更新，以建立新的資源和刪除] 以移除現有的文章。圖 3顯示 RESTful 介面周圍的範例資源類型的基本架構，因為它會造成從 ASP.NET Core 類別。

圖 3 常見 RESTful 的基本架構程式碼

[HttpGet]
public ObjectResult Get(Guid id)
{
  // Do something here to retrieve the resource
  var res = FindResourceInSomeWay(id);
  return Ok(res);
}
[HttpPut]
public AcceptedResult UpdateResource(Guid id, string content)
{
  // Do something here to update the resource
  var res = UpdateResourceInSomeWay(id, content);
  var path = String.Format("/api/resource/{0}", res.Id);
  return Accepted(new Uri(path));  
}
[HttpPost]
public CreatedResult AddNews(MyResource res)
{
  // Do something here to create the resource
  var resId = CreateResourceInSomeWay(res);
  // Returns HTTP 201 and sets the URI to the Location header
  var path = String.Format("/api/resource/{0}", resId);
  return Created(path, res);
}
[HttpDelete]
public NoContentResult DeleteResource(Guid id)
{
  // Do something here to delete the resource
  // ...
  return NoContent();
}

如果您有興趣進一步來瀏覽 ASP.NET Core 建置 Web API 控制器的實作，看看 [GitHub] 資料夾在bit.ly/2j4nyUe。

總結

Web API 現在是大多數應用程式中的常見項目。它用來提供資料給 Angular 或 MVC 前端，以及提供服務給行動或桌面應用程式。在 ASP.NET Core 內容中，詞彙"Web API 」，最後會達到其真正的意義不模稜兩可，或需要進一步解釋其分佈。Web API 是組成的公開通常 （但不是一定） 會傳回 JSON 或 XML 資料至呼叫端的 HTTP 端點的數字的程式設計介面。控制器中的基礎結構 ASP.NET Core 完全支援這個願景改寫的實作與新的動作結果型別。建置在 ASP.NET 中的 RESTful API 從未如此輕鬆 ！

---

Dino Esposito是作者"MICROSOFT.NET:架構的企業應用程式 」 (Microsoft Press，2014年) 和"程式設計 ASP.NET Core"(Microsoft Press，2018年)。Pluralsight 作者及開發人員主張在 JetBrains，Esposito 共用 Twitter 上的軟體願景： @despos。

非常感謝下列 Microsoft 技術專家檢閱這篇文章：Ugo Lattanzi

---

MSDN Magazine 論壇中的這篇文章的討論