C#のserializationでjsonへ変換！データ保存の基本を解説

web API連携や設定保存、ログ出力など、データを扱うC#アプリケーションではjson形式への変換が不可欠です。serializationとdeserializationを正しく設計しなければ、パフォーマンスの低下や予期しない動作を招くことがあります。この記事ではSystem.Text.JsonやNewtonsoft.Jsonの使いどころ、属性やオプションの設定、最新のソース生成(source generation)など、jsonへの変換に関する基礎から応用までを網羅的に解説します。変換処理を最適化したい方やjson操作で迷っている方に有益な内容です。

C# serialization json 変換とは何か

まずは「C# serialization json 変換」が具体的に示す意味を整理します。serializationとは、C#のオブジェクトをjson文字列などに変換する処理で、変換とはこのserializationや逆のdeserializationのプロセスを指すことが多いです。jsonは軽量で可読性が高いため、多くのシステムでデータ形式として採用されます。C#では標準ライブラリと外部ライブラリの両方が利用可能で、それぞれ特徴があります。

C#の変換処理を使う場面として、ファイル保存、データベース、通信APIとのやりとり、ログ記録などがあり、それぞれに適した設定が求められます。jsonの型安全性、プロパティ名のマッピング、nullや既定値の処理、形式整形（インデントなど）のオプションが重要です。正しく設定することで、可読性・保守性・性能をバランスよく保てます。

JSONとは何か／なぜ使われるか

jsonはJavaScript Object Notationの略で、キーと値の組み合わせで構成されたテキスト形式のデータ表現です。軽量で人間にも読みやすく機械でも処理しやすいため、通信・設定・データ保存で広く使われています。XMLに比べて冗長性が少ないこと、パース・生成処理が高速でライブラリが豊富なことがその理由です。

C#ではjson形式を扱うライブラリが標準で提供されており、新たにパッケージを追加しなくても使えるものがあるため、プロジェクトの依存を減らしやすい点もメリットです。軽量なデータ交換や設定ファイルとしてjsonを選ぶケースが多くなっています。

C#でのserializationとdeserializationの基本

C#でserialization（オブジェクト→json）とdeserialization（json→オブジェクト）を行うには、publicプロパティを持つクラスやレコードを定義し、それをライブラリに渡します。System.Text.JsonのJsonSerializerや、Newtonsoft.JsonのJsonConvertが典型例です。例として、オブジェクトをjson文字列に変換するserializeメソッドと、jsonを読み込んでオブジェクトに戻すdeserializeメソッドを使います。

デシリアライズ時には型の安全性と例外処理も重要です。json入力が不正な場合や型不一致が起きた場合はJsonExceptionなどを捕捉し、データの整合性を保つことが望まれます。必須プロパティを使う記述により、入力jsonに期待するキーがないときに例外が発生する設定も可能です。

C# serialization json 変換が抱える課題

json変換に際し、次のような問題がしばしば発生します。まず、命名規約の不一致。C#ではPascalCaseが標準ですが、jsonではcamelCaseやsnake_caseが使われることが多く、対応を忘れるとjsonとC#間のマッピングで不整合が生じます。

また、null値や既定値(default)の扱い、数値を文字列として扱う必要があるケース、コメントや末尾のカンマなどjsonのフォーマットのバリエーションへの対応、動的型のjson構造を扱う必要性など、多様な要件があります。これらを意図的に扱わないと、変換の結果が予期せぬものになります。

主要なjson変換ライブラリの比較と選び方

C#における主要なjson変換ライブラリとして、標準機能であるSystem.Text.Jsonと外部で歴史が長いNewtonsoft.Jsonが挙げられます。それぞれ性能や機能に強みがありますので、プロジェクトの要件に応じて使い分けることが重要です。変換速度や依存性、動的構造の扱いやすさなどを考慮します。

System.Text.Jsonの特徴と利点

System.Text.Jsonは.NET Core 3以降および新しい.NETバージョンに標準で組み込まれており、追加の依存なく利用できる点が大きなメリットです。変換速度が高速で、メモリ使用量も少ないというベンチマーク結果があり、通常のAPI応答などで高い性能を発揮します。最新バージョンでは出力のフォーマットオプションも拡張されています。

さらに、ソース生成(source generation)機能を用いれば、コンパイル時に属性や型情報を生成し、実行時のリフレクションコストを削減できるため、スタートアップ時間やメモリ使用量の改善が見込めます。標準的な命名規則のポリシーやnull値の扱い、コメントの許容などのオプションも充実しています。

Newtonsoft.Jsonの特徴と利点

Newtonsoft.Jsonは長く使われてきた成熟したライブラリで、LINQ-to-JSON機能(JObject/JToken)、動的型のjson操作、柔軟なカスタムコンバータの追加など、多くの高度な機能があります。既存のプロジェクトや、複雑なjson構造を扱う必要がある場面では依然として有力な選択肢です。

デシリアライズ時の型不一致への対応や、カスタム属性での制御、古い.NET Frameworkとの互換性も強みです。標準ライブラリよりも柔軟性が高いため、動的構造を解析したい、未知のjsonフィールドを動的に処理したいといった要件のある場合に適しています。

