JSON-Serialisierung und -Deserialisierung (Marshalling und Rückgängigmachen von Marshalling) in .NET: Überblick
Der System.Text.Json-Namespace bietet Funktionalitäten zum Serialisieren in und Deserialisieren aus JSON (JavaScript Object Notation). Serialisierung ist der Prozess der Konvertierung des Zustands eines Objekts, d. h. der Werte seiner Eigenschaften, in eine Form, die gespeichert oder übertragen werden kann. Die serialisierte Form enthält keinerlei Informationen zu den zugeordneten Methoden eines Objekts. Deserialisierung rekonstruiert ein Objekt aus der serialisierten Form.
Beim Entwerfen der System.Text.Json-Bibliothek wurde mehr Wert auf eine hohe Leistung und eine geringe Arbeitsspeicherbelegung gelegt als auf eine große Bandbreite von Features. Die integrierte UTF-8-Unterstützung optimiert den Prozess des Lesens und Schreibens von JSON-Text, der als UTF-8 codiert ist. Dies ist die am häufigsten verwendete Codierung für Daten im Web und Dateien auf Datenträgern.
Die Bibliothek stellt außerdem Klassen für die Arbeit mit einem In-Memory-Dokumentobjektmodell (DOM) zur Verfügung. Diese Funktion ermöglicht einen zufälligen Zugriff auf die Elemente in einer JSON-Datei oder -Zeichenfolge.
Für Visual Basic gibt es einige Einschränkungen hinsichtlich der verwendbaren Teile der Bibliothek. Weitere Informationen finden Sie unter Visual Basic-Unterstützung.
Abrufen der Bibliothek
Die Bibliothek ist als Teil des gemeinsamen Frameworks für .NET Core 3.0 und höhere Versionen integriert. Die Quellgenerierungsfunktion ist als Teil des gemeinsamen Frameworks für .NET 6 und höhere Versionen integriert.
Installieren Sie für Frameworkversionen vor .NET Core 3.0 das NuGet-Paket System.Text.Json. Das Paket unterstützt:
- .NET Standard 2.0 und höher
- .NET Framework 4.6.2 und höher
- .NET Core 2.1 und höher
- .NET 5 und höher
Namespaces und APIs
- Der System.Text.Json-Namespace enthält alle Einstiegspunkte und die Haupttypen.
- Der System.Text.Json.Serialization-Namespace enthält Attribute und APIs für erweiterte Szenarien und Anpassungen, die für die Serialisierung und Deserialisierung spezifisch sind.
Die in diesem Artikel gezeigten Codebeispiele erfordern using-Anweisungen für einen oder beide Namespaces.
Wichtig
System.Text.Json unterstützt die folgenden Serialisierungs-APIs, die Sie möglicherweise zuvor verwendet haben, nicht:
- Attribute aus dem System.Runtime.Serialization-Namespace.
- Das System.SerializableAttribute-Attribut und die ISerializable-Schnittstelle. Diese Typen werden nur für die Binärserialisierung und die XML-Serialisierung verwendet.
Erweiterungsmethoden für HttpClient und HttpContent
Das Serialisieren und Deserialisieren von aus dem Netzwerk stammenden JSON-Nutzdaten sind gängige Vorgänge. Erweiterungsmethoden für HttpClient und HttpContent ermöglichen Ihnen das Ausführen dieser Vorgänge in einer einzelnen Codezeile. Diese Erweiterungsmethoden verwenden Webstandardwerte für JsonSerializerOptions.
Im folgenden Beispiel wird die Verwendung von HttpClientJsonExtensions.GetFromJsonAsync und HttpClientJsonExtensions.PostAsJsonAsync veranschaulicht:
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
Es gibt auch Erweiterungsmethoden für System.Text.Json für HttpContent.
Reflektion im Vergleich zur Quellgenerierung
Standardmäßig erfasst System.Text.Json die Metadaten, die für den Zugriff auf Eigenschaften von Objekten für die Serialisierung und Deserialisierung zur Laufzeit erforderlich sind, mittels Reflexion. Alternativ kann System.Text.Json das C#-Feature zur Quellgenerierung verwenden, um die Leistung zu verbessern, die Nutzung des privaten Arbeitsspeichers zu reduzieren und das Kürzen von Assemblys zu erleichtern, wodurch die App-Größe reduziert wird.
Weitere Informationen finden Sie unter Reflexion im Vergleich zur Quellgenerierung.
Informationen zur Sicherheit
Informationen zu Sicherheitsbedrohungen, die beim Entwerfen von JsonSerializer berücksichtigt wurden, und zu ihrer Entschärfung finden Sie unter System.Text.Json Bedrohungsmodell.
Threadsicherheit
Der System.Text.Json-Serialisierer wurde im Hinblick auf Threadsicherheit entwickelt. Praktisch bedeutet dies, dass JsonSerializerOptions-Instanzen nach der Sperrung sicher über mehrere Threads hinweg freigegeben werden können. JsonDocument stellt eine unveränderliche und in .NET 8 und höheren Versionen, threadsichere DOM-Darstellung für JSON-Werte bereit.
