Delen via

Ondersteunde typen in System.Text.Json

  • Artikel

Dit artikel bevat een overzicht van welke typen worden ondersteund voor serialisatie en deserialisatie.

Typen die worden geserialiseerd als JSON-objecten

De volgende typen serialiseren als JSON-objecten:

  • Klassen*
  • Structs
  • Interfaces
  • Records en struct-records

* Niet-woordenlijsttypen die IEnumerable<T> serialiseren als JSON-matrices. Woordenlijsttypen, die IEnumerable<T>implementeren, serialiseren als JSON-objecten.

Het volgende codefragment toont de serialisatie van een eenvoudige struct.

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 worden geserialiseerd als JSON-matrices

.NET-verzamelingstypen serialiseren als JSON-matrices. System.Text.Json.JsonSerializer ondersteunt een verzamelingstype voor serialisatie als dit het volgende is:

De serializer roept de GetEnumerator() methode aan en schrijft de elementen.

Deserialisatie is ingewikkelder en wordt niet ondersteund voor sommige verzamelingstypen.

De volgende secties zijn ingedeeld op naamruimte en laten zien welke typen worden ondersteund voor serialisatie en deserialisatie.

System.Array-naamruimte

Type Serialisatie Deserialisatie
eendimensionale matrices ✔️ ✔️
multidimensionale matrices ❌ ❌
gemarkeerde matrices ✔️ ✔️

System.Collections-naamruimte

Type Serialisatie Deserialisatie
ArrayList ✔️ ✔️
BitArray ✔️ ❌
DictionaryEntry ✔️ ✔️
Hashtable ✔️ ✔️
ICollection ✔️ ✔️
IDictionary ✔️ ✔️
IEnumerable ✔️ ✔️
IList ✔️ ✔️
Queue ✔️ ✔️
SortedList ✔️ ✔️
Stack * ✔️ ✔️

* Zie Ondersteuningsrondje voor Stack typen.

System.Collections.Generic-naamruimte

Type Serialisatie Deserialisatie
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> ‡ ✔️ ✔️

* Zie Ondersteunde sleuteltypen.

† Zie de volgende sectie over IAsyncEnumerable<T>.

‡ Zie Ondersteuningsrondje voor Stack typen.

IAsyncEnumerable<T->

In de volgende voorbeelden worden streams gebruikt als een weergave van een asynchrone gegevensbron. De bron kan bestanden op een lokale computer zijn, of resultaten van een databasequery of webservice-API-aanroep.

Stream-serialisatie

System.Text.Json ondersteunt het serialiseren van IAsyncEnumerable<T> waarden als JSON-matrices, zoals wordt weergegeven in het volgende voorbeeld:

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> waarden worden alleen ondersteund door de asynchrone serialisatiemethoden, zoals JsonSerializer.SerializeAsync.

Stroomdeserialisatie

De methode DeserializeAsyncEnumerable ondersteunt streamingdeserialisatie, zoals wordt weergegeven in het volgende voorbeeld:

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

De methode DeserializeAsyncEnumerable biedt alleen ondersteuning voor het lezen van JSON-matrices op hoofdniveau.

De methode DeserializeAsync ondersteunt IAsyncEnumerable<T>, maar de handtekening staat streaming niet toe. Het uiteindelijke resultaat wordt als één waarde geretourneerd, zoals wordt weergegeven in het volgende voorbeeld.

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 dit voorbeeld buffert deserializer alle IAsyncEnumerable<T> inhoud in het geheugen voordat het gedeserialiseerde object wordt geretourneerd. Dit gedrag is nodig omdat de deserializer de volledige JSON-nettolading moet lezen voordat een resultaat wordt geretourneerd.

System.Collections.Immutable naamruimte

Type Serialisatie Deserialisatie
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> * ✔️ ✔️

* Zie Ondersteuningsrondje voor Stack typen.

† Zie Ondersteunde sleuteltypen.

System.Collections.Specialized-naamruimte

