Sérialisation et désérialisation JSON (marshalling et unmarshalling) dans .NET - vue d’ensemble

  • Article

L’espace de noms System.Text.Json fournit des fonctionnalités de sérialisation vers et de désérialisation à partir de JavaScript Object Notation (JSON). La sérialisation est le processus de conversion de l’état d’un objet, c’est-à-dire les valeurs de ses propriétés, dans une forme qui peut être stockée ou transmise. La forme sérialisée n’inclut aucune information sur les méthodes associées d’un objet. La désérialisation reconstruit un objet à partir de la forme sérialisée.

La conception de la bibliothèque System.Text.Json met l’accent sur les performances élevées et la faible allocation de mémoire sur un ensemble complet de fonctionnalités. La prise en charge intégrée d’UTF-8 optimise le processus de lecture et d’écriture de texte JSON encodé en UTF-8, qui est l’encodage le plus répandu pour les données sur le web et les fichiers sur disque.

La bibliothèque fournit également des classes pour utiliser un modèle DOM (document object model) en mémoire. Cette fonctionnalité permet un accès aléatoire aux éléments d’un fichier ou d’une chaîne JSON.

Pour Visual Basic, il existe des limitations sur les parties de la bibliothèque que vous pouvez utiliser. Pour plus d’informations, consultez le Support Visual Basic.

Comment obtenir la bibliothèque

La bibliothèque est intégrée dans le cadre du framework partagé pour .NET Core 3.0 et versions ultérieures. La fonctionnalité de génération de source est intégrée dans le cadre du framework partagé pour .NET 6 et versions ultérieures.

Pour les versions de framework antérieures à .NET Core 3.0, installez le package NuGet System.Text.Json. Le package prend en charge :

  • .NET Standard 2.0 et ultérieur
  • .NET Framework 4.6.2 et versions ultérieures
  • .NET Core 2.1 et ultérieur
  • .NET 5 et versions ultérieures

Espaces de noms et API

  • L’espace de noms System.Text.Json contient tous les points d’entrée et les types principaux.
  • L’espace de noms System.Text.Json.Serialization contient des attributs et des API pour les scénarios avancés, et la personnalisation spécifique à la sérialisation et à la désérialisation.

Les exemples de code présentés dans cet article nécessitent des directives using pour l’un de ces espaces de noms ou les deux.

Important

System.Text.Json ne prend pas en charge les API de sérialisation suivantes (que vous avez éventuellement déjà utilisées) :

Méthodes d’extension HttpClient et HttpContent

La sérialisation et la désérialisation des charges utiles JSON à partir du réseau sont des opérations courantes. Les méthodes d’extension sur HttpClient et HttpContent vous permettent d’effectuer ces opérations en une seule ligne de code. Ces méthodes d’extension utilisent des valeurs web par défaut pour JsonSerializerOptions.

L’exemple suivant illustre l’utilisation de HttpClientJsonExtensions.GetFromJsonAsync et HttpClientJsonExtensions.PostAsJsonAsync :

using System.Net.Http.Json;

namespace HttpClientExtensionMethods
{
    public class User
    {
        public int Id { get; set; }
        public string? Name { get; set; }
        public string? Username { get; set; }
        public string? Email { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            using HttpClient client = new()
            {
                BaseAddress = new Uri("https://jsonplaceholder.typicode.com")
            };

            // Get the user information.
            User? user = await client.GetFromJsonAsync<User>("users/1");
            Console.WriteLine($"Id: {user?.Id}");
            Console.WriteLine($"Name: {user?.Name}");
            Console.WriteLine($"Username: {user?.Username}");
            Console.WriteLine($"Email: {user?.Email}");

            // Post a new user.
            HttpResponseMessage response = await client.PostAsJsonAsync("users", user);
            Console.WriteLine(
                $"{(response.IsSuccessStatusCode ? "Success" : "Error")} - {response.StatusCode}");
        }
    }
}

// Produces output like the following example but with different names:
//
//Id: 1
//Name: Tyler King
//Username: Tyler
//Email: Tyler @contoso.com
//Success - Created

Imports System.Net.Http
Imports System.Net.Http.Json

Namespace HttpClientExtensionMethods

    Public Class User
        Public Property Id As Integer
        Public Property Name As String
        Public Property Username As String
        Public Property Email As String
    End Class

    Public Class Program

        Public Shared Async Function Main() As Task
            Using client As New HttpClient With {
                .BaseAddress = New Uri("https://jsonplaceholder.typicode.com")
                }

                ' Get the user information.
                Dim user1 As User = Await client.GetFromJsonAsync(Of User)("users/1")
                Console.WriteLine($"Id: {user1.Id}")
                Console.WriteLine($"Name: {user1.Name}")
                Console.WriteLine($"Username: {user1.Username}")
                Console.WriteLine($"Email: {user1.Email}")

                ' Post a new user.
                Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("users", user1)
                Console.WriteLine(
                $"{(If(response.IsSuccessStatusCode, "Success", "Error"))} - {response.StatusCode}")
            End Using
        End Function

    End Class

End Namespace

' Produces output like the following example but with different names:
'
'Id: 1
'Name: Tyler King
'Username: Tyler
'Email: Tyler @contoso.com
'Success - Created

Il existe également des méthodes d’extension pour System.Text.Json sur HttpContent.

Réflexion et génération de source

Par défaut, System.Text.Json collecte les métadonnées dont il a besoin pour accéder aux propriétés des objets pour la sérialisation et la désérialisation au moment du temps d’exécution en utilisant réflexion. En guise d’alternative, System.Text.Json peut utiliser la fonctionnalité de génération de source C# pour améliorer les performances, réduire l’utilisation de la mémoire privée et faciliter le découpage d’assembly, ce qui réduit la taille de l’application.

Pour plus d’informations, voir Réflexion et génération de sources.

Informations de sécurité

Pour plus d’informations sur les menaces de sécurité qui ont été prises en compte lors de la conception de JsonSerializer et sur la façon dont elles peuvent être atténuées, consultez Modèle de menace System.Text.Json.

Sécurité des threads

Le sérialiseur System.Text.Json a été conçu en gardant à l’esprit la sécurité des threads. En pratique, cela signifie qu’une fois verrouillées, les instances JsonSerializerOptions peuvent être partagées de façon sécurisée entre plusieurs threads. JsonDocument fournit une représentation DOM thread-safe, immuable et dans .NET 8 (et les versions ultérieures), pour les valeurs JSON.

Ressources supplémentaires