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

Article
11/08/2023

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.

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

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)

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)

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.

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

Comportements de sérialisation

Sérialiser vers UTF-8

Sérialiser en JSON mis en forme

Commentaires

Ressources supplémentaires