ASP.NET Core 8.0 重大变更：移除 ProblemDetails 自定义序列化转换器

ASP.NET Core 8.0 重大变更：移除 ProblemDetails 自定义序列化转换器

docs This repository contains .NET Documentation. 项目地址: https://gitcode.com/gh_mirrors/docs2/docs

背景介绍

在 ASP.NET Core 中，ProblemDetails 和 ValidationProblemDetails 是用于表示 HTTP API 错误响应的标准格式。在之前的版本中，由于 System.Text.Json 序列化器缺乏对 IgnoreNullValues 选项的原生支持，ASP.NET Core 为这些类型实现了自定义的 JSON 转换器。

变更内容

ASP.NET Core 8.0 移除了 ProblemDetails 和 ValidationProblemDetails 的自定义 JSON 序列化转换器，转而使用 System.Text.Json 提供的原生序列化功能。这一变更带来了以下影响：

1. 不再自动将属性名称转换为小写形式
2. 需要显式配置 JsonNamingPolicy 来获得预期的命名策略
3. 枚举类型的序列化行为发生变化

变更原因

System.Text.Json 已经成熟，现在原生支持 IgnoreNullValues 选项（现已被 PropertyNameCaseInsensitive 替代），因此不再需要维护自定义转换器。这一变更简化了框架代码，并提高了与标准 JSON 序列化行为的一致性。

代码示例对比

旧版行为 (8.0 之前)

string content = "{\"status\":400,\"detail\":\"HTTP egress is not enabled.\"}";
using MemoryStream stream = new();
using StreamWriter writer = new(stream);
writer.Write(content);
writer.Flush();
stream.Position = 0;

JsonSerializerOptions options = new();
options.Converters.Add(new JsonStringEnumConverter());

ValidationProblemDetails? details = await JsonSerializer.DeserializeAsync<ValidationProblemDetails>(stream, options);
Console.WriteLine(details.Status); // 输出 400

新版行为 (8.0 及以后)

string content = "{\"status\":400,\"detail\":\"HTTP egress is not enabled.\"}";
using MemoryStream stream = new();
using StreamWriter writer = new(stream);
writer.Write(content);
writer.Flush();
stream.Position = 0;

JsonSerializerOptions options = new();
options.Converters.Add(new JsonStringEnumConverter());

ValidationProblemDetails? details = await JsonSerializer.DeserializeAsync<ValidationProblemDetails>(stream, options);
Console.WriteLine(details.Status); // 输出 null

迁移建议

为了保持与之前版本相同的行为，您需要显式配置 JsonSerializerOptions：

JsonSerializerOptions options = new()
{
   PropertyNameCaseInsensitive = true
};
ValidationProblemDetails? details = await JsonSerializer.DeserializeAsync<ValidationProblemDetails>(stream, options);

如果需要自定义属性名称的大小写策略，可以配置 JsonNamingPolicy：

JsonSerializerOptions options = new()
{
   PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

影响范围

此变更主要影响以下 API：

• 直接使用 ProblemDetails 类型的代码
• 使用 ValidationProblemDetails 类型的代码
• 自定义了 JSON 序列化选项的 Web API 项目

最佳实践

1. 在升级到 ASP.NET Core 8.0 后，检查所有 ProblemDetails 相关的序列化代码
2. 确保为 JSON 序列化配置了适当的命名策略
3. 测试 API 的错误响应是否仍然符合预期格式
4. 考虑在全局配置中统一设置 JsonSerializerOptions

这一变更是 ASP.NET Core 8.0 中众多性能优化和简化的一部分，虽然需要少量迁移工作，但长期来看将使您的代码更加标准化和可维护。

docs This repository contains .NET Documentation. 项目地址: https://gitcode.com/gh_mirrors/docs2/docs