System.Text.Json 中的源生成模式

源生成可用于两种模式: 基于元数据 和 序列化优化。 本文介绍不同的模式。

有关如何使用源生成模式的信息,请参阅如何在 System.Text.Json 中使用源生成。

基于元数据的模式

可以使用源生成将元数据收集过程从运行时移动到编译时间。 在编译期间,系统将收集元数据并生成源代码文件。 生成的源代码文件会自动编译为应用程序的一个整型部分。 此方法消除了运行时元数据集合,从而提高序列化和反序列化的性能。

源生成提供的性能改进可能很大。 例如,测试结果显示出可获得高达 40% 或更高的启动时间缩减、专用内存缩减、吞吐速度增加(在序列化优化模式下)和应用大小减小。

非公共成员和构造函数

默认情况下,反射模式和源生成模式都仅将 public 属性和字段包含在序列化契约中。

从 .NET 11 开始,源生成支持使用 [JsonInclude] 属性显式标记的成员。 成员可以是 private, internal也可以 protected。 它还支持用于使用 protected 标记的属性的 private、internal 和 [JsonInclude] 访问器。 源生成还支持使用 [JsonConstructor] 标记的不可访问构造函数。

在 .NET 11 上,生成的访问器使用 UnsafeAccessorAttribute。

仅当 JSON 负载中包含该属性时,源生成的仅限 init 的属性 setter 方法才会运行。 有效负载省略的仅 init 属性会保留其属性初始化表达式中的值。

在 .NET 10 及更早版本中,源生成具有以下限制:

  • 源生成不支持 private 或 protected 成员或访问器。 如果用 [JsonInclude] 标记此类成员,序列化程序会在运行时抛出 NotSupportedException。
  • 仅当 JsonSerializerContext 成员和访问器可被同一程序集中的生成的 internal 访问时,源生成才支持这些成员和访问器。
  • 源生成不支持对生成的上下文无法访问的构造函数,即使使用它们 [JsonConstructor]进行标记也是如此。

已知问题

有关源生成的其他已知问题的信息,请参阅 dotnet/runtime 存储库中标记为“source-generator”的 GitHub 问题。

序列化优化(快速路径)模式

JsonSerializer 具有许多自定义序列化输出的功能,例如命名策略和保留引用。 对所有这些功能的支持会导致一些性能开销。 源生成可以通过生成直接使用 Utf8JsonWriter 的优化代码来提高序列化性能。

序列化优化模式发出快速路径序列化方法,但不会发出序列化元数据。 快速路径序列化在可以执行的作中受到限制;它不支持异步序列化或任何反序列化模式。

此外,优化代码不支持 JsonSerializer 支持的所有序列化功能。 如果指定了不受支持的选项,则序列化程序将检测是否可以使用该优化代码并回退到默认序列化代码。 例如,JsonNumberHandling.AllowReadingFromString 不适用于写入,因此,指定此选项不会导致回退到默认代码。

下表显示了快速路径序列化所支持的 JsonSerializerOptions 中的选项:

序列化选项 支持快速路径
AllowTrailingCommas ✔️
Converters ❌
DefaultBufferSize ✔️
DefaultIgnoreCondition ✔️
DictionaryKeyPolicy ❌
Encoder ❌
IgnoreNullValues ❌
IgnoreReadOnlyFields ✔️
IgnoreReadOnlyProperties ✔️
IncludeFields ✔️
MaxDepth ✔️
NumberHandling ❌
PropertyNamingPolicy ✔️
ReferenceHandler ❌
TypeInfoResolver ✔️
WriteIndented ✔️

(由于以下选项仅适用于反序列化,因此不受支持:PropertyNameCaseInsensitive、ReadCommentHandling 和 UnknownTypeHandling。)

下表显示了快速路径序列化所支持的属性:

特征 支持快速路径
JsonConstructorAttribute ❌
JsonConverterAttribute ❌
JsonDerivedTypeAttribute ✔️
JsonExtensionDataAttribute ❌
JsonIgnoreAttribute ✔️
JsonIncludeAttribute ✔️
JsonNumberHandlingAttribute ❌
JsonPolymorphicAttribute ✔️
JsonPropertyNameAttribute ✔️
JsonPropertyOrderAttribute ✔️
JsonRequiredAttribute ✔️

如果为类型指定了不支持的选项或属性,则序列化程序会回退到 元数据模式,假设源生成器已配置为生成元数据。 在这种情况下,序列化该类型时不会使用优化的代码,但可能用于其他类型的代码。 因此,请务必使用选项和工作负载进行性能测试,以确定序列化优化模式实际可带来多少益处。 此外,回退到 JsonSerializer 代码的功能需要使用元数据模式。 如果只选择了序列化优化模式,则对于需要回退到 JsonSerializer 代码的类型或选项,序列化可能会失败。

另请参阅