练习 - 创建 Web API 项目

8 分钟

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

dotnet --list-sdks

将显示类似于以下示例的输出：

6.0.317 [C:\Program Files\dotnet\sdk]
7.0.401 [C:\Program Files\dotnet\sdk]
8.0.100 [C:\Program Files\dotnet\sdk]

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

创建并浏览 Web API 项目

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

在 Visual Studio Code 中，选择“文件”>“打开文件夹”。
在所选位置创建名为 ContosoPizza 的新文件夹，然后选择“选择文件夹”。
从主菜单中选择“视图”>“终端”，以便从 Visual Studio Code 中打开集成终端。
在终端窗口中，复制粘贴以下命令：
```
dotnet new webapi -controllers -f net8.0
```
此命令将为使用控制器的基本 Web API 项目创建文件，以及一个名为 ContosoPizza.csproj 的 C# 项目文件，该文件将返回天气预报列表。如果遇到错误，请确保已安装 .NET 8 SDK。

重要

默认使用 https 保护 Web API 项目。如果遇到问题，请配置 ASP.NET Core HTTPS 开发证书。

Visual Studio Code 可能会提示你添加资产以调试项目。在对话框中，选择“是”。

此命令使用别名为 webapi 的 ASP.NET Core 项目模板来搭建基于 C# 的 Web API 项目的基架。将创建一个 ContosoPizza 目录。此目录包含在 .NET 上运行的 ASP.NET Core 项目。项目名称与 ContosoPizza 目录名称匹配。

现在应该可以访问以下文件和目录：
```
-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| ContosoPizza.csproj
-| ContosoPizza.http
-| Program.cs
-| WeatherForecast.cs
```

检查以下文件和目录：

名称	描述
Controllers/	包含公共方法公开为 HTTP 终结点的类。
Program.cs	配置服务和应用的 HTTP 请求管道，包含应用的托管入口点。
ContosoPizza.csproj	包含项目的配置元数据。
ContosoPizza.http	包含直接从 Visual Studio Code 测试 REST API 的配置。

生成并测试 Web API

在命令行界面中运行以下 .NET Core CLI 命令：
```
dotnet run
```
上述命令：
- 在当前目录中找到项目文件。
- 检索并安装此项目所需的任何项目依赖项。
- 编译项目代码。
- 使用 ASP.NET Core Kestrel Web 服务器将 Web API 托管在 HTTP 和 HTTPS 终结点中。
创建项目时，将为 HTTP 选择 5000 到 5300 端口，为 HTTPS 选择 7000 到 7300 端口。通过编辑项目的 launchSettings.json 文件，可以轻松更改开发过程中使用的端口。本模块使用以 https 开头的安全 localhost URL。

应获得类似于以下内容的输出，用于指示应用正在运行：
```
Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7294
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5118 
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development        
```
如果你是在自己的计算机上运行此应用，可以将浏览器指向输出中显示的 HTTPS 链接（在上例中为 https://localhost:7294）以查看生成的页面。请记住此端口，因为在使用 {PORT} 的整个模块中将一直使用它。

重要

如果遇到任何意外行为，请查看终端输出。如果生成失败或发生其他错误，请根据日志文件中的信息进行故障排除。对代码进行更改时，需要通过选择键盘上的 CTRL+C 并重新运行 dotnet run 命令来停止 Web API。

打开 Web 浏览器并转到：

https://localhost:{PORT}/weatherforecast

应会看到类似于这个示例的 JSON 输出：

[
    {
    "date": "2021-11-09T20:36:01.4678814+00:00",
    "temperatureC": 33,
    "temperatureF": 91,
    "summary": "Scorching"
    },
    {
    "date": "2021-11-09T20:36:01.4682337+00:00",
    "temperatureC": -8,
    "temperatureF": 18,
    "summary": "Cool"
    },
    // ...
]

可选：使用 `.http` 文件进行浏览

项目中包含的文件为 ContosoPizza.http，该文件用于通过标准格式测试 API 终结点。多个集成开发环境 (IDE) 都支持 .http 文件，包括 Visual Studio 以及安装了 REST 客户端扩展的 Visual Studio Code 内部。

打开 ContosoPizza.http 文件。

在某些 IDE 中，此文件已预配置了 @ContosoPizza_HostAddress 变量和调用 /weatherforecast/ 的 GET 命令，该命令接受 application/json。

如果它存在于文件中，选择 GET 上方的“发送请求”命令，该命令会将请求发送到正在运行的服务。

调用此命令将打开一个响应窗口，其输出与我们在浏览器中看到的以下内容类似：

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json; charset=utf-8
Date: Wed, 17 Jan 2024 16:46:40 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
    {
        "date": "2024-01-18",
        "temperatureC": -2,
        "temperatureF": 29,
        "summary": "Warm"
    },
    {
        "date": "2024-01-19",
        "temperatureC": 24,
        "temperatureF": 75,
        "summary": "Chilly"
    },
    // ..
]

可选：使用命令行 HTTP REPL 探索 API

通过从主菜单中选择“终端”>“新终端”，打开一个新的集成终端，然后运行以下命令:
```
dotnet tool install -g Microsoft.dotnet-httprepl
```
上述命令将安装 .NET HTTP Read-Eval-Print Loop (REPL) 命令行工具，你将使用该工具向 Web API 发出 HTTP 请求。
通过运行以下命令连接到 Web API：
```
httprepl https://localhost:{PORT}
```
或者，在 HttpRepl 运行时随时运行以下命令：
```
connect https://localhost:{PORT}
```
提示

如果 HttpRepl 工具发出“找不到 OpenAPI 说明”的警告，最有可能的原因是开发证书不受信任。 HttpRepl 需要信任连接。在继续之前，必须使用 dotnet dev-certs https --trust 配置系统以信任开发证书
通过运行以下命令浏览可用的终结点：
```
ls
```
前面的命令检测到连接终结点上可用的所有 API，并列出了它们，如以下输出所示：
```
https://localhost:{PORT}/> ls
.                 []
WeatherForecast   [GET] 
```
运行以下命令以转到 WeatherForecast 终结点：
```
cd WeatherForecast
```
前面的命令将显示 WeatherForecast 终结点的可用 API 的输出：
```
https://localhost:{PORT}/> cd WeatherForecast
/WeatherForecast    [GET]
```

使用以下命令在 HttpRepl 中发出 GET 请求：

get

前面的命令发出的 GET 请求类似于转到浏览器中的终结点：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Apr 2021 17:31:43 GMT
Server: Kestrel
Transfer-Encoding: chunked
[
    {
    "date": 4/3/2021 10:31:44 AM,
    "temperatureC": 13,
    "temperatureF": 55,
    "summary": "Sweltering"
    },
    {
    "date": 4/4/2021 10:31:44 AM,
    "temperatureC": -13,
    "temperatureF": 9,
    "summary": "Warm"
    },
    // ..
]

使用以下命令结束当前的 HttpRepl 会话：
```
exit
```
在 Visual Studio Code 中返回到下拉列表中的 dotnet 终端。通过选择键盘上的 CTRL+C 关闭 Web API。

现在，已创建了 Web API，我们将对其进行修改以满足披萨 Web API 的需求。

练习 - 创建 Web API 项目

创建并浏览 Web API 项目

生成并测试 Web API

可选：使用 .http 文件进行浏览

可选：使用命令行 HTTP REPL 探索 API

反馈

可选：使用 `.http` 文件进行浏览