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. 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.

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

Generate code to use System.Text.Json to deserialize a JSON string {"FirstName":"John","LastName":"Doe","Age":30} to an equivalent .NET object.
Map property names & values.
Provide example output.

GitHub Copilot est alimenté par l’IA, donc des surprises et des erreurs sont possibles. Pour plus d’informations, consultez FAQ copilot.

En savoir plus sur GitHub Copilot dans Visual Studio et GitHub Copilot dans VS Code.