使用 ASP.NET Core 控制器创建 Web API

使用支持创建、读取、更新、删除 (CRUD) 操作的 ASP.NET Core 控制器创建 RESTful 服务。

学习目标

在本模块中，你将：

• 使用 ASP.NET Core 控制器创建 Web API 项目。
• 创建用于保存产品的内存数据库。
• 添加对 CRUD 操作的支持。
• 从命令 shell 测试 Web API 操作方法。

介绍

本模块介绍如何将 ASP.NET Core Web API 控制器与 .NET 和 C# 结合使用来创建跨平台 RESTful 服务。

本模块使用 .NET CLI（命令行接口）和 Visual Studio Code 进行本地开发。 学习完本模块后，你可以使用 Visual Studio (Windows) 和 Visual Studio for Mac (macOS) 等开发环境来应用其概念。 还可以通过 Visual Studio Code（Windows、Linux 和 macOS）将概念应用于持续开发。

示例方案

假设你是一家名为 Contoso Pizza 的披萨公司的雇员。 经理要求你为披萨库存管理开发一个 RESTful 服务，作为公司 Web 店面和移动应用程序的必备组件。 该服务必须支持添加、查看、修改和删除披萨类型；HTTP 谓词的标准化使用方式，也称为创建、读取、更新、删除 (CRUD)。

我们将执行哪些操作？

在本模块中，你将使用 ASP.NET Core 创建新的 Web API 应用程序，并了解如何从命令行运行和测试该应用程序。 然后，你将添加数据存储和新的 API 控制器。 最后，你将实现并测试用于在数据存储中创建、读取、更新和删除披萨的 API 方法。

主要目标是什么？

完成本课程后，你将能够使用 ASP.NET Core 创建新的 Web API 应用程序。还将了解如何创建可实现基本 CRUD 逻辑的 API 控制器。

ASP.NET Core 中的 REST

当你浏览网页时，Web 服务器将使用 HTML、CSS 和 JavaScript 与浏览器通信。 如果你与页面进行某种交互，例如提交登录窗体或选择购买按钮，浏览器会将信息发送回 Web 服务器。

同样，Web 服务器可以使用 Web 服务与各种各样的客户端（浏览器、移动设备、其他 Web 服务器等）通信。 API 客户端通过 HTTP 与服务器通信，两者都使用 JSON 或 XML 等数据格式来交换信息。 API 通常供单页应用程序 (SPA) 用于在 Web 浏览器中执行大部分用户界面逻辑。 与 Web 服务器的通信主要是通过 Web API 进行的。

REST：用于使用 HTTP 生成 API 的常见模式

表述性状态转移 (REST) 是一种用于生成 Web 服务的体系结构样式。 REST 请求是通过 HTTP 发出的。 它们使用 Web 浏览器用于检索网页和将数据发送到服务器的相同 HTTP 谓词。 谓词如下：

• GET：从 Web 服务检索数据。
• POST：在 Web 服务上创建新的数据项。
• PUT：更新 Web 服务上的数据项。
• PATCH：通过描述有关如何修改项的一组说明，更新 Web 服务上的数据项。 本模块中的示例应用程序不使用此谓词。
• DELETE：删除 Web 服务上的数据项。

遵循 REST 的 Web 服务 API 称为 RESTful API。 它们通过以下方法进行定义：

• 一个基 URI。
• HTTP 方法，如 GET、POST、PUT、PATCH 或 DELETE。
• 数据的媒体类型，例如 JavaScript 对象表示法 (JSON) 或 XML。

API 通常需要为几种不同但相关的事物提供服务。 例如，我们的披萨 API 可以管理披萨、客户和订单。 我们使用路由，以将 URI 映射到代码中的逻辑分区，从而将向 https://localhost:5000/pizza 发出的请求路由到 PizzaController，并将向 https://localhost:5000/order 发出的请求路由到 OrderController。

在 ASP.NET Core 中创建 API 的好处

借助 ASP.NET，可以使用相同的框架和模式来生成网页和服务。 这意味着可以在同一个项目中重用模型类和验证逻辑，甚至还可以并行为网页和服务提供服务。 此方法有很多优点：

• 简单的序列化：ASP.NET 设计用于提供新式 Web 体验。 终结点会自动将类序列化为格式正确的现成 JSON。 不需要特殊配置。 当然，你可以为具有独特要求的终结点自定义序列化。

• 身份验证和授权：出于安全原因，API 终结点内置了对行业标准 JSON Web 令牌 (JWT) 的支持。 基于策略的授权使你可以灵活地在代码中定义强大的访问控制规则。

• 与代码一起路由：ASP.NET 让你可以使用属性来定义与代码内联的路由和谓词。 请求路径、查询字符串和请求正文中的数据将自动绑定到方法参数。

• 默认使用 HTTPS：HTTPS 是新式专业 Web API 的一个重要组成部分。 它依赖于端到端加密来提供隐私保护，并有助于确保 API 调用不会在客户端和服务器之间被截获和更改。

  ASP.NET 提供对 HTTPS 的现成支持。 它会自动生成测试证书，并轻松导入该证书以启用本地 HTTPS，使你可以在发布应用程序之前安全地运行并调试应用程序。

与 .NET 应用共享代码和知识

可以使用 .NET 技能和生态系统，与使用 .NET 生成的其他应用（包括移动应用、Web 应用、桌面应用和服务）共享 Web API 的逻辑。

使用 .NET HTTP REPL 测试 Web API

当你开发传统网站时，你通常会在 Web 浏览器中查看和测试工作成果。 Web API 接受并返回数据而不是 HTML，因此 Web 浏览器不是最佳的 Web API 测试工具。

用于浏览 Web API 以及与其交互的最简单选项之一是 .NET HTTP REPL。 REPL 表示读取-求值-打印循环 (read-evaluate-print loop)。 这是一种简单而常用的交互式命令行环境构建方法。 在下一单元中，你将创建一个简单的 Web API，然后使用 .NET HTTP REPL 与其交互。

练习 - 创建 Web API 项目

此模块使用 .NET 6.0 SDK。 通过在首选终端中运行以下命令，确保你已安装 .NET 6.0：

dotnet --list-sdks

将显示类似于下面的输出：

3.1.100 [C:\program files\dotnet\sdk]
5.0.100 [C:\program files\dotnet\sdk]
6.0.100 [C:\program files\dotnet\sdk]

确保列出了以 6 开头的版本。 如果未列出任何版本或未找到命令，请安装最新的 .NET 6.0 SDK。

创建并浏览 Web API 项目

为了设置 .NET 项目以与 Web API 配合工作，我们将使用 Visual Studio Code。 Visual Studio Code 包含一个集成终端，这使创建新项目变得很简单。 如果你不想使用代码编辑器，可在终端中运行本模块中的命令。

1. 在 Visual Studio Code 中，选择“文件”>“打开文件夹”。

2. 在所选位置创建名为 “ContosoPizza” 的新文件夹，然后单击“选择文件夹”。

3. 从主菜单中选择“视图”>“终端”，以便从 Visual Studio Code 中打开集成终端。

4. 在终端窗口中，复制粘贴以下命令：