Type Serialisatie Deserialisatie
BitVector32 ✔️ ❌*
HybridDictionary ✔️ ✔️
IOrderedDictionary ✔️ ❌
ListDictionary ✔️ ✔️
NameValueCollection ✔️ ❌
StringCollection ✔️ ❌
StringDictionary ✔️ ❌

* Wanneer BitVector32 wordt gedeserialiseerd, wordt de eigenschap Data overgeslagen omdat deze geen openbare setter heeft. Er wordt geen uitzondering gegenereerd.

System.Collections.Concurrent-naamruimte

Type Serialisatie Deserialisatie
BlockingCollection<T> ✔️ ❌
ConcurrentBag<T> ✔️ ❌
ConcurrentDictionary<TKey,TValue> † ✔️ ✔️
ConcurrentQueue<T> ✔️ ✔️
ConcurrentStack<T> * ✔️ ✔️

* Zie Ondersteuningsrondje voor Stack typen.

† Zie Ondersteunde sleuteltypen.

System.Collections.ObjectModel-naamruimte

Type Serialisatie Deserialisatie
Collection<T> ✔️ ✔️
KeyedCollection<tekenreeks, TValue> * ✔️ ❌
ObservableCollection<T> ✔️ ✔️
ReadOnlyCollection<T> ✔️ ❌
ReadOnlyDictionary<TKey,TValue> ✔️ ❌
ReadOnlyObservableCollection<T> ✔️ ❌

* Niet-string sleutels worden niet ondersteund.

Aangepaste verzamelingen

Een verzamelingstype dat zich niet in een van de voorgaande naamruimten bevindt, wordt beschouwd als een aangepaste verzameling. Dergelijke typen omvatten door de gebruiker gedefinieerde typen en typen die zijn gedefinieerd door ASP.NET Core. Microsoft.Extensions.Primitives bevindt zich bijvoorbeeld in deze groep.

Alle aangepaste verzamelingen (alles wat is afgeleid van IEnumerable) worden ondersteund voor serialisatie, zolang hun elementtypen worden ondersteund.

Ondersteuning voor deserialisatie

Een aangepaste verzameling wordt ondersteund voor deserialisatie als deze:

Bekende problemen

Er zijn bekende problemen met de volgende aangepaste verzamelingen:

Zie de openstaande problemen in System.Text.Jsonvoor meer informatie over bekende problemen.

Ondersteunde sleuteltypen

Wanneer deze worden gebruikt als sleutels van Dictionary en SortedList typen, hebben de volgende typen ingebouwde ondersteuning:

  • Boolean
  • Byte
  • DateTime
  • DateTimeOffset
  • Decimal
  • Double
  • Enum
  • Guid
  • Int16
  • Int32
  • Int64
  • Object (alleen bij serialisatie en als het runtimetype een van de ondersteunde typen in deze lijst is.)
  • SByte
  • Single
  • String
  • TimeSpan
  • UInt16
  • UInt32
  • UInt64
  • Uri
  • Version

Bovendien kunt u met de methoden JsonConverter<T>.WriteAsPropertyName(Utf8JsonWriter, T, JsonSerializerOptions) en JsonConverter<T>.ReadAsPropertyName(Utf8JsonReader, Type, JsonSerializerOptions) woordenlijstsleutels toevoegen voor elk type van uw keuze.

Niet-ondersteunde typen

De volgende typen worden niet ondersteund voor serialisatie:

System.Data-naamruimte

Er zijn geen ingebouwde conversieprogramma's voor DataSet, DataTableen gerelateerde typen in de System.Data-naamruimte. Het deserialiseren van deze typen van niet-vertrouwde invoer is niet veilig, zoals wordt uitgelegd in de beveiligingsrichtlijnen. U kunt echter een aangepast conversieprogramma schrijven om deze typen te ondersteunen. Zie RoundtripDataTable.csvoor voorbeeldcode voor aangepaste conversieprogramma's waarmee een DataTablewordt geserialiseerd en gedeserialiseerd.

Zie ook