Как считать JSON как объекты .NET (десериализация)

Статья
12/21/2024

В этой статье показано, как использовать System.Text.Json пространство имен для десериализации из нотации объектов JavaScript (JSON). Если вы переносите существующий код из Newtonsoft.Json, ознакомьтесь со статьей Переход с Newtonsoft.Json на System.Text.JsonSystem.Text.Json.

Общий способ десериализации JSON — иметь (или создать) класс .NET со свойствами и полями, представляющими одно или несколько свойств JSON. Затем для десериализации из строки или файла вызовите JsonSerializer.Deserialize метод. Для универсальных перегрузок параметр универсального типа является классом .NET. Для не универсальных перегрузок передайте тип класса в качестве параметра метода. Десериализировать можно синхронно или асинхронно.

Совет

Вы можете использовать помощь ИИ для десериализации строки JSON с помощью GitHub Copilot.

Все свойства JSON, которые не представлены в классе, игнорируются по умолчанию. Кроме того, если необходимы какие-либо свойства типа, но не присутствуют в полезных данных JSON, десериализация завершится ошибкой.

Примеры

В следующем примере показано, как десериализировать строку 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)

Чтобы выполнить десериализацию из файла с помощью синхронного кода, выполните считывание файла в строку, как показано в следующем примере:

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)

Чтобы выполнить десериализацию из файла с помощью асинхронного кода, вызовите метод 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)

Поведение десериализации

При десериализации JSON применяются следующие правила поведения:

По умолчанию при сопоставлении имен свойств учитывается регистр. Вы можете указать учет регистра.
Сериализатор не учитывает конструкторы, которые не являются открытыми.
Десериализация для неизменяемых объектов или свойств, не имеющих общедоступных set методов доступа, поддерживается, но не включена по умолчанию. См . неизменяемые типы и записи.
По умолчанию перечисления поддерживаются в виде чисел. Можно десериализировать поля перечисления строк.
По умолчанию поля игнорируются. Вы можете включить поля.
По умолчанию комментарии или завершающие запятые в JSON вызывают исключения. Вы можете разрешить комментарии и завершающие запятые.
Максимальная глубина по умолчанию равна 64.

При косвенном использовании System.Text.Json в приложении ASP.NET Core некоторые поведения по умолчанию отличаются. Дополнительные сведения см. в разделе Стандартные параметры веб-приложений для JsonSerializerOptions.

Для обеспечения функциональности, которая не поддерживается встроенными преобразователями, можно реализовать пользовательские преобразователи.

Десериализация без класса .NET

Если у вас есть JSON, в который требуется десериализировать, и у вас нет класса для десериализации, у вас есть варианты, отличные от создания класса, необходимого вручную:

Используйте Utf8JsonReader напрямую.
Десериализация в json DOM (объектная модель документа) и извлекает необходимые данные из DOM.

DOM позволяет перейти к подразделу полезных данных JSON и десериализировать одно значение, пользовательский тип или массив. Сведения о DOM см. в JsonNode подразделах десериализации полезных данных JSON. Сведения о DOM см. в разделе "Поиск jsonDocument и JsonElement" JsonDocument для вложенных элементов.
Используйте Visual Studio 2022 для автоматического создания нужного класса:
- Скопируйте JSON, необходимый для десериализации.
- Создайте файл класса и удалите код шаблона.
- Выберите >>в качестве классов.
Результатом является класс, который можно использовать для целевого объекта десериализации.

Десериализация из UTF-8

Для десериализации из UTF-8 вызовите перегрузку JsonSerializer.Deserialize, которая принимает значения ReadOnlySpan<byte> или Utf8JsonReader, как показано в следующих примерах. В примерах предполагается, что JSON находится в массиве байтов 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

Использование GitHub Copilot для десериализации JSON

Вы можете использовать GitHub Copilot в интегрированной среде разработки для создания кода, который используется System.Text.Json для десериализации из JSON. Вы можете настроить запрос на использование строки JSON с именами свойств и значениями, которые соответствуют вашим требованиям.

В следующем тексте показан пример запроса для 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 работает СИ, поэтому возможны сюрпризы и ошибки. Дополнительные сведения см. в часто задаваемых вопросыCopilot.

Дополнительные сведения о GitHub Copilot в Visual Studio и GitHub Copilot в VS Code.

Поделиться через