2026年5月5日に確認された「.NET documentation update: update AGENTS.md file for System.Text.Json」は、.NETアプリの実行時動作を直接変える更新ではなく、System.Text.Jsonに関するドキュメントおよびAIエージェント向け参照情報の整理として読むべき内容です。
ただし、AGENTS.mdにまとめられている内容には、.NET 10のSystem.Text.Jsonで確認すべき新API、破壊的変更、移行時の注意点が含まれています。特に、.NET 10へ移行予定のチーム、外部JSONを受け取るAPI、Native AOTやトリミング対応を進めているプロジェクトは、早めに設定とテストを見直す価値があります。
今回のポイントは、AGENTS.mdというファイル名の変更だけではありません。JsonSerializerOptions.Strict、重複プロパティの扱い、PipeReader対応、ソース生成でのReferenceHandler指定、メタデータプロパティ名の競合チェックなど、System.Text.Jsonを実務で使ううえで影響しやすい論点が一つに整理されています。PR自体はGitHub上でDraftとして表示されているため、最終確定情報としてではなく、移行準備のチェックリストとして活用するのが安全です。(GitHub)
今回の.NET documentation updateで変わったこと
今回の更新は、dotnet/docsリポジトリのPull Request #52302に含まれる「System.Text.Json向けAGENTS.md」の追加が中心です。Files changedでは、docs/standard/serialization/system-text-json/AGENTS.mdが新規追加され、従来のllms.txtが削除対象として表示されています。追加されたAGENTS.mdには、System.Text.Jsonの概要、.NET 10の新API、破壊的変更、ベストプラクティスが短くまとめられています。(GitHub)
AGENTS.mdは、一般的にはAIコーディングエージェントにプロジェクトの文脈や作業ルールを伝えるためのMarkdownファイルとして使われます。人間向けのREADMEとは別に、ビルド手順、テスト方針、コード規約、注意点などをエージェント向けに整理する位置づけです。(エージェント.md)
つまり今回の変更は、.NETランタイムやSystem.Text.Jsonパッケージの即時アップデートではなく、AIエージェントやドキュメント生成・評価で参照しやすい形にSystem.Text.Jsonの重要情報を再編する更新と捉えると分かりやすいです。
| 確認項目 | 内容 | 実務での見方 |
|---|---|---|
| AGENTS.mdの追加 | System.Text.Json向けの要約ドキュメントを追加 | AIエージェントやドキュメントレビュー向けの参照情報 |
| llms.txtの削除 | 旧ファイルを置き換える流れ | ファイル名・運用形式の変更に注意 |
| .NET 10新APIの整理 | Strict、AllowDuplicateProperties、PipeReader対応など | .NET 10移行時の確認対象 |
| 破壊的変更の明記 | メタデータプロパティ名との競合検証 | 多態性・参照保持を使うモデルで要確認 |
| ベストプラクティス | Options再利用、ソース生成、UTF-8出力など | 既存コードの品質改善ポイント |
まず対応すべき人、様子見でよい人
この更新を見て、すべての.NET開発者がすぐコードを変更する必要はありません。影響が大きいのは、System.Text.Jsonを使っているうえで、.NET 10への移行、API境界でのJSON検証、Native AOT対応、AI支援開発の整備を進めているチームです。
| 対象 | 対応優先度 | 理由 |
|---|---|---|
| .NET 10へ移行予定のWeb API・バックエンド | 高 | Strict設定や重複プロパティ検出、破壊的変更の影響を受ける可能性がある |
| 外部からJSONを受け取るAPI | 高 | 重複キーや未知プロパティを許容すると、意図しない値で処理されるリスクがある |
多態性、ReferenceHandler.Preserve、循環参照を使うコード | 高 | $type、$id、$refなどのメタデータ名競合を確認すべき |
| Native AOT、トリミング対応アプリ | 中〜高 | リフレクション依存を減らし、ソース生成へ寄せる必要がある |
| .NET 8や.NET 9で安定運用中のアプリ | 中 | すぐ修正は不要でも、移行前テストの観点として押さえるべき |
| AIエージェントに.NETコード調査や移行を任せるチーム | 中 | AGENTS.mdにより、エージェントが参照する前提情報が変わる可能性がある |
System.Text.Jsonで確認すべき.NET 10の新API
AGENTS.mdに記載された新APIは、Microsoftの.NET 10ライブラリ更新情報でもSerialization項目として整理されています。主な内容は、JsonSourceGenerationOptionsAttributeでのReferenceHandler指定、重複JSONプロパティを許可しないオプション、StrictなJSONシリアライズ設定、PipeReaderからの直接デシリアライズです。(GitHub)
JsonSerializerOptions.Strictは新規開発で検討したい設定
JsonSerializerOptions.Strictは、従来より厳格なJSON処理を行うためのプリセットです。Microsoftの説明では、未知メンバーを許可しない設定、重複プロパティの無効化、大文字小文字を区別したバインド、nullable注釈や必須コンストラクタパラメータの尊重などが含まれます。(GitHub)
実務では、既存APIにいきなり全面適用するより、次のような場面で段階的に使うのが現実的です。
| 使いどころ | 判断基準 |
|---|---|
| 新規API | クライアントとの契約を厳密にしたい場合に向く |
| 管理画面・社内API | 入力元を制御しやすく、早期に不正データを検出しやすい |
| 外部公開API | 既存クライアントが未知プロパティや大小文字違いを送っていないか事前検証が必要 |
| レガシー移行 | まずテスト環境でエラー件数を把握してから適用する |
例として、.NET 10以降で新規APIの入力検証を厳しくしたい場合は、次のような方向で検討できます。
using System.Text.Json;
public static class JsonSettings
{
public static readonly JsonSerializerOptions StrictApiJson =
JsonSerializerOptions.Strict;
}
var dto = JsonSerializer.Deserialize<OrderRequest>(
json,
JsonSettings.StrictApiJson);注意点は、Strict化によって「いままで何となく通っていたJSON」がエラーになる可能性があることです。特に、クライアントが余分なプロパティを送っている、nullableではない値にnullを送っている、コンストラクタ引数が不足している、といったケースは移行時に見つかりやすいポイントです。
AllowDuplicatePropertiesは外部入力の安全性に関わる
JSONでは、同じオブジェクト内に同名プロパティが複数回登場するケースがあります。Microsoftの.NET 10更新情報では、JsonSerializerOptions.AllowDuplicatePropertiesを使って重複JSONプロパティを許可しない設定が紹介されており、falseにすると重複が検出されたときにJsonExceptionが発生します。(GitHub)
たとえば、次のようなJSONは見た目以上に危険です。
{
"role": "user",
"role": "admin"
}最後の値が採用される実装に依存していると、ログや画面表示ではuserに見えても、実処理ではadminとして扱われるような誤解が起きる可能性があります。外部入力、Webhook、認可情報を含むJSONでは、重複プロパティを許可しない設定を検討すべきです。
using System.Text.Json;
var options = new JsonSerializerOptions
{
AllowDuplicateProperties = false
};
var request = JsonSerializer.Deserialize<LoginRequest>(json, options);既存APIに導入する場合は、最初から本番で拒否するのではなく、テスト環境やログ収集で「実際に重複キーが届いているか」を確認してから段階的に適用すると安全です。
PipeReader対応は高スループット処理で効く
.NET 10のSystem.Text.Jsonでは、PipeReaderから直接デシリアライズできるAPIが追加されています。これまではPipeReaderをStreamに変換してから処理する必要がありましたが、新しいオーバーロードにより、パイプライン上のデータをそのままJSONデシリアライズへ渡しやすくなります。(GitHub)
この変更が特に役立つのは、次のようなケースです。
| 活用シーン | 期待できる効果 |
|---|---|
| 高頻度のネットワーク受信処理 | 余計な変換を減らしやすい |
| ストリーミング処理 | チャンク単位のデータ処理と相性がよい |
| ASP.NET Coreの内部処理に近い設計 | System.IO.Pipelinesを使った設計と合わせやすい |
| 大量JSONを扱うバックエンド | メモリ割り当てや変換コストを抑えやすい |
ただし、通常の業務アプリでStreamや文字列ベースの処理がボトルネックになっていないなら、優先度は高くありません。まずは既存のJSON処理でCPU、割り当て、レイテンシのどこが詰まっているかを測定してから採用を判断しましょう。
ソース生成でReferenceHandlerを指定しやすくなる
.NET 10の更新情報では、JSONシリアライズのソース生成でJsonSourceGenerationOptionsAttributeにReferenceHandlerを指定できるようになる点も挙げられています。循環参照や参照保持を扱うモデルでは、実行時オプションだけでなく、生成コンテキスト側に方針を寄せられるため、AOTやトリミング対応時の設計が整理しやすくなります。(GitHub)
Native AOTやトリミングを意識するアプリでは、System.Text.Jsonのソース生成が重要です。Microsoft Learnでは、System.Text.Jsonのソース生成はパフォーマンス向上、メモリ使用量削減、トリミング容易化に役立ち、Native AOTアプリでは特定のリフレクションAPIが使えないためソース生成が必要になると説明されています。([Microsoft Learn][5])
基本形は次のようになります。
using System.Text.Json.Serialization;
[JsonSerializable(typeof(OrderRequest))]
[JsonSerializable(typeof(OrderResponse))]
internal partial class AppJsonContext : JsonSerializerContext
{
}AOT対応で失敗しやすいのは、object型のプロパティや、実行時に型が決まる多態的なデータです。Microsoft Learnのソース生成ガイドでも、objectとして宣言されたメンバーでは実行時型を明示的に指定する必要がある例が示されています。([Microsoft Learn][6])
破壊的変更：メタデータプロパティ名の競合チェック
今回の更新で最も移行時に注意したいのは、System.Text.Jsonがメタデータプロパティ名との競合を検証するようになる点です。Microsoftの互換性ドキュメントでは、System.Text.Jsonは多態性や参照保持の文脈で$type、$id、$refなどの名前をメタデータ出力に使い、.NET 10以降はユーザー定義プロパティ名との競合を検証すると説明されています。(GitHub)
たとえば、次のような設計は注意が必要です。
using System.Text.Json.Serialization;
[JsonPolymorphic(TypeDiscriminatorPropertyName = "Type")]
[JsonDerivedType(typeof(Dog), "dog")]
public abstract class Animal
{
public string Type { get; init; } = "";
}
public sealed class Dog : Animal
{
public string Name { get; init; } = "";
}この例では、多態性の型識別子としてTypeを使っている一方で、モデルにもTypeプロパティがあります。こうした競合は、以前は重複プロパティを含む曖昧なJSONを生む可能性がありました。新しい挙動では、早い段階でInvalidOperationExceptionとして検出されるため、問題を開発時に見つけやすくなります。(GitHub)
修正方針は主に2つです。
| 修正方法 | 向いているケース | 注意点 |
|---|---|---|
| プロパティ名を変更する | API契約を変更できる場合 | クライアント側のJSON名も変わる可能性がある |
[JsonIgnore]を付ける | 内部的な補助プロパティでJSON出力が不要な場合 | 入出力に必要な値を無視しないよう確認する |
using System.Text.Json.Serialization;
[JsonPolymorphic(TypeDiscriminatorPropertyName = "Type")]
[JsonDerivedType(typeof(Dog), "dog")]
public abstract class Animal
{
[JsonIgnore]
public string Type => GetType().Name;
}多態性、循環参照、参照保持を使っていない単純なDTOでは影響が小さい可能性があります。一方で、ドメインモデルをそのままJSON化しているアプリや、古いAPI仕様に合わせてType、$type、id系の名前を多用しているアプリでは、.NET 10移行前にテストで洗い出すべきです。
移行前に確認するべき設定とコード
System.Text.Jsonの変更確認では、単に「ビルドが通るか」だけでは不十分です。JSONはAPI契約そのものなので、データの受け取り方、エラーの出方、ログ、クライアント互換性まで確認する必要があります。
JsonSerializerOptionsを毎回newしていないか
AGENTS.mdのベストプラクティスには、JsonSerializerOptionsインスタンスを再利用することが含まれています。これは一般的な性能改善としても重要です。MicrosoftのCA1869ルールでは、ローカルのJsonSerializerOptionsを1回だけ使うと、System.Text.Jsonがそのインスタンスにキャッシュするシリアル化関連メタデータを活かせず、繰り返し実行時に性能が大きく低下する可能性があると説明されています。(Microsoft Learn)
避けたい例は次のようなコードです。
public string ToJson(Order order)
{
var options = new JsonSerializerOptions
{
WriteIndented = true
};
return JsonSerializer.Serialize(order, options);
}改善例です。
public static class JsonSettings
{
public static readonly JsonSerializerOptions WriteOptions = new()
{
WriteIndented = true
};
}
public string ToJson(Order order)
{
return JsonSerializer.Serialize(order, JsonSettings.WriteOptions);
}ただし、リクエストごとに異なる設定が必要な場合まで無理に共有する必要はありません。共通設定は共有し、ユーザー入力やテナント設定に応じて変わるものは別管理にする、という線引きが現実的です。
Strictを全体適用する前にテストケースを増やす
JsonSerializerOptions.Strictは魅力的ですが、既存システムで急に全体適用すると、これまで許容していたJSONがエラーになる可能性があります。特に確認したいのは次のケースです。
| テストすべきJSON | 起きやすい問題 |
|---|---|
| 未知プロパティを含むJSON | Strict設定で拒否される可能性がある |
| 大文字小文字が異なるプロパティ名 | ケースセンシティブな扱いでバインドされない可能性がある |
nullを含むJSON | nullable注釈との不整合が見つかる可能性がある |
| 必須コンストラクタ引数が欠けたJSON | デシリアライズ時にエラーになる可能性がある |
| 重複プロパティを含むJSON | AllowDuplicateProperties無効化で拒否される |
移行の基本は、まずテスト環境でStrict相当の設定を使い、失敗したリクエストを分類することです。分類すると、「クライアント側を直すべきもの」と「サーバー側で互換性を残すべきもの」を判断しやすくなります。
Newtonsoft.Jsonからの移行プロジェクトは挙動差を再確認する
System.Text.Jsonは、Newtonsoft.Jsonと完全互換ではありません。たとえば、プロパティ名の大文字小文字、コメントや末尾カンマの扱い、コンバーターの書き方、多態性の扱いは差が出やすい領域です。
今回のAGENTS.md更新をきっかけに、Newtonsoft.JsonからSystem.Text.Jsonへ移行中のプロジェクトでは、次の観点を再確認してください。
| 確認観点 | 見るべきコード |
|---|---|
| 大文字小文字の扱い | PropertyNameCaseInsensitive、Web既定値 |
| 日付・数値の形式 | JsonNumberHandling、独自コンバーター |
| 多態性 | JsonPolymorphic、JsonDerivedType、型識別子 |
| 循環参照 | ReferenceHandler.Preserve、ソース生成設定 |
| 例外処理 | JsonException、InvalidOperationExceptionのログ出力 |
実務向けチェックリスト
移行や設定確認では、次の順番で見ると手戻りが少なくなります。
| 手順 | 作業 | 完了条件 |
| -: | ——————————— | ——————————————————————— |
| 1 | 対象プロジェクトの.NETバージョンを確認する | .NET 10移行対象か、当面.NET 8/9維持かを分ける |
| 2 | System.Text.Jsonの使用箇所を洗い出す | JsonSerializer.Serialize、Deserialize、JsonSerializerOptionsを検索する |
| 3 | JsonSerializerOptionsの生成方法を確認する | 毎回newしている箇所を共有インスタンスへ寄せる |
| 4 | 外部入力JSONの重複キーを確認する | テストまたはログで重複プロパティの有無を確認する |
| 5 | 多態性・参照保持の設定を確認する | $type、$id、$ref、TypeDiscriminatorPropertyNameとの競合を洗い出す |
| 6 | Strict適用の可否を判断する | 新規APIから適用するか、既存APIは段階導入にする |
| 7 | AOT・トリミング対応を確認する | JsonSerializerContextとJsonSerializableの定義漏れをなくす |
| 8 | 本番反映前に契約テストを実行する | クライアント互換性、エラー形式、ログを確認する |
検索コマンドの例です。
grep -R "JsonSerializer.Deserialize" -n ./src
grep -R "JsonSerializer.Serialize" -n ./src
grep -R "new JsonSerializerOptions" -n ./src
grep -R "JsonPolymorphic\|JsonDerivedType\|ReferenceHandler" -n ./srcWindows環境でPowerShellを使う場合は、次のように確認できます。
Select-String -Path .\src\**\*.cs -Pattern "JsonSerializer.Deserialize","JsonSerializer.Serialize","new JsonSerializerOptions","JsonPolymorphic","JsonDerivedType","ReferenceHandler"よくある失敗と回避策
ドキュメント更新だから何もしなくてよいと判断する
今回のPR自体はドキュメント更新ですが、内容には.NET 10移行時に影響するAPIや破壊的変更が含まれています。すぐにコードを変える必要がなくても、移行計画やテスト観点には反映しておくべきです。
Strict設定を本番APIに一括適用する
Strict設定は、データ品質を上げる一方で、既存クライアントの曖昧なJSONを拒否する可能性があります。まずは新規エンドポイントや内部APIから始め、既存APIではログ収集、テスト、クライアント調整を挟むのが安全です。
重複プロパティを「どうせ来ない」と考える
重複プロパティは、通常の画面操作では起きなくても、Webhook、外部連携、手書きJSON、攻撃的リクエストでは起こり得ます。認可、金額、権限、ステータスなど重要な値を含むJSONでは、AllowDuplicateProperties = falseを検討する価値があります。
AOT対応でDTOの指定漏れを起こす
ソース生成では、シリアル化・デシリアル化する型を[JsonSerializable]で指定する必要があります。特にobject、インターフェイス、多態性、コレクションの中身は漏れやすい箇所です。AOT対応では、実際にdotnet publishまで実行して確認しましょう。
パフォーマンス改善を測定せずに判断する
AGENTS.mdにはUTF-8出力やOptions再利用などのベストプラクティスが含まれていますが、性能改善はペイロードサイズ、呼び出し頻度、実行環境で変わります。SerializeToUtf8Bytes()のようなUTF-8ベースのAPIは、文字列変換を避けられる場面で有効ですが、導入前後で割り当て量と処理時間を測定することが重要です。
今回の更新をチームでどう扱うべきか
今回の「.NET documentation update: update AGENTS.md file for System.Text.Json」は、リリースノートのようにそのまま「全員対応」と判断するものではありません。チーム内では、次のように扱うと実務に落とし込みやすくなります。
| チームの状況 | 次にやること |
|---|---|
| .NET 10へ移行予定 | System.Text.Jsonの契約テストを移行タスクに追加する |
| APIのセキュリティを見直したい | 重複プロパティ拒否とStrict設定を検証する |
| Native AOT対応中 | ソース生成コンテキストの定義漏れを洗い出す |
| AIエージェントでコード調査している | AGENTS.mdの内容を前提に、System.Text.Jsonの確認指示を整備する |
| 現行バージョンを維持 | 破壊的変更と設定項目だけを移行メモに残す |
特におすすめなのは、.NET 10移行チェックリストの中に「System.Text.Json」の章を作ることです。そこに、重複プロパティ、Strict、メタデータ名競合、Options再利用、ソース生成の5項目を入れておけば、移行時の見落としをかなり減らせます。
まとめ：AGENTS.md更新は、System.Text.Json移行準備の合図として使う
今回の更新は、System.Text.Jsonの実装を直接変更するものではなく、dotnet/docs側でAGENTS.mdを追加し、AIエージェントやドキュメント参照向けに情報を整理する動きです。ただし、そこに含まれている.NET 10のSystem.Text.Json関連情報は、実務上かなり重要です。
まず確認すべきなのは、次の5点です。
- .NET 10移行予定があるか
JsonSerializerOptionsを毎回生成していないか- 外部入力JSONで重複プロパティを許容してよいか
- 多態性や参照保持でメタデータ名とモデルのプロパティ名が競合していないか
- Native AOTやトリミング対応でソース生成の定義漏れがないか
すぐに全設定を変える必要はありません。まずは使用箇所の棚卸し、テストケースの追加、Strictや重複プロパティ拒否の検証から始めるのが現実的です。System.Text.Jsonは単なるシリアライザーではなく、API契約とセキュリティ境界に関わる部品です。今回のAGENTS.md更新を、.NET 10移行前の点検タイミングとして活用しましょう。
[5]: https://learn.microsoft.com/ja-jp/dotnet/standard/serialization/system-text-json/reflection-vs-source-generation “
System.Text.Json でリフレクションまたはソース生成を選択する方法 – .NET | Microsoft Learn”
[6]: https://learn.microsoft.com/ja-jp/dotnet/standard/serialization/system-text-json/source-generation “
System.Text.Json でソース生成を使用する方法 – .NET | Microsoft Learn”
コメント