Mikel
来源： .net 温故知新【11】：Asp.Net Core WebAPI 入门使用及介绍 – XSpringSun – 博客园
在ASP.NET Core 上面由于现在前后端分离已经是趋势，所以ASP.NET core MVC用的没有那么多，主要以WebApi作为学习目标。
一、创建一个WebApi项目
我使用的是VS2022, .Net 7版本。
在创建界面有几项配置：
- 配置Https
- 启用Docker
- 使用控制器
- 启用OpenAPI支持
- 不使用顶级语句
其中配置Https 是WebApi是否使用https协议，启用docker是配置服务是否docker部署支持。我们这边作为学习就先不管docker了。
然后下面还有三个配置，第一个是说是否使用控制器，如果使用接口服务放在Controllers文件夹下统一管理并且相关路由规则不一样。
第二个启用OpenAPI支持，如果启用OpenAPI说的是swagger支持，也就是说.net 自动集成了swagger。
第三个不使用顶级语句，如果勾选后则程序的Program类和Main方法完整。
那么我们看下上面配置是什么意思，第二个swagger支持我们就不管了默认开启。我建两个项目AspNetCoreWebAPI_1、AspNetCoreWebAPI_2，AspNetCoreWebAPI_1我们勾选上【使用控制器】、【不使用顶级语句】。AspNetCoreWebAPI_2项目这两项都不选。
先看下项目目录结构
不同在于AspNetCoreWebAPI_1项目多了Controllers文件夹和一个WeatherForecast类，WeatherForecast类是示例接口中有使用。
我们再对比一下 Program类
可以看到在AspNetCoreWebAPI_1项目中Program类和Main方法完整，因为要使用Controller的原因，所以依赖注入了Controller服务。并且使用了MapControllers注册路由。
在AspNetCoreWebAPI_2项目中没有只有Main方法内的代码，这就是顶级语句。然后由于我们还使用了最小API,就是不使用Controller方式注册和配置路由，直接在代码中自己注册接口和实现接口处理的代理方法。
按照以前asp.net习惯和项目清晰度维护性我们一般是使用Controller的方式，并且不使用顶级语句。
而最小 API，是创建具有最小依赖项的 HTTP API。 它非常适合于需要在 ASP.NET Core 中仅包括最少文件、功能和依赖项的微服务和应用。
另外还有一个appsetting.json配置文件，这部分内容也在前面已经介绍过,欢迎了解：.net 温故知新：【8】.NET 中的配置从xml转向json
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*"
}
二、WebApi运行
我们调试项目AspNetCoreWebAPI_1，此时会启动一个服务在后端，同时启动浏览器访问该站点的swagger，该swagger用于调我们调试webapi接口。
我们点击示例接口WeatherForecast，访问接口会返回json格式数据。响应的headers里面可以看到后端运行的服务器是Kestrel,和我们以前.net framework不一样的事需要借助IIS作为服务器。现在的Kestrel是包含在程序中的，这个Kestrel 以后再讨论。
三、WeatherForecastController
WeatherForecastController是在创建项目后默认生成的一个示例Controller。在该Controller中我们可以看到几个重点项。
using Microsoft.AspNetCore.Mvc;
namespace AspNetCoreWebAPI_1.Controllers
{
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
private readonly ILogger<WeatherForecastController> _logger;
public WeatherForecastController(ILogger<WeatherForecastController> logger)
{
_logger = logger;
}
[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
}
}
- ControllerBase 基类
web API 控制器通常应派生自 ControllerBase 而不是 Controller。 Controller 派生自 ControllerBase，并添加对视图的支持，因此它用于处理 Web 页面，而不是 Web API 请求。 如果同一控制器必须支持视图和 Web API，则派生自 Controller。 - [ApiController]
[ApiController] 属性可应用于控制器类，以启用下述 API 特定的固定行为：
1）属性路由要求：不能通过由 UseEndpoints、UseMvc 或 UseMvcWithDefaultRoute 定义的传统路由访问操作，传统路由就是以前老的路由规则，型如”{controller=Home}/{action=Index}/{id?}”。需要使用[Route(“XX”)]指定路由。
自动 HTTP 400 响应：[ApiController] 属性使模型验证错误自动触发 HTTP 400 响应。
2）绑定源参数推理：绑定源特性定义可找到操作参数值的位置，接口的参数通过推理规则应用于操作参数的默认数据源。
3）Multipart/form-data 请求推理：[ApiController] 属性对 IFormFile 和 IFormFileCollection 类型的操作参数应用推理规则。 为这些类型推断 multipart/form-data 请求内容类型。
4）、错误状态代码的问题详细信息： 将错误结果（状态代码为 400 或更高的状态码）转换为为 ProblemDetails 的结果。也就是说状态码会转换如下json格式返回信息。
{
type: "https://tools.ietf.org/html/rfc7231#section-6.5.4",
title: "Not Found",
status: 404,
traceId: "0HLHLV31KRN83:00000001"
}
- [Route(“[controller]”)]
指定控制器上的属性路由,属性路由将应用的功能建模为一组资源，其中操作由 HTTP 谓词表示。也就是说路由该属性配置了路由，如上图请求时的路由https://localhost:7122/WeatherForecast，配置中“[controller]”为标记替换，为方便起见，属性路由支持标记替换，方法是将标记用方括号（[、]）括起来[controller]用于替换WeatherForecastController中WeatherForecast部分。 - [HttpGet(Name = “GetWeatherForecast”)]
HttpGet指示Get方法为Route路由的操作，即使我们将Get方法改为其他名字仍然不影响请求路由https://localhost:7122/WeatherForecast，并且以Get方式。这种api风格即为Rest风格。Rest风格我们后面再学习。
ASP.NET Core 具有以下 HTTP 谓词模板：- [HttpGet]
- [HttpPost]
- [HttpPut]
- [HttpDelete]
- [HttpHead]
- [HttpPatch]
- logger日志记录
日志记录是基础知识点，这部分内容在我们之前温故知新中已经详细介绍过，可移步了解：.net 温故知新：【9】.NET日志记录 ILogger使用和原理
以上为我们入门WebApi创建的一个默认项目，并对创建选项、项目结构、服务要点进行了分析，后面将更进一步学习分享其他asp.net core webapi重要知识。
