【转】asp.net Core 系列【二】—— 使用 ASP.NET Core 和 VS2017 for Windows 创建 Web API

2021-10-24 23:32:42

在本教程中，将生成用于管理“待办事项”列表的 Web API。不会生成 UI。

概述

以下是将创建的 API：

API	描述	请求正文	响应正文
GET /api/todo	获取所有待办事项	无	待办事项的数组
GET /api/todo/{id}	按 ID 获取项	无	待办事项
POST /api/todo	添加新项	待办事项	待办事项
PUT /api/todo/{id}	更新现有项	待办事项	无
DELETE /api/todo/{id}	删除项	无	无

下图显示了应用的基本设计。

客户端使用的是 Web API（移动应用、浏览器等）。在本教程中，我们不编写客户端，而使用 Postman 或 curl 来测试应用。
模型是表示应用程序中的数据的对象。在此示例中，唯一的模型是待办事项。模型表示为 C# 类，也称为 Plain Old C# Object (POCO)。
控制器是处理 HTTP 请求并创建 HTTP 响应的对象。此应用将有一个控制器。
为了简化教程，应用不会使用永久数据库。示例应用将待办事项存储在内存数据库中。

先决条件

安装以下组件：

.NET Core 2.0.0 SDK 或更高版本。
已安装 ASP.NET 和 Web 开发工作负载的 Visual Studio 2017 15.3 版或更高版本。

请参阅此 PDF 了解有关 ASP.NET Core 1.1 版本的信息。

创建项目

在 Visual Studio 中，选择“文件”菜单 >“新建” > “项目”。

选择“ASP.NET Core Web 应用程序(.NET Core)”项目模板。将此项目命名为 TodoApi ，然后选择“确定”。

在“新建 ASP.NET Core Web 应用程序 - TodoApi”对话框中，选择“Web API”模板。选择“确定”。请不要选择“启用 Docker 支持”。

启动应用

在 Visual Studio 中，按 CTRL+F5 启动应用。 Visual Studio 启动浏览器并导航到 http://localhost:port/api/values，其中“端口”是随机选择的端口号。 Chrome、Edge 和 Firefox 将显示以下内容：

复制

["value1","value2"]

添加模型类

模型是表示应用程序中的数据的对象。在此示例中，唯一的一个模型是待办事项。

添加名为“Models”的文件夹。在解决方案资源管理器中，右键单击项目。选择“添加” > “新建文件夹”。将文件夹命名为“Models”。

注意：模型类可位于项目的任意位置，但按照惯例会使用“Models”文件夹。

添加 TodoItem 类。右键单击“Models”文件夹，然后选择“添加” > “类”。将此类命名为 TodoItem，然后选择“添加”。

将生成的代码替换为以下内容：

C#复制

namespace TodoApi.Models

{

    public class TodoItem

    {

        public long Id { get; set; }

        public string Name { get; set; }

        public bool IsComplete { get; set; }

    }

}

创建 TodoItem 时，数据库将生成 Id。

创建数据库上下文

数据库上下文是为给定数据模型协调实体框架功能的主类。此类由 Microsoft.EntityFrameworkCore.DbContext 类派生而来。

添加 TodoContext 类。右键单击“Models”文件夹，然后选择“添加” > “类”。将此类命名为 TodoContext，然后选择“添加”。

将生成的代码替换为以下内容：

C#复制

using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models

{

    public class TodoContext : DbContext

    {

        public TodoContext(DbContextOptions<TodoContext> options)

            : base(options)

        {

        }

        public DbSet<TodoItem> TodoItems { get; set; }

    }

}

注册数据库上下文

若要将数据库上下文注入到控制器中，需要将它注册到依赖关系注入容器。使用依赖关系注入的内置支持将数据库上下文注册到服务容器。使用以下内容替换 Startup.cs 文件的内容：

C#复制

using Microsoft.AspNetCore.Builder;

using Microsoft.EntityFrameworkCore;

using Microsoft.Extensions.DependencyInjection;

