JSON DOM в .NET 6

В .NET 6 появилось новое пространство имен под названием System.Text.Json.Nodes. В этом пространстве имен содержатся классы для работы с JSON-документом как с DOM (Document Object Model), что позволяет получать произвольный доступ к элементам JSON-документа.

Классы и структуры System.Text.Json.Nodes

В System.Text.Json.Nodes содержатся следующие классы и структуры:

• JsonNode  — базовый класс, представляющий отдельный узел в изменяемом документе JSON.
• JsonObject — класс, представляющие изменяемый объект JSON.
• JsonArray — класс, представляющий изменяемый массив JSON.
• JsonValue — класс, представляющий изменяемое значение JSON.
• JsonNodeOptions — структура, представляющая параметры управления поведением для JsonNode.

Пример чтения JSON DOM в C#

Рассмотрим пример чтения JSON с использованием классов из пространства имен System.Text.Json.Nodes. В качестве примера, используем вот такой объект JSON:

{
  "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"
  ]
}

Получим произвольный доступ к некоторым элемента этого JSON:

using System.Text.Json.Nodes;
const string json = "{ \"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\" ] }";

JsonNode? data = JsonObject.Parse(json);
if (data == null)
    Console.WriteLine("Не удалось прочитать JSON");

//доступ к массиву DatesAvailable
JsonArray jsonArray = data["DatesAvailable"].AsArray();
foreach (var element in jsonArray)
    Console.WriteLine(element.AsValue().ToString());

//доступ к объекту TemperatureRanges.Hot
JsonObject jsonHot = data["TemperatureRanges"]["Hot"].AsObject();
//получение значений из пар High и Low
Console.WriteLine(jsonHot["High"].GetValue<int>());
Console.WriteLine(jsonHot["Low"].GetValue<int>());

Класс JsonNode

У класса JsonNode определены следующие свойства:

• Item[Int32] — возвращает или задает элемент по указанному индексу
• Item[String] возвращает или задает элемент с указанным именем свойства. Если свойство не найдено, то возвращается значение null.
• Options — параметры для управления поведением.
• Parent — возвращает родительский узел JsonNode. Если родительский объект отсутствует, то возвращается null. Родительский объект может иметь значение JsonObject или JsonArray.
• Root — возвращает корень JsonNode для текущего узла. Если текущий объект JsonNode является корневым, то возвращается null.

Основные методы JsonNode:

• AsArray() — приводит текущий узел к типу JsonArray.
• AsObject()— приводит текущий узел к типу JsonObject.
• AsValue()— приводит текущий узел к типу JsonValue.
• GetPath()— возвращает путь JSON.
• GetValue<T>()— возвращает значение для текущего узла.
• Parse()— выполняет синтаксический анализ текста, представляющего значение JSON.
• ToJsonString() — преобразует текущий экземпляр в строку в формате JSON.
• WriteTo() — записывает JsonNode в предоставленный экземпляр Utf8JsonWriter.

В представленном выше примере продемонстрирована работа некоторых свойств и методов класса JsonNode.

Класс JsonObject

Класс JsonObject является наследником класса JsonNode, поэтому ниже представлены только свойства и методы не унаследованные от JsonNode:

Свойства JsonObject:

• Count — возвращает количество элементов, содержащихся в JsonObject

Методы JsonObject

• Add() — добавляет указанное свойство в JsonObject .
• Clear() удаляет из коллекции JsonObject все элементы.
• ContainsKey() определяет,  содержит ли JsonObject элемент с указанным именем свойства.
• TryGetPropertyValue() — возвращает значение свойства с указанным именем.
• GetEnumerator() — возвращает перечислитель, осуществляющий перебор списка элементов JsonObject.

Пример использования свойств и методов класса JsonObject

using System.Text.Json.Nodes;
const string json = "{ \"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\" ] }";

JsonObject? data = JsonObject.Parse(json).AsObject();
if (data == null)
    Console.WriteLine("Не удалось прочитать JSON");

Console.WriteLine($"Количество элементов: {data.Count}");

var elements = data.GetEnumerator();
while (elements.MoveNext())
{ 
   Console.WriteLine($"Имя пары: {elements.Current.Key}");

Результат:

Класс JsonArray

Класс JsonArray представляет массив элементов JSON. Большинство методов и свойств этого класса унаследовано от JsonNode, поэтому повторять их не имеет смысла. Стоит лишь отметить, что с помощью этого класса можно перебирать элементы массива JSON или записывать массив Json в объекты.

Класс JsonValue

Класс JsonValue представляет какое-либо определенное значение в JSON и может использоваться для чтения/записи значений. Из основных методов у JsonValue стоит отметить метод Create() с помощью которого можно создавать различные значения в объекте JSON: строки, числа, булевы значения и т.д.

Итого

Сегодня мы рассмотрели основные классы для работы с JSON Node в .NET 6. JSON Node позволяет работать с json как с DOM и получать произвольный доступ к различным элементам JSON, а также записывать JSON-объекты. В большинстве случаев, при работе с JSON нам требуется сериализовать/десериализовать различные объекты и для этих целей мы всё также можем использовать уже известный нам JsonSerializer, однако, в некоторых случаях JSON DOM также оказывается востребован, например, для чтения/записи отдельных элементов Json или для работы с небольшими объектами.