第二章 创建第一个Web API项目

2.1 项目模板选择

控制器型Web API与最小API

ASP.NET Core提供了两种主要的Web API开发方式：

1. 控制器型Web API (Controller-based Web API)：

   • 基于控制器类和动作方法
   • 提供更多开箱即用的功能和结构
   • 适合复杂或大型API项目
   • 有丰富的特性支持，如模型绑定、验证、筛选器等

2. 最小API (Minimal API)：

   • 简化的API开发方法，减少样板代码
   • 直接在Program.cs中定义端点
   • 适合小型项目或微服务
   • 从.NET 6开始引入，并在后续版本不断增强

本手册主要聚焦于控制器型Web API，它更适合学习完整的ASP.NET Core Web API功能集。

2.2 使用Visual Studio创建项目

步骤详解：

1. 启动Visual Studio 2022
2. 点击"创建新项目"
3. 在搜索框中输入"Web API"
4. 选择"ASP.NET Core Web API"模板，点击"下一步"
5. 在"配置新项目"对话框中：
   • 输入项目名称（如"TodoApi"）
   • 选择合适的位置保存项目
   • 可选：修改解决方案名称
   • 点击"下一步"
6. 在"附加信息"对话框中：
   • 确认使用.NET 8.0（或最新版本）
   • 确保"使用控制器"选项被勾选
   • 确保"启用OpenAPI支持"被勾选（这将添加Swagger文档）
   • 根据需要配置"启用Docker"和"配置HTTPS"选项
   • 点击"创建"

Visual Studio将创建项目并打开解决方案，包含基本的项目结构和示例控制器。

2.3 使用.NET CLI创建项目

如果您使用Visual Studio Code或其他编辑器，可以通过.NET CLI创建项目：

# 创建新的Web API项目
dotnet new webapi -n TodoApi

# 进入项目目录
cd TodoApi

# 打开VS Code（如果使用）
code .

2.4 理解项目结构

默认文件与文件夹

创建的Web API项目包含以下关键文件和文件夹：

• Program.cs：应用程序入口点，包含应用配置和启动代码
• appsettings.json：应用程序配置文件
• Controllers/ ：控制器类所在的文件夹
  • WeatherForecastController.cs：示例API控制器
• Properties/ ：包含启动和项目配置
  • launchSettings.json：定义如何启动应用程序
• WeatherForecast.cs：示例数据模型
• [项目名].csproj：项目定义文件，包含项目依赖和配置

Program.cs详解

.NET 6+使用顶级语句（Top-level statements）简化了Program.cs文件。以下是一个典型的Program.cs文件及其关键部分：

var builder = WebApplication.CreateBuilder(args);

// 添加服务到依赖注入容器
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// 配置HTTP请求管道（中间件）
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

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

app.Run();

关键部分解释：

1. WebApplication.CreateBuilder(args)：创建应用程序构建器
2. 服务注册：将服务添加到依赖注入容器
3. builder.Build()：构建应用程序实例
4. 中间件配置：设置请求处理管道
5. app.Run()：启动应用程序

2.5 运行和测试初始项目

运行项目

使用Visual Studio：

1. 按F5启动调试，或Ctrl+F5启动不调试
2. 项目将在浏览器中打开（通常指向Swagger UI）

使用.NET CLI：

dotnet run

运行后，终端会显示应用程序的URL，通常是https://localhost:7xxx和http://localhost:5xxx（端口可能不同）。

使用浏览器测试

1. 在浏览器中打开显示的URL
2. 如果启用了Swagger，将显示Swagger UI界面
3. 展开"GET /WeatherForecast"端点
4. 点击"Try it out"按钮，然后点击"Execute"
5. 查看响应结果