using TodoApi.Models;

namespace TodoApi

{

    public class Startup

    {

        public void ConfigureServices(IServiceCollection services)

        {

            services.AddDbContext<TodoContext>(opt => opt.UseInMemoryDatabase("TodoList"));

            services.AddMvc();

        }

        public void Configure(IApplicationBuilder app)

        {

            app.UseMvc();

        }

    }

}

前面的代码：

删除未使用的代码。
指定将内存数据库注入到服务容器中。

添加控制器

在解决方案资源管理器中，右键单击“控制器”文件夹。选择“添加” > “新建项”。在“添加新项”对话框中，选择“Web API 控制器类”模板。将此类命名为 TodoController。

将生成的代码替换为以下内容：

C#复制

using System.Collections.Generic;

using Microsoft.AspNetCore.Mvc;

using TodoApi.Models;

using System.Linq;

namespace TodoApi.Controllers

{

    [Route("api/[controller]")]

    public class TodoController : Controller

    {

        private readonly TodoContext _context;

        public TodoController(TodoContext context)

        {

            _context = context;

            if (_context.TodoItems.Count() == 0)

            {

                _context.TodoItems.Add(new TodoItem { Name = "Item1" });

                _context.SaveChanges();

            }

        }

    }

}

前面的代码：

定义空控制器类。在接下来的部分中，我们将添加方法来实现 API。
构造函数使用依赖关系注入将数据库上下文 (TodoContext) 注入到控制器中。数据库上下文将在控制器中的每个 CRUD 方法中使用。
构造函数将一个项（如果不存在）添加到内存数据库。

获取待办事项

若要获取待办事项，请将下面的方法添加到 TodoController 类中。

C#复制

[HttpGet]

public IEnumerable<TodoItem> GetAll()

{

    return _context.TodoItems.ToList();

}

[HttpGet("{id}", Name = "GetTodo")]

public IActionResult GetById(long id)

{

    var item = _context.TodoItems.FirstOrDefault(t => t.Id == id);

    if (item == null)

    {

        return NotFound();

    }

    return new ObjectResult(item);

}

这些方法实现两种 GET 方法：

GET /api/todo
GET /api/todo/{id}

以下是 GetAll 方法的 HTTP 响应示例：

复制

HTTP/1.1 200 OK

   Content-Type: application/json; charset=utf-8

   Server: Microsoft-IIS/10.0

   Date: Thu, 18 Jun 2015 20:51:10 GMT

   Content-Length: 82

   [{"Key":"1", "Name":"Item1","IsComplete":false}]

稍后在本教程中将演示如何使用 Postman 或 curl 查看 HTTP 响应。

路由和 URL 路径

[HttpGet] 特性指定 HTTP GET 方法。每个方法的 URL 路径构造如下所示：

在控制器的路由特性中采用模板字符串：

C#复制

namespace TodoApi.Controllers

{

    [Route("api/[controller]")]

    public class TodoController : Controller

    {

