C#でJSON操作をマスター！JsonSerializerの使い方を初心者向けに徹底解説

1. JSONとは何かをイメージで理解しよう

1. JSONとは何かをイメージで理解しよう

プログラミングの世界では、情報を整理して管理する必要があります。例えば、ある人の「名前」や「年齢」という情報を保存したいとき、どのような形式で書けばコンピューターが理解しやすいでしょうか。そこで登場するのがJSON（ジェイソン）です。

JSONは「JavaScript Object Notation」の略ですが、名前を覚える必要はありません。イメージとしては、「ラベル付きの箱」が並んでいる状態だと考えてください。例えば、名前が田中さんで年齢が20歳なら、{ "Name": "田中", "Age": 20 } という風に、名前と値をセットにして記述します。この形式は人間が見ても読みやすく、コンピューターにとっても扱いやすいため、現代のシステム開発では欠かせない技術となっています。

C#というプログラミング言語を使ってこのJSONを扱う場合、標準で用意されているSystem.Text.Jsonというライブラリ（便利な道具箱のようなもの）を使用するのが一般的です。これを使うことで、複雑な記述を自分で書かなくても、自動的に変換を行ってくれます。

2. シリアル化とデシリアル化という言葉の解説

2. シリアル化とデシリアル化という言葉の解説

JSON操作を学ぶ上で必ず出てくるのが「シリアル化」と「デシリアル化」という少し難しい言葉です。パソコンに詳しくない方でもわかるように、料理に例えて説明します。

シリアル化（シリアライズ）とは、プログラムの中で動いているデータ（料理）を、保存や送信ができるようにテキスト形式（レシピ）に変換することを指します。C#の中にあるオブジェクトという実体を、JSONという文字列に変換する作業です。

反対に、デシリアル化（デシリアライズ）とは、テキスト形式（レシピ）を読み込んで、再びプログラムの中で使えるデータ（料理）として復元することを指します。外部から受け取ったJSON文字列を、C#のクラスという設計図に当てはめて、プログラムが操作できる形に戻す作業です。

この二つの操作を自由自在に扱えるようになると、アプリの設定をファイルに保存したり、インターネットを通じて情報をやり取りしたりすることが可能になります。

3. データの設計図「クラス」を作成する

3. データの設計図「クラス」を作成する

C#でJSONを扱うには、まず「どんなデータを扱うか」という設計図を作る必要があります。これをクラスと呼びます。クラスは、情報の項目を定義したテンプレートのようなものです。

例えば、商品の情報を扱うプログラムを作るとしましょう。商品には「名前」と「価格」という項目が必要です。これをC#のコードで書くと以下のようになります。まずは基本となるデータの形を定義してみましょう。

public class Product
{
    // 商品の名前を入れるための項目
    public string Name { get; set; }
    
    // 商品の価格を入れるための項目
    public int Price { get; set; }
}

ここで出てくる public は「どこからでも使える」という意味、string は「文字」、int は「整数」を扱うための決まり文句です。この設計図があるおかげで、C#は「Nameという項目には文字が入り、Priceという項目には数字が入るんだな」と理解できるのです。

4. JsonSerializerでデータをJSONに変換する（シリアル化）

4. JsonSerializerでデータをJSONに変換する（シリアル化）

設計図ができたら、次は実際にデータを入れて、それをJSON形式の文字列に変換してみましょう。ここで使うのが JsonSerializer.Serialize という命令です。この一行を書くだけで、C#の複雑なデータが瞬時にテキストへと姿を変えます。

以下のコードは、先ほど作った「商品」の設計図に具体的な値（リンゴ、100円）を入れて、JSONに変換する例です。プログラムを動かす際は、ファイルの先頭に using System.Text.Json; と書くことを忘れないでください。これは「JSON操作の道具を使いますよ」という宣言です。

using System;
using System.Text.Json;

public class Program
{
    public static void Main()
    {
        // 1. 商品データを作成する
        Product myProduct = new Product
        {
            Name = "リンゴ",
            Price = 100
        };

        // 2. C#のデータをJSON文字列に変換（シリアル化）
        string jsonString = JsonSerializer.Serialize(myProduct);

        // 3. 画面に表示して確認
        Console.WriteLine(jsonString);
    }
}

