Unterstützte Typen in System.Text.Json

In diesem Artikel finden Sie eine Übersicht darüber, welche Typen für die Serialisierung und Deserialisierung unterstützt werden.

Typen, die als JSON-Objekte serialisiert werden

Die folgenden Typen serialisieren als JSON-Objekte:

• Klassen^*
• Strukturen
• Schnittstellen
• Datensätze und Strukturdatensätze

* Nichtwörterbuchtypen, die IEnumerable<T> als JSON-Arrays serialisieren. Wörterbuchtypen, die IEnumerable<T>implementieren, serialisieren sie als JSON-Objekte.

Der folgende Codeausschnitt zeigt die Serialisierung einer einfachen Struktur.

public static void Main()
{
    var coordinates = new Coords(1.0, 2.0);
    string json = JsonSerializer.Serialize(coordinates);
    Console.WriteLine(json);

    // Output:
    // {"X":1,"Y":2}
}

public readonly struct Coords
{
    public Coords(double x, double y)
    {
        X = x;
        Y = y;
    }

    public double X { get; }
    public double Y { get; }
}

Typen, die als JSON-Arrays serialisiert werden

.NET-Sammlungstypen serialisieren als JSON-Arrays. System.Text.Json.JsonSerializer unterstützt einen Sammlungstyp für die Serialisierung, wenn er:

• Abgeleitet von IEnumerable oder IAsyncEnumerable<T>.
• Enthält Elemente, die serialisierbar sind.

Der Serialisierer ruft die GetEnumerator()-Methode auf und schreibt die Elemente.

Die Deserialisierung ist komplizierter und wird für einige Sammlungstypen nicht unterstützt.

Die folgenden Abschnitte sind nach Namespace organisiert und zeigen an, welche Typen für die Serialisierung und Deserialisierung unterstützt werden.

• System.Array-Namespace
• System.Collections-Namespace
• System.Collections.Generic-Namespace
• System.Collections.Immutable Namespace
• System.Collections.Specialized Namespace
• System.Collections.Gleichzeitiger Namespace
• System.Collections.ObjectModel-Namespace
• benutzerdefinierte Auflistungen

System.Array-Namespace

* byte[] wird speziell behandelt und als base64-Zeichenfolge und nicht als JSON-Array serialisiert.

System.Collections-Namespace

* Siehe Support Roundtrip für Stack Typen.

System.Collections.Generic-Namespace

* Siehe Unterstützte Schlüsseltypen.

† Weitere Informationen finden Sie im folgenden Abschnitt zu IAsyncEnumerable<T>.

– Siehe Support Roundtrip für Stack Typen.

§ System.Text.Json unterstützt IReadOnlySet<T> in .NET 11 und neueren Versionen. Wenn Sie die Schnittstelle deserialisieren, erstellt der Serializer eine HashSet<T> Instanz. Erstellt für generierte Metadaten JsonMetadataServices.CreateIReadOnlySetInfo den Sammlungsvertrag.

IAsyncEnumerable<T->

In den folgenden Beispielen werden Datenströme als Darstellung einer asynchronen Datenquelle verwendet. Die Quelle kann Dateien auf einem lokalen Computer oder Ergebnisse aus einem Datenbankabfrage- oder Webdienst-API-Aufruf sein.

Stream serialisierung

System.Text.Json unterstützt die Serialisierung IAsyncEnumerable<T> Werte als JSON-Arrays, wie im folgenden Beispiel gezeigt:

using System.Text.Json;

namespace IAsyncEnumerableSerialize;

public class Program
{
    public static async Task Main()
    {
        using Stream stream = Console.OpenStandardOutput();
        var data = new { Data = PrintNumbers(3) };
        await JsonSerializer.SerializeAsync(stream, data);
    }

    static async IAsyncEnumerable<int> PrintNumbers(int n)
    {
        for (int i = 0; i < n; i++)
        {
            await Task.Delay(1000);
            yield return i;
        }
    }
}
// output:
//  {"Data":[0,1,2]}

IAsyncEnumerable<T> Werte werden nur von den asynchronen Serialisierungsmethoden wie JsonSerializer.SerializeAsyncunterstützt.

In .NET 11 und neueren Versionen JsonSerializer.SerializeAsyncEnumerable schreibt eine IAsyncEnumerable<T> Sequenz entweder in eine Stream oder eine PipeWriter. Mit der Standardeinstellung topLevelValues: falseschreibt die Methode ein einzelnes JSON-Array auf Stammebene. Legen Sie topLevelValues: true stattdessen fest, dass JSON-Zeilen geschrieben werden, wobei jedes Element ein separater Wert auf oberster Ebene ist:

{"id":1,"name":"apple"}
{"id":2,"name":"banana"}

