System.Text.Json のソース生成のモード

ソース生成は、 メタデータベース と シリアル化の最適化の 2 つのモードで使用できます。 この記事では、さまざまなモードについて説明します。

ソース生成モードの使用方法については、「System.Text.Json でソース生成を使用する方法」を参照してください。

メタデータベースのモード

ソース生成を使用して、メタデータ収集プロセスをランタイムからコンパイル時に移動できます。 コンパイル中に、メタデータが収集され、ソース コード ファイルが生成されます。 生成されたソース コード ファイルは、アプリケーションの不可欠な部分として自動的にコンパイルされます。 この手法により、実行時メタデータ収集が不要になり、シリアル化と逆シリアル化の両方のパフォーマンスが向上します。

ソース生成によってパフォーマンスが大幅に改善する可能性があります。 たとえば、テスト結果には、最大で 40% 以上の起動時間の短縮、プライベート メモリの削減、スループット速度の増加 (シリアル化の最適化モードで)、アプリ サイズの縮小が示されています。

既知の問題

既定では、 public プロパティとフィールドのみがシリアル化モード (リフレクションまたはソース生成) でサポートされます。 ただし、リフレクション モードでは private メンバーの使用がサポートされますが、ソース生成モードではサポートされません。 たとえば、 JsonInclude 属性 を private プロパティまたは private セッターまたはゲッターを持つプロパティに適用すると、リフレクション モードでシリアル化されます。 ソース生成モードでは、 public または internal メンバーと、 public プロパティの internal アクセサーまたは public アクセサーのみがサポートされます。 [JsonInclude]メンバーまたはアクセサーにprivateを設定し、ソース生成モードを選択すると、実行時にNotSupportedExceptionがスローされます。

ソース生成に関するその他の既知の問題の詳細については、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 コードへのフォールバックを必要とする型またはオプションについてはシリアル化が失敗する場合があります。

関連項目

• .NET での JSON のシリアル化と逆シリアル化 - 概要
• ライブラリを使用する方法