使用 ASP.NET Core 建立 Web API 服務

.NET Core(ASP.NET Core)與之前的 ASP.NET MVC / ASP.NET Web API 兩套不同的 Framework 不同，ASP.NET Core 中的 MVC 整合了 Web API，現在要建立 API 或 Web 都將更為簡單，因為整合後的 ASP.NET Core MVC 基於相同的程式碼與管線(pipeline)。

開發環境

ASP.NET Core 的跨平台特性，使用開發工具與開發環境的選擇相當多元。

.NET Core SDK 安裝：

• .NET Core #Windows

安裝頁面有各平台(Windows, Linux, Mac, Docker)的安裝指南，照步驟安裝即可。

開發工具方面：

• Visual Studio 2015 Update 3 + .NET Core Tooling Preview 2 for Visual Studio 2015
• Visual Studio Code + C# for Visual Studio Code(Extensions)

使用 Windows 的開發者，地表最強的 Visual Studio 當然是最好的選擇，如果使用 MAC(Windows) 那 VS Code + C# 擴充套件後也不差。如果 Visual Studio 2015 Update 3 並安裝了最新的 .NET Core Tooling Preview 2 for Visual Studio 2015 ，那麼已包含 .NET Core SDK 的安裝。

如果 VS Code + C# 擴充套件，使用起來不是很順(例如，IntelliSense、提示加 using 等)，看一下 OmniSharp Log (檢視 → 切換輸出)是否正常。重開幾次 VS Code 看看。

測試工具：

• POSTMAN
• Fiddler

兩套測試工具都行，挑喜歡的用即可。

範本工具：

• generator-aspnet

安裝指令：

npm install -g yo 
npm install -g generator-aspnet
    

這是延伸自 yeoman 的範本產生器，在不使用 Visual Studio 的情況下，它會很有幫助。

以下範例，讓我們使用 VS Code 來走一次建立 ASP.NET Core - Web API 的過程。相同的過程，使用 Visual Studio 的體驗與以前沒有太大差異，更重要的是，使用 VS Code 可以讓我們更瞭解 .NET Core 運作流程(因為要下指令)，所以選擇使用指令與 VS Code 來進行實作。

ASP.NET Core - Web API 專案

我們透過 cmd.exe 下使用 yo aspnet 指令來建立 ASP.NET Core - Web API 專案。

Data Models

使用 VS Code 開啟專案資料夾，新增 Models 資料夾，新增 TodoItem 類別。

透過 VS Code 新增的檔案內容都是空白，這對記憶力是個不小的考驗。建立檔案這件事，generator-aspnet 也有想到。

yo aspnet:Class TodoItem

