Comment écrire des objets .NET au format JSON (sérialisation)

Article
10/15/2024

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

Conseil

Vous pouvez utiliser l’assistance AI pour sérialiser en JSON avec GitHub Copilot.

Pour écrire du JSON dans une chaîne ou dans un fichier, appelez la méthode JsonSerializer.Serialize.

Exemple de sérialisation

L’exemple suivant crée du JSON en tant que chaîne :

using System.Text.Json;

namespace SerializeBasic
{
    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()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim jsonString As String

La sortie JSON est réduite au minimum (les espaces blancs, la mise en retrait et les caractères de nouvelle ligne sont supprimés) par défaut.

L’exemple suivant utilise du code synchrone pour créer un fichier JSON :

using System.Text.Json;

namespace SerializeToFile
{
    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()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json"; 
            string jsonString = JsonSerializer.Serialize(weatherForecast);
            File.WriteAllText(fileName, jsonString);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(weatherForecast1)
File.WriteAllText(fileName, jsonString)

L’exemple suivant utilise du code asynchrone pour créer un fichier JSON :

using System.Text.Json;

namespace SerializeToFileAsync
{
    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()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json";
            await using FileStream createStream = File.Create(fileName);
            await JsonSerializer.SerializeAsync(createStream, weatherForecast);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim createStream As FileStream = File.Create(fileName)
Await JsonSerializer.SerializeAsync(createStream, weatherForecast1)

Les exemples précédents utilisent l’inférence de type pour le type sérialisé. Une surcharge de Serialize() prend un paramètre de type générique :

using System.Text.Json;

namespace SerializeWithGenericParameter
{
    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()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize<WeatherForecast>(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

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

Vous pouvez également utiliser GitHub Copilot pour générer le code de sérialisation pour vous. Pour obtenir des instructions, consultez la section Utiliser GitHub Copilot de cet article.

Comportements de sérialisation

Par défaut, l’ensemble des propriétés publiques sont sérialisées. Vous pouvez spécifier des propriétés à ignorer. Vous pouvez également inclure des membres privés.
L’encodeur par défaut échappe les caractères non ASCII, les caractères HTML dans la plage ASCII et les caractères qui doivent être échappés selon la spécification JSON RFC 8259.
Par défaut, le JSON est minifié. Vous pouvez imprimer le JSON de façon élégante.
Par défaut, la casse des noms JSON correspond aux noms .NET. Vous pouvez personnaliser la casse de nom JSON.
Par défaut, les références circulaires sont détectées et des exceptions levées en conséquence. Vous pouvez conserver les références et gérer les références circulaires.
Par défaut, les champs sont ignorés. Vous pouvez inclure des champs.

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.

Les types pris en charge comprennent les suivants :

Primitives .NET qui mappées sur des primitives JavaScript, comme les types numériques, les chaînes et les booléens.
Objets CLR traditionnels (OCT) définis par l’utilisateur.
Tableaux unidimensionnels et en escalier (T[][]).
Collections et dictionnaires provenant des espaces de noms suivants :
Pour plus d’informations, consultez Types de collection pris en charge dans System.Text.Json.

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

Voici un exemple montrant comment une classe qui contient des propriétés de collection et un type défini par l’utilisateur est sérialisée :

using System.Text.Json;

namespace SerializeExtra
{
    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()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot",
                SummaryField = "Hot",
                DatesAvailable = new List<DateTimeOffset>() 
                    { DateTime.Parse("2019-08-01"), DateTime.Parse("2019-08-02") },
                TemperatureRanges = new Dictionary<string, HighLowTemps>
                    {
                        ["Cold"] = new HighLowTemps { High = 20, Low = -10 },
                        ["Hot"] = new HighLowTemps { High = 60 , Low = 20 }
                    },
                SummaryWords = new[] { "Cool", "Windy", "Humid" }
            };

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "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"
//  ]
//}

Public Class WeatherForecastWithPOCOs
    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

' serialization output formatted (pretty-printed with whitespace and indentation):
' {
'   "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"
'   ]
' }

Sérialiser vers UTF-8

Il est 5 à 10 % plus rapide de sérialiser vers un tableau d’octets UTF-8 que d’utiliser les méthodes basées sur des chaînes. En effet, les octets (UTF-8) n’ont pas besoin d’être convertis en chaînes (UTF-16).

Pour sérialiser dans un tableau d’octets UTF-8, appelez la méthode JsonSerializer.SerializeToUtf8Bytes :

byte[] jsonUtf8Bytes =JsonSerializer.SerializeToUtf8Bytes(weatherForecast);

Dim jsonUtf8Bytes As Byte()
Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast1, options)

Une surcharge Serialize qui prend un Utf8JsonWriter est également disponible.

Sérialiser en JSON mis en forme

Pour imprimer élégamment la sortie JSON, définissez JsonSerializerOptions.WriteIndented sur true :

using System.Text.Json;

namespace SerializeWriteIndented
{
    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()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot"
//}

Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, options)

À partir de .NET 9, vous pouvez également personnaliser le caractère et la taille du retrait à l’aide IndentCharacter de and IndentSize.

Conseil

Si vous utilisez JsonSerializerOptions plusieurs fois avec les mêmes options, ne créez pas d’instance de JsonSerializerOptions chaque fois que vous l’utilisez. Réutilisez la même instance pour chaque appel. Pour plus d’informations, consultez Réutiliser des instances de JsonSerializerOptions.

Utiliser GitHub Copilot pour sérialiser en JSON

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

Si vous utilisez Visual Studio 2022 version 17.8 ou ultérieure, vous pouvez essayer le GitHub Copilot in Visual Studio piloté par l’IA pour générer du code qui utilise System.Text.Json pour sérialiser en 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.

Remarque

GitHub Copilot est alimenté par l’IA, donc des surprises et des erreurs sont possibles. Assurez-vous de vérifier tout code ou suggestion généré. Pour plus d’informations sur l’utilisation générale de GitHub Copilot, l’impact du produit, la supervision humaine et la confidentialité, veuillez consulter FAQ GitHub Copilot.

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

Générer du code pour utiliser System.Text.Json afin de sérialiser un objet en une chaîne JSON. L’objet contient les champs suivants : FirstName (chaîne), Lastname (chaîne), Age (int). Fournir un exemple de sortie.

Vous pouvez personnaliser la requête pour utiliser les champs d’objet qui répondent à 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 serialize #Classname in #Filename to JSON.

Voici un exemple de réponse du chat Copilot :

Sure! Below is an example of how to use System.Text.Json to serialize an object with the specified fields to a JSON string 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()
    {
        var person = new Person
        {
            FirstName = "John",
            LastName = "Doe",
            Age = 30
        };

        string jsonString = JsonSerializer.Serialize(person);
        Console.WriteLine(jsonString);
    }
}

**Example Output**
{"FirstName":"John","LastName":"Doe","Age":30}

This code defines a `Person` class, creates an instance of it, and then serializes it to a JSON string using `JsonSerializer.Serialize`. The resulting JSON string is then printed 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.

Remarque

Vos résultats peuvent être différents de ce qui est montré dans les réponses d’exemple. Les modèles IA sont non déterministes, ce qui signifie qu’ils peuvent renvoyer des réponses différentes lorsqu’on leur pose la même question. Cela peut être dû à un apprentissage et à une adaptation supplémentaires au fil du temps, à une variation de la langue, à des changements de contexte, tels que l’historique de votre chat, et plus encore.

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

Partage via