public class Product
{
    public string Name { get; set; }
    public int Price { get; set; }
}

このプログラムを実行すると、以下のような結果が表示されます。

{"Name":"リンゴ","Price":100}

このように、波括弧で囲まれ、項目名と値がペアになった文字列が生成されます。これがJSONの正体です。

5. JSONを読み込んでデータに戻す方法（デシリアル化）

5. JSONを読み込んでデータに戻す方法（デシリアル化）

今度は逆に、JSON形式のテキストを読み込んで、C#のプログラムで計算や表示ができるように戻してみましょう。これには JsonSerializer.Deserialize という命令を使います。例えば、Webサイトから送られてきたデータや、ファイルに保存しておいたデータを読み出すときに使います。

デシリアル化を行うときは、どの設計図（クラス）に当てはめるかを指定する必要があります。以下の例では、文字列として用意したJSONデータを、再び Product クラスの形に復元しています。

using System;
using System.Text.Json;

public class Program
{
    public static void Main()
    {
        // 1. JSON形式のテキストを用意
        string jsonInput = "{\"Name\":\"オレンジ\",\"Price\":150}";

        // 2. JSON文字列をC#のオブジェクトに変換（デシリアル化）
        Product loadedProduct = JsonSerializer.Deserialize<Product>(jsonInput);

        // 3. 復元されたデータを使ってみる
        Console.WriteLine("商品名: " + loadedProduct.Name);
        Console.WriteLine("価格: " + loadedProduct.Price + "円");
    }
}

public class Product
{
    public string Name { get; set; }
    public int Price { get; set; }
}

実行結果は以下のようになります。テキストだったデータが、プログラムで自由に扱える形式に戻っていることがわかります。

商品名: オレンジ
価格: 150円

6. 日本語が文字化けしないように設定する方法

6. 日本語が文字化けしないように設定する方法

標準の JsonSerializer.Serialize をそのまま使うと、日本語（ひらがなや漢字）が「\u3042」のような特殊な記号（Unicodeエスケープ）に変換されてしまうことがあります。これはコンピューターが確実にデータを伝えるための仕組みですが、人間が見るには不便です。

日本語をそのままの見た目で出力したい場合は、オプション設定を追加します。JsonSerializerOptions というクラスを使い、エンコーダーを指定することで解決できます。少し呪文のように見えるかもしれませんが、定型文として覚えておくと便利です。

using System;
using System.Text.Json;
using System.Text.Encodings.Web;
using System.Text.Unicode;

public class Program
{
    public static void Main()
    {
        var person = new { Name = "佐藤", Message = "こんにちは" };

        // 日本語をエスケープせずに表示するための設定
        var options = new JsonSerializerOptions
        {
            Encoder = JavaScriptEncoder.Create(UnicodeRanges.All),
            WriteIndented = true // 見やすく改行を入れる設定
        };

        string json = JsonSerializer.Serialize(person, options);
        Console.WriteLine(json);
    }
}

この設定を行うことで、出力結果は以下のようになります。WriteIndented = true を加えたことで、改行が入って非常に読みやすくなっています。

{
  "Name": "佐藤",
  "Message": "こんにちは"
}

7. リストや配列をJSONにする方法

7. リストや配列をJSONにする方法

実際の開発では、一つのデータだけでなく、複数のデータをまとめて扱いたい場面が多くあります。C#では List という機能を使って複数のデータをひとまとめにできますが、これらもまとめてJSONに変換することが可能です。

例えば、複数の学生の成績データをまとめて保存したい場合を考えてみましょう。個別のデータをリストに追加していき、そのリスト全体をシリアル化するだけです。特別なループ処理などを自分で書く必要はありません。

using System;
using System.Collections.Generic;
using System.Text.Json;

public class Student
{
    public string Name { get; set; }
    public int Score { get; set; }
}

