ASP.NET Core 创建 API（第一日）：入门和 ASP.NET Core 请求管道

• 下载 PDF 文章 - 1.4 MB
• 下载源代码 - 152.4 KB

目录

• 目录
• 引言
• 必备组件
• 路线图
• ASP.NET Core
• 安装 ASP.NET Core
• .NET Core 项目及其结构
• ASP.NET Core 中间件和请求管道
• 配置请求管道
• 结论
• Github 上的源代码
• 参考文献
• 其他系列

引言

本系列关于使用 ASP.NET Core 学习 API 的教程将重点介绍 ASP.NET Core 的功能、请求管道、如何创建 ASP.NET Core API 以及如何使用 Entity Framework Core。我们将尝试使用 ASP.NET Core 创建 API，并尝试通过 Entity Framework Core 与数据库进行通信以执行简单的 CURD 操作。该系列将包含后续文章，详细介绍该主题，并最终完成一个功能性应用程序。

先决条件

既然我们从零开始，我们预计本文/系列的读者对 ASP.NET Core 是新手，并且并不真正了解它的全部内容。话虽如此，我们将坚持我们的目标，从头开始学习 ASP.NET Core。我们将使用 Visual Studio 2017 企业版来完成整个系列，但也可以使用 Visual Studio 2015 或 Visual Studio 的社区版。ASP.NET Core 应用程序最棒的地方在于，它们也可以使用 Visual Studio Code 进行开发，Visual Studio Code 可以在 OS X 和 Linux 上运行。为了检查 API 的请求和响应，我们将使用一个名为 Postman 的工具。它免费且易于使用。或者，您也可以选择自己喜欢的工具，例如 Fiddler。

路线图

我们将遵循路线图，详细学习和涵盖 ASP.NET Core 的所有方面。以下是涵盖整个系列的路线图或文章列表。

1. ASP.NET Core 创建 API（第一日）：入门和 ASP.NET Core 请求管道
2. ASP.NET Core 创建 API（第二日）：在 ASP.NET Core 中创建 API 并返回资源
3. ASP.NET Core 创建 API（第三日）：在 ASP.NET Core API 中处理 HTTP 状态码、序列化器设置和内容协商
4. ASP.NET Core 创建 API（第四日）：理解 ASP.NET Core API 中的资源
5. ASP.NET Core 创建 API（第五日）：ASP.NET Core API 中的控制反转和依赖注入
6. ASP.NET Core 创建 API（第六日）：Entity Framework Core 入门
7. ASP.NET Core 创建 API（第七日）：ASP.NET Core API 中的 Entity Framework Core

ASP.NET Core

微软一直以来都热衷于提供一些开源、跨平台且或多或少与移动性相关的产品。因此，总的来说，ASP.NET Core 就是对这种热衷的回应。它是一个开源框架，具有跨平台功能，可用于构建基于云的、与 Internet 相连的应用程序。您可以开发任何类型的应用程序，例如，普通的 Web 应用程序、API 或基于移动的应用程序。其开源和跨平台的特性使开发人员可以为 Windows、Mac 和 Linux 开发应用程序，也可以贡献代码或根据需要自定义现有代码，并跨越平台障碍。ASP.NET Core 的另一个有趣的优势是，它可以运行在完整的 .NET Framework 或仅 .NET Core 上。我们知道 .NET Framework 是什么，但 .NET Core 是什么？简单来说，.NET Core 是 .NET Framework 的模块化版本，或者说它是完整 .NET Framework 的一个子集。

“ASP.NET Core 是一个精简且可组合的框架，用于构建 Web 和云应用程序。ASP.NET Core 是完全开源的，可在GitHub 上获得。ASP.NET Core 可在 Windows、Mac 和 Linux 上使用。”摘自https://www.asp.net/core

我们称之为模块化，因为它通过 NuGet 以程序集包的形式发布，而不是一个包含大部分核心功能的大型程序集。当我们阅读有关 .NET Core 的内容时，我们还会遇到 .NET Standard。 .NET Standard 是一个指定平台应支持的通用分层的标准，而 .NET Core 是 Microsoft 对该 .NET Standard 的实现。

安装 ASP.NET Core

