Le opzioni PropertyNamingPolicy, PropertyNameCaseInsensitive ed Encoder vengono rispettate durante la serializzazione e la deserializzazione di coppie chiave-valore

  • Articolo

JsonSerializer ora rispetta le opzioni PropertyNamingPolicy e Encoder durante la serializzazione dei nomi delle proprietà Key e Value di un'istanza di KeyValuePair<TKey,TValue>. Inoltre, JsonSerializer rispetta le opzioni PropertyNamingPolicy e PropertyNameCaseInsensitive durante la deserializzazione delle istanze di KeyValuePair<TKey,TValue>.

Descrizione delle modifiche

Serializzazione

Nelle versioni di .NET Core 3.x e nelle versioni 4.6.0-4.7.2 del pacchetto NuGet System.Text.Json le proprietà delle istanze di KeyValuePair<TKey,TValue> vengono sempre serializzate esattamente come "Key" e "Value", indipendentemente da eventuali opzioni JsonSerializerOptions.PropertyNamingPolicy e JsonSerializerOptions.Encoder. Nell'esempio di codice riportato di seguito viene illustrato come per le proprietà Key e Valuenon venga usata la notazione Camel dopo la serializzazione, anche se i criteri di denominazione delle proprietà specificati lo prevedono.

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}

A partire da .NET 5, le opzioni PropertyNamingPolicy e Encoder vengono rispettate durante la serializzazione delle istanze di KeyValuePair<TKey,TValue>. L'esempio di codice riportato di seguito mostra come per le proprietà Key e Value venga usata la notazione Camel dopo la serializzazione, conformemente a quanto previsto dai criteri di denominazione delle proprietà specificati.

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}

Deserializzazione

Nelle versioni di .NET Core 3.x e nelle versioni 4.7.x del pacchetto NuGet System.Text.Json viene generata un'eccezione JsonException quando i nomi delle proprietà JSON non sono esattamente Key e Value, ad esempio, se non iniziano con una lettera maiuscola. L'eccezione viene generata anche se un criterio di denominazione delle proprietà specificato lo consente espressamente.

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

A partire da .NET 5, le opzioni PropertyNamingPolicy e PropertyNameCaseInsensitive vengono rispettate quando si esegue la deserializzazione con JsonSerializer. Ad esempio, il frammento di codice seguente mostra la corretta deserializzazione dei nomi delle proprietà Key e Value con lettere minuscole perché i criteri di denominazione delle proprietà specificati lo consentono.

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

Per supportare i payload serializzati con le versioni precedenti, i nomi delle proprietà "Key" e "Value" contengono maiuscole e minuscole speciali per consentire la deserializzazione. Anche se per i nomi delle proprietà Key e Value non viene usata la notazione Camel in base all'opzione PropertyNamingPolicy nell'esempio di codice seguente, la deserializzazione viene completata correttamente.

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

Versione introdotta

5.0

Motivo della modifica

Un feedback sostanziale dei clienti ha indicato che è necessario rispettare PropertyNamingPolicy. Per completezza, vengono rispettate anche le opzioni PropertyNameCaseInsensitive e Encoder, affinché le istanze di KeyValuePair<TKey,TValue> vengano trattate come qualsiasi altro oggetto Plain Old CLR Object (POCO).

Se questa modifica causa interruzioni nell'ambiente in uso, è possibile usare un convertitore personalizzato che implementa la semantica desiderata.

API interessate