JSON-Serialisierung und -Deserialisierung (Marshalling und Rückgängigmachen von Marshalling) in .NET: Überblick

  • Artikel

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:

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.

Zusätzliche Ressourcen