Serializzazione e deserializzazione (marshalling e annullamento del marshalling) di JSON in .NET - Panoramica
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:
- Attributi dallo spazio dei nomi System.Runtime.Serialization.
- Attributo System.SerializableAttribute e interfaccia ISerializable. Questi tipi vengono usati solo per la serializzazione in formato binario e XML.
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.
