ソース生成は、 メタデータベース と シリアル化の最適化の 2 つのモードで使用できます。 この記事では、さまざまなモードについて説明します。
ソース生成モードの使用方法については、「System.Text.Json でソース生成を使用する方法」を参照してください。
メタデータベースのモード
ソース生成を使用して、メタデータ収集プロセスをランタイムからコンパイル時に移動できます。 コンパイル中に、メタデータが収集され、ソース コード ファイルが生成されます。 生成されたソース コード ファイルは、アプリケーションの不可欠な部分として自動的にコンパイルされます。 この手法により、実行時メタデータ収集が不要になり、シリアル化と逆シリアル化の両方のパフォーマンスが向上します。
ソース生成によってパフォーマンスが大幅に改善する可能性があります。 たとえば、テスト結果には、最大で 40% 以上の起動時間の短縮、プライベート メモリの削減、スループット速度の増加 (シリアル化の最適化モードで)、アプリ サイズの縮小が示されています。
非公開メンバーとコンストラクター
既定では、リフレクション モードとソース生成モードの両方に、シリアル化コントラクト内の public プロパティとフィールドのみが含まれます。
.NET 11 以降、ソース生成では、[JsonInclude] 属性で明示的にマークするメンバーがサポートされています。 メンバーは、 private、 internal、または protectedできます。 また、[JsonInclude]でマークするプロパティのprivate、internal、およびprotectedアクセサーもサポートします。 ソース生成では、[ JsonConstructor] でマークされたアクセスできないコンストラクターもサポートされます。
.NET 11 では、生成されたアクセサーはUnsafeAccessorAttributeを使用します。
init専用プロパティのソース生成セッターは、JSON ペイロードにそのプロパティが含まれている場合にのみ実行されます。 ペイロードが省略する init専用プロパティは、プロパティ初期化子から値を保持します。
.NET 10 以前のバージョンでは、ソースの生成には次の制限があります。
- ソース生成では、
privateまたはprotectedメンバーまたはアクセサーはサポートされていません。 このようなメンバーを[JsonInclude]でマークすると、シリアライザーは実行時に NotSupportedException をスローします。 - ソース生成では、
internalメンバーとアクセサーは、同じアセンブリ内の生成された JsonSerializerContext にアクセスできる場合にのみサポートされます。 - ソース生成では、生成されたコンテキストにアクセスできないコンストラクターは、
[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。
次の表に、高速パス シリアル化でどの属性がサポートされているかを示します。
サポートされていないオプションまたは属性が型に対して指定されている場合、ソース ジェネレーターがメタデータを生成するように構成されていると仮定すると、シリアライザーは メタデータ モードにフォールバックします。 その場合、最適化されたコードはその型をシリアル化するときに使用されませんが、他の型に使用される可能性があります。 したがって、オプションとワークロードを使用してパフォーマンス テストを実行し、実際にシリアル化最適化モードから得られるベネフィットを判断することが重要です。 また、 JsonSerializer コードにフォールバックする機能には 、メタデータ モードが必要です。 シリアル化最適化モードのみを選択した場合、JsonSerializer コードへのフォールバックを必要とする型またはオプションについてはシリアル化が失敗する場合があります。
関連項目
GitHub で Microsoft と共同作業する
このコンテンツのソースは GitHub にあります。そこで、issue や pull request を作成および確認することもできます。 詳細については、共同作成者ガイドを参照してください。
.NET