CKTIS / C#
JsonSerializerOptions — configurare la lettura e la scrittura di JSON
System.Text.Json.JsonSerializerOptions controlla la conversione degli oggetti .NET in JSON e la lettura da JSON. Permette di configurare i nomi delle proprietà, i commenti, le proprietà sconosciute, la gestione dei numeri e l’omissione dei valori null. Configura un’istanza prima del primo utilizzo e riutilizzala in seguito.
Versione: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Sintassi
var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, ReadCommentHandling = JsonCommentHandling.Skip, UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, NumberHandling = JsonNumberHandling.AllowReadingFromString, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
var value = JsonSerializer.Deserialize<T>(json, options);
string result = JsonSerializer.Serialize(value, options);System.Text.Json.JsonSerializerOptions fornisce la configurazione a JsonSerializer.Serialize e JsonSerializer.Deserialize. L’esempio è destinato a .NET 10; UnmappedMemberHandling è disponibile da .NET 8. Non è richiesta alcuna funzionalità del linguaggio in anteprima. new JsonSerializerOptions() senza altre impostazioni conserva i nomi delle proprietà, distingue tra maiuscole e minuscole durante la lettura e applica una gestione rigorosa dei numeri; le impostazioni predefinite delle applicazioni web possono essere diverse.
JsonNamingPolicy rappresenta una regola di conversione dei nomi. PropertyNamingPolicy = JsonNamingPolicy.CamelCase converte ItemCount in itemCount sia in scrittura sia in lettura. Questo non abilita la corrispondenza senza distinzione tra maiuscole e minuscole: per quella si usa PropertyNameCaseInsensitive. L’attributo [JsonPropertyName] ha la precedenza sulla regola.
ReadCommentHandling usa JsonCommentHandling: il valore predefinito Disallow rifiuta i commenti, mentre Skip li accetta e li ignora. Il valore Allow, pensato per un reader, non è supportato da questa opzione del serializzatore. UnmappedMemberHandling usa JsonUnmappedMemberHandling: il valore predefinito Skip ignora le proprietà JSON non mappate, a meno che non vengano raccolte come dati di estensione. Se per un tipo è effettivamente in vigore Disallow, una proprietà JSON non mappata genera una JsonException. La configurazione specifica di un tipo può prevalere sull’impostazione nelle opzioni del serializzatore. Se Disallow è impostato solo nelle opzioni, un membro contrassegnato con [JsonExtensionData] può raccogliere le proprietà non mappate senza che venga generata un’eccezione. Questa impostazione non richiede che tutte le proprietà del modello siano presenti nell’input.
NumberHandling usa i flag di JsonNumberHandling. Il valore predefinito Strict richiede token numerici; AllowReadingFromString permette anche di leggere "3" come numero, ma lo scrive comunque come 3. Il flag distinto WriteAsString scrive i numeri tra virgolette. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull omette in scrittura le proprietà con valore null; non omette 0 o false e non impedisce di leggere null.
Configura le opzioni prima della prima serializzazione o deserializzazione: in seguito l’istanza diventa immutabile. Riutilizzala per mantenere le cache dei metadati; condividerla tra thread è sicuro. L’esempio ignora un commento, legge un numero tra virgolette e scrive l’oggetto senza Note. Una proprietà JSON non mappata genererebbe una JsonException durante la deserializzazione del tipo Payload dell’esempio.
Esempi
#nullable enable
using System;
using System.Text.Json;
using System.Text.Json.Serialization;
var options = new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
ReadCommentHandling = JsonCommentHandling.Skip,
UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,
NumberHandling = JsonNumberHandling.AllowReadingFromString,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
const string json = "{ /* input */ \"itemCount\": \"3\", \"note\": null }";
var value = JsonSerializer.Deserialize<Payload>(json, options)
?? throw new InvalidOperationException();
Console.WriteLine(JsonSerializer.Serialize(value, options));
public sealed class Payload
{
public int ItemCount { get; set; }
public string? Note { get; set; }
}
Risultato
{"itemCount":3}Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.
Fonti
- .NET API browser
- JsonSerializerOptions Class
- How to instantiate JsonSerializerOptions instances with System.Text.Json
- How to customize property names and values with System.Text.Json
- JsonSerializerOptions.ReadCommentHandling Property
- Handle unmapped members during deserialization
- JsonNumberHandling Enum
- JsonIgnoreCondition Enum