System.Text.Json 時代の読み取り専用プロパティを持つオブジェクトのデシリアライズ

C# でのプログラミングの話。

昨今の C# プログラミングでは、オブジェクトの JSON 文字列へのシリアル化/逆シリアル化を行なうには、System.Text.Json アセンブリおよび同名の名前空間の、JsonSerializer クラスを活用することも多いと思われる。

そして他方、昨今の C# プログラミングでは、オブジェクトのプロパティは、なるべく変更不可・読み取り専用で実装することも多くなったのではないだろうか。

例えば次のような C# クラスである。

class PersonClass

{

  public string? Name { get; }

  public int Age { get; }

  public PersonClass(string name, int age)

  {

    Name = name;

    Age = age;

  }

}

さて、このように読み取り専用プロパティを持つ、コンストラクタでのみ各プロパティ値を初期化するようなクラスであっても、System.Text.Json 名前空間の JsonSerializer クラスでは、ちゃんと、JSON 文字列からのクラスのインスタンスへ逆シリアル化できる。

例えばこんな感じ。

var json = @"{""Name"":""Taro"",""Age"":23}";

var person = JsonSerializer.Deserialize<PersonClass>(json);

// person.Name -> "Taro"

// person.Age -> 23

これは、JsonSerializer.Deserialize<T>() メソッドが、引数が適合するコンストラクタをちゃんと探し当てて、その引数付きコンストラクタを使ってインスタンス化してくれるからだ。

なので、コンストラクタ引数名とプロパティ名が (英字の大小違いは構わないが) 一致しない場合、例えば先の PersonClass クラスのコンストラクタ引数名が、

public PersonClass(string foo, int age)