public class Program
{
    public static void Main()
    {
        // 学生のリストを作成
        List<Student> students = new List<Student>
        {
            new Student { Name = "田中", Score = 85 },
            new Student { Name = "鈴木", Score = 92 },
            new Student { Name = "伊藤", Score = 78 }
        };

        // リスト全体をJSONに変換
        string json = JsonSerializer.Serialize(students);
        Console.WriteLine(json);
    }
}

このように実行すると、全体が角括弧 [] で囲まれた形式で出力されます。これはJSONにおいて「配列（データの集まり）」を意味します。

[{"Name":"田中","Score":85},{"Name":"鈴木","Score":92},{"Name":"伊藤","Score":78}]

8. JSON操作でよくある失敗と注意点

8. JSON操作でよくある失敗と注意点

初心者がJSON操作でつまずきやすいポイントをいくつか紹介します。まず一つ目は、クラスのプロパティ（項目）に public を付け忘れることです。JsonSerializer は、公開されている項目しか見ることができません。非公開（private）になっていると、無視されてしまうので注意しましょう。

二つ目は、項目の名前が一致していないことです。JSONの中にある名前と、C#のクラスで定義した名前が異なると、デシリアル化（読み込み）のときにデータがうまく入りません。大文字と小文字も区別されるため、正確に合わせる必要があります。もし名前を変えたい場合は [JsonPropertyName("名前")] という属性を使って紐付けを行う方法もあります。

三つ目は、データの型が合っていない場合です。数字が入るべき場所に文字が入っているJSONを読み込もうとすると、エラーが発生してプログラムが止まってしまいます。データをやり取りする相手と、どのような形式にするかを事前にしっかり決めておくことが大切です。これらの基本を押さえておけば、JSON操作で困ることは格段に減るはずです。

まとめ

まとめ

C#でJSONを扱うときに中心となるのが、System.Text.Json名前空間に用意されているJsonSerializerです。JSONは、Web APIから受け取ったデータ、アプリケーションの設定情報、外部サービスとのデータ交換、ファイルへのデータ保存など、さまざまな場面で利用されるデータ形式です。C#のオブジェクトをJSON文字列へ変換する処理をシリアル化、JSON文字列をC#のオブジェクトへ戻す処理をデシリアル化と呼びます。まずは、この2つの方向を理解することがC#のJSON操作を学ぶ第1歩です。

JSONという名前だけを見ると難しそうに感じますが、基本的には項目名と値を組み合わせてデータを表現する仕組みです。例えば商品であれば商品名と価格、利用者であれば名前と年齢、学生であれば名前と点数というように、データが何を表しているのかを項目名によって分かりやすく整理できます。人間が読んでも比較的理解しやすく、異なるプログラミング言語の間でも利用しやすいため、現在のアプリケーション開発では非常によく使われています。

JsonSerializerで覚えたい基本はSerializeとDeserialize

C#のJsonSerializerを学習するときに、最初に覚えておきたいのがSerializeとDeserializeです。JsonSerializer.Serializeは、C#のオブジェクトをJSON形式の文字列へ変換します。反対にJsonSerializer.Deserializeは、JSON形式の文字列をC#のオブジェクトへ戻します。

SerializeはC#からJSONへ変換する処理、DeserializeはJSONからC#へ変換する処理と整理すると覚えやすくなります。どちらも実際の開発で頻繁に利用されるため、名前だけを暗記するのではなく、データがどちらの方向へ変換されているのかを意識することが大切です。

クラスとJSONの関係を理解することが重要

JsonSerializerを使うときには、JSONだけを見るのではなく、C#のクラスとの関係を理解することが重要です。クラスはデータの設計図であり、プロパティはデータを入れるための項目です。例えば商品情報ならNameとPriceを持つProductクラスを作ることで、商品名と価格をまとめて扱えるようになります。

次のプログラムでは、Productクラスから商品オブジェクトを作成し、そのオブジェクトをJSONへシリアル化しています。

using System;
using System.Text.Json;

public class Product
{
    public string Name { get; set; }
    public int Price { get; set; }
}

public class Program
{
    public static void Main()
    {
        Product product = new Product
        {
            Name = "リンゴ",
            Price = 120
        };

        string json = JsonSerializer.Serialize(product);

        Console.WriteLine(json);
    }
}

