ASP.NET Core 10.0 预览版1 新特性解析

OpenAPI 3.1 支持

ASP.NET Core 10.0 预览版1 引入了对 OpenAPI 3.1 规范的支持。虽然版本号只是从3.0升级到3.1，但这是一个重要的更新，特别是完全支持了JSON Schema规范2020-12。

在新版本中，你将看到生成的OpenAPI文档有以下变化：

• 可空类型不再使用nullable: true属性，而是将null作为类型数组中的一个值

默认情况下，生成的OpenAPI文档版本是3.1，但你可以通过配置轻松修改：

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
});

如果是构建时生成OpenAPI文档，可以通过MSBuild项设置：

<OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_0</OpenApiGenerateDocumentsOptions>

重大变更

支持OpenAPI 3.1需要将底层OpenAPI.NET库升级到2.0版本，这带来了一些不兼容变更。最显著的变化是移除了OpenApiAny类，改为直接使用JsonNode。

例如，在.NET 9中添加示例的代码：

schema.Example = new OpenApiObject
{
    ["date"] = new OpenApiString(DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")),
    ["temperatureC"] = new OpenApiInteger(0),
    ["temperatureF"] = new OpenApiInteger(32),
    ["summary"] = new OpenApiString("Bracing"),
};

在.NET 10中需要改为：

schema.Example = new JsonObject
{
    ["date"] = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"),
    ["temperatureC"] = 0,
    ["temperatureF"] = 32,
    ["summary"] = "Bracing",
};

OpenAPI YAML格式支持

ASP.NET Core现在支持以YAML格式提供生成的OpenAPI文档。YAML相比JSON更加简洁，省略了大括号和引号等冗余符号，还支持多行字符串，适合长描述。

要配置应用程序以YAML格式提供OpenAPI文档，可以在MapOpenApi调用中指定".yaml"或".yml"后缀：

app.MapOpenApi("/openapi/{documentName}.yaml");

目前YAML支持仅限于OpenAPI端点，构建时生成YAML格式的OpenAPI文档将在未来预览版中添加。

响应描述增强

ProducesAttribute、ProducesResponseTypeAttribute和ProducesDefaultResponseType属性现在支持可选的Description参数，用于设置响应描述：

[ProducesResponseType<IEnumerable<WeatherForecast>>(StatusCodes.Status200OK, 
    Description = "未来5天的天气预报")]

生成的OpenAPI文档将包含这个描述：

"responses": {
  "200": {
    "description": "未来5天的天气预报",
    "content": {

改进对使用顶级语句应用的测试支持

.NET 10改进了对使用顶级语句应用的测试支持。在C# 9中，顶级语句功能生成的Program类是internal的，开发者必须手动添加public partial class Program声明以便测试项目引用。

在.NET 10中，如果开发者没有显式声明，源代码生成器会自动生成public partial class Program声明。同时添加了分析器，当检测到显式声明时会建议开发者移除它。

Blazor新特性

QuickGrid新增RowClass参数

Blazor的QuickGrid组件新增了RowClass参数，允许为表格行设置自定义CSS类。

Blazor脚本作为静态资源提供

Blazor脚本现在作为静态Web资源提供，支持自动压缩和指纹识别。

路由语法高亮

Blazor中的RouteAttribute现在支持路由语法高亮，帮助开发者更直观地理解路由模板结构。

本地URL检测辅助方法

新增了RedirectHttpResult.IsLocalUrl(url)辅助方法，用于检测URL是否是本地的。本地URL是指不包含主机或授权部分且具有绝对路径的URL。这个方法在重定向前验证URL非常有用，可以防止开放重定向攻击：

if (RedirectHttpResult.IsLocalUrl(url))
{
    return Results.LocalRedirect(url);
}

这些新特性展示了ASP.NET Core 10.0在API文档、测试支持和安全方面的持续改进，为开发者提供了更强大、更易用的工具集。