.NET WebAPI 项目的七项核心配置：数据库连接与 EF Core 迁移、依赖注入服务注册、Swagger 文档生成、接口 JSON 大小写处理、跨域资源共享（CORS）、身份验证与授权策略以及日志框架集成。通过合理配置这些选项，可确保项目的高效运行、安全性及可维护性。
.NET 支持多种数据库，如 SQL Server、MySQL、Oracle 等，每种数据库都有相应的官方或第三方提供程序。以 SQL Server 为例，常用的是 Microsoft.EntityFrameworkCore.SqlServer。通过 NuGet 包管理器，在项目中安装此包，即可引入 SQL Server 的相关支持。对于 MySQL，可以安装 MySql.Data.EntityFrameworkCore；对于 Oracle，可能需要 Oracle.EntityFrameworkCore 等，具体取决于所使用的数据库版本和开发需求。
{
"ConnectionStrings": {
"DefaultConnection": "Server=YOUR_SERVER_NAME;Database=YOUR_DATABASE_NAME;User ID=YOUR_USERNAME;Password=YOUR_PASSWORD;Trusted_Connection=False;MultipleActiveResultSets=true"
}
}
其中，YOUR_SERVER_NAME 是数据库服务器名称，YOUR_DATABASE_NAME 是数据库名称，YOUR_USERNAME 和 YOUR_PASSWORD 是登录数据库的凭证。如果使用 Windows 身份验证，可以将 User ID 和 Password 替换为 Trusted_Connection=True。
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<YourDbContext>(options =>
options.UseSqlServer(connectionString));
这里的 YourDbContext 是继承自 DbContext 的自定义数据库上下文类，用于管理与数据库的交互。
using Microsoft.EntityFrameworkCore;
public class YourDbContext : DbContext
{
public YourDbContext(DbContextOptions<YourDbContext> options) : base(options)
{
}
// 定义 DbSet 属性来映射数据库表
public DbSet<YourEntity> YourEntities { get; set; }
}
其中，YourEntity 是与数据库表对应的实体类。
dotnet ef migrations add InitialCreate：此命令会创建一个新的迁移，InitialCreate 是迁移的名称，可以根据实际情况修改。它会根据当前 YourDbContext 类的定义和已有的数据库结构，生成用于创建或更新数据库的迁移脚本。
dotnet ef database update：该命令会将数据库更新到最新的迁移状态，即执行上一步生成的迁移脚本，创建或更新数据库架构。
依赖注入（Dependency Injection，简称 DI）是一种设计模式，它通过将对象的创建和依赖关系的管理从对象本身转移到外部容器中，从而实现松耦合的设计。在.NET WebAPI 项目中，依赖注入由框架内置的服务容器来管理。
builder.Services.AddLogging();
这将启用框架内置的日志记录功能。
public interface IYourService
{
void DoSomething();
}
public class YourService : IYourService
{
public void DoSomething()
{
// 业务逻辑代码
}
}
在 Program.cs 中注册该服务：
builder.Services.AddScoped<IYourService, YourService>();
这里使用 AddScoped 方法，表示该服务在每个请求范围内是单例的，即每次请求都会创建一个新的 YourService 实例，但在同一个请求中，多次获取 IYourService 都会返回同一个实例。其他常见的生命周期方法还有 AddSingleton（整个应用程序生命周期内单例）和 AddTransient（每次请求都会创建一个新实例）。
在控制器或其他需要使用服务的地方，通过构造函数注入依赖。例如，在一个控制器中使用 IYourService：
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("[controller]")]
public class YourController : ControllerBase
{
private readonly IYourService _yourService;
public YourController(IYourService yourService)
{
_yourService = yourService;
}
[HttpGet]
public IActionResult Get()
{
_yourService.DoSomething();
return Ok("Service executed successfully");
}
}
这样，当控制器实例化时，服务容器会自动将 IYourService 的实例注入到控制器的构造函数中。
通过 NuGet 包管理器安装 Swashbuckle.AspNetCore 包，它提供了在.NET 项目中集成 Swagger 的功能。Swagger 是一个用于生成、描述、调用和可视化 RESTful Web 服务的工具，能极大地简化接口文档的生成和测试工作。
在 Program.cs 文件中，添加 Swagger 服务配置：
using Swashbuckle.AspNetCore.SwaggerGen;
using Microsoft.OpenApi.Models;
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "Your WebApi Title",
Version = "v1",
Description = "A detailed description of your WebApi",
Contact = new OpenApiContact
{
Name = "Your Name",
Email = "[email protected]",
Url = new Uri("https://example.com")
}
});
// 配置 XML 注释文件路径，用于生成详细的接口文档
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
这里，SwaggerDoc 方法定义了 API 的版本（v1）、标题、描述和联系人等信息。IncludeXmlComments 方法用于指定包含 XML 注释的文件路径，以便 Swagger 能生成更详细的接口文档，包括参数说明、返回值说明等。要生成 XML 注释文件，需要在项目属性的'生成'选项卡中，勾选'XML 文档文件'。
在 Program.cs 的 Configure 方法中，启用 Swagger 中间件：
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your WebApi V1");
c.RoutePrefix = "swagger";// 设置 Swagger UI 的访问路径
});
UseSwagger 方法用于生成 Swagger JSON 文档，UseSwaggerUI 方法用于启用 Swagger UI 界面，通过该界面可以方便地查看和测试 API 接口。SwaggerEndpoint 方法指定了 Swagger JSON 文档的路径和版本描述，RoutePrefix 设置了 Swagger UI 的访问路径，例如，访问 http://localhost:YOUR_PORT/swagger 即可打开 Swagger UI 界面。
默认情况下，.NET WebAPI 在接收 JSON 数据时，会尝试匹配属性名，不区分大小写。但在某些场景下，可能需要严格区分大小写。要实现严格区分大小写，可以在 Program.cs 中进行如下配置：
builder.Services.AddControllers()
.AddJsonOptions(options =>
{
options.JsonSerializerOptions.PropertyNameCaseInsensitive = false;
});
这将使 WebAPI 在反序列化 JSON 数据时，严格按照属性名的大小写进行匹配。如果客户端发送的 JSON 数据中的属性名大小写与模型类中的属性名不完全一致，将导致属性值无法正确绑定。
builder.Services.AddControllers()
.AddNewtonsoftJson(options =>
{
options.SerializerSettings.ContractResolver = new DefaultContractResolver();
});
DefaultContractResolver 默认会将属性名以驼峰命名法输出。如果希望以原属性名输出（即不进行命名转换），可以使用 CamelCasePropertyNamesContractResolver 来实现驼峰命名法输出，或者自定义 ContractResolver 来满足特定的命名规则。
builder.Services.AddControllers()
.AddJsonOptions(options =>
{
options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
});
这里使用 JsonNamingPolicy.CamelCase 将属性名转换为驼峰命名法输出。如果希望以原属性名输出，可以设置 PropertyNamingPolicy 为 null。
当一个前端应用程序运行在一个域名下，而它试图访问另一个域名下的 API 时，就会出现跨域问题。这是因为浏览器的同源策略限制了不同源（协议、域名、端口中有一个不同即为不同源）之间的资源访问。在开发 WebAPI 项目时，尤其是与前端分离开发时，经常需要处理跨域问题。
{
"AllowedOrigins": [
"http://localhost:3000",
"https://example.com"
]
}
这里列出了允许跨域访问的前端应用的 URL。
using Microsoft.AspNetCore.Cors.Infrastructure;
var allowedOrigins = builder.Configuration.GetSection("AllowedOrigins").Get<string[]>();
var corsBuilder = new CorsPolicyBuilder();
corsBuilder.AllowAnyHeader();
corsBuilder.AllowAnyMethod();
corsBuilder.WithOrigins(allowedOrigins);
builder.Services.AddCors(options =>
{
options.AddPolicy("AllowSpecificOrigins", corsBuilder.Build());
});
这里创建了一个名为 AllowSpecificOrigins 的 CORS 策略，允许指定源（从配置文件中读取）、任何 HTTP 方法和任何请求头。然后在 Configure 方法中启用该策略：
app.UseCors("AllowSpecificOrigins");
如果希望允许所有源跨域访问（不推荐在生产环境中使用，因为存在安全风险），可以简化配置为：
builder.Services.AddCors(options =>
{
options.AddPolicy("AllowAll", builder =>
{
builder.AllowAnyOrigin()
.AllowAnyMethod()
.AllowAnyHeader();
});
});
并在 Configure 方法中使用 app.UseCors("AllowAll");
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;
var jwtSettings = builder.Configuration.GetSection("JwtSettings");
var key = Encoding.ASCII.GetBytes(jwtSettings["SecretKey"]);
builder.Services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.RequireHttpsMetadata = false;
options.SaveToken = true;
options.TokenValidationParameters = new TokenValidationParameters
{
ValidateIssuer = true,
ValidateAudience = true,
ValidateLifetime = true,
ValidateIssuerSigningKey = true,
ValidIssuer = jwtSettings["Issuer"],
ValidAudience = jwtSettings["Audience"],
IssuerSigningKey = new SymmetricSecurityKey(key)
};
});
这里从配置文件 appsettings.json 中的 JwtSettings 节点读取 JWT 的相关配置，如密钥（SecretKey）、颁发者（Issuer）和受众（Audience）。配置 TokenValidationParameters 用于验证 JWT 的有效性。
builder.Services.AddAuthorization();
然后，在控制器中使用 Authorize 特性。例如：
[ApiController]
[Route("[controller]")]
[Authorize(Roles = "Admin")]
public class AdminController : ControllerBase
{
// 只有具有 Admin 角色的用户才能访问此控制器的方法
}
这里表示只有具有 Admin 角色的用户才能访问 AdminController 中的方法。
builder.Services.AddAuthorization(options =>
{
options.AddPolicy("MustBeOver21", policy =>
policy.RequireAssertion(context =>
{
// 这里可以编写自定义的授权逻辑，例如检查用户年龄
var user = context.User;
// 假设用户声明中包含年龄信息
var ageClaim = user.FindFirst("Age");
if (ageClaim != null)
{
int age = int.Parse(ageClaim.Value);
return age >= 21;
}
return false;
}));
});
然后在控制器中使用该策略：
[ApiController]
[Route("[controller]")]
[Authorize(Policy = "MustBeOver21")]
public class AgeRestrictedController : ControllerBase
{
// 只有满足 MustBeOver21 策略的用户才能访问此控制器的方法
}
这样可以根据具体的业务需求，灵活地定义和应用授权策略。
.NET 提供了多种日志框架，如内置的 ILogger 接口及相关实现，还有第三方的 Serilog、NLog 等。以 Serilog 为例，首先通过 NuGet 包管理器安装 Serilog.AspNetCore、Serilog.Sinks.Console 等相关包。Serilog.AspNetCore 用于将 Serilog 集成到 ASP.NET Core 应用中，Serilog.Sinks.Console 用于将日志输出到控制台。
在 Program.cs 中进行如下配置：
using Serilog;
using Serilog.Events;
var logger = new LoggerConfiguration()
.MinimumLevel.Override("Microsoft", LogEventLevel.Information)
.Enrich.FromLogContext()
.WriteTo.Console()
.CreateLogger();
builder.Logging.ClearProviders();
builder.Logging.AddSerilog(logger);
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online