Freigeben über

Unterstützte Typen in System.Text.Json

  • Artikel

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:

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

Art Serialisierung Deserialisierung
eindimensionale Arrays ✔️ ✔️
mehrdimensionalen Arrays ❌ ❌
Jagged Arrays ✔️ ✔️

System.Collections-Namespace

Art Serialisierung Deserialisierung
ArrayList ✔️ ✔️
BitArray ✔️ ❌
DictionaryEntry ✔️ ✔️
Hashtable ✔️ ✔️
ICollection ✔️ ✔️
IDictionary ✔️ ✔️
IEnumerable ✔️ ✔️
IList ✔️ ✔️
Queue ✔️ ✔️
SortedList ✔️ ✔️
Stack * ✔️ ✔️

* Siehe Support Roundtrip für Stack Typen.

System.Collections.Generic-Namespace

Art Serialisierung Deserialisierung
Dictionary<TKey,TValue> * ✔️ ✔️
HashSet<T> ✔️ ✔️
IAsyncEnumerable<T> † ✔️ ✔️
ICollection<T> ✔️ ✔️
IDictionary<TKey,TValue> * ✔️ ✔️
IEnumerable<T> ✔️ ✔️
IList<T> ✔️ ✔️
IReadOnlyCollection<T> ✔️ ✔️
IReadOnlyDictionary<TKey,TValue> * ✔️ ✔️
IReadOnlyList<T> ✔️ ✔️
ISet<T> ✔️ ✔️
KeyValuePair<TKey,TValue> ✔️ ✔️
LinkedList<T> ✔️ ✔️
LinkedListNode<T> ✔️ ❌
List<T> ✔️ ✔️
Queue<T> ✔️ ✔️
SortedDictionary<TKey,TValue> * ✔️ ✔️
SortedList<TKey,TValue> * ✔️ ✔️
SortedSet<T> ✔️ ✔️
Stack<T> ** ✔️ ✔️

* Siehe Unterstützte Schlüsseltypen.

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

– Siehe Support Roundtrip für Stack Typen.

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.

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

Die DeserializeAsyncEnumerable-Methode unterstützt nur das Lesen von JSON-Arrays auf Stammebene.

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

Art Serialisierung Deserialisierung
IImmutableDictionary<TKey,TValue> † ✔️ ✔️
IImmutableList<T> ✔️ ✔️
IImmutableQueue<T> ✔️ ✔️
IImmutableSet<T> ✔️ ✔️
IImmutableStack<T> * ✔️ ✔️
ImmutableArray<T> ✔️ ✔️
ImmutableDictionary<TKey,TValue> † ✔️ ✔️
ImmutableHashSet<T> ✔️ ✔️
ImmutableQueue<T> ✔️ ✔️
ImmutableSortedDictionary<TKey,TValue> † ✔️ ✔️
ImmutableSortedSet<T> ✔️ ✔️
ImmutableStack<T> * ✔️ ✔️

* Siehe Support Roundtrip für Stack Typen.

† Siehe Unterstützte Schlüsseltypen.

System.Collections.Specialized-Namespace

Art Serialisierung Deserialisierung
BitVector32 ✔️ ❌*
HybridDictionary ✔️ ✔️
IOrderedDictionary ✔️ ❌
ListDictionary ✔️ ✔️
NameValueCollection ✔️ ❌
StringCollection ✔️ ❌
StringDictionary ✔️ ❌

* 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

Art Serialisierung Deserialisierung
BlockingCollection<T> ✔️ ❌
ConcurrentBag<T> ✔️ ❌
ConcurrentDictionary<TKey,TValue> † ✔️ ✔️
ConcurrentQueue<T> ✔️ ✔️
ConcurrentStack<T> * ✔️ ✔️

* Siehe Support Roundtrip für Stack Typen.

† Siehe Unterstützte Schlüsseltypen.

System.Collections.ObjectModel-Namespace

Art Serialisierung Deserialisierung
Collection<T> ✔️ ✔️
KeyedCollection<Zeichenfolge, TValue> * ✔️ ❌
ObservableCollection<T> ✔️ ✔️
ReadOnlyCollection<T> ✔️ ❌
ReadOnlyDictionary<TKey,TValue> ✔️ ❌
ReadOnlyObservableCollection<T> ✔️ ❌

* 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:

Bekannte Probleme

Es gibt bekannte Probleme mit den folgenden benutzerdefinierten Auflistungen:

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:

  • Boolean
  • Byte
  • DateTime
  • DateTimeOffset
  • Decimal
  • 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.

Nicht unterstützte Typen

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

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