Typer som stöds i System.Text.Json

Den här artikeln ger en översikt över vilka typer som stöds för serialisering och deserialisering.

Typer som serialiseras som JSON-objekt

Följande typer serialiserar som JSON-objekt:

• Klasser^*
• Structs
• Gränssnitt
• Poster och struct-poster

* Icke-ordlistetyper som implementerar IEnumerable<T> serialisera som JSON-matriser. Ordlistetyper, som implementerar IEnumerable<T>, serialiserar som JSON-objekt.

Följande kodfragment visar serialiseringen av en enkel 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; }
}

Typer som serialiseras som JSON-matriser

.NET-samlingstyper serialiseras som JSON-matriser. System.Text.Json.JsonSerializer stöder en samlingstyp för serialisering om den:

• Härleds från IEnumerable eller IAsyncEnumerable<T>.
• Innehåller element som kan serialiseras.

Serialiseraren anropar metoden GetEnumerator() och skriver elementen.

Deserialisering är mer komplicerat och stöds inte för vissa samlingstyper.

Följande avsnitt ordnas efter namnområde och visar vilka typer som stöds för serialisering och deserialisering.

• System.Array-namnområde
• System.Collections namnområde
• System.Collections.Generic
• System.Collections.Oföränderlig namnrymd
• System.Collections.Specialized
• System.Collections.Concurrent
• System.Collections.ObjectModel-namnområde
• Anpassade samlingar

System.Array-namnområde

* byte[] hanteras speciellt och serialiseras som en base64-sträng, inte en JSON-matris.

System.Collections-namnområde

* Se Support tur och retur för Stack typer.

System.Collections.Generic-namnområde

* Se nyckeltyper som stöds.

† Se följande avsnitt om IAsyncEnumerable<T>.

‡ Se Support tur och retur för Stack typer.

IAsyncEnumerable<T>

I följande exempel används strömmar som en representation av alla asynkrona datakällor. Källan kan vara filer på en lokal dator eller resultat från en databasfråga eller ett API-anrop för webbtjänsten.

Stream-serialisering

System.Text.Json stöder serialisering av IAsyncEnumerable<T> värden som JSON-matriser, enligt följande exempel:

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> värden stöds endast av asynkrona serialiseringsmetoder, till exempel JsonSerializer.SerializeAsync.

Stream-deserialisering

Metoden DeserializeAsyncEnumerable stöder strömmande deserialisering, som du ser i följande exempel:

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

Metoden DeserializeAsyncEnumerable stöder endast läsning från JSON-matriser på rotnivå.

Metoden DeserializeAsync stöder IAsyncEnumerable<T>, men signaturen tillåter inte strömning. Det returnerar slutresultatet som ett enda värde, som du ser i följande exempel.

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

I det här exemplet buffrar deserialiseraren allt IAsyncEnumerable<T> innehåll i minnet innan det deserialiserade objektet returneras. Det här beteendet är nödvändigt eftersom deserialiseraren måste läsa hela JSON-nyttolasten innan resultatet returneras.

System.Collections.Oföränderligt namnområde

* Se Support tur och retur för Stack typer.

† Se nyckeltyper som stöds.

System.Collections.Specialized namespace

* När BitVector32 deserialiseras hoppas egenskapen Data över eftersom den inte har någon offentlig setter. Inget undantag utlöses.

System.Collections.Concurrent-namnområde

* Se Support tur och retur för Stack typer.

† Se nyckeltyper som stöds.

System.Collections.ObjectModel-namnrymd

* Icke-string nycklar stöds inte.

Anpassade samlingar

Alla samlingstyper som inte finns i någon av de föregående namnrymderna anses vara en anpassad samling. Sådana typer omfattar användardefinierade typer och typer som definieras av ASP.NET Core. Till exempel finns Microsoft.Extensions.Primitives i den här gruppen.

Alla anpassade samlingar (allt som härleds från IEnumerable) stöds för serialisering, så länge deras elementtyper stöds.

Stöd för deserialisering

En anpassad samling stöds för deserialisering om den:

• Är inte ett gränssnitt eller abstrakt.

• Har en parameterlös konstruktor.

• Innehåller elementtyper som stöds av JsonSerializer.

• Implementerar eller ärver ett eller flera av följande gränssnitt eller klasser:

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

  * Se Support tur och retur för Stack typer.

  † Se nyckeltyper som stöds.

Kända problem

Det finns kända problem med följande anpassade samlingar:

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

Mer information om kända problem finns i öppna problem i System.Text.Json.

Nyckeltyper som stöds

När de används som nycklar för Dictionary och SortedList typer har följande typer inbyggt stöd:

• Boolean
• Byte
• DateTime
• DateTimeOffset
• Decimal
• Double
• Enum
• Guid
• Int16
• Int32
• Int64
• Object (Endast vid serialisering och om körningstypen är en av de typer som stöds i den här listan.)
• SByte
• Single
• String
• TimeSpan
• UInt16
• UInt32
• UInt64
• Uri
• Version

Med metoderna JsonConverter<T>.WriteAsPropertyName(Utf8JsonWriter, T, JsonSerializerOptions) och JsonConverter<T>.ReadAsPropertyName(Utf8JsonReader, Type, JsonSerializerOptions) kan du dessutom lägga till stöd för ordlistenycklar för valfri typ.

Typer som inte stöds

Följande typer stöds inte för serialisering:

• System.Type och System.Reflection.MemberInfo
• ReadOnlySpan<T>, Span<T>och ref structs i allmänhet
• Delegera typer
• IntPtr och UIntPtr

System.Data-namnrymd

Det finns inga inbyggda konverterare för DataSet, DataTableoch relaterade typer i System.Data namnområdet. Det är inte säkert att deserialisera dessa typer från ej betrodda indata, vilket beskrivs i säkerhetsvägledningen. Du kan dock skriva en anpassad konverterare för att stödja dessa typer. Exempel på anpassad konverterarkod som serialiserar och deserialiserar en DataTablefinns i RoundtripDataTable.cs.

Se även

• Fyll i initierade egenskaper
• System.Text.Json översikt
• System.Text.Json API-referens
• System.Text.Json. Referens för serialiserings-API:et