Come leggere JSON come oggetti .NET (deserializzazione)

Articolo
09/26/2024

Questo articolo illustra come usare lo spazio dei nomi System.Text.Json per la deserializzazione da JavaScript Object Notation (JSON). Se si sta eseguendo la conversione di codice esistente da Newtonsoft.Json, vedere Come eseguire la migrazione a System.Text.Json.

Un modo comune per deserializzare JSON consiste nell'avere (o creare) una classe .NET con proprietà e campi che rappresentano una o più proprietà JSON. Quindi, per deserializzare da una stringa o da un file, chiamare il metodo JsonSerializer.Deserialize. Per gli overload generici, il parametro di tipo generico è la classe .NET. Per gli overload non generici, passare il tipo della classe come parametro del metodo. È possibile deserializzare in modo sincrono o asincrono.

Suggerimento

È possibile usare l'assistenza per l'intelligenza artificiale per deserializzare una stringa JSON con GitHub Copilot.

Tutte le proprietà JSON non rappresentate nella classe vengono ignorate per impostazione predefinita. Inoltre, se le proprietà del tipo sono necessarie ma non presenti nel payload JSON, la deserializzazione avrà esito negativo.

Esempi

L'esempio seguente illustra come deserializzare una stringa JSON:

using System.Text.Json;

