Jak číst JSON jako objekty .NET (deserializovat)

Tento článek ukazuje, jak použít System.Text.Json obor názvů k deserializaci z javascriptového objektového zápisu (JSON). Pokud portujete existující kód z Newtonsoft.Json, přečtěte si, jak migrovat na System.Text.Json.

Běžným způsobem, jak deserializovat JSON, je mít (nebo vytvořit) třídu .NET s vlastnostmi a poli, které představují jednu nebo více vlastností JSON. Potom, chcete-li deserializovat z řetězce nebo souboru, zavolejte metodu JsonSerializer.Deserialize . Pro obecná přetížení je parametr obecného typu třída .NET. Pro negenerické přetížení předáte typ třídy jako parametr metody. Můžete deserializovat buď synchronně, nebo asynchronně.

Doporučení

Pomoc s AI můžete použít k deserializaci řetězce JSON.

Všechny vlastnosti JSON, které nejsou ve vaší třídě reprezentované, se ve výchozím nastavení ignorují. Pokud jsou některé vlastnosti typu povinné a chybí v datové části JSON, deserializace selže.

Příklady

Následující příklad ukazuje, jak deserializovat řetězec JSON, který obsahuje kolekce a vnořené objekty:

using System.Text.Json;

namespace DeserializeExtra
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
        public string? SummaryField;
        public IList<DateTimeOffset>? DatesAvailable { get; set; }
        public Dictionary<string, HighLowTemps>? TemperatureRanges { get; set; }
        public string[]? SummaryWords { get; set; }
    }

    public class HighLowTemps
    {
        public int High { get; set; }
        public int Low { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            string jsonString =
                """
                {
                  "Date": "2019-08-01T00:00:00-07:00",
                  "TemperatureCelsius": 25,
                  "Summary": "Hot",
                  "DatesAvailable": [
                    "2019-08-01T00:00:00-07:00",
                    "2019-08-02T00:00:00-07:00"
                  ],
                  "TemperatureRanges": {
                    "Cold": {
                      "High": 20,
                      "Low": -10
                    },
                    "Hot": {
                      "High": 60,
                      "Low": 20
                    }
                  },
                  "SummaryWords": [
                    "Cool",
                    "Windy",
                    "Humid"
                  ]
                }
                """;
                
            WeatherForecast? weatherForecast = 
                JsonSerializer.Deserialize<WeatherForecast>(jsonString);

            Console.WriteLine($"Date: {weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast?.Summary}");

            if (weatherForecast?.DatesAvailable != null)
            {
                foreach (DateTimeOffset dateTimeOffset in weatherForecast.DatesAvailable)
                {
                    Console.WriteLine($"DateAvailable: {dateTimeOffset}");
                }
            }

            if (weatherForecast?.TemperatureRanges != null)
            {
                foreach (KeyValuePair<string, HighLowTemps> temperatureRange in weatherForecast.TemperatureRanges)
                {
                    Console.WriteLine($"TemperatureRange: {temperatureRange.Key} is {temperatureRange.Value.Low} to {temperatureRange.Value.High}");
                }
            }

            if (weatherForecast?.SummaryWords != null)
            {
                foreach (string summaryWord in weatherForecast.SummaryWords)
                {
                    Console.WriteLine($"SummaryWord: {summaryWord}");
                }
            }
        }
    }
}

/* Output:
 * 
 * Date: 8/1/2019 12:00:00 AM -07:00
 * TemperatureCelsius: 25
 * Summary: Hot
 * DateAvailable: 8/1/2019 12:00:00 AM -07:00
 * DateAvailable: 8/2/2019 12:00:00 AM -07:00
 * TemperatureRange: Cold is -10 to 20
 * TemperatureRange: Hot is 20 to 60
 * SummaryWord: Cool
 * SummaryWord: Windy
 * SummaryWord: Humid
 * */

Imports System.Text.Json

