Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

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