对于 Visual Studio 2017，.NET Core 工具已包含在安装程序中。您可以在 https://www.microsoft.com/net/core#windowsvs2017 找到安装指南。

但是，如果您使用的是 Visual Studio 2015，安装 .NET Core 工具并不难；您可以下载适用于 Visual Studio 的 .NET Core SDK 和工具。当前的 .NET Core 版本是 1.1，但这取决于您阅读本文的时间，因此版本可能会因您阅读此帖子的时间而异。您可以在

https://www.microsoft.com/net/download/core.

找到所有与安装相关的 SDK、工具和特定于平台的安装程序。安装 .NET Core 后，您就可以开始创建 .NET Core 项目了。要验证 .NET Core 是否已安装，请打开 Visual Studio，然后转到“文件”->“新建项目”，您就可以看到已安装的 .NET Core 项目模板。

.NET Core 项目及其结构

接下来，我们将进行一些实际操作练习，创建一个示例 ASP.NET Core 项目，并尝试理解项目结构和其他细节。我们将从头开始创建一个全新的 ASP.NET Core Web 应用程序。

因此，请打开 Visual Studio，然后转到“文件”->“新建项目”，您将看到可用的 .NET Core 模板，并按如下所示过滤 ASP.NET Core Web 应用程序。

过滤后，我们可以在模板中看到两个选项，一个说使用 .NET Core 创建 ASP.NET Core Web 应用程序，另一个说使用 .NET Framework。我们之前讨论过 .NET Core 应用程序和 .NET Framework 应用程序之间的区别，并且知道 ASP.NET Core Web 应用程序可以根据我们的选择和需求使用这两个选项中的任何一个来开发。我们将选择 .NET Core 选项，因为我们只需要关注这一领域，并且并不真正需要完整 .NET Framework 的其他功能。我们将尝试创建一个返回员工信息的 API。因此，我们将我们的 API 命名为 EmployeeInfo.API，并将解决方案命名为 EmployeeInfo，如下图所示。

点击“确定”，然后我们就会看到需要选择的模板列表来创建我们的应用程序。当我们选择模板时，其他依赖项和附加文件将通过 Nuget 添加到项目中。

请注意，我们也可以选择当前 ASP.NET Core 版本，即 1.1，或者之前的稳定版本 1.0。在提供的三个模板中，由于我们正在创建 API，因此可以选择 Web API 模板，但这可能会导致下载不必要的 Nuget 包和默认的控制器结构，而这些是我们不需要的。本文的目的是从头开始创建一个 .NET Core 应用程序，以获得更好的理解/概念。所以，为了理解每一个细节，让我们从空模板开始，这样我们就可以完全控制添加我们真正想要的东西。因此，选择“Empty”（空）并按“OK”（确定）按钮。Nuget 还原将下载所需程序包以支持我们选择的空模板，并且我们看到创建的空项目也包含一些结构和基本代码，如下图所示。

我们得到一个名为 EmployeeInfo 的解决方案和一个名为 EmployeeInfo.API 的项目，即我们的 ASP.NET Core 项目。添加了两个类：*Program.cs* 和 *Startup.cs*。我们可以仔细查看这些类并理解它们。

Program.cs

与 .NET 中的其他控制台应用程序一样，*Program.cs* 是应用程序的起点。它包含 `Main` 方法作为起点。因此，我们看到 ASP.NET Core 通常是一个控制台应用程序，它与 ASP.NET 特定组件和库进行通信。应用程序配置和执行是这里 `Main` 方法的职责。我们知道要运行 Web 应用程序，它需要被托管，我们也需要这样做。因此，如果我们仔细查看 `Main` 方法，我们会看到 `WebHostBuilder` 被初始化，并且由于我们托管 Web 应用程序，因此需要一个 Web 服务器。ASP.NET Core 的优点在于它与提供 Web 应用程序托管的 Web 服务器环境是解耦的。它附带两个 HTTP 服务器。第一个是 WebListener，例如，一个基于 Windows 的 Web 服务器。另一个是 Kestrel，例如，一个用于跨平台应用程序托管的 Web 服务器。因此，`UseKestrel` 语句表示 Kestrel 是默认的。由于我们目前在 Visual Studio 中，它将默认使用 IIS Express 作为默认主机。`UseIISIntegration` 语句指定 IIS Express 作为 Kestrel 的反向代理服务器。因此，如果需要在 Windows 服务器上部署 ASP.NET Core 应用程序，应该运行 IIS 作为 Kestrel 的反向代理服务器；如果应用程序要在 Linux 上部署，则应使用 Apache 等类似的服务器来代理请求到 Kestrel。

