Как настроить имена и значения свойств с помощью System.Text.Json

По умолчанию имена и ключи словарей не изменяются в выходных данных JSON, включая регистр. Значения перечисления представлены в виде чисел. В этой статье вы узнаете, как выполнять следующие задачи.

• Настраивать отдельные имена свойств.
• Преобразовывать все имена свойств в неоднородный регистр.
• Реализовывать политики именования пользовательских свойств.
• Преобразовывать ключи словаря в "верблюжий" стиль.
• Преобразовывать перечисления в строки и "верблюжий" стиль.

• Настройка порядка сериализованных свойств

Примечание

Стандартный параметр веб-приложения представлен в "верблюжем" стиле.

Для других сценариев, требующих специальной обработки имен и значений свойств JSON, можно реализовать пользовательские преобразователи.

Настройка отдельных имен свойств

Чтобы задать имена отдельных свойств, используйте атрибут [JsonPropertyName].

Ниже приведен пример типа для сериализации и полученный код JSON:

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}

Public Class WeatherForecastWithPropertyNameAttribute
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String

    <JsonPropertyName("Wind")>
    Public Property WindSpeed As Integer

End Class

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "Wind": 35
}

Имя свойства, заданное этим атрибутом:

• Применяется в обоих направлениях для сериализации и десериализации.
• Имеет приоритет над политиками именования свойств.
• Не влияет на сопоставление имен параметров для параметризованных конструкторов.

Использование "верблюжьего" стиля для всех имен свойств JSON

Чтобы использовать "верблюжий" стиль для всех имен свойств JSON, задайте для параметра JsonSerializerOptions.PropertyNamingPolicy значение JsonNamingPolicy.CamelCase, как показано в следующем примере:

var serializeOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions);

Dim serializeOptions As JsonSerializerOptions = New JsonSerializerOptions With {
    .PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions)

Ниже приведен пример класса для сериализации и вывода JSON.

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}

Public Class WeatherForecastWithPropertyNameAttribute
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String

    <JsonPropertyName("Wind")>
    Public Property WindSpeed As Integer

End Class

{
  "date": "2019-08-01T00:00:00-07:00",
  "temperatureCelsius": 25,
  "summary": "Hot",
  "Wind": 35
}

Политика именования свойств "верблюжьего" стиля:

• Применяется к сериализации и десериализации.
• Переопределяется атрибутами [JsonPropertyName]. Именно поэтому имя свойства JSON, Wind в примере, не указано в "верблюжьем" стиле.

Использование настраиваемой политики именования свойств JSON

Чтобы использовать настраиваемую политику именования свойств JSON, создайте класс, производный от JsonNamingPolicy, и переопределите метод ConvertName, как показано в следующем примере:

using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class UpperCaseNamingPolicy : JsonNamingPolicy
    {
        public override string ConvertName(string name) =>
            name.ToUpper();
    }
}

Imports System.Text.Json

Namespace SystemTextJsonSamples

    Public Class UpperCaseNamingPolicy
        Inherits JsonNamingPolicy

        Public Overrides Function ConvertName(name As String) As String
            Return name.ToUpper()
        End Function

    End Class

End Namespace

Затем задайте для свойства JsonSerializerOptions.PropertyNamingPolicy экземпляр класса политики именования:

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = new UpperCaseNamingPolicy(),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .PropertyNamingPolicy = New UpperCaseNamingPolicy,
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast1, options)

Ниже приведен пример класса для сериализации и вывода JSON.

public class WeatherForecastWithPropertyNameAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}

Public Class WeatherForecastWithPropertyNameAttribute
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String

    <JsonPropertyName("Wind")>
    Public Property WindSpeed As Integer

End Class

{
  "DATE": "2019-08-01T00:00:00-07:00",
  "TEMPERATURECELSIUS": 25,
  "SUMMARY": "Hot",
  "Wind": 35
}

Политика именования свойств JSON:

• Применяется к сериализации и десериализации.
• Переопределяется атрибутами [JsonPropertyName]. Именно поэтому имя свойства JSON, Wind в примере, не указано в верхнем регистре.

Ключи словаря в "верблюжьем" стиле.

Если свойство сериализуемого объекта имеет тип Dictionary<string,TValue>, ключи string можно преобразовать в "верблюжий" стиль. Для этого задайте для параметра DictionaryKeyPolicy значение JsonNamingPolicy.CamelCase, как показано в следующем примере:

var options = new JsonSerializerOptions
{
    DictionaryKeyPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .DictionaryKeyPolicy = JsonNamingPolicy.CamelCase,
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, options)

