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

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

• Указание определенных сериализованных свойств и имен элементов перечисления.
• Используя встроенную политику именования, такую как верблюжийРегистр, snake_case или kebab-case, для имен свойств и ключей словаря.
• Использование настраиваемой политики именования для имен свойств и ключей словаря.
• Сериализация значений enum в строки с политикой именования или без нее.
• Настройка порядка сериализованных свойств.

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

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

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

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

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

Public Class WeatherForecastWithPropertyName
    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
}

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

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

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

В следующей таблице показаны встроенные политики именования и их влияние на имена свойств.

* Доступно в .NET 8 и более поздних версиях.

В следующем примере показано, как использовать верблюжий регистр для всех имен свойств 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 WeatherForecastWithPropertyName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}

Public Class WeatherForecastWithPropertyName
    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 WeatherForecastWithPropertyName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}

Public Class WeatherForecastWithPropertyName
    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 можно преобразовать с помощью политики именования, например, camelCase. Для этого задайте JsonSerializerOptions.DictionaryKeyPolicy нужную политику именования. В следующем примере политика именования 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-файлу, даже если задана JsonSerializerOptions.DictionaryKeyPolicy политика именования по умолчанию.

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

По умолчанию перечисления сериализуются как числа. Для сериализации имен перечислений в виде строк используйте преобразователь JsonStringEnumConverter или JsonStringEnumConverter<TEnum>. Поддерживается только JsonStringEnumConverter<TEnum> родной средой выполнения AOT.

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

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:

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)

JsonConverterAttribute

Вы также можете указать преобразователь, который будет использоваться путем аннотирования перечисления.JsonConverterAttribute В следующем примере показано, как указать JsonStringEnumConverter<TEnum> (доступное в .NET 8 и более поздних версиях) с помощью атрибута JsonConverterAttribute . Например, предположим, что необходимо сериализовать следующий класс, имеющий перечисление:

public class WeatherForecastWithPrecipEnum
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public Precipitation? Precipitation { get; set; }
}

[JsonConverter(typeof(JsonStringEnumConverter<Precipitation>))]
public enum Precipitation
{
    Drizzle, Rain, Sleet, Hail, Snow
}

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

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

Результирующие данные JSON выглядят следующим образом.

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Precipitation": "Sleet"
}

Пользовательские имена элементов перечисления

Начиная с .NET 9 можно настроить имена отдельных элементов перечисления для типов, сериализованных в виде строк. Чтобы настроить имя члена перечисления, заметите его атрибутом JsonStringEnumMemberName.

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

public class WeatherForecastWithEnumCustomName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public CloudCover? Sky { get; set; }
}

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum CloudCover
{
    Clear,
    [JsonStringEnumMemberName("Partly cloudy")]
    Partial,
    Overcast
}

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

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

Результирующие данные JSON выглядят следующим образом.

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Sky": "Partly cloudy"
}

Создание источника

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

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

По умолчанию свойства сериализуются в порядке, в котором они определены в своем классе. Атрибут [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"
//}

Использование GitHub Copilot для кастомизации имен и порядка свойств

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

В следующем примере показано, как использовать Copilot для изменения существующего кода для настройки имен свойств и порядка при сериализации в JSON.

1. Добавьте следующий пример кода C# в файл Example.cs кода в редакторе. В Visual Studio можно использовать проект консольного приложения C#, чтобы попробовать этот пример.

   using System.Text.Json;
   
   public class Person
   {
       public string? FirstName { get; set; }
       public string? LastName { get; set; }
       public int Age { get; set; }
       public string? Country { get; set; }
   }
   
   public class Program
   {
       public static void Main()
       {
           var person = new Person
           {
               FirstName = "John",
               LastName = "Doe",
               Age = 30,
               Country = "USA"
           };
   
           string jsonString = JsonSerializer.Serialize(person);
           Console.WriteLine(jsonString);
       }
   }
   

   Example.cs Код выполняет следующее:

   • Создает экземпляр Person класса и инициализирует его свойства со значениями.
   • Сериализует person объект в строку JSON с помощью JsonSerializer.Serialize.
   • Выводит следующую строку JSON в консоль:

   {"FirstName":"John","LastName":"Doe","Age":30,"Country":"USA"}
   

2. В Copilot Chat введите следующий запрос, чтобы изменить код для настройки имен и порядка выходных данных сериализации JSON.

   #Example.cs modify code to use System.Text.Json to customize property names and order of JSON output from serialization.
   Set property names: FirstName to first_name, LastName to last_name.
   Set order to: Country, FirstName, LastName, Age.
   Provide customized serialization output.
   

GitHub Copilot работает на ИИ, поэтому возможны сюрпризы и ошибки. Дополнительные сведения см. в Часто задаваемые вопросы Copilot.

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

См. также

• Обзор System.Text.Json
• Как сериализовать и десериализовать JSON