実行すると、C#のProductオブジェクトがJSON形式の文字列へ変換されます。

{"Name":"リンゴ","Price":120}

この例ではNameプロパティがJSONのNameという項目に、PriceプロパティがPriceという項目に対応しています。このように、C#側のクラスとJSONのデータ構造を対応させて考えることが、JsonSerializerを理解する重要なポイントです。

デシリアル化ではJSONをC#のオブジェクトへ戻す

Web APIやJSONファイルから受け取ったデータをC#で利用したい場合には、デシリアル化を行います。JsonSerializer.Deserializeを使うと、JSON文字列から指定した型のオブジェクトを作成できます。

using System;
using System.Text.Json;

public class Product
{
    public string Name { get; set; }
    public int Price { get; set; }
}

public class Program
{
    public static void Main()
    {
        string json = "{\"Name\":\"バナナ\",\"Price\":180}";

        Product product = JsonSerializer.Deserialize<Product>(json);

        if (product != null)
        {
            Console.WriteLine("商品名: " + product.Name);
            Console.WriteLine("価格: " + product.Price + "円");
        }
    }
}

商品名: バナナ
価格: 180円

デシリアル化すると、単なるJSON文字列だったデータをProductオブジェクトとして扱えるようになります。そのため、product.Nameのようにプロパティを指定して値を取り出したり、価格を計算に利用したりできます。

Deserializeの結果については、データが存在しない場合などを考慮してnullを確認することも大切です。JSONを読み込めたことと、アプリケーションが必要としているデータが正しくそろっていることは同じではありません。実際の開発では、変換後のデータについても必要な確認を行います。

複数のデータはListとJSON配列で扱える

JSONでは1件のオブジェクトだけでなく、複数件のデータも扱えます。例えば商品一覧、利用者一覧、学生一覧などをJSONとして表現できます。C#ではListなどのコレクションをシリアル化すると、JSON側では配列として表現されます。

using System;
using System.Collections.Generic;
using System.Text.Json;

public class Product
{
    public string Name { get; set; }
    public int Price { get; set; }
}

public class Program
{
    public static void Main()
    {
        List<Product> products = new List<Product>
        {
            new Product { Name = "リンゴ", Price = 120 },
            new Product { Name = "バナナ", Price = 180 },
            new Product { Name = "オレンジ", Price = 150 }
        };

        string json = JsonSerializer.Serialize(products);

        Console.WriteLine(json);
    }
}

[{"Name":"リンゴ","Price":120},{"Name":"バナナ","Price":180},{"Name":"オレンジ","Price":150}]

JSONで角括弧によって囲まれている部分は、複数のデータをまとめた配列を表します。C#側ではListなどを利用することで、このようなJSON配列を扱えます。Web APIから商品一覧や利用者一覧を受け取る場合にも同じ考え方を利用できます。

JsonSerializerOptionsでJSONの出力方法を変更できる

JsonSerializerにはJsonSerializerOptionsという設定用のクラスがあります。これを使うことで、JSONをどのような形式で出力するのかを調整できます。

代表的なのがWriteIndentedです。WriteIndentedを有効にすると、JSONに改行や字下げが追加され、人間が読みやすい形式になります。開発中にJSONの内容を確認したい場合や、設定ファイルとして人が直接読む場合に便利です。

var options = new JsonSerializerOptions
{
    WriteIndented = true
};

string json = JsonSerializer.Serialize(product, options);

Console.WriteLine(json);

{
  "Name": "リンゴ",
  "Price": 120
}

見やすいJSONは確認や修正には便利ですが、通信するときには改行や空白の分だけデータ量が増えます。そのため、常にWriteIndentedを有効にするのではなく、JSONを人が直接読む必要があるかどうかを考えて使い分けるとよいでしょう。

日本語のUnicodeエスケープは文字化けとは限らない

JsonSerializerで日本語を含むデータをシリアル化すると、日本語の一部がUnicodeエスケープという形式で出力されることがあります。見慣れない文字列が表示されるため、初心者は文字化けしたと考えてしまうことがありますが、必ずしもデータが壊れているわけではありません。

