使用 ASP.NET Core 为本机移动应用创建后端服务

作者：James Montemagno

移动应用可与 ASP.NET Core 后端服务通信。 有关从 iOS 模拟器和 Android 仿真程序连接本地 Web 服务的说明，请参阅从 iOS 模拟器和 Android 仿真程序连接到本地 Web 服务。

查看或下载后端服务代码示例

本教程演示如何使用 ASP.NET Core 创建后端服务，以支持本机移动应用。 它使用 Xamarin.Forms TodoRest 应用作为其本机客户端，其中包括 Android、iOS、Windows 的单独本机客户端。 你可以遵循链接中的教程来创建本机应用（并安装必要的免费 Xamarin 工具），以及下载 Xamarin 示例解决方案。 Xamarin 示例包含一个 ASP.NET Core Web API 服务项目，使用本文中的 ASP.NET Core 应用替换（客户端无需进行任何更改）。

TodoREST 应用支持列出、添加、删除和更新待办事项。 每个项都有一个 ID、 Name（名称）、Notes（说明）以及一个指示该项是否已完成的属性 Done。

在上一示例中，项目的主视图列出了每个项的名称，并使用复选标记指示其是否已完成。

点击 + 图标打开“添加项”对话框：

点击主列表屏幕上的项将打开一个编辑对话框，在其中可以修改项的名称、 说明以及是否完成，或删除项目：

若要使用在你计算机上运行的下一节创建的 ASP.NET Core 应用对其进行测试，请更新应用的 RestUrl 常量。

Android 模拟器不在本地计算机上运行，而是使用环回 IP (10.0.2.2) 与本地计算机进行通信。 使用 Xamarin.Essentials DeviceInfo 检测正在运行的操作系统，以使用正确的 URL。

转到 TodoREST 项目，并打开 Constants.cs 文件。 Constants.cs 文件包含以下配置。

可以选择性地将 Web 服务部署到 Azure 等云服务并更新 RestUrl。

在 Visual Studio 中创建一个新的 ASP.NET Core Web 应用程序。 选择 Web API 模板。 将项目命名为 TodoAPI。

该应用应响应向端口 5000 发出的所有请求，包括我们移动客户端的明文 HTTP 流量。 更新 Startup.cs，使 UseHttpsRedirection 不在开发中运行：

注意

直接运行应用，而不是在 IIS Express 后面。 IIS Express 将默认忽略非本地请求。 从命令提示符处运行 dotnet run，或从 Visual Studio 工具栏中的“调试目标”下拉列表中选择应用名称配置文件。

添加一个模型类来表示待办事项。 使用 [Required] 属性标记必需字段：

API 方法需要通过某种方式处理数据。 使用原始 Xamarin 示例所用的 ITodoRepository 接口：

在此示例中，该实现仅使用一个专用项集合：

在 Startup.cs 中配置实现：

在项目中添加新控制器 TodoItemsController。 它应该从 ControllerBase 继承。 添加 Route 属性以指示控制器处理针对以 api/todoitems 开头的路径发出的请求。 路由中的 [controller] 标记会被控制器的名称代替（省略 Controller 后缀），这对全局路由特别有用。 详细了解 路由。

控制器需要 ITodoRepository 才能正常运行；通过控制器的构造函数请求该类型的实例。 在运行时，将使用框架对依赖关系注入的支持来提供此实例。

此 API 支持四个不同的 HTTP 谓词来执行对数据源的 CRUD（创建、读取、更新、删除）操作。 其中最简单的是读取操作，它对应于 HTTP GET 请求。

你可以使用各种工具来测试 API 方法。 在本教程中，将使用以下开源命令行工具：

curl 已在 macOS 中预安装，可直接在 macOS 终端应用程序中使用。 有关安装 curl 的详细信息，请参阅官方 curl 网站。

jq 可以在终端中使用 Homebrew 安装：

使用以下命令安装 Homebrew（如果尚未安装）：

按照安装程序提供的说明进行操作。

通过以下命令使用 Homebrew 安装 jq：

有关 Homebrew 和 jq 安装的详细信息，请参阅 Homebrew 和 jq。

