Comment lire du JSON en tant qu’objets .NET (désérialiser)

Cet article montre comment utiliser l'espace de noms System.Text.Json pour désérialiser à partir de JavaScript Object Notation (JSON). Si vous transférez du code existant à partir de Newtonsoft.Json, consultez Comment migrer vers System.Text.Json.

Une façon courante de désérialiser du JSON consiste à avoir (créer) une classe .NET avec des propriétés et des champs qui représentent une ou plusieurs des propriétés JSON. Ensuite, pour désérialiser à partir d’une chaîne ou d’un fichier, appelez la méthode JsonSerializer.Deserialize. Pour les surcharges génériques, le paramètre de type générique est la classe .NET. Pour les surcharges non génériques, vous transmettez le type de la classe en tant que paramètre de la méthode. Vous pouvez désérialiser de façon synchrone ou asynchrone.

Toutes les propriétés JSON qui ne sont pas représentées dans votre classe sont ignorées par défaut. En outre, si des propriétés sur le type sont requises, mais qu’elles ne sont pas présentes dans la charge utile JSON, la désérialisation échoue.

Exemples

L’exemple suivant montre comment désérialiser une chaîne 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)

Pour désérialiser à partir d’un fichier à l’aide de code synchrone, lisez le fichier dans une chaîne, comme illustré dans l’exemple suivant :

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)

Pour désérialiser à partir d’un fichier à l’aide de code asynchrone, appelez la méthode 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)

Comportement de désérialisation

Les comportements suivants s’appliquent lors de la désérialisation de JSON :

• Par défaut, la correspondance de nom de propriété respecte la casse. Vous pouvez spécifier l’insensibilité à la casse.
• Les constructeurs non publics sont ignorés par le sérialiseur.
• La désérialisation vers des objets ou des propriétés immuables qui n’ont pas d’accesseurs publics set est prise en charge, mais elle n’est pas activée par défaut. Consultez Types et enregistrements immuables.
• Par défaut, les énumérations sont prises en charge en tant que nombres. Vous pouvez désérialiser des champs d’une énumération de chaîne.
• Par défaut, les champs sont ignorés. Vous pouvez inclure des champs.
• Par défaut, les commentaires ou les virgules de fin dans le JSON lèvent des exceptions. Vous pouvez autoriser les commentaires et les virgules de fin.
• La profondeur maximale par défaut est de 64.

Lorsque vous utilisez System.Text.Json indirectement dans une application ASP.NET Core, certains comportements par défaut sont différents. Pour plus d’informations, consultez Valeurs web par défaut pour JsonSerializerOptions.

Vous pouvez implémenter des convertisseurs personnalisés pour fournir des fonctionnalités qui ne sont pas prises en charge par les convertisseurs intégrés.

Désérialiser sans une classe .NET

Si vous avez du JSON que vous souhaitez désérialiser et que vous n’avez pas la classe pour le désérialiser, vous avez d’autres options que la création manuelle de la classe dont vous avez besoin :

• Utilisez Utf8JsonReader directement.

• Désérialisez dans un DOM (modèle objet de document) JSON et extrayez ce dont vous avez besoin du DOM.

  Le DOM vous permet d’accéder à une sous-section d’une charge utile JSON et de désérialiser une valeur unique, un type personnalisé ou un tableau. Pour plus d’informations sur le DOM JsonNode, consultez Désérialiser les sous-sections d’une charge utile JSON. Pour plus d’informations sur le DOM JsonDocument, consultez Comment rechercher des sous-éléments dans jsonDocument et JsonElement.

• Utilisez Visual Studio 2022 pour générer automatiquement la classe dont vous avez besoin :

  • Copiez le JSON que vous devez désérialiser.
  • Créez un fichier de classe et supprimez le code du modèle.
  • Choisissez Modifier>Collage spécial>Coller le code JSON en tant que classes.

  Le résultat est une classe que vous pouvez utiliser pour votre cible de désérialisation.

Désérialiser à partir d’UTF-8

Pour désérialiser à partir de UTF-8, appelez une surcharge de JsonSerializer.Deserialize qui prend un ReadOnlySpan<byte> ou un Utf8JsonReader, comme illustré dans les exemples suivants. Les exemples supposent que le JSON se trouve dans un tableau d’octets nommé 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

Utilisez GitHub Copilot pour désérialiser du JSON

Vous pouvez utiliser GitHub Copilot dans votre IDE pour générer du code qui utilise System.Text.Json pour désérialiser depuis JSON.

Si vous utilisez Visual Studio 2022 version 17.8 ou une version ultérieure, vous pouvez essayer le GitHub Copilot piloté par l’IA dans Visual Studio pour générer du code qui utilise System.Text.Json pour désérialiser du JSON. Soumettez votre question sous forme de requête dans la fenêtre de discussion de Copilot, comme dans l’exemple suivant. Vous pouvez également soumettre des requêtes en utilisant le chat en ligne dans la fenêtre de l’éditeur elle-même.

Le texte suivant montre un exemple d’invite pour le chat Copilot :

Générez du code pour utiliser System.Text.Json pour désérialiser une chaîne JSON {"FirstName":"John","LastName":"Doe","Age":30} en un objet .NET équivalent. Associez les noms de propriétés & les valeurs. Fournir un exemple de sortie.

Vous pouvez personnaliser l’invite pour utiliser une chaîne JSON avec des noms de propriétés et des valeurs qui correspondent à vos besoins.

Vous pouvez utiliser les fonctionnalités du chat, telles que les commandes à barres obliques, les références à des fichiers, des méthodes ou des classes, et les threads, pour définir l’intention et obtenir de meilleures réponses avec un contexte élargi. Pour une classe existante dans un projet ouvert dans l’IDE, vous pouvez demander à GitHub Copilot avec /generate code to dserialize JSON to equivalent .NET object in #Filename.

Voici un exemple de réponse du chat Copilot :

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.

Lorsque Copilot retourne un bloc de code, la réponse inclut des options pour copier le code, insérer le code dans un nouveau fichier, ou prévisualiser la sortie du code.

Pour plus d’informations, consultez l’article suivant :

• Centre de gestion de la confidentialité GitHub Copilot
• GitHub Copilot dans Visual Studio
• GitHub Copilot dans VS Code