Unicodeエスケープは文字を別の表現で記録しているものです。人がJSONファイルを直接読む必要があり、日本語をそのまま表示したい場合には、JsonSerializerOptionsとエンコーダーの設定を利用できます。

JSONの見た目とデータの内容は分けて考えることが大切です。日本語がエスケープされて表示されていても、デシリアル化したC#のオブジェクトでは元の日本語として利用できる場合があります。

JsonPropertyNameでJSON側の項目名を指定できる

外部のWeb APIを利用すると、JSON側の項目名とC#側で使いたいプロパティ名が異なる場合があります。そのような場合にはJsonPropertyName属性を利用できます。

例えばJSONではproduct_nameという名前が決められているものの、C#ではProductNameという名前で扱いたい場合があります。JsonPropertyNameを利用すれば、JSON側とC#側で異なる名前を対応付けられます。

using System.Text.Json.Serialization;

public class Product
{
    [JsonPropertyName("product_name")]
    public string ProductName { get; set; }

    [JsonPropertyName("price")]
    public int Price { get; set; }
}

このような機能を利用すると、自分で変更できない外部サービスのJSON形式に合わせながら、C#側では分かりやすいプロパティ名を使用できます。Web APIと連携するC#アプリケーションでは覚えておくと便利な機能です。

大文字と小文字の違いを許可する設定もある

JSONの項目名とC#のプロパティ名では、大文字と小文字の違いが問題になる場合があります。外部から受け取るJSONの命名方法に対応したい場合には、JsonSerializerOptionsのPropertyNameCaseInsensitiveを利用して、大文字と小文字を区別せずにプロパティを照合する設定もできます。

var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true
};

Product product =
    JsonSerializer.Deserialize<Product>(json, options);

ただし、設定だけで何でも解決しようとするのではなく、外部サービスがどのようなJSONを返すのかを確認することが基本です。Web APIを利用するときには、項目名だけではなく、文字列、整数、真偽値などのデータ型についても仕様を確認しましょう。

JSONのデシリアル化では例外処理も重要

自分のプログラムで作成したJSONだけを扱う場合とは違い、Web APIや外部ファイルから受け取るJSONが常に正しいとは限りません。JSONの文法が壊れていたり、C#側で想定している型とは異なる値が入っていたりすると、デシリアル化するときに例外が発生する可能性があります。

そのため、実際のアプリケーションではtryとcatchを利用して、JSONの変換に失敗した場合の処理を用意することがあります。

using System;
using System.Text.Json;

try
{
    string json = "{\"Name\":\"リンゴ\",\"Price\":120}";

    Product product =
        JsonSerializer.Deserialize<Product>(json);

    if (product != null)
    {
        Console.WriteLine(product.Name);
    }
}
catch (JsonException)
{
    Console.WriteLine("JSONの形式を確認してください。");
}

このようにしておけば、JSONの形式に問題があったときに、何も対応せずプログラムを終了させるのではなく、利用者へ分かりやすいメッセージを表示するなどの処理につなげられます。

JSONファイルへの保存にも応用できる

JSONは文字列なので、ファイルへ保存することもできます。例えばアプリケーションの設定情報をJSONファイルへ保存し、次回の起動時に読み込むといった使い方ができます。

基本的な考え方は、C#のオブジェクトをSerializeでJSON文字列へ変換し、その文字列をファイルへ保存するという流れです。読み込む場合には、ファイルからJSON文字列を取得し、DeserializeでC#のオブジェクトへ戻します。

つまり、JSONファイルを扱う場合でもJsonSerializerの基本は変わりません。シリアル化とデシリアル化の間にファイルへの書き込みや読み込みが追加されるだけです。

Web APIを学ぶとJSONの知識がさらに重要になる

C#でWeb APIを利用するときにもJSONは頻繁に登場します。例えば天気情報を提供するWeb APIからJSONを受け取り、C#のクラスへデシリアル化して画面に表示するといった処理があります。

反対に、C#で入力された会員情報や注文情報をJSONへシリアル化し、サーバーへ送信する場合もあります。このように、C#と外部システムとの間でデータを受け渡すときにJSONが橋渡しの役割をします。