Сериализация объекта с помощью словаря с именем TemperatureRanges, имеющего пары "ключ-значение" "ColdMinTemp", 20 и "HotMinTemp", 40, приведет к выходным данным JSON, как в следующем примере:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "TemperatureRanges": {
    "coldMinTemp": 20,
    "hotMinTemp": 40
  }
}

Политика именования в "верблюжьем" стиле для ключей словаря применяется только к сериализации. При десериализации словаря ключи будут соответствовать JSON-файлу, даже если для параметра DictionaryKeyPolicy указано значение JsonNamingPolicy.CamelCase.

Перечисление в виде строк

По умолчанию перечисления сериализуются как числа. Чтобы сериализовать имена перечислений как строки, используйте JsonStringEnumConverter.

Например, предположим, что необходимо сериализовать следующий класс, имеющий перечисление:

public class WeatherForecastWithEnum
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public Summary? Summary { get; set; }
}

public enum Summary
{
    Cold, Cool, Warm, Hot
}

Public Class WeatherForecastWithEnum
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As Summary
End Class

Public Enum Summary
    Cold
    Cool
    Warm
    Hot
End Enum

Если параметр "Сводка" имеет значение Hot, то по умолчанию сериализованный код JSON имеет числовое значение 3:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": 3
}

Следующий пример кода сериализует имена перечислений вместо числовых значений и преобразует имена в "верблюжий" стиль:

options = new JsonSerializerOptions
{
    WriteIndented = true,
    Converters =
    {
        new JsonStringEnumConverter(JsonNamingPolicy.CamelCase)
    }
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

options = New JsonSerializerOptions With {
    .WriteIndented = True
}
options.Converters.Add(New JsonStringEnumConverter(JsonNamingPolicy.CamelCase))
jsonString = JsonSerializer.Serialize(weatherForecast, options)

Итоговый код JSON выглядит следующим образом:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "hot"
}

Встроенные также JsonStringEnumConverter могут десериализовать строковые значения. Она работает без указанной политики именования или с политикой CamelCase именования. Она не поддерживает другие политики именования, такие как регистр змеи. В следующем примере показана десериализация с использованием CamelCase:

options = new JsonSerializerOptions
{
    Converters =
    {
        new JsonStringEnumConverter(JsonNamingPolicy.CamelCase)
    }
};
weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithEnum>(jsonString, options)!;

options = New JsonSerializerOptions
options.Converters.Add(New JsonStringEnumConverter(JsonNamingPolicy.CamelCase))
weatherForecast = JsonSerializer.Deserialize(Of WeatherForecastWithEnum)(jsonString, options)

Сведения о пользовательском коде преобразователя, поддерживающем десериализацию при использовании политики именования регистра змеи, см. в разделе "Десериализация строковых значений перечисления".

Настройка порядка сериализованных свойств

Атрибут [JsonPropertyOrder] позволяет указать порядок свойств в выходных данных JSON из сериализации. Значение Order свойства по умолчанию равно нулю. Задайте Order положительное число, чтобы разместить свойство после значений по умолчанию. Order Отрицательное положение свойства перед значениями по умолчанию. Свойства записываются в порядке от наименьшего до самого Order высокого. Ниже приведен пример:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace PropertyOrder
{
    public class WeatherForecast
    {
        [JsonPropertyOrder(-5)]
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        [JsonPropertyOrder(-2)]
        public int TemperatureF { get; set; }
        [JsonPropertyOrder(5)]
        public string? Summary { get; set; }
        [JsonPropertyOrder(2)]
        public int WindSpeed { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureC = 25,
                TemperatureF = 25,
                Summary = "Hot",
                WindSpeed = 10
            };

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);
            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00",
//  "TemperatureF": 25,
//  "TemperatureC": 25,
//  "WindSpeed": 10,
//  "Summary": "Hot"
//}

См. также раздел

• Общие сведения о System.Text.Json
• Практическое руководство. Сериализация и десериализация JSON
• Создание экземпляров JsonSerializerOptions
• Сопоставление без учета регистра
• Игнорирование свойств
• Применение недействительного кода JSON
• Обработка переполнения JSON или использование JsonElement или JsonNode
• Сохранение ссылок и обработка циклических ссылок
• Десериализация в неизменяемые типы и методы доступа, не являющиеся открытыми
• Полиморфная сериализация
• Миграция из Newtonsoft.Json в System.Text.Json
• Настройка кодировки символов
• Использование DOM, Utf8JsonReader и Utf8JsonWriter
• Написание пользовательских преобразователей для сериализации JSON
• Поддержка DateTime и DateTimeOffset
• Как использовать создание источника
• Поддерживаемые типы коллекций
• Справочник по API System.Text.Json
• Справочник по API System.Text.Json.Serialization