Serializzazione e deserializzazione (marshalling e annullamento del marshalling) di JSON in .NET - Panoramica

  • Articolo

Lo spazio dei nomi System.Text.Json fornisce funzionalità per la serializzazione e la deserializzazione da JavaScript Object Notation (JSON). La serializzazione è il processo di conversione dello stato di un oggetto, ovvero dei valori delle relative proprietà, in un formato che può essere archiviato o trasmesso. Il formato serializzato non include informazioni sui metodi associati di un oggetto. La deserializzazione ricostruisce un oggetto dal formato serializzato.

La struttura della libreria System.Text.Json privilegia le prestazioni elevate e la bassa allocazione di memoria rispetto a un set di funzionalità esteso. Il supporto predefinito per UTF-8 ottimizza il processo di lettura e scrittura del testo JSON con codifica UTF-8, che è quella più diffusa per i dati sul Web e per i file su disco.

La libreria fornisce anche classi per l'uso di un modello DOM (Document Object Model) in memoria. Questa funzionalità consente l'accesso casuale agli elementi in una stringa o un file JSON.

Per Visual Basic esistono alcune limitazioni in merito alle parti della libreria che è possibile usare. Per altre informazioni, vedere Supporto di Visual Basic.

Come ottenere la libreria

La libreria è incorporata nel framework condiviso per .NET Core 3.0 e versioni successive. La funzionalità di generazione dell'origine è incorporata nel framework condiviso per .NET 6 e versioni successive.

Per le versioni del framework precedenti a .NET Core 3.0, installare il pacchetto NuGet System.Text.Json. Il pacchetto supporta:

  • .NET Standard 2.0 e versioni successive
  • .NET Framework 4.6.2 e versioni successive
  • .NET Core 2.1 e versioni successive
  • .NET 5 e versioni successive

Spazi dei nomi e API

  • Lo spazio dei nomi System.Text.Json contiene tutti i punti di ingresso e i tipi principali.
  • Lo spazio dei nomi System.Text.Json.Serialization contiene attributi e API per personalizzazione e scenari avanzati specifici per la serializzazione e la deserializzazione.

Gli esempi di codice illustrati in questo articolo richiedono direttive using per uno o entrambi questi spazi dei nomi.

Importante

System.Text.Json non supporta le API di serializzazione seguenti che potrebbero essere state usate in precedenza:

Metodi di estensione HttpClient e HttpContent

La serializzazione e la deserializzazione dei payload JSON dalla rete sono operazioni comuni. I metodi di estensione in HttpClient e HttpContent consentono di eseguire queste operazioni in una singola riga di codice. Questi metodi di estensione usano le impostazioni predefinite Web per JsonSerializerOptions.

Nell'esempio seguente viene illustrato l'uso di HttpClientJsonExtensions.GetFromJsonAsync e 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

Esistono anche metodi di estensione per System.Text.Json in HttpContent.

Reflection e generazione dell'origine

Per impostazione predefinita, System.Text.Json raccoglie i metadati necessari per accedere alle proprietà degli oggetti per la serializzazione e la deserializzazione in fase di esecuzione tramite reflection. In alternativa, System.Text.Json può usare la funzionalità di generazione dell'origine di C# per migliorare le prestazioni, ridurre l'utilizzo della memoria privata e facilitare il taglio dell'assembly, riducendo così le dimensioni dell'app.

Per altre informazioni, vedere Reflection e generazione di origini.

Informazioni sulla sicurezza

Per informazioni sulle minacce alla sicurezza considerate durante la progettazione di JsonSerializer e su come attenuarle, vedere Modello di minaccia di System.Text.Json.

Thread safety

Il serializzatore System.Text.Json è stato progettato tenendo conto della thread safety. In pratica, questo significa che una volta bloccate, le istanze di JsonSerializerOptions possono essere condivise in modo sicuro tra più thread. JsonDocument fornisce una rappresentazione DOM non modificabile e thread-safe (in .NET 8 e nelle versioni successive) per i valori di JSON.

Risorse aggiuntive