可空的 JsonDocument 属性会反序列化为 JsonValueKind.Null

2025-06-19

从 .NET 9 开始，将 null JSON 值反序列化为 JsonDocument 会产生类型为 JsonValueKind.Null 的非 Null 文档。

using System.Text.Json;

var doc = JsonSerializer.Deserialize<JsonDocument>("null");

// Returns true in .NET 8 and false in .NET 9.
Console.WriteLine(doc is null);

// Returns false in .NET 8 and true in .NET 9.
Console.WriteLine(doc is { RootElement.ValueKind: JsonValueKind.Null });

已引入的版本

.NET 9

以前的行为

在 .NET 8 及更早版本中，将 null JSON 值反序列化为 JsonDocument 会返回 null 结果。

var doc = JsonSerializer.Deserialize<JsonDocument>("null");
Console.WriteLine(doc is null); // True.

新行为

从 .NET 9 开始，将 null JSON 值反序列化为 JsonDocument 会返回非 null 实例而不是 JsonValueKind.Null。

var doc = JsonSerializer.Deserialize<JsonDocument>("null");
Console.WriteLine(doc is null); // False.
Console.WriteLine(doc is { RootElement.ValueKind: JsonValueKind.Null }); // True.

破坏性变更的类型

此更改为行为更改。

更改原因

此更改解决了根级 JSON null 和文档中嵌套的 null 之间的不一致问题。它还使 JsonDocument.Parse 方法的行为保持一致。返回 null 的行为被视为一个 bug，并进行了更新，以确保与预期结果一致。

建议的措施

将使用包含 JsonDocument 类型的反序列化对象的代码更新为预期的 JsonValueKind.Null 而不是 null。