第一章 开发环境安装指南

根据您的搜索任务，以下是关于 .NET Web API 开发环境搭建、工具配置和项目创建的详细报告：

.NET Web API 开发环境搭建报告

本报告旨在提供设置 .NET Web API 开发环境、配置工具以及创建项目的详细步骤和最佳实践。

1. 必要条件与开发工具选择

要开始开发 ASP.NET Core Web API，您需要安装以下工具：

• Visual Studio 2022：
  • 需安装「ASP.NET 和 Web 开发」工作负载。此工作负载包含了 .NET SDK 和其他必要的开发工具。
  • Visual Studio 2022 安装程序工作负载截图:
    
• Visual Studio Code：
  • 虽然本报告的创建项目部分主要基于 Visual Studio，但 Visual Studio Code 也是一个受支持的开发环境选项。
• .NET SDK：
  • Visual Studio 工作负载会自动安装相应的 .NET SDK（例如，本教程中使用的是 .NET 9.0）。您也可以从 dotnet.microsoft.com/download 单独下载。

资料来源：

• 教程：使用 ASP.NET Core 创建控制器型 Web API | Microsoft Learn
• Tutorial: Create a controller-based web API with ASP.NET Core | Microsoft Learn

2. 项目创建

以下是在 Visual Studio 中创建 ASP.NET Core Web API 项目的步骤：

1. 从 文件 (File) 菜单中，选择 新建 (New) > 项目 (Project)。
2. 在搜索框中输入 Web API。
3. 选择「ASP.NET Core Web API 模板 (ASP.NET Core Web API template)」，然后点击 下一步 (Next)。
4. 在「配置您的新项目 (Configure your new project)」对话框中，将项目命名为例如 TodoApi，然后点击 下一步 (Next)。
5. 在「其他信息 (Additional information)」对话框中：
   • 确认框架 (Framework) 为 .NET 9.0 (或您选择的最新 LTS/STS 版本)。
   • 确认已勾选「启用 OpenAPI 支持 (Enable OpenAPI support)」复选框。
   • 确认已勾选「使用控制器 (Use controllers)」复选框（若要使用 Minimal APIs 则取消勾选）。
6. 点击 创建 (Create)。

资料来源：

• 教程：使用 ASP.NET Core 创建控制器型 Web API | Microsoft Learn
• Tutorial: Create a controller-based web API with ASP.NET Core | Microsoft Learn

3. NuGet 包管理

NuGet 是 .NET 的包管理器，用于在项目中添加、更新和管理第三方库。

添加 NuGet 包的步骤：

1. 从 工具 (Tools) 菜单中，选择 NuGet 包管理器 (NuGet Package Manager) > 管理解决方案的 NuGet 包 (Manage NuGet Packages for Solution)。
2. 选择「浏览 (Browse)」选项卡。
3. 在搜索框中输入要查找的包，例如 Microsoft.EntityFrameworkCore.InMemory。
4. 选择右侧窗格中的项目复选框，然后点击 安装 (Install)。

自动安装的包：
在脚手架 (Scaffolding) 操作期间，通常会自动添加以下必要的 NuGet 包：

• Microsoft.VisualStudio.Web.CodeGeneration.Design
• Microsoft.EntityFrameworkCore.Tools

资料来源：

• 教程：使用 ASP.NET Core 创建控制器型 Web API | Microsoft Learn
• Tutorial: Create a controller-based web API with ASP.NET Core | Microsoft Learn

4. 数据模型与数据库上下文配置

在开发 Web API 时，数据模型（如 TodoItem 类）和数据库上下文（如 TodoContext）是核心组成部分。

a. 添加模型类：
模型是代表应用程序所管理数据的一组类。例如，创建一个 TodoItem 类来表示待办事项。

• 在「解决方案资源管理器 (Solution Explorer)」中，右键单击您的项目。
• 选择 添加 (Add) > 文件夹 (New Folder)，并将其命名为 Models。
• 右键单击 Models 文件夹并选择 添加 (Add) > 类 (Class)。
• 将类命名为 TodoItem，然后点击 添加 (Add)。

