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.

Conseil

Vous pouvez utiliser l’assistance IA pour désérialiser une chaîne JSON.

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 qui contient des collections et des objets imbriqués :

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}");

            if (weatherForecast?.DatesAvailable != null)
            {
                foreach (DateTimeOffset dateTimeOffset in weatherForecast.DatesAvailable)
                {
                    Console.WriteLine($"DateAvailable: {dateTimeOffset}");
                }
            }

            if (weatherForecast?.TemperatureRanges != null)
            {
                foreach (KeyValuePair<string, HighLowTemps> temperatureRange in weatherForecast.TemperatureRanges)
                {
                    Console.WriteLine($"TemperatureRange: {temperatureRange.Key} is {temperatureRange.Value.Low} to {temperatureRange.Value.High}");
                }
            }

            if (weatherForecast?.SummaryWords != null)
            {
                foreach (string summaryWord in weatherForecast.SummaryWords)
                {
                    Console.WriteLine($"SummaryWord: {summaryWord}");
                }
            }
        }
    }
}

/* Output:
 * 
 * Date: 8/1/2019 12:00:00 AM -07:00
 * TemperatureCelsius: 25
 * Summary: Hot
 * DateAvailable: 8/1/2019 12:00:00 AM -07:00
 * DateAvailable: 8/2/2019 12:00:00 AM -07:00
 * TemperatureRange: Cold is -10 to 20
 * TemperatureRange: Hot is 20 to 60
 * SummaryWord: Cool
 * SummaryWord: Windy
 * SummaryWord: Humid
 * */

Imports System.Text.Json

Namespace DeserializeExtra

    Public Class WeatherForecast
        Public Property [Date] As DateTimeOffset
        Public Property TemperatureCelsius As Integer
        Public Property Summary As String
        Public SummaryField As String
        Public Property DatesAvailable As IList(Of DateTimeOffset)
        Public Property TemperatureRanges As Dictionary(Of String, HighLowTemps)
        Public Property SummaryWords As String()
    End Class

    Public Class HighLowTemps
        Public Property High As Integer
        Public Property Low As Integer
    End Class

    Public NotInheritable Class Program

        Public Shared Sub Run()
            Dim jsonString As String =
                "{
                  ""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""
                  ]
                }"

            Dim weatherForecast As WeatherForecast =
                JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

            Console.WriteLine($"Date: {weatherForecast?.Date}")
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}")
            Console.WriteLine($"Summary: {weatherForecast?.Summary}")

            If weatherForecast?.DatesAvailable IsNot Nothing Then
                For Each dateTimeOffset As DateTimeOffset In weatherForecast.DatesAvailable
                    Console.WriteLine($"DateAvailable: {dateTimeOffset}")
                Next
            End If

            If weatherForecast?.TemperatureRanges IsNot Nothing Then
                For Each temperatureRange As KeyValuePair(Of String, HighLowTemps) In weatherForecast.TemperatureRanges
                    Console.WriteLine($"TemperatureRange: {temperatureRange.Key} is {temperatureRange.Value.Low} to {temperatureRange.Value.High}")
                Next
            End If

            If weatherForecast?.SummaryWords IsNot Nothing Then
                For Each summaryWord As String In weatherForecast.SummaryWords
                    Console.WriteLine($"SummaryWord: {summaryWord}")
                Next
            End If
        End Sub

    End Class

End Namespace

' Output:
'
'Date: 8/1/2019 12:00:00 AM -07:00
'TemperatureCelsius: 25
'Summary: Hot
'DateAvailable: 8/1/2019 12:00:00 AM -07:00
'DateAvailable: 8/2/2019 12:00:00 AM -07:00
'TemperatureRange: Cold is -10 to 20
'TemperatureRange: Hot is 20 to 60
'SummaryWord: Cool
'SummaryWord: Windy
'SummaryWord: Humid

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 ou version ultérieure 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

Utiliser l’IA pour désérialiser JSON

Vous pouvez utiliser des outils IA, tels que GitHub Copilot, pour générer du code qui utilise System.Text.Json pour désérialiser à partir de JSON. Par exemple, vous pouvez personnaliser l’invite pour illustrer la désérialisation lorsque la classe cible définit une propriété manquante à partir de l’entrée JSON.

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

Generate C# code to use System.Text.Json to deserialize a JSON string {"FirstName":"John","LastName":"Doe"} to an equivalent .NET object, where the class defines an Age property.
Show what happens when the JSON is missing a property defined in the class.
Provide example output.

Passez en revue les suggestions de Copilot avant de les appliquer.

Pour plus d’informations sur GitHub Copilot, consultez les FAQ de GitHub.

Voir aussi

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-11-19