namespace DeserializeExtra
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
        public string? SummaryField;
        public IList<DateTimeOffset>? DatesAvailable { get; set; }
        public Dictionary<string, HighLowTemps>? TemperatureRanges { get; set; }
        public string[]? SummaryWords { get; set; }
    }

    public class HighLowTemps
    {
        public int High { get; set; }
        public int Low { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            string jsonString =
                """
                {
                  "Date": "2019-08-01T00:00:00-07:00",
                  "TemperatureCelsius": 25,
                  "Summary": "Hot",
                  "DatesAvailable": [
                    "2019-08-01T00:00:00-07:00",
                    "2019-08-02T00:00:00-07:00"
                  ],
                  "TemperatureRanges": {
                                "Cold": {
                                    "High": 20,
                      "Low": -10
                                },
                    "Hot": {
                                    "High": 60,
                      "Low": 20
                    }
                            },
                  "SummaryWords": [
                    "Cool",
                    "Windy",
                    "Humid"
                  ]
                }
                """;
                
            WeatherForecast? weatherForecast = 
                JsonSerializer.Deserialize<WeatherForecast>(jsonString);

            Console.WriteLine($"Date: {weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast?.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

weatherForecast = JsonSerializer.Deserialize(Of WeatherForecastWithPOCOs)(jsonString)

Per deserializzare da un file usando codice sincrono, leggere il file in una stringa, come illustrato nell'esempio seguente:

using System.Text.Json;

namespace DeserializeFromFile
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            string fileName = "WeatherForecast.json";
            string jsonString = File.ReadAllText(fileName);
            WeatherForecast weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString)!;

            Console.WriteLine($"Date: {weatherForecast.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

jsonString = File.ReadAllText(fileName)
weatherForecast1 = JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

Per deserializzare da un file usando codice asincrono, chiamare il metodo DeserializeAsync:

using System.Text.Json;

namespace DeserializeFromFileAsync
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            string fileName = "WeatherForecast.json";
            using FileStream openStream = File.OpenRead(fileName);
            WeatherForecast? weatherForecast = 
                await JsonSerializer.DeserializeAsync<WeatherForecast>(openStream);

            Console.WriteLine($"Date: {weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast?.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

Dim openStream As FileStream = File.OpenRead(fileName)
weatherForecast1 = Await JsonSerializer.DeserializeAsync(Of WeatherForecast)(openStream)

Comportamento di deserializzazione

Durante la deserializzazione di JSON si applicano i comportamenti seguenti:

Per impostazione predefinita, la corrispondenza dei nomi delle proprietà fa distinzione tra maiuscole e minuscole. È possibile specificare la distinzione tra maiuscole e minuscole.
I costruttori non pubblici vengono ignorati dal serializzatore.
La deserializzazione per oggetti o proprietà non modificabili che non dispongono di funzioni di accesso pubbliche set è supportata ma non abilitata per impostazione predefinita. Vedere Tipi e record non modificabili.
Per impostazione predefinita, le enumerazioni sono supportate come numeri. È possibile deserializzare i campi di enumerazione stringa.
Per impostazione predefinita, i campi vengono ignorati. È possibile includere campi.
Per impostazione predefinita, i commenti o le virgole finali nel codice JSON generano eccezioni. È possibile consentire commenti e virgole finali.
Il valore massimo di profondità predefinito è 64.

Quando si usa System.Text.Json indirettamente in un'app ASP.NET Core, alcuni comportamenti predefiniti sono diversi. Per altre informazioni, vedere Riutilizzare le istanze JsonSerializerOptions.

È possibile implementare convertitori personalizzati per fornire funzionalità non supportate dai convertitori predefiniti.

Deserializzare senza una classe .NET

Se si ha JSON in cui si vuole deserializzare e non si dispone della classe in cui deserializzarla, sono disponibili opzioni diverse dalla creazione manuale della classe necessaria:

Usare direttamente Utf8JsonReader.
Deserializzare in un DOM JSON (document object model) ed estrarre gli elementi necessari dal DOM.

Il DOM consente di passare a una sottosezione di un payload JSON e di deserializzare un singolo valore, un tipo personalizzato o una matrice. Per informazioni sul DOM JsonNode, vedere Deserializzare le sottosezioni di un payload JSON. Per informazioni sul DOM di JsonDocument, vedere Come cercare elementi secondari in jsonDocument e JsonElement .
Usare Visual Studio 2022 per generare automaticamente la classe necessaria:
- Copiare il codice JSON da deserializzare.
- Creare un file di classe ed eliminare il codice del modello.
- Scegliere Modifica>Incolla speciale>Incolla JSON come classi.
Il risultato è una classe che è possibile usare per la destinazione di deserializzazione.

Deserializzare da UTF-8

Per deserializzare da UTF-8, chiamare un overload JsonSerializer.Deserialize che accetta un ReadOnlySpan<byte> o un Utf8JsonReader, come illustrato negli esempi seguenti. Gli esempi presuppongono che JSON sia in una matrice di byte denominata jsonUtf8Bytes.

var readOnlySpan = new ReadOnlySpan<byte>(jsonUtf8Bytes);
WeatherForecast deserializedWeatherForecast = 
    JsonSerializer.Deserialize<WeatherForecast>(readOnlySpan)!;

Dim jsonString = Encoding.UTF8.GetString(jsonUtf8Bytes)
weatherForecast1 = JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
WeatherForecast deserializedWeatherForecast = 
    JsonSerializer.Deserialize<WeatherForecast>(ref utf8Reader)!;

' This code example doesn't apply to Visual Basic. For more information, go to the following URL:
' https://learn.microsoft.com/dotnet/standard/serialization/system-text-json-how-to#visual-basic-support

Usare GitHub Copilot per deserializzare in JSON

È possibile usare GitHub Copilot nell'IDE per generare codice che usa System.Text.Json per deserializzare da JSON.

Se si usa Visual Studio 2022 versione 17.8 o successiva, è possibile provare GitHub Copilot supportato da IA in Visual Studio per generare un codice che utilizza System.Text.Json per deserializzare JSON. Inviare la domanda e il codice da convertire come richiesta nella finestra di chat Copilot, come nell'esempio seguente. È anche possibile inviare richieste usando chat inline nella finestra dell'editor stessa.

Nota

GitHub Copilot è supportato dall'IA, quindi sono possibili sorprese ed errori. Assicurarsi di verificare il codice o i suggerimenti generati. Per maggiori informazioni sull'uso generale di GitHub Copilot, sull'impatto sul prodotto, sulla supervisione umana e sulla privacy, vedere le Domande frequenti su GitHub Copilot.

Il testo seguente mostra un esempio di richiesta di chat di Copilot:

Generare codice da usare System.Text.Json per deserializzare una stringa JSON {"FirstName":"John","LastName":"Doe","Age":30} in un oggetto .NET equivalente. Mapping dei nomi e dei valori & delle proprietà. Fornire un output di esempio.

È possibile personalizzare la richiesta di usare una stringa JSON con nomi di proprietà e valori che soddisfano i requisiti.

È possibile usare funzionalità di chat, ad esempio comandi barra, riferimenti a file, metodi, classi o thread, per impostare la finalità e ottenere risposte migliori con il contesto con ambito. Per una classe esistente in un progetto aperto nell'IDE, è possibile richiedere GitHub Copilot con /generate code to dserialize JSON to equivalent .NET object in #Filename

L'output seguente mostra un esempio di risposta Copilot Chat:

Here's an example of how you can use `System.Text.Json` to deserialize a JSON string into a .NET object in C#:

using System;
using System.Text.Json;
public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
}
public class Program
{
    public static void Main()
    {
        string jsonString = "{\"FirstName\":\"John\",\"LastName\":\"Doe\",\"Age\":30}";
        Person person = JsonSerializer.Deserialize<Person>(jsonString);
        Console.WriteLine($"FirstName: {person.FirstName}");
        Console.WriteLine($"LastName: {person.LastName}");
        Console.WriteLine($"Age: {person.Age}");
    }
}

**Example Output**
FirstName: John
LastName: Doe
Age: 30

This code defines a Person class with properties that match the JSON string. It then uses `JsonSerializer.Deserialize` to convert the JSON string into a `Person` object and prints the properties to the console.

Quando Copilot restituisce un blocco di codice, la risposta include opzioni per copiare il codice, inserire il codice in un nuovo file o visualizzare in anteprima l'output del codice.

Nota

I risultati potrebbero essere diversi da quanto illustrato nelle risposte di esempio. I modelli di IA non sono deterministici, il che significa che possono restituire risposte diverse quando viene posta la stessa domanda. Questo potrebbe essere dovuto ad apprendimento e adattamento aggiuntivo nel tempo, alla variazione della lingua, ai cambiamenti nel contesto, ad esempio alla cronologia delle chat e altro ancora.

Per altre informazioni, vedi:

Condividi tramite