Die Methode schreibt einen einzelnen Zeilenvorschub (LF), \nnach jedem Wert, einschließlich des letzten Werts. Es verwendet immer LF, unabhängig von JsonSerializerOptions.NewLine. Die Methode ignoriert JsonSerializerOptions.WriteIndented, sodass jeder Wert in einer Zeile verbleibt.

Stream-Deserialisierung

Die DeserializeAsyncEnumerable-Methode unterstützt die Streaming-Deserialisierung, wie im folgenden Beispiel gezeigt:

using System.Text;
using System.Text.Json;

namespace IAsyncEnumerableDeserialize;

public class Program
{
    public static async Task Main()
    {
        using var stream = new MemoryStream(Encoding.UTF8.GetBytes("[0,1,2,3,4]"));
        await foreach (int item in JsonSerializer.DeserializeAsyncEnumerable<int>(stream))
        {
            Console.WriteLine(item);
        }
    }
}
// output:
//0
//1
//2
//3
//4

Liest standardmäßig JsonSerializer.DeserializeAsyncEnumerable Elemente aus einem einzelnen JSON-Array auf Stammebene. Legen Sie diese Einstellung topLevelValues: true fest, um stattdessen eine Sequenz von Leerzeichen getrennten Werten auf oberster Ebene zu lesen. Dieses Eingabeformat ist eine Obermenge von JSON-Zeilen. Überladungen akzeptieren entweder ein Stream oder ein PipeReader.

Die DeserializeAsync-Methode unterstützt IAsyncEnumerable<T>, die Signatur lässt jedoch kein Streaming zu. Das Endergebnis wird als einzelner Wert zurückgegeben, wie im folgenden Beispiel gezeigt.

using System.Text;
using System.Text.Json;

namespace IAsyncEnumerableDeserializeNonStreaming;

public class MyPoco
{
    public IAsyncEnumerable<int>? Data { get; set; }
}

public class Program
{
    public static async Task Main()
    {
        using var stream = new MemoryStream(Encoding.UTF8.GetBytes(@"{""Data"":[0,1,2,3,4]}"));
        MyPoco? result = await JsonSerializer.DeserializeAsync<MyPoco>(stream)!;
        await foreach (int item in result!.Data!)
        {
            Console.WriteLine(item);
        }
    }
}
// output:
//0
//1
//2
//3
//4

In diesem Beispiel puffert der Deserializer alle IAsyncEnumerable<T> Inhalte im Arbeitsspeicher, bevor das deserialisierte Objekt zurückgegeben wird. Dieses Verhalten ist erforderlich, da der Deserializer die gesamte JSON-Nutzlast lesen muss, bevor ein Ergebnis zurückgegeben wird.

System.Collections.Immutable Namespace

* Siehe Support Roundtrip für Stack Typen.

† Siehe Unterstützte Schlüsseltypen.

System.Collections.Specialized-Namespace

* Wenn BitVector32 deserialisiert wird, wird die Data-Eigenschaft übersprungen, da kein öffentlicher Setter vorhanden ist. Es wird keine Ausnahme ausgelöst.

System.Collections.Gleichzeitiger Namespace

* Siehe Support Roundtrip für Stack Typen.

† Siehe Unterstützte Schlüsseltypen.

System.Collections.ObjectModel-Namespace

* Nichtstring Schlüssel werden nicht unterstützt.

Benutzerdefinierte Auflistungen

Jeder Sammlungstyp, der sich nicht in einem der vorherigen Namespaces befindet, wird als benutzerdefinierte Auflistung betrachtet. Zu diesen Typen gehören benutzerdefinierte Typen und Typen, die von ASP.NET Core definiert werden. Beispielsweise befindet sich Microsoft.Extensions.Primitives in dieser Gruppe.

Alle benutzerdefinierten Auflistungen (alles, was von IEnumerableabgeleitet wird) werden für die Serialisierung unterstützt, solange ihre Elementtypen unterstützt werden.

Deserialisierungsunterstützung

Eine benutzerdefinierte Auflistung wird für die Deserialisierung unterstützt, wenn sie:

• Es handelt sich nicht um eine Schnittstelle oder eine abstrakte Schnittstelle.

• Besitzt einen parameterlosen Konstruktor.

• Enthält Elementtypen, die von JsonSerializerunterstützt werden.

• Implementiert oder erbt eine oder mehrere der folgenden Schnittstellen oder Klassen:

  • ConcurrentQueue<T>
  • ConcurrentStack<T> *
  • ICollection<T>
  • IDictionary
  • IDictionary<TKey,TValue> †
  • IList
  • IList<T>
  • Queue
  • Queue<T>
  • Stack *
  • Stack<T> *

  * Siehe Support Roundtrip für Stack Typen.

  † Siehe Unterstützte Schlüsseltypen.

Bekannte Probleme