        private readonly TodoContext _context;

将“[Controller]”替换为控制器的名称，即在控制器类名称中去掉“Controller”后缀。对于此示例，控制器类名称为“Todo”控制器，根名称为“todo”。 ASP.NET Core 路由不区分大小写。
如果 [HttpGet] 特性具有路由模板（如 [HttpGet("/products")]），则将它追加到路径。此示例不使用模板。有关详细信息，请参阅使用 Http [Verb] 特性的特性路由。

在 GetById 方法中：

C#复制

[HttpGet("{id}", Name = "GetTodo")]

public IActionResult GetById(long id)

"{id}" 是 todo 项的 ID 的占位符变量。调用 GetById 时，它会将 URL 中“{id}”的值分配给方法的 id 参数。

Name = "GetTodo" 创建一个命名的路由，使你能够 HTTP 响应中链接到此路由。稍后将使用示例进行解释。有关详细信息，请参阅路由到控制器操作。

返回值

GetAll 方法返回 IEnumerable。 MVC 自动将对象序列化为 JSON，并将 JSON 写入响应消息的正文中。在假设没有未经处理的异常的情况下，此方法的响应代码为 200。（未经处理的异常将转换为 5xx 错误。）

相反，GetById 方法返回多个常规的 IActionResult 类型，它表示一系列返回类型。 GetById 具有两个不同的返回类型：

如果没有任何项与请求的 ID 匹配，此方法将返回 404 错误。此通过返回 NotFound 来实现。
否则，此方法将返回具有 JSON 响应正文的 200。此通过返回 ObjectResult 来完成

启动应用

在 Visual Studio 中，按 CTRL+F5 启动应用。 Visual Studio 启动浏览器并导航到 http://localhost:port/api/values，其中“端口”是随机选择的端口号。如果使用的是 Chrome、Edge 或 Firefox，则会显示数据。如果使用的是 IE，IE 将提示你打开或保存 values.json 文件。导航到刚刚创建的 Todo 控制器 http://localhost:port/api/todo。

实现其他的 CRUD 操作

我们将向控制器添加 Create、Update 和 Delete 方法。这些是主题的变体，因此在这里只提供代码并突出显示主要的差异。添加或更改代码后生成项目。

创建

C#复制

[HttpPost]

public IActionResult Create([FromBody] TodoItem item)

{

    if (item == null)

    {

        return BadRequest();

    }

    _context.TodoItems.Add(item);

    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);

}

这是 HTTP POST 方法，由 [HttpPost] 特性指示的。 [FromBody] 特性告诉 MVC 从 HTTP 请求正文获取待办事项的值。

CreatedAtRoute 方法返回 201 响应，这是在服务器上创建新资源的 HTTP POST 方法的标准响应。 CreatedAtRoute 还会向响应添加位置标头。位置标头指定新建的待办事项的 URI。请参阅 10.2.2 201 已创建。

使用 Postman 发送创建请求

将 HTTP 方法设置为 POST
选择“正文”单选按钮
选择“原始”单选按钮
将类型设置为 JSON
在键值编辑器中，输入一个待办事项，例如

JSON复制

{

    "name":"walk dog",

    "isComplete":true

}

选择“发送”
选择下窗格中的“标头”选项卡，然后复制“位置”标头：

可以使用此位置标头 URI 访问刚刚创建的资源。重新调用创建名为 "GetTodo" 路由时使用的 GetById 方法：

C#复制

[HttpGet("{id}", Name = "GetTodo")]

public IActionResult GetById(long id)

更新

C#复制

[HttpPut("{id}")]

public IActionResult Update(long id, [FromBody] TodoItem item)

{

    if (item == null || item.Id != id)

    {

        return BadRequest();

    }

    var todo = _context.TodoItems.FirstOrDefault(t => t.Id == id);

    if (todo == null)

    {

        return NotFound();

    }

    todo.IsComplete = item.IsComplete;

    todo.Name = item.Name;

    _context.TodoItems.Update(todo);

    _context.SaveChanges();

    return new NoContentResult();

}

Update 与 Create 类似，但是使用的是 HTTP PUT。响应是 204（无内容）。根据 HTTP 规范，PUT 请求需要客户端发送整个更新的实体，而不仅仅是增量。若要支持部分更新，请使用 HTTP PATCH。

删除

C#复制

[HttpDelete("{id}")]

public IActionResult Delete(long id)

{

    var todo = _context.TodoItems.FirstOrDefault(t => t.Id == id);

    if (todo == null)

    {

        return NotFound();

    }

    _context.TodoItems.Remove(todo);

    _context.SaveChanges();

    return new NoContentResult();

}

响应是 204（无内容）。

码农公寓

概述

先决条件

创建项目

启动应用

添加模型类

创建数据库上下文

注册数据库上下文

添加控制器

获取待办事项

路由和 URL 路径

返回值

启动应用

实现其他的 CRUD 操作

创建

使用 Postman 发送创建请求

更新

删除

相关文章