性能比較と選びどころ

性能面ではSystem.Text.Jsonが高速かつ低メモリ使用であり、一般的なシリアライズ／デシリアライズ用途では標準で充分なケースが多くなっています。表形式で主要な違いをまとめると次の通りです。

選びどころとしては、新規プロジェクトであればSystem.Text.Jsonをまず検討し、特殊なjson構造や動的解析の要件があればNewtonsoft.Jsonを追加検討するのが一般的です。

実践：C#でjsonへ変換する方法とオプション設定

ここでは具体的なコード例とオプション設定を通じて、C#でオブジェクトをjsonに変換する方法を解説します。標準のjson変換メソッド、属性による制御、ソース生成、enum／静的メンバーなど特殊なケースへの対応方法を含めた設計例を提示します。

基本的なSerialize／Deserializeの使い方

System.Text.Jsonを使う場合、通常はJsonSerializer.Serialize と JsonSerializer.Deserialize を使います。例として、次のようなrecordやクラス定義を用意し、json文字列へシリアライズし、逆にjsonからオブジェクトを復元する流れです。非同期I/Oを使うこともでき、ストリームやUtf8バイト列を直接処理することで文字列の中間生成を抑えることが重要です。

例：

public record UserDto(string Name, string Email, int Age);

var user = new UserDto("Taro", "taro@example", 28);

string json = JsonSerializer.Serialize(user);

UserDto? obj = JsonSerializer.Deserialize(json);

このように型安全性とnullチェックを含めた処理を設計することが基本です。

属性での制御：JsonPropertyName・JsonIgnoreなど

プロパティ名をjsonのキーに別名で出したい場合は、System.Text.JsonではJsonPropertyName属性、Newtonsoft.JsonではJsonProperty属性を使います。プロパティをjsonに含めたくない場合はJsonIgnore属性を適用します。jsonキーとC#プロパティの命名規約が一致しないケースで必須となることがあります。

また、null値や既定値のプロパティを出力から省略したり、enumの文字列形式変換なども属性やオプションで制御できます。これによりjsonの可読性が増し、データ量削減やAPIとの互換性確保に繋がります。

JsonSerializerOptionsでの詳細設定

変換処理全体に影響を与える設定はJsonSerializerOptionsで行います。命名ポリシー、null処理、コメント読み込み許可、末尾のカンマ対応、数値の文字列読み替え、インデントの有無などが主な設定項目です。オプションをstatic readonlyで一度生成し再利用することで性能劣化を防ぎます。オプションを毎回新しく生成するとキャッシュ構築が繰り返されるためコストが高くなります。

例：

static readonly JsonSerializerOptions s_options = new()
{
  PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
  PropertyNameCaseInsensitive = true,
  DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
  AllowTrailingCommas = true,
  ReadCommentHandling = JsonCommentHandling.Skip,
  NumberHandling = JsonNumberHandling.AllowReadingFromString,
  WriteIndented = true
};

source generationを使った高速化アプローチ

json変換で性能が重要な場面では、source generationを活用することが推奨されます。これは型情報や属性情報をコンパイル時にコード生成し、リフレクションを抑えることで高速化やメモリ効率の改善を図るものです。標準のメタデータベースモードとシリアライズ最適化モードなどがあり、用途に応じて選択できます。

ただし、最適化モードではすべてのオプションや属性がサポートされない場合があります。たとえばカスタムコンバータや動的型、参照ハンドリングなどは制限されることがあるため、テストを通じて動作を確認することが大切です。

特殊ケース：enum・静的メンバーなどの取り扱い

enum型をjson文字列として表現したい場合は、文字列コンバータを使用したり属性を適用したりします。System.Text.Jsonでは標準のJsonStringEnumConverterやカスタムConverterを定義してenum→文字列やその逆を制御できます。整数として扱うのがデフォルトですが、多くのAPI連携では文字列形式が望まれます。

静的プロパティや定数メンバーは通常のserializeでは出力されませんが、最新のオプション設定でTypeInfoResolverを使って静的プロパティを含めるように変更可能です。デシリアライズは未実装のケースもあるため、読み込み側では注意が必要です。

トラブルシューティング：よくある問題と解決策

json変換（serialization / deserialization）を行う際、エラーや意図しない結果が返ってくることがあります。ここでは典型的な問題とそれぞれの解決策を示します。

プロパティが出力されない／読み込まれない

publicプロパティでない、getterまたはsetterがprivate、属性が適切に指定されていないなどが原因です。System.Text.Jsonではデフォルトでpublicかつpublicなgetterとsetterを持つプロパティのみ対象となります。属性で制御したい場合、JsonInclude属性を用いるか、プロパティ設定を変更する必要があります。

また、命名規則（camelCase vs PascalCase）が一致しないケースではPropertyNamingPolicyやJsonPropertyName属性でキー名を合わせる必要があります。読み込み時に大文字小文字を無視する設定(PropertyNameCaseInsensitive)も有効です。

数値・日付・nullの表現での問題