Namespace DeserializeExtra

    Public Class WeatherForecast
        Public Property [Date] As DateTimeOffset
        Public Property TemperatureCelsius As Integer
        Public Property Summary As String
        Public SummaryField As String
        Public Property DatesAvailable As IList(Of DateTimeOffset)
        Public Property TemperatureRanges As Dictionary(Of String, HighLowTemps)
        Public Property SummaryWords As String()
    End Class

    Public Class HighLowTemps
        Public Property High As Integer
        Public Property Low As Integer
    End Class

    Public NotInheritable Class Program

        Public Shared Sub Run()
            Dim jsonString As String =
                "{
                  ""Date"": ""2019-08-01T00:00:00-07:00"",
                  ""TemperatureCelsius"": 25,
                  ""Summary"": ""Hot"",
                  ""DatesAvailable"": [
                    ""2019-08-01T00:00:00-07:00"",
                    ""2019-08-02T00:00:00-07:00""
                  ],
                  ""TemperatureRanges"": {
                    ""Cold"": {
                      ""High"": 20,
                      ""Low"": -10
                    },
                    ""Hot"": {
                      ""High"": 60,
                      ""Low"": 20
                    }
                  },
                  ""SummaryWords"": [
                    ""Cool"",
                    ""Windy"",
                    ""Humid""
                  ]
                }"

            Dim weatherForecast As WeatherForecast =
                JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

            Console.WriteLine($"Date: {weatherForecast?.Date}")
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}")
            Console.WriteLine($"Summary: {weatherForecast?.Summary}")

            If weatherForecast?.DatesAvailable IsNot Nothing Then
                For Each dateTimeOffset As DateTimeOffset In weatherForecast.DatesAvailable
                    Console.WriteLine($"DateAvailable: {dateTimeOffset}")
                Next
            End If

            If weatherForecast?.TemperatureRanges IsNot Nothing Then
                For Each temperatureRange As KeyValuePair(Of String, HighLowTemps) In weatherForecast.TemperatureRanges
                    Console.WriteLine($"TemperatureRange: {temperatureRange.Key} is {temperatureRange.Value.Low} to {temperatureRange.Value.High}")
                Next
            End If

            If weatherForecast?.SummaryWords IsNot Nothing Then
                For Each summaryWord As String In weatherForecast.SummaryWords
                    Console.WriteLine($"SummaryWord: {summaryWord}")
                Next
            End If
        End Sub

    End Class

End Namespace

' Output:
'
'Date: 8/1/2019 12:00:00 AM -07:00
'TemperatureCelsius: 25
'Summary: Hot
'DateAvailable: 8/1/2019 12:00:00 AM -07:00
'DateAvailable: 8/2/2019 12:00:00 AM -07:00
'TemperatureRange: Cold is -10 to 20
'TemperatureRange: Hot is 20 to 60
'SummaryWord: Cool
'SummaryWord: Windy
'SummaryWord: Humid

Pokud chcete deserializovat ze souboru pomocí synchronního kódu, načtěte soubor do řetězce, jak je znázorněno v následujícím příkladu:

using System.Text.Json;

namespace DeserializeFromFile
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            string fileName = "WeatherForecast.json";
            string jsonString = File.ReadAllText(fileName);
            WeatherForecast weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString)!;

            Console.WriteLine($"Date: {weatherForecast.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

jsonString = File.ReadAllText(fileName)
weatherForecast1 = JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

Pokud chcete deserializovat ze souboru pomocí asynchronního kódu, zavolejte metodu DeserializeAsync :

using System.Text.Json;

namespace DeserializeFromFileAsync
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            string fileName = "WeatherForecast.json";
            using FileStream openStream = File.OpenRead(fileName);
            WeatherForecast? weatherForecast = 
                await JsonSerializer.DeserializeAsync<WeatherForecast>(openStream);

            Console.WriteLine($"Date: {weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast?.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

Dim openStream As FileStream = File.OpenRead(fileName)
weatherForecast1 = Await JsonSerializer.DeserializeAsync(Of WeatherForecast)(openStream)

Chování deserializace

Při deserializaci JSON platí následující chování:

• Ve výchozím nastavení se název vlastnosti rozlišuje podle malých a velkých písmen. Můžete určit, že se nerozlišují velká a malá písmena.
• Neveřejné konstruktory jsou serializátorem ignorovány.
• Deserializace na neměnné objekty nebo vlastnosti, které nemají veřejné set přístupové objekty, je podporována, ale ve výchozím nastavení není povolená. Viz neměnné typy a záznamy.
• Ve výchozím nastavení jsou výčty podporovány jako čísla. Můžete deserializovat pole výčtu řetězců.
• Ve výchozím nastavení se pole ignorují. Můžete zahrnout pole.
• Ve výchozím nastavení vyvolávají v JSON komentáře nebo koncové čárky výjimky. Můžete povolit komentáře a koncové čárky.
• Výchozí maximální hloubka je 64.

Když v aplikaci ASP.NET Core použijete System.Text.Json nepřímo, liší se některé výchozí chování. Další informace najdete v tématu Výchozí nastavení webu pro JsonSerializerOptions.

Můžete implementovat vlastní převaděče , které poskytují funkce, které nejsou podporovány integrovanými převaděči.

Deserializace bez třídy .NET

Pokud máte JSON, který chcete deserializovat a nemáte třídu k deserializaci, máte jiné možnosti než ruční vytvoření třídy, kterou potřebujete:

• Přímo použijte Utf8JsonReader.

• Deserializace do modelu JSON DOM (objektový model dokumentu) a extrakce toho, co potřebujete, z modelu DOM.

  DoM umožňuje přejít do pododdílu datové části JSON a deserializovat jednu hodnotu, vlastní typ nebo pole. Informace o objektu JsonNode DOM najdete v tématu Deserializace pododdílů datové části JSON. Informace o objektu JsonDocument DOM najdete v tématu Jak hledat v JsonDocument a JsonElement podřízené prvky.

• Pomocí sady Visual Studio 2022 nebo novější můžete automaticky vygenerovat požadovanou třídu:

  • Zkopírujte JSON, který potřebujete deserializovat.
  • Vytvořte soubor třídy a odstraňte kód šablony.
  • Zvolte Upravit>Vložit speciálně>Vložit JSON jako Třídy.

  Výsledkem je třída, kterou můžete použít pro cíl deserializace.

Deserializace z UTF-8

Chcete-li deserializovat z UTF-8, zavolejte JsonSerializer.Deserialize přetížení, které přebírá ReadOnlySpan<byte> nebo Utf8JsonReader, jak je znázorněno v následujících příkladech. Příklady předpokládají, že JSON je v bajtovém poli s názvem jsonUtf8Bytes.

var readOnlySpan = new ReadOnlySpan<byte>(jsonUtf8Bytes);
WeatherForecast deserializedWeatherForecast = 
    JsonSerializer.Deserialize<WeatherForecast>(readOnlySpan)!;

Dim jsonString = Encoding.UTF8.GetString(jsonUtf8Bytes)
weatherForecast1 = JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
WeatherForecast deserializedWeatherForecast = 
    JsonSerializer.Deserialize<WeatherForecast>(ref utf8Reader)!;

' This code example doesn't apply to Visual Basic. For more information, go to the following URL:
' https://learn.microsoft.com/dotnet/standard/serialization/system-text-json-how-to#visual-basic-support

Použití AI k deserializaci JSON

Pomocí nástrojů AI, jako je GitHub Copilot, můžete vygenerovat kód, který používá System.Text.Json k deserializaci z JSON. Můžete například přizpůsobit výzvu k předvedení deserializace, když cílová třída definuje vlastnost, která chybí ve vstupu JSON.

Následující text ukazuje příklad výzvy pro Copilot Chat:

Generate C# code to use System.Text.Json to deserialize a JSON string {"FirstName":"John","LastName":"Doe"} to an equivalent .NET object, where the class defines an Age property.
Show what happens when the JSON is missing a property defined in the class.
Provide example output.

Než je použijete, přečtěte si návrhy společnosti Copilot.

Další informace o GitHub Copilotu najdete v nejčastějších dotazech GitHubu.

Viz také

• Jak deserializovat do rozhraní
• GitHub Copilot v sadě Visual Studio
• GitHub Copilot v editoru Visual Studio Code