curl 会随 Windows 10 版本 1802 或更高版本一起安装。 有关安装 curl 的详细信息，请参阅官方 curl 网站。

在 PowerShell 或命令提示符中使用以下命令安装 jq：

PowerShell 或命令提示符关闭并重启后，jq 命令将可用。

有关 jq 安装的更多详细信息，请参阅 jq。

要请求项列表，可对 List 方法使用 GET 请求。 [HttpGet] 方法的 List 属性指示此操作应仅处理 GET 请求。 此操作的路由是在控制器上指定的路由。 你不一定必须将操作名称用作路由的一部分。 你只需确保每个操作都有唯一的和明确的路由。 路由属性可以分别应用在控制器和方法级别，以此生成特定的路由。

在终端中，调用以下 curl 命令：

注意

Windows PowerShell 5.1 会将 curl 识别为 Invoke-WebRequst 的别名。 若要改用 curl.exe，请键入 & 运算符，然后键入 curl.exe 的完整路径。 通过在命令提示符中键入 where curl 来查找 curl.exe 的完整路径。 例如，如果 curl.exe 的完整路径为 C:\Windows\System32\curl.exe， 那么请使用 & 'C:\Windows\System32\curl.exe' --help，而不是键入命令 curl --help。 PowerShell 7 使用 curl 作为 curl.exe 的命令，因此不需要完整路径。

在 PowerShell 中，调用以下 curl 命令：

前面的 curl 命令包含以下组成部分：

List 方法将返回一个 200 OK 响应代码和所有 Todo 项，并将起序列化为 JSON：

按照约定，创建新数据项将映射到 HTTP POST 谓词。 Create 方法具有应用于它的 [HttpPost] 属性，并接受 TodoItem 实例。 由于 item 参数在 POST 的正文中传递，因此该参数会指定 [FromBody] 属性。

在该方法中，会检查项的有效性和之前是否存在于数据存储，并且如果没有任何问题，则使用存储库添加。 检查 ModelState.IsValid 将执行 模型验证，应该在每个接受用户输入的 API 方法中执行此步骤。

该示例使用包含传递给移动客户端的错误代码的 enum：

在终端中，使用 POST 谓词调用以下 curl 命令，并在请求正文中以 JSON 格式提供新对象来测试添加新项的表现。

前面的 curl 命令包括以下选项：

该方法返回在响应中新建的项。

修改记录可通过 HTTP PUT 请求完成。 除了此更改之外，Edit 方法几乎与 Create 完全相同。 如果未找到相应记录，Edit 操作将返回 NotFound (404) 响应。

若要使用 curl 进行测试，请将谓词更改为 PUT。 在请求正文中指定要更新的对象数据。

为了与预先存在的 API 保持一致，此方法在成功时返回 NoContent (204) 响应。

删除记录可以通过向服务发出 DELETE 请求并传递要删除项的 ID 来完成。 与更新一样，请求的项不存在时会收到 NotFound 响应。 否则，成功的请求将返回 NoContent (204) 响应。

请将 HTTP 谓词更改为 DELETE 并在 URL 末尾追加要删除的数据对象的 ID，以使用 curl 进行测试。 请求正文中不需要任何内容。

目前，示例应用公开了整个 TodoItem 对象。 生产应用通常使用模型的子集来限制输入和返回的数据。 这背后有多种原因，但安全性是主要原因。 模型的子集通常称为数据传输对象 (DTO)、输入模型或视图模型。 本文使用的是 DTO。

DTO 可用于：

要演示 DTO 方法，请参阅防止过度发布

开发应用的后端服务时，需要制定一组一致的约定或策略来处理跨领域问题。 例如，在上面所示的服务中，未找到请求的特定记录时会收到 NotFound 响应，而不是 BadRequest 响应。 同样，对于此服务，传递模型绑定类型的命令始终检查 ModelState.IsValid 并为无效的模型类型返回 BadRequest。

一旦为 Api 指定通用策略，一般可以将其封装在 Filter（筛选器）。 详细了解 如何封装 ASP.NET Core MVC 应用程序中的通用 API 策略。