namespace corewebapi.Models
{
    public class TodoItem
    {
        public string Key { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

加入 Repository 類別

此範例沒有使用資料庫，我們使用 Repository 來進行資料層的封裝。

yo aspnet:Interface ITodoRepository

加前 CURD 對應的方法介面：

namespace corewebapi.Models
{
    public interface ITodoRepository
    {
        void Add(TodoItem item);
        IEnumerable<TodoItem> GetAll();
        TodoItem Find(string key);
        TodoItem Remove(string key);
        void Update(TodoItem item);
    }
}

新增 TodoRepository 類別以實作介面：

yo aspnet:Class TodoRepository

TodoRepository 類別：

namespace corewebapi.Models
{
    public class TodoRepository : ITodoRepository
    {
        private static ConcurrentDictionary<string, TodoItem> _todos = 
            new ConcurrentDictionary<string, TodoItem>();

        public TodoRepository()
        {
            Add(new TodoItem { Name = "Item1"});
        }
        public void Add(TodoItem item)
        {
            item.Key = Guid.NewGuid().ToString();
            _todos[item.Key] = item;
        }

        public TodoItem Find(string key)
        {
            TodoItem item;
            _todos.TryGetValue(key, out item);
            return item;
        }

        public IEnumerable<TodoItem> GetAll()
        {
            return _todos.Values;
        }

        public TodoItem Remove(string key)
        {
            TodoItem item;
            _todos.TryGetValue(key, out item);
            _todos.TryRemove(key, out item);
            return item;
        }

        public void Update(TodoItem item)
        {
            _todos[item.Key] = item;
        }
    }
}

註冊 Repository

ASP.NET Core 內建 DI (dependency injection) 機制，讓我們能在 Controller 被初始化時進行注入作業，使用 DI 之後，可大幅提升應用程式的可測試性。

我們要註冊 Repository 到 DI 容器中。開啟 Startup.cs ，先 Models 的參考：

using corewebapi.Models;

在 ConfigureServices 方法加入以下程式碼：

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services.
    services.AddMvc();

    // 註冊 repository 型別
    services.AddSingleton<ITodoRepository, TodoRepository>();
}

dotnet 指令

.NET Core SDK 新增 dotnet 指令，讓我們可以新增專案、套件還原、專案建置、發行專案、執行專案、測試專案，封裝為NuGet套件等。

dotnet 的新增專案會新增一個 Console - Hello World 專案，要改到能執行 ASP.NET Core 需要一些設置，所以我們選擇 yeoman 來快速建立範本。

dotnet -h 可以查詢指令相關參數。

.NET Command Line Tools (1.0.0-preview2-003121)
Usage: dotnet [host-options] [command] [arguments] [common-options]

Arguments:
  [command]             The command to execute
  [arguments]           Arguments to pass to the command
  [host-options]        Options specific to dotnet (host)
  [common-options]      Options common to all commands

Common options:
  -v|--verbose          Enable verbose output
  -h|--help             Show help

Host options (passed before the command):
  -v|--verbose          Enable verbose output
  --version             Display .NET CLI Version Number
  --info                Display .NET CLI Info

Common Commands:
  new           Initialize a basic .NET project
  restore       Restore dependencies specified in the .NET project
  build         Builds a .NET project
  publish       Publishes a .NET project for deployment (including the runtime)
  run           Compiles and immediately executes a .NET project
  test          Runs unit tests using the test runner specified in the project
  pack          Creates a NuGet package

依下面順序輸入執行：

1. dotnet restore
2. dotnet build

建置過程如果有錯誤，請依錯誤訊息進行排除。

記得在執行 dotnet build 之前，確定所有檔案已經存檔，筆者有好幾次都忘了存檔，然後跑不出正確結果，查程式碼查了半天又查不出來。想要怪東怪西時才發現自己是豬頭。

新增 Controller

在 Controllers 目錄下新增 TodoController：

yo aspnet:WebApiController TodoController

移除預設 API Action 程式碼，替換為下列程式碼：

namespace corewebapi.Controllers
{
    [Route("api/[controller]")]
    public class TodoController : Controller
    {
        public TodoController(ITodoRepository todoItems)
        {
            TodoItems = todoItems;
        }
        public ITodoRepository TodoItems { get; set; }
    }
}

這裡先定義一個空的 Controller，TodoItems 會透過前面定義的 DI 進行注入作業。

取得 Todo 清單

依照下列程式碼，可以取得 Todo 清單：

public IEnumerable<TodoItem> GetAll()
{
    return TodoItems.GetAll();
}

[HttpGet("{id}", Name = "GetTodo")]
public IActionResult GetById(string id)
{
    var item = TodoItems.Find(id);
    if (item == null)
    {
        return NotFound();
    }
    return new ObjectResult(item);
}

由屬性 [HttpGet] 與命名 GetXXX 可以得知，這些方法實作 HTTP Get 方法，透過 dotnet run 可以把 ASP.NET Core 專案執行起來，預設位置是 http://localhost:5000，進行 Get 方法測試：

• http://localhost:5000/api/todo
• http://localhost:5000/api/todo/{guid}

ObjectResult

GetAll 回傳一個 CLR 物件，ASP.NET Core MVC 自動序列化物件為 JSON 並將 JSON 寫入回應訊息的 Body 之中。

GetById 需回傳一個 IActionResult 型別，因為 GetById 有兩種不同的回傳型別的選擇。

• 如果找不到對應的 id，方法會回傳 404 狀態(NotFound).
• 如果成功，ObjectResult 回傳 200 狀態並回 JSON 寫入 Body 回傳。

ObjectResult 的繼承關係：

public class ObjectResult : ActionResult, IActionResult

完成CUD實作

前面我們完成 Read 的實作，現在往下進行 Create、Update、Delete 相關實作。

Create

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }
    TodoItems.Add(item);
    return CreatedAtRoute("GetTodo", new { controller = "Todo", id = item.Key }, item);
}

CreatedAtRoute 會建立一個狀態 201 的回應，這是為了符合 HTTP 的標準，也就為通知 Client 端新增資源位於那個位置。

Update

[HttpPut("{id}")]
public IActionResult Update(string id, [FromBody] TodoItem item)
{
    if (item == null || item.Key != id)
    {
        return BadRequest();
    }

    var todo = TodoItems.Find(id);
    if (todo == null)
    {
        return NotFound();
    }

    TodoItems.Update(item);
    return new NoContentResult();
}

Update 類似 Create，但它使用 HTTP PUT 方法，如果成功，依照 HTTP 標準要回傳狀態 204(No Content)。PUT 方法需要傳遞完整的 Update 實體，如果是部分更新，使用 HTTP PATCH。

Delete

[HttpDelete("{id}")]
public void Delete(string id)
{
    TodoItems.Remove(id);
}

void 回傳 狀態 204(No Content)，意思是，Client 收到 204 事件代表資源已經刪除或不存在。

所以有二個方向來思考：

• Delete 意思是"刪除已存在的資源"，如果不存在，回傳狀態 404。
• Delete 意思是"確定 item 不在集合裡"，如果 item 不存在集合，回傳狀態 204。

小結

以上的實例，故意沒有使用 Visual Studio / IIS Express 等常用的開發工具，使用 VS Code + C# + yo + dotnet 一樣可以開發與執行 ASP.NET Core Web API 服務。如果你覺得打 dotnet 指令太麻煩，VS Code 的偵錯，一樣可下中斷點，可以啟動 ASP.NET Core 都沒問題。

---

工商時間：ASP.NET Web API 2實戰訓練營 第二梯

如果各位是一位 REST API 的開發者，筆者在4月22日起，將利用三個週六時間為大家詳盡介紹REST、HTTP並透過微軟提出的ASP.NET Web API 2開發框架來實作整個RESTful API實戰開發，如果是對 RESTful API 開發有興趣的人可以參考ASP.NET Web API 2實戰訓練營 第二梯說明。