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.

§ System.Text.Json stöder IReadOnlySet<T> i .NET 11 och senare versioner. När du deserialiserar gränssnittet skapar serialiseraren en HashSet<T> instans. För genererade metadata JsonMetadataServices.CreateIReadOnlySetInfo skapar du samlingskontraktet.

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.

I .NET 11 och senare versioner JsonSerializer.SerializeAsyncEnumerable skriver du en IAsyncEnumerable<T> sekvens till antingen en Stream eller en PipeWriter. Med standardvärdet topLevelValues: falseskriver metoden en enda JSON-matris på rotnivå. Ställ in topLevelValues: true på att skriva JSON-rader i stället, där varje element är ett separat värde på den översta nivån:

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

Metoden skriver en enskild radfeed (LF), \n, efter varje värde, inklusive det sista. Den använder alltid LF, oavsett JsonSerializerOptions.NewLine. Metoden ignorerar JsonSerializerOptions.WriteIndented, så varje värde förblir på en rad.

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

Som standard JsonSerializer.DeserializeAsyncEnumerable läser element från en enda JSON-matris på rotnivå. Ange topLevelValues: true att läsa en sekvens med blankstegsavgränsade värden på den översta nivån i stället. Det här indataformatet är en superuppsättning med JSON-linjer. Överlagringar accepterar antingen en Stream eller en PipeReader.

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:

• BFloat16(.NET 11 och senare)
• Boolean
• Byte
• DateTime
• DateTimeOffset
• Decimal
• Decimal32(.NET 11 och senare)
• Decimal64(.NET 11 och senare)
• Decimal128(.NET 11 och senare)
• 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.

Flyttalstyper för BFloat16 och decimaler

Från och med .NET 11 innehåller System.Text.Json inbyggda konverterare för typerna BFloat16, Decimal32, Decimal64och Decimal128 . Finita värden serialiseras som JSON-tal.

Dessa typer fungerar som de andra inbyggda numeriska typerna:

• Konvertering av ordlistenyckel stöder alla fyra typerna.
• De respekterar JsonNumberHandling, inklusive "NaN", "Infinity"och "-Infinity" literaler via AllowNamedFloatingPointLiterals.

JsonMetadataServices exponerar konverteraregenskaper för källgenererade metadata. Egenskaperna är JsonMetadataServices.BFloat16Converter, JsonMetadataServices.Decimal32Converter, JsonMetadataServices.Decimal64Converteroch JsonMetadataServices.Decimal128Converter.

F# diskriminerade fackföreningar

Från och med .NET 11 System.Text.Json serialiserar och deserialiserar F#-diskriminerade fackföreningar, inklusive klass, struct och rekursiva fackföreningar:

type Shape =
    | Point
    | Circle of radius: float

• Ett ärende utan fält serialiseras som en JSON-sträng som innehåller skiftlägesnamnet, till exempel "Point".
• Ett ärende som har fält serialiserar som ett JSON-objekt. Objektet innehåller en $type diskriminerande följd av ärendets namngivna fält, till exempel {"$type":"Circle","radius":3.14}.

JsonSerializerOptions.PropertyNamingPolicy gäller för skiftlägesnamn och fältnamn. En skiftlägesnivå JsonPropertyNameAttribute har företräde. Om du vill använda ett annat egenskapsnamn än $typeanger du JsonPolymorphicAttribute.TypeDiscriminatorPropertyName.

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