Es gibt bekannte Probleme mit den folgenden benutzerdefinierten Auflistungen:

• ExpandoObject: Siehe dotnet/runtime#29690.
• DynamicObject: Siehe dotnet/runtime#1808.
• DataTable: Siehe dotnet/docs#21366.
• Microsoft.AspNetCore.Http.FormFile: Siehe dotnet/runtime#1559.
• Microsoft.AspNetCore.Http.IFormCollection: Siehe dotnet/runtime#1559.

Weitere Informationen zu bekannten Problemen finden Sie in den offenen Problemen in System.Text.Json.

Unterstützte Schlüsseltypen

Bei Verwendung als Schlüssel von Dictionary- und SortedList Typen haben die folgenden Typen integrierte Unterstützung:

• BFloat16(.NET 11 und höher)
• Boolean
• Byte
• DateTime
• DateTimeOffset
• Decimal
• Decimal32(.NET 11 und höher)
• Decimal64(.NET 11 und höher)
• Decimal128(.NET 11 und höher)
• Double
• Enum
• Guid
• Int16
• Int32
• Int64
• Object (Nur bei serialisierung und wenn der Laufzeittyp einer der unterstützten Typen in dieser Liste ist.)
• SByte
• Single
• String
• TimeSpan
• UInt16
• UInt32
• UInt64
• Uri
• Version

Darüber hinaus können Sie mit den Methoden JsonConverter<T>.WriteAsPropertyName(Utf8JsonWriter, T, JsonSerializerOptions) und JsonConverter<T>.ReadAsPropertyName(Utf8JsonReader, Type, JsonSerializerOptions) Wörterbuchschlüsselunterstützung für jede Art Ihrer Wahl hinzufügen.

BFloat16- und Dezimalkomma-Gleitkommatypen

Ab .NET 11 System.Text.Json sind integrierte Konverter für die BFloat16, Decimal32, , Decimal64und Decimal128 Typen enthalten. Endliche Werte serialisieren als JSON-Zahlen.

Diese Typen verhalten sich wie die anderen integrierten numerischen Typen:

• Die Wörterbuchschlüsselkonvertierung unterstützt alle vier Typen.
• Sie ehren JsonNumberHandling, einschließlich der "NaN", "Infinity"und "-Infinity" Literale durch AllowNamedFloatingPointLiterals.

JsonMetadataServices macht Konvertereigenschaften für vom Quell generierte Metadaten verfügbar. Die Eigenschaften sind JsonMetadataServices.BFloat16Converter, JsonMetadataServices.Decimal32Converter, JsonMetadataServices.Decimal64Converter und JsonMetadataServices.Decimal128Converter.

F# diskriminierte Gewerkschaften

Beginnend mit .NET 11 System.Text.Json serialisiert und deserialisiert F#diskriminierte Gewerkschaften, einschließlich Klassen-, Struktur- und rekursive Gewerkschaften:

type Shape =
    | Point
    | Circle of radius: float

• Ein Fall ohne Felder serialisiert als JSON-Zeichenfolge, die den Fallnamen enthält, z "Point". B. .
• Ein Fall, in dem Felder als JSON-Objekt serialisiert werden. Das Objekt enthält einen $type Diskriminator gefolgt von den benannten Feldern des Falls, z {"$type":"Circle","radius":3.14}. B. .

JsonSerializerOptions.PropertyNamingPolicy gilt für Groß- und Kleinschreibungsnamen und Feldnamen. Eine Fallebene JsonPropertyNameAttribute hat Vorrang. Wenn Sie einen anderen Namen als die Diskriminatoreigenschaft verwenden $typemöchten, legen Sie fest JsonPolymorphicAttribute.TypeDiscriminatorPropertyName.

Nicht unterstützte Typen

Die folgenden Typen werden für die Serialisierung nicht unterstützt:

• System.Type und System.Reflection.MemberInfo
• ReadOnlySpan<T>, Span<T>und Referenzstruktur im Allgemeinen
• Delegattypen
• IntPtr und UIntPtr

System.Data-Namespace

Es gibt keine integrierten Konverter für DataSet, DataTableund verwandte Typen im System.Data-Namespace. Das Deserialisieren dieser Typen von nicht vertrauenswürdigen Eingaben ist nicht sicher, wie in der Sicherheitsleitfadenerläutert. Sie können jedoch einen benutzerdefinierten Konverter schreiben, um diese Typen zu unterstützen. Beispielcode für benutzerdefinierte Konverter, der eine DataTableserialisiert und deserialisiert, finden Sie unter RoundtripDataTable.cs.

Siehe auch

• Auffüllen initialisierter Eigenschaften
• System.Text.Json Übersicht
• System.Text.Json API-Referenz-
• System.Text.Json. Serialisierungs-API-Referenz