.NET 10 New feature 新增功能介绍-Minimal APIs增强

一、复杂参数对象中空字符串按null处理

在使用复杂对象参数的 Minimal APIs 时，表单提交中的空字符串值现在将被转换为 [FromForm]，而不是解析失败。

复制代码

using Microsoft.AspNetCore.Http;

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapPost("/todo", ([FromForm] Todo todo) => TypedResults.Ok(todo));

app.Run();

public class Todo
{
  public int Id { get; set; }
  public DateOnly? DueDate { get; set; } // Empty strings map to `null`
  public string Title { get; set; }
  public bool IsCompleted { get; set; }
}

二、参数验证

此功能允许请求验证发送到 API 终结点的数据。启用验证允许 ASP.NET Core 运行时对以下项执行定义的任何验证：

Query
Header
请求主体

使用命名空间中的 DataAnnotations 属性定义验证。开发人员通过以下方式自定义验证系统的行为：

创建自定义 $Validation$ 属性实现。
实现复杂验证逻辑的 IValidatableObject 接口。

如果验证失败，运行时将返回 400 错误的请求响应，其中包含验证错误的详细信息。

三、启用内置验证支持

调用 AddValidation 扩展方法在应用程序的服务容器中注册所需的服务，为最小 API 启用内置验证支持：

builder.Services.AddValidation();

自动发现在最小 API 处理程序中定义的类型，或作为在最小 API 处理程序中定义的类型的基类型。终结点筛选器对这些类型执行验证，并为每个终结点添加。

可以使用扩展方法为特定终结点 DisableValidation 禁用验证，如以下示例所示：

复制代码

app.MapPost("/products",
    ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name)
        => TypedResults.Ok(productId))
    .DisableValidation();

四、使用 C# 记录类型进行验证

支持使用 C# 记录类型进行验证。可以使用命名空间中的 System.ComponentModel.DataAnnotations 属性（类似于类）验证记录类型。例如：

|-------|------------------------------------------------------------------------------------------------------|
| 1 2 3 | public record Product( ``[Required] ``string Name, ``[Range(1, 1000)] ``int Quantity); |

在最小 API 终结点中将记录类型用作参数时，验证属性将自动应用与类类型相同的方式：

|-----------|-----------------------------------------------------------------------------------------------------------------------------------|
| 1 2 3 4 5 | app.MapPost(``"/products"``, (Product product) => { ``// Endpoint logic here ``return TypedResults.Ok(product); }); |

　同时，验证 API 已移动到 Microsoft.Extensions.Validation 命名空间和 NuGet 包。

这让这个 API 在 ASP.NET 核心 HTTP 方案之外仍然可以复用、使用。

公共 API 和行为保持不变，只有包和命名空间不同。现有项目不需要更改代码，因为旧引用会重定向到新实现。

五、支持服务器端事件 (SSE)

此项功能对大模型服务调用非常友好，方便快速集成大模块SSE请求调用

ASP.NET Core 现在支持使用 TypedResults.ServerSentEvents API 返回 ServerSentEvents 结果。最小 API 和基于控制器的应用都支持此功能。

Server-Sent 事件是一种服务器推送技术，允许服务器通过单个 HTTP 连接将事件消息流发送到客户端。

在 .NET 中，事件消息表示为SseItem<T>对象，这些对象可能包含事件类型、ID 和数据有效负载。T

TypedResults 类具有一个名为 ServerSentEvents 的新静态方法，可用于返回ServerSentEvents结果。

此方法的第一个参数是 IAsyncEnumerable<SseItem<T>>，它表示要发送到客户端的事件消息流。

以下示例演示如何使用 TypedResults.ServerSentEvents API 将心率事件流作为 JSON 对象返回到客户端：

复制代码

app.MapGet("/json-item", (CancellationToken cancellationToken) =>
{
    async IAsyncEnumerable<HeartRateRecord> GetHeartRate(
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            var heartRate = Random.Shared.Next(60, 100);
            yield return HeartRateRecord.Create(heartRate);
            await Task.Delay(2000, cancellationToken);
        }
    }

    return TypedResults.ServerSentEvents(GetHeartRate(cancellationToken),
                                                  eventType: "heartRate");
});