我们可以独立地使用 Kestrel 自托管应用程序，但使用 IIS 作为反向代理可以获得许多优势。例如，IIS 可以过滤请求，管理 SSL 层和证书，并确保应用程序在崩溃时重新启动等。

`UseContentRoot` 语句表示 Web 主机使用的内容的根目录。默认情况下，内容根与托管应用程序的可执行文件的应用程序基本部分相同。您可以根据需要通过在 `UseContentRoot` 语句中传递位置来指定备用位置，但现在我们可以坚持使用默认的当前目录。`UseStartup` 行表示 Web 主机必须使用的启动类型。Startup 是我们在创建时在空 Web 应用程序中获得的第二个类。“**Build**”语句意味着它构建一个 iWeb host 实例来托管我们的 Web 应用程序。最后，host.run 将最终运行应用程序并阻止调用线程，直到主机完全关闭。

Startup.cs

理论上，`Startup` 类是应用程序的入口点。如图所示，它包含两个方法。`ConfigureServices` 方法用于向用于依赖注入的容器添加和配置服务。在 ASP.NET Core 的上下文中，服务是一个为应用程序的通用消费而创建的组件。例如，有与框架相关的服务，如 Identity MVC Entity Framework Core 服务，但也有应用程序服务，这些服务是应用程序特定的。例如，我们可以添加一个应用程序特定的服务来发送电子邮件或进行日志记录，这些可以通过在 `ConfigureServices` 方法中注册来通过依赖注入提供。

`Configure` 方法接收容器提供的 `IApplicationBuilder`、`IHostingEnvironment` 和 `ILoggerFactory` 实例。请注意，`ConfigureServices` 是一个可选方法。但应用程序在某些时候将需要一些未自动注册的服务。`Configure` 方法在 `ConfigureServices` 方法之后调用，因为它使用在该方法中注册和配置的服务。它指定 ASP.NET Core 应用程序在单个 HTTP 请求上的行为。这是我们在后续文章中将通过 MVC 处理 HTTP 请求的地方。目前根据默认实现，每个 HTTP 请求都会在屏幕上打印“Hello World”。因此，当我们运行应用程序时，首先会如预期般调用 `ConfigureServices`，然后调用 `Configure` 方法，该方法会在屏幕上打印“Hello World”。您可以通过设置断点并运行应用程序来检查控制流。

 

ASP.NET Core 中间件和请求管道

当我们的应用程序收到 HTTP 请求时，必须有一个对该请求的 HTTP 响应，并且内部会处理该请求以生成响应并发送。负责处理请求和生成响应结果的组件构成了请求管道。我们始终可以在管道中的中间件组件之间添加一个中间件组件来处理请求和响应。在早期或旧版本的 ASP.NET 中，有一个模块和处理程序的概念，用于处理这些请求和响应。在 ASP.NET Core 中，这是通过中间件完成的。例如，可以在请求管道中添加一个中间件来处理身份验证和授权。

MVC 有自己的中间件，可以添加到请求管道中。每当收到请求时，它都会进入请求管道，而请求管道包含一系列请求，这些请求从一个中间件组件一个接一个地委托到另一个中间件组件。

每个中间件都有一个选项，可以在接收到请求和委托请求后执行操作，并最终生成所需的响应。因此，每个中间件组件都决定是否将请求委托给下一个组件。例如，身份验证中间件组件如果发现请求未授权，它将不会将请求传递给管道中的下一个组件，而是从其自身组件返回响应结果。

配置请求管道

