キーと値のペアのシリアル化および逆シリアル化時、PropertyNamingPolicy、PropertyNameCaseInsensitive、Encoder オプションが許可される

  • [アーティクル]

JsonSerializer で、KeyValuePair<TKey,TValue> インスタンスの Key および Value プロパティ名をシリアル化するときに、PropertyNamingPolicy オプションと Encoder オプションが許可されるようになりました。 また、JsonSerializer で KeyValuePair<TKey,TValue> インスタンスを逆シリアル化するときに、PropertyNamingPolicy オプションと PropertyNameCaseInsensitive オプションが許可されるようになりました。

変更内容

シリアル化

JsonSerializerOptions.PropertyNamingPolicy オプションおよび JsonSerializerOptions.Encoder オプションがあった場合でも、.NET Core 3.x バージョンと、System.Text.Json NuGet パッケージの 4.6.0 から 4.7.2 のバージョンで、KeyValuePair<TKey,TValue> インスタンスのプロパティは常に "キー" と "値" として正確にシリアル化されます。 次のコード例は、指定したプロパティの名前付けポリシーで指定されている場合でも、シリアル化後に Key プロパティと Value プロパティがキャメル ケースで表記 "されない" ことを示しています。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
KeyValuePair<int, int> kvp = KeyValuePair.Create(1, 1);
Console.WriteLine(JsonSerializer.Serialize(kvp, options));
// Expected: {"key":1,"value":1}
// Actual: {"Key":1,"Value":1}

.NET 5 以降では、KeyValuePair<TKey,TValue> インスタンスをシリアル化するときに、PropertyNamingPolicy オプションと Encoder オプションが許可されます。 次のコード例は、指定したプロパティの名前付けポリシーに従い、シリアル化後に Key プロパティと Value プロパティがキャメル ケースで表示されることを示しています。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
KeyValuePair<int, int> kvp = KeyValuePair.Create(1, 1);
Console.WriteLine(JsonSerializer.Serialize(kvp, options));
// {"key":1,"value":1}

逆シリアル化

JSON プロパティの名前が大文字で始まらない場合など、正確に Key および Value でない場合、.NET Core 3.x のバージョンと System.Text.Json NuGet パッケージの 4.7. x バージョンにより、JsonException がスローされます。 この例外は、指定したプロパティの名前付けポリシーで明示的にそれが許可されている場合でもスローされます。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
string json = @"{""key"":1,""value"":1}";
// Throws JsonException.
JsonSerializer.Deserialize<KeyValuePair<int, int>>(json, options);

.NET 5 以降の場合、JsonSerializer を使用してシリアル化するときに、PropertyNamingPolicy オプションと PropertyNameCaseInsensitive オプションが許可されます。 たとえば、以下のコードスニペットは、指定されたプロパティ命名ポリシーでそれが許可されているため、小文字の Key と Value プロパティ名の逆シリアル化に成功したことを示しています。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
string json = @"{""key"":1,""value"":1}";

KeyValuePair<int, int> kvp = JsonSerializer.Deserialize<KeyValuePair<int, int>>(json);
Console.WriteLine(kvp.Key); // 1
Console.WriteLine(kvp.Value); // 1

以前のバージョンでシリアル化されたペイロードに対応するために、逆シリアル化で照合されるよう、"Key" と "Value" には特殊文字が使用されます。 次のコード例で、Key プロパティ名と Value プロパティ名は PropertyNamingPolicy オプションに従ってキャメル ケースで表示されていませんが、正常に逆シリアル化されます。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
string json = @"{""Key"":1,""Value"":1}";

KeyValuePair<int, int> kvp = JsonSerializer.Deserialize<KeyValuePair<int, int>>(json);
Console.WriteLine(kvp.Key); // 1
Console.WriteLine(kvp.Value); // 1

導入されたバージョン

5.0

変更理由

多くのお客様からのフィードバックにより、PropertyNamingPolicy を許可する必要があることがわかりました。 完全を期すために、他の単純な従来の CLR オブジェクト (POCO) と同様に KeyValuePair<TKey,TValue> インスタンスが扱われるよう、PropertyNameCaseInsensitive オプションと Encoder オプションも許可されています。

この変更による破壊的な影響がある場合は、希望のセマンティクスを実装するカスタム コンバーターを使用してください。

影響を受ける API