そのため、JsonSerializerの使い方を理解しておくことは、コンソールアプリケーションだけでなく、Webアプリケーション、Web API、スマートフォン向けサービス、クラウドサービスとの連携などを学ぶときにも役立ちます。

JSONの構造を読む力も身につけよう

JsonSerializerのメソッドだけを覚えるのではなく、JSONそのものの構造を読めるようになることも重要です。基本的には、波括弧で囲まれた部分を1つのオブジェクト、角括弧で囲まれた部分を複数のデータが集まった配列として考えます。

長いJSONを見たときも、最初からすべてを理解しようとする必要はありません。まず項目名を確認し、その値が文字列なのか数値なのか、さらに別のオブジェクトなのか、配列なのかを順番に確認していきます。この見方に慣れると、複雑なWeb APIのJSONも少しずつ読み取れるようになります。

外部から受け取ったJSONを無条件に信用しない

JSONは便利なデータ形式ですが、外部から受け取ったJSONの内容が必ず正しいとは限りません。必要な項目がなかったり、想定している範囲を超えた数値が入っていたり、不正な文字列が含まれていたりする可能性があります。

そのため、デシリアル化に成功した後も、アプリケーションで必要な値がそろっているかを確認することが大切です。例えば価格であれば負の値になっていないか、名前であれば空の文字列になっていないかなど、用途に合わせてデータを検証します。

また、JSONへ変換したからといってデータが暗号化されるわけではありません。パスワード、秘密鍵、アクセストークンなどの重要な情報をJSONへ書いただけでは、その情報を安全に保護したことにはなりません。JSONはあくまでデータを表現するための形式であることを覚えておきましょう。

C#のJSON操作を学ぶおすすめの順番

C#初心者がJsonSerializerを学ぶ場合は、最初に小さなクラスを1つ作り、そのオブジェクトをSerializeでJSONへ変換するところから始めると分かりやすいです。次に、そのJSONをDeserializeで元のクラスへ戻します。

その後、Listを使ったJSON配列、JsonSerializerOptionsによる出力設定、JsonPropertyNameによる項目名の指定、例外処理、JSONファイルの保存と読み込みという順番で学ぶと、知識を段階的につなげられます。

最初から複雑なWeb APIを使おうとすると、通信処理とJSON操作を同時に理解しなければならなくなります。まずは自分で作った小さなJSONを使い、シリアル化とデシリアル化を何度か試してからWeb APIへ進むと理解しやすくなります。

JsonSerializerで特に覚えておきたいポイント

C#のJsonSerializerを使う目的は、単にJSONらしい文字列を作ることではありません。C#のオブジェクトと、保存や通信に利用しやすいJSON形式との間でデータを変換することが本来の役割です。

SerializeはC#のオブジェクトをJSONへ変換し、DeserializeはJSONをC#のオブジェクトへ戻します。クラスのプロパティとJSONの項目が対応し、Listなどの複数データはJSON配列として表現できます。必要に応じてJsonSerializerOptionsを使えば、改行や字下げ、プロパティ名の扱いなども調整できます。

外部のJSONを扱う場合には、JsonPropertyNameによる名前の対応、データ型の違い、null、例外処理なども意識する必要があります。JSONを読み込めたから終わりではなく、変換されたデータがアプリケーションで安全に利用できる内容なのかを確認することも重要です。

JSONはC#だけの技術ではありません。JavaScript、Python、Java、PHPなど多くのプログラミング言語で利用されます。そのため、C#でJsonSerializerの基本とJSONの構造を理解しておけば、将来ほかのプログラミング言語やWeb APIを学ぶときにも知識を活かせます。

まずはC#のクラスを1つJSONへ変換し、そのJSONを再び同じクラスへ戻す小さなプログラムを作ってみましょう。データがJSONへ変化し、再びC#のオブジェクトへ戻る様子を実際に確認すると、シリアル化とデシリアル化の意味を理解しやすくなります。この基本が身につけば、ファイル保存やWeb APIとの通信など、より実践的なJSON操作へ進みやすくなります。