让我们尝试配置 ASP.NET Core 的请求管道。我们将尝试将其配置为在应用程序抛出异常时显示一个对开发人员友好的异常页面。我们已经创建了一个空应用程序模板，如果我们检查 `Startup` 类的 `Configure` 方法，我们会看到 `app.UseDeveloperExceptionPage()` 方法在 `Configure` 方法中被调用，并且它是在检查应用程序是否处于开发环境时调用的，所以我们的一半工作已经由这个空模板完成了。

        if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

此方法基本上以一种方式配置我们的请求管道，即它添加了开发人员异常页面的中间件，因此现在在开发模式下抛出异常时，该中间件负责处理它。

在此方法上按 F12 查看程序集详细信息，我们会发现它是 `Microsoft.AspNetCore.Diagnostic` 程序集的一部分。

同样，您可以在各种独立的程序集中找到各种中间件。这显示了 ASP.NET Core 的模块化。

让我们检查一下在发生任何异常的情况下会发生什么。因此，我们将修改 `Configure` 方法，并抛出异常而不是显示“Hello World”。

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
      loggerFactory.AddConsole();

      if (env.IsDevelopment())
      {
        app.UseDeveloperExceptionPage();
      }

      app.Run(async (context) =>
      {
        throw new Exception("Test Dev Exception Page");
      });

      //app.Run(async (context) =>
      //{
      //  await context.Response.WriteAsync("Hello World!");
      //});
    }

因此，由于我们已经配置了请求管道以在开发人员异常页面上显示异常详细信息，所以我们应该能看到一个。因此，运行应用程序并抛出一个异常，由于我们是故意抛出异常，按 F5 继续处理异常，我们就会看到一个开发人员异常页面，如下所示。

由于这是一个开发人员异常页面，它只会在开发期间显示，而不会在应用程序处于生产环境中时显示。

如果我们导航到项目属性中的“调试”选项卡，如下图所示。

我们发现一个名为 `ASPNETCORE_ENVIRONMENT` 的环境变量设置为“Development”。ASP.NET Core 引用一个唯一的环境变量和托管环境来维护应用程序当前运行的环境。它可以设置为三个常规值之一：Development、Staging 和 Production，但好处是我们也可以添加自己的值。

这些值可以以编程方式访问，我们利用 `IHostingEnvironment` 服务。

从环境变量中，您可以访问有关托管环境的所有信息，如下所示。

由于我们需要在应用程序处于开发模式时显示开发人员异常页面，因此我们使用了 `UseDeveloperExceptionPage`；否则，我们将捕获异常或将其记录下来。为此，ASP.NET Core 还提供了一个中间件（例如，异常处理程序中间件）。您可以向 `UseExceptionHandler()` 方法传递参数（例如，显示一个对用户友好的错误页面）。

现在，我们坚持使用默认实现。

让我们尝试将开发环境更改为 Production。

现在运行应用程序，我们会看到一个友好的错误页面，当向 `UseExceptionHandler()` 方法传递参数时，这个页面可以变得更有意义。

现在要在此处检查异常，请打开开发人员工具（例如，在页面上按 F12）。在控制台中，我们看到异常被抛出了两次。

一次是为收藏图标，另一次是我们期望从应用程序中得到的。这意味着异常处理程序中间件也会记录异常，那么哪个部分负责记录异常呢？回到 `Configure` 方法，我们看到默认注入的 `ILoggerFactory`，它负责记录异常。我们将在本系列的后续部分详细介绍这个主题。

结论

在本文中，我们学习了如何开始使用 ASP.NET Core。我们了解到 ASP.NET Core 是开源的，用于构建跨平台的基于云的 Internet 应用程序。我们弄清楚了它与完整的 .NET Framework 有何不同。我们还探索了如何使用 ASP.NET Core 安装和创建基本的服务应用程序，并探讨了请求管道和中间件是什么。我们还学习了如何通过中间件配置请求管道，并获得了一些关于 ASP.NET Core 的有趣见解。**下一篇文章…**

GitHub 上的源代码

源代码

参考文献

• https://www.asp.net/core
• https://www.pluralsight.com/courses/asp-dotnet-core-api-building-first

其他系列

我的文章系列

• 使用 C# 学习 OOP 概念
• 学习 MVC
• 学习 .NET 中的 WebAPI
• 深入了解 Visual Studio 2015
• 学习 Visual Studio 扩展性