b. 添加数据库上下文：
数据库上下文是协调 Entity Framework 数据模型功能的主要类。它继承自 Microsoft.EntityFrameworkCore.DbContext。

• 右键单击 Models 文件夹并选择 添加 (Add) > 类 (Class)。
• 将类命名为 TodoContext，然后点击 添加 (Add)。

c. 注册数据库上下文：
在 ASP.NET Core 中，数据库上下文等服务必须向依赖注入 (DI) 容器注册，以便控制器可以使用它们。

在 Program.cs 文件中，添加以下代码来注册数据库上下文（例如，使用内存数据库进行开发）：

using Microsoft.EntityFrameworkCore;
using TodoApi.Models; // 确保有此 using 指令

var builder = WebApplication.CreateBuilder(args);

// ... 其他服务配置

builder.Services.AddControllers();
builder.Services.AddOpenApi(); // 启用 OpenAPI/Swagger
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList")); // 注册数据库上下文并指定使用内存数据库

var app = builder.Build();

// ... 其他中间件配置

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // 开发环境下启用 Swagger UI
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

资料来源：

• 教程：使用 ASP.NET Core 创建控制器型 Web API | Microsoft Learn
• Tutorial: Create a controller-based web API with ASP.NET Core | Microsoft Learn

5. 生成控制器 (Scaffolding)

Visual Studio 提供了脚手架功能，可以自动生成基于 Entity Framework 的 API 控制器。

生成控制器的步骤：

1. 右键单击 Controllers 文件夹。
2. 选择 添加 (Add) > 新建脚手架项目 (New Scaffolded Item...)。
3. 选择「使用 Entity Framework 执行操作的 API 控制器 (API Controller with actions, using Entity Framework)」，然后点击 添加 (Add)。
4. 在对话框中：
   • 在「模型类 (Model class)」中选择您的模型类（例如 TodoItem (TodoApi.Models)）。
   • 在「数据上下文类 (Data context class)」中选择您的数据库上下文类（例如 TodoContext (TodoApi.Models)）。
5. 点击 添加 (Add)。

生成的控制器将自动包含用于 CRUD (Create, Read, Update, Delete) 操作的 API 方法，并通过依赖注入获取数据库上下文。

资料来源：

• 教程：使用 ASP.NET Core 创建控制器型 Web API | Microsoft Learn
• Tutorial: Create a controller-based web API with ASP.NET Core | Microsoft Learn

6. 测试与最佳实践

• 运行项目：
  • 在 Visual Studio 中，按下 Ctrl+F5 可以运行项目而不安装调试器。
  • 当项目首次运行并使用 SSL 时，可能会弹出对话框询问您是否信任 IIS Express 或开发证书。请选择「是」以避免浏览器警告。
• 测试 API：
  • 项目模板会创建一个 WeatherForecast API，您可以通过浏览器访问 https://localhost:<port>/weatherforecast 来测试。
  • 教程建议使用 Endpoints Explorer 和 .http 文件进行 API 测试，这是在 Visual Studio 中测试 RESTful API 的便捷方式。
  • 其他测试工具包括 http-repl、curl 和 Fiddler。
• 防止过度发布 (Over-posting)：
  • 使用数据传输对象 (DTO) 是最佳实践，可以防止用户发布未经授权或不必要的数据，同时隐藏不应暴露给客户端的属性，并减少数据负载大小。
• 身份验证与授权：
  • 对于需要安全性的 Web API，可以整合身份验证支持，例如 Microsoft Entra ID、Azure Active Directory B2C 或 Duende Identity Server。
• 部署：
  • 完成开发后，您可以将 ASP.NET Core Web API 部署到各种环境，例如 Azure App Service。

资料来源：

• 教程：使用 ASP.NET Core 创建控制器型 Web API | Microsoft Learn
• Tutorial: Create a controller-based web API with ASP.NET Core | Microsoft Learn

总结

本报告详细概述了搭建 .NET Web API 开发环境的关键步骤，包括工具选择、项目创建、NuGet 包管理、数据模型与上下文配置以及常用的测试与最佳实践。遵循这些步骤，您可以有效地开始您的 .NET Web API 开发之旅。