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

Статья
10/26/2023

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

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

Все свойства 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, необходимый для десериализации.
- Создайте файл класса и удалите код шаблона.
- Выберите "Изменить>вставку специального 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

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

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

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

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

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

Обратная связь

Дополнительные ресурсы