{

  Name = foo; // コンストラクタ引数名とプロパティ名が一致しない

  ...

のようになっている場合は、JsonSerializer.Deserialize<T>() メソッド実行時に、「これは逆シリアル化できない!」となって例外が発生する。

なお、コンストラクタ引数の出現順序と、プロパティの出現順序は関係ない。

名前と型が適合するかどうかがポイントとなる。

コンストラクタが複数あると逆シリアル化できない!?

さてこのような読み取り専用プロパティで構成されるクラス、希ではあるが、引数違いのコンストラクタをオーバーロード実装する場合がある。

例えば、引数無しデフォルトコンストラクタを必須とするような O/R マッパーライブラリでも同じクラスを使いたい場合、などだ。

では試しに、先の PersonClass に引数無しデフォルトコンストラクタを追加したとしよう。

class PersonClass

{

  ...

  public PersonClass() { } // 👈これを追加

  public PersonClass(string name, int age) {...}

  ...

すると、例外こそ発生しないものの、先のコードの実行結果としては、期待どおりには逆シリアル化されなくなってしまう (下記例)。

var json = @"{""Name"":""Taro"",""Age"":23}";

var person = JsonSerializer.Deserialize<PersonClass>(json);

// person.Name -> null ... "Taro" ではない

// person.Age -> 0 ... 23 ではない

さらには、引数無しデフォルトコンストラクタではなく、引数は持つがシグネチャ違いのコンストラクタオーバーロードがある場合は、JsonSerializer.Deserialize<T>() メソッド実行時に例外が発生するようになる。

class PersonClass

{

  ...

  public PersonClass(string name) { } // 👈これを追加 -> 例外発生

  public PersonClass(string name, int age) {...}

  ...

なお、引数無しデフォルトコンストラクタがある限りは、例外は発生しなくなるようだが、いずれにしても、複数オーバーロードバージョンのコンストラクタがあると、期待どおりの逆シリアル化はされなくなるようだ。

[JsonConstructor] 属性で解決

このように、JsonSerializer.Deserialize<T>() メソッドでは、複数のコンストラクタがある場合、逆シリアル化に最適なコンストラクタの用意があっても、引数無しデフォルトコンストラクタを最優先に使ってオブジェクトをインスタンス化したあとに、そのオブジェクトのプロパティを設定していくようだ。

そして複数のコンストラクタがあるものの、引数無しデフォルトコンストラクタがない場合は、どのコンストラクタを選ぶかを自動では判断せずに諦めるようである。

このように、せっかく逆シリアル化に最適なコンストラクタの用意があっても、複数のコンストラクタがあるせいで、JsonSerializer.Deserialize<T>() メソッドは自動ではその最適なコンストラクタを使うようにはなっていない。

このようなシナリオの場合は、開発者が明示的に、その "逆シリアル化に最適なコンストラクタ" に [JsonConstructor] 属性を付けてやる必要がある。

class PersonClass

{

  ...

  public PersonClass() { }

  [JsonConstructor] // 👈これを追加

  public PersonClass(string name, int age) {...}

  ...

こうすることで JsonSerializer.Deserialize<T>() メソッドは、引数無しデフォルトコンストラクタよりも優先して、[JsonConstructor] 属性で修飾されたコンストラクタを使ってオブジェクトをインスタンス化するようになり、期待どおりの逆シリアル化が実現できる。

補足1 - 初期化専用セッターを持つプロパティの場合

先の例では読み取り専用プロパティについての話であったが、これが初期化専用セッター (init-only セッター) を持つプロパティだったらどうなるか?

class PersonClass

{

  public string Name { get; init; }

  public int Age { get; init; }

  public PersonClass() { }

  public PersonClass(string name, int age) {...}

  ...

これはちゃんと期待どおりの逆シリアル化がされる。

ただし、使われるコンストラクタはあくまでも引数無しデフォルトコンストラクタ。

補足2 - プライベートセッターを持つプロパティの場合

ではプライベートセッターの場合はどうか?

class PersonClass

{

  public string Name { get; private set; }

  public int Age { get; private set; }

  public PersonClass() { }

  public PersonClass(string name, int age) {...}

  ...

この場合は、期待どおりの逆シリアル化にはならない。

各プロパティは、引数無しデフォルトコンストラクタでインスタンス化されたときの初期値のままである。

この場合は、前述のように、適切なコンストラクタオーバーロードの実装、およびそのコンストラクタを [JsonConstructor] 属性で修飾、という手立てで対処するのがよい。

しかし他にも、プライベートセッターを持つプロパティに、[JsonInclude] 属性を付与する、という方法もある。

class PersonClass

{

  [JsonInclude]

  public string Name { get; private set; }

  [JsonInclude]

  public int Age { get; private set; }

  public PersonClass() { }

  public PersonClass(string name, int age) {...}

  ...

こうすると、期待どおりの逆シリアル化がされるようになる。
ただしこの場合も、使われるコンストラクタは、引数無しデフォルトコンストラクタであることに注意。

プロパティに [JsonInclude] 属性を付ける方法のほうがよいというシナリオは、自分には思いつかなかったが、このような方法があることを知っておくと、何かレアケースな実装パターンで役に立つかもしれない。

(実際、何か需要があるからこそ [JsonInclude] などという属性が用意されていることと思うので。)

おわりに

以上、今回は「読み取り専用プロパティを持つオブジェクト」を取り上げたが、このようなクラスの必要があった際は、レコード型 (record) の採用を検討することもお忘れなく。

[2021/05/01 追記]
じんぐるさんから Twitter でコメント頂戴した。
なるほど、こういう観点からの指針決定・判断もあるということで、今後自分の方針も適宜改善していくかもしれない。

まさに最近こればっかりやってました！僕個人の Practice としては

- [JsonInclude] は「常に」付ける
- [JsonConstructor] より private init を好む

という方針にしてました。

[JsonConstructor] はプロパティ名と引数名が異なると動かないのが若干危なっかしい、という理由ですが。

— じんぐる (Takaaki Suzuki) (@xin9le) April 30, 2021