jsonにおける数値を文字列として扱っているjsonをデシリアライズする場合、NumberHandlingオプションでAllowReadingFromStringを設定することで対応可能です。日付型ではDateOnly/TimeOnlyが新しく導入され、フォーマットが標準化されていないケースがあるため、カスタムConverterで書式を指定することが望まれます。

nullや省略可能なプロパティにはDefaultIgnoreConditionをWhenWritingNullに設定することで出力から除外できます。読み込み時にnull許容型としてNullableやnullable annotationsを適切に使用することで型安全性を高められます。

フォーマットの不一致・互換性問題

jsonのキー命名規則、インデントの有無、コメントや末尾カンマの許可などフォーマット仕様が異なるシステム間で互換性の問題が生じることがあります。System.Text.JsonとNewtonsoft.Jsonで仕様が異なる箇所があるため、相互運用や移行時には仕様書およびテストを通して確認が必要です。

また、ソース生成モードでは一部のオプションや属性がサポートされていないため、その制限による挙動の変化に注意してください。モードを切り替える場合はSerialize最適化モードかメタデータモードかを明確に理解して選ぶことが望まれます。

最新動向と新機能：変換の効率化と機能拡張

json変換処理は日々進化しており、新しい.NETバージョンではフォーマットオプションや性能最適化機能が追加されています。ここでは最新の機能を紹介し、どのように活用できるかを解説します。

新しいフォーマットオプションの追加

.NET 9では、デフォルトのjson出力形式に関する新しいフォーマットオプションが導入されています。日付型フォーマットやインデント設定など、従来よりも柔軟にjson出力形式を制御できるようになっており、フォーマットの整形や可読性向上に役立ちます。これにより、API仕様書やログ出力の要件に応じて細かい調整がしやすくなっています。

性能改善とソース生成の進化

最新のjson変換処理では、ソース生成のmetadataベースとserialization最適化モードが強化され、起動時のメタデータ収集時間やメモリ使用量の改善が報告されています。最適化モードでは、書き込み方向の高速パスが特に効果を示します。ただし、すべての属性や機能が最適化モードでサポートされているわけではないため、要件との照合が不可欠です。

Web API・ASP.NET Coreとの統合

ASP.NET Coreや最小API(minimal API)では、json変換オプションをグローバル設定する仕組みが提供されています。コントローラーのJsonOptions設定やHttpResponseへのjsonシリアライズを行う際の既定設定を統一することで、プロジェクト全体で一貫した変換ルールを適用できます。こうしたグローバル設定は可読性や保守性を高め、バグを減らす効果があります。

実務への応用例：設計と最適化のヒント

これまで得た知見をもとに、実務でjson変換処理を設計・最適化する際のヒントを紹介します。開発・保守・パフォーマンス・関係者との整合性すべてを考慮した最適な設計に役立ちます。

プロジェクト開始時の設計のポイント

プロジェクトを始める段階で命名規則、null許容の設計、日付やenumの表現方法を仕様として決めておくと後で修正するコストが減ります。変換オプションをグローバルに設定し、全域で一致させることで統一性が保てます。動的なjson構造を扱う場合はNewtonsoft.Jsonの活用を検討し、標準変換で足りる場合はSystem.Text.Jsonを選ぶ設計指針を定めます。

パフォーマンスを意識した実装

高速なjson変換のためにはソース生成を利用し、オプションインスタンスを使い回すことが重要です。中間文字列の生成を抑えるために、ストリームやUtf8バイト列を直接扱う方法を採用するとよいです。また、WriteIndentedを多用するとサイズ・CPU使用量が増えるため、開発時／本番時で使い分けることをおすすめします。

テストと互換性保証のためのチェックリスト

仕様に対して以下のチェックを行っておくとトラブルを減らせます：

• 対象jsonの構造が仕様通りか、テストデータで確認する
• 命名規則の変換が正しく行われているか
• 必須プロパティがないときの挙動が期待通りか
• null値・既定値・enum・日付など特殊型の扱いが仕様通りか
• 互換性のあるjson入力を受け入れられるか（末尾カンマ・コメントへの対応など）

移行時の注意点（Newtonsoft.Json → System.Text.Jsonなど）

既存プロジェクトでNewtonsoft.Jsonを使っていたものをSystem.Text.Jsonに移行する場合、属性やオプションの対応差異を把握する必要があります。例えばLINQ-to-JSONやJToken、コメント付きjson、動的解析などがSystem.Text.Jsonでは制限されるケースがあります。これらを代替する設計や必要な機能の取捨選択を行ってから移行計画を立てることが重要です。

まとめ

「C# serialization json 変換」は、C#アプリケーションにおいてデータの保存・交換を行ううえで欠かせない技術です。標準で提供されるSystem.Text.Jsonと歴史と柔軟性のあるNewtonsoft.Jsonの両方を理解し、用途に応じて使い分けることが最善策です。

最新のフォーマットオプションやsource generationのような性能改善機能を活用することで、大規模アプリケーションでも高速かつメモリ効率の良いjson変換処理が可能になります。設計段階で変換ルールを固め、テストを重ね、互換性と読みやすさを忘れずに保つことが、変換処理の品質を高める鍵です。