.net 温故知新【11】：Asp.Net Core WebAPI 入门使用及介绍

在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();
        }
    }
}

1. ControllerBase 基类
   
   web API 控制器通常应派生自 ControllerBase 而不是 Controller。 Controller 派生自 ControllerBase，并添加对视图的支持，因此它用于处理 Web 页面，而不是 Web API 请求。 如果同一控制器必须支持视图和 Web API，则派生自 Controller。
2. [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"
}

1. [Route("[controller]")]
   
   指定控制器上的属性路由,属性路由将应用的功能建模为一组资源，其中操作由 HTTP 谓词表示。也就是说路由该属性配置了路由，如上图请求时的路由https://localhost:7122/WeatherForecast，配置中“[controller]”为标记替换，为方便起见，属性路由支持标记替换，方法是将标记用方括号（[、]）括起来[controller]用于替换WeatherForecastController中WeatherForecast部分。
2. [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]
3. logger日志记录
   
   日志记录是基础知识点，这部分内容在我们之前温故知新中已经详细介绍过，可移步了解：.net 温故知新：【9】.NET日志记录 ILogger使用和原理

以上为我们入门WebApi创建的一个默认项目，并对创建选项、项目结构、服务要点进行了分析，后面将更进一步学习分享其他asp.net core webapi重要知识。