Die Optionen „PropertyNamingPolicy“, „PropertyNamingPolicy“ und „Encoder“ werden beim Serialisieren und Deserialisieren von Schlüssel-Wert-Paaren berücksichtigt

  • Artikel

JsonSerializer berücksichtigt nun die Optionen PropertyNamingPolicy und Encoder beim Serialisieren der Eigenschaftsnamen Key und Value einer KeyValuePair<TKey,TValue>-Instanz. Außerdem berücksichtigt JsonSerializer die Optionen PropertyNamingPolicy und PropertyNameCaseInsensitive beim Deserialisieren von KeyValuePair<TKey,TValue>-Instanzen.

Änderungsbeschreibung

Serialisierung

In .NET Core 3.x-Versionen und in den Versionen 4.6.0–4.7.2 des NuGet-Pakets „System.Text.Json“ werden die Eigenschaften der KeyValuePair<TKey,TValue>-Instanzen immer als „Key“ und „Value“ serialisiert – unabhängig von jeglichen JsonSerializerOptions.PropertyNamingPolicy- und JsonSerializerOptions.Encoder-Optionen. Im folgenden Codebeispiel wird gezeigt, wie die Eigenschaften Key und Value nach der Serialisierung nicht mit gemischter Groß-/Kleinschreibung geschrieben werden, obwohl dies von der Richtlinie für die Benennung von Eigenschaften vorgeschrieben wird.

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}

Ab .NET 5 werden die Optionen PropertyNamingPolicy und Encoder beim Serialisieren von KeyValuePair<TKey,TValue>-Instanzen berücksichtigt. Im folgenden Codebeispiel wird gezeigt, wie die Eigenschaften Key und Value gemäß der Richtlinie für die Benennung von Eigenschaften nach der Serialisierung mit gemischter Groß-/Kleinschreibung geschrieben werden.

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}

Deserialisierung

In .NET Core 3.x-Versionen und in 4.7.x-Versionen des NuGet-Pakets „System.Text.Json“wird eine JsonException ausgelöst, wenn die JSON-Eigenschaftsnamen nicht exakt Key und Value entsprechen, also z. B. nicht mit einem Großbuchstaben beginnen. Die Ausnahme wird auch dann ausgelöst, wenn eine bestimmte Richtlinie zur Benennung von Eigenschaften dies ausdrücklich gestattet.

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

Ab .NET 5 werden die Optionen PropertyNamingPolicy und PropertyNameCaseInsensitive bei der Deserialisierung mithilfe von JsonSerializer berücksichtigt. Der folgende Codeausschnitt zeigt z. B. die erfolgreiche Deserialisierung der Eigenschaftsnamen Key und Value in Kleinbuchstaben, weil die entsprechende Richtlinie für die Benennung von Eigenschaften dies gestattet.

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

Zur Unterstützung von Nutzdaten, die mit früheren Versionen deserialisiert wurden, gilt für die Eigenschaftsnamen „Key“ und „Value“ ein Sonderfall in Bezug auf die Groß-/Kleinschreibung, um diese bei der Deserialisierung abzugleichen. Obwohl die Eigenschaftsnamen Key und Value im folgenden Codebeispiel nicht entsprechend der Option PropertyNamingPolicy mit gemischter Groß-/Kleinschreibung geschrieben werden, werden sie erfolgreich deserialisiert.

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

Eingeführt in Version

5.0

Grund für die Änderung

Umfassendes Kundenfeedback hat ergeben, dass die Eigenschaft PropertyNamingPolicy berücksichtigt werden sollte. Aus Gründen der Vollständigkeit werden die Optionen PropertyNameCaseInsensitive und Encoder ebenfalls berücksichtigt, sodass KeyValuePair<TKey,TValue>-Instanzen genauso wie alle anderen Plain Old CLR Objects (POCO) behandelt werden.

Wenn Sie diese Änderung stört, können Sie einen benutzerdefinierten Konverter verwenden, der die gewünschte Semantik implementiert.

Betroffene APIs