第一部分 简介

本书的第一部分主要介绍本书的内容, 我们会讨论基本的 Minimal API, 以及它是如何运行的. 我们希望一点点的添加所需的知识, 慢慢进入强大的功能.

文本会在这一部分包含:

  • ch01 Minimal API 简介
  • ch02 探索 Minimal API 与进阶
  • ch03 使用 Minimal API

ch01 Minimal API 简介

主要介绍 .NET 6 中 Minimal API 的基础. 介绍如何配置开发环境, 以及创建一个 Minimal API 应用.

首先简要介绍一下历史. 然后分别使用 VS 和 VSCode 创建 Minimal API 应用. 最后看看项目的结构.

最后我们需要创建一个 Minimal API. 并使用 REST API 模板来使用它.

本章我们会涉及下面主题:

  • Microsoft Minimal API 历史简述
  • 创建 Minimal API 项目
  • 观察 Minimal API 项目文件结构

技术要求

首先要安装 .NET 6 开发环境.

如果你没有安装, 可以... (略)

运行下面命令查看安装的 SDK 版本

dotnet --list-sdks

在开始之前, 你需要文本编辑器来编辑代码, 或 IDE

这里略, 介绍 VS 与 VSCode 的安装. 作者推荐使用 VSCode

下面是推荐安装的 VSCode 插件

  • MSBuild project tools
  • REST Client
  • ILSpy .NET Decompiler

Microsoft Web API 简要历史

2007 年 MVC 模式诞生.

五年后的 2012 年, REST 风格带来了 WebAPI, 这是对 WCF 的重大改进.

... 略

创建 Minimal API 项目

下面创建 Minimal API 项目来实现 RESTful API. 作者分别采用 VS 2022 和 VSCode 来创建.

这里罗列创建用的命令行

dotnet new webapi -minimal -o Chapter01

image-20231011225816147

然后使用 VSCode 将其打开

cd Chapter01
code .

查看项目结构

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Minimal API 的代码默认是放在一个文件中. 有经验的开发者会发现逻辑上与 基于控制器的 代码是类似的.

但这实际上是另一种开发模式, 基于纯净的 ASP.NET Core.

注意, minimal 是指用最少的组件来构建应用, 而不是指构建编写过程简单. 实际上 Minimal 更需要合理的编排项目.

最后还需要说明的是, minimal api 不是为去取代 MVC 等项目架构, 它仅仅是提供了另一种开发方式.

让我们回到代码.

minimal api 采用一个新的模板来开发, 使用了 top-level 应用模型. 意味着为它仅仅使用一个文件 Program.cs 取代了以前两个文件的配置

以前是 Program.cs 和 Startup.cs

如果不喜欢这个风格, 改回原来的方式也可以.

有关 Top-Level 可以参考文档.

默认情况下, 新模板支持 OpenAPI 规范, 特别是 Swagger.

下面两句代码是 Swagger 的默认配置

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

通常我们不会将所有的端都都暴露出去, 特别是开发环境中. 默认情况下, 仅在开发模式下 Swagger 才会对外开放. 以为下面这个代码

if (app.Environment.IsDevelopment()) {
  app.UseSwagger();
  app.UseSwaggerUI();
}

即在开发模式下会包含 Swagger 文档, 其他情况不会.

有关 Swagger 的细节会在第三章介绍

文档最后的几行代码, 我们正在.NET 6 中引入一个通用的概念: 环境.

通常, 在开发一个应用的时候会有好几个阶段, 包括开发, 测试, 交付等.

按照惯例, 这些阶段有专门的名字, development, staging(预言), 和 production. 作为开发者, 可能会在当前环境下修改程序行为.

在 .NET 6 中可以通过访问环境变量来获得这些信息

if (app.Environment.IsDevelopment()) {
           // your code here
}
if (app.Environment.IsStaging()) {
           // your code here
}
if (app.Environment.IsProduction()) {
           // your code here
}

很多时候, 我们需要自定义环境, 那么可以这么使用

if (app.Environment.IsEnvironment("TestEnvironment")) {
  // 你的代码
}

问题是环境怎么定义???

其中一个方法是修改 Properities/lanuchSettings.json 文件

可以在运行时带上 --environment 参数

细节可以参考文档

在 Minimal API 中定义路由使用 MapGet, MapPost, MapPut, MapDelete. 如果你习惯 HTTP 动词, 你会发现没有 Patch. 实际上可以使用 MapMethods 来自定义动词. 例如, 你需要使用 POST 来请求 API 可以这么写:

app.MapPost("/weatherforecast", async (WeatherForecast model, IWhetherService repo) => {
  // ...
});

可见添加端点很容易.

有一个比较困难的是, 参数绑定, 以及添加依赖注入.

注意, 会在第二章介绍路由, 第四章介绍依赖注入.

小结 (略)

Last Updated:
Contributors: jk