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

2025-06-27

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:

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}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

weatherForecast = JsonSerializer.Deserialize(Of WeatherForecastWithPOCOs)(jsonString)

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 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. Tuto výzvu můžete přizpůsobit tak, aby používala řetězec JSON s názvy vlastností a hodnotami, které vyhovují vašim požadavkům.

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

Generate code to use System.Text.Json to deserialize a JSON string {"FirstName":"John","LastName":"Doe","Age":30} to an equivalent .NET object.
Map property names & values.
Provide example output.

GitHub Copilot využívá technologii AI, takže jsou možná překvapení a chyby. Další informace najdete v nejčastějších dotazech ke copilotu.

Sdílet prostřednictvím