Cara menyesuaikan nama dan nilai properti dengan System.Text.Json

Artikel
10/18/2023

Secara default, nama properti dan kunci kamus tidak berubah dalam output JSON, termasuk kasus. Nilai enum dinyatakan sebagai angka. Dan properti diserialisasikan dalam urutan yang ditentukan. Namun, Anda dapat menyesuaikan perilaku ini dengan:

Menentukan nama properti berseri tertentu.
Menggunakan kebijakan penamaan bawaan, seperti camelCase, snake_case, atau kebab-case, untuk nama properti dan kunci kamus.
Menggunakan kebijakan penamaan kustom untuk nama properti dan kunci kamus.
Menserialisasikan nilai enum sebagai string, dengan atau tanpa kebijakan penamaan.
Mengonfigurasi urutan properti berseri.

Catatan

Kebijakan penamaan default web adalah kasus camel.

Untuk skenario lain yang memerlukan penanganan khusus nama dan nilai properti JSON, Anda dapat menerapkan pengonversi kustom.

Mengkustomisasi nama properti individual

Untuk mengatur nama properti individual, gunakan atribut [JsonPropertyName ].

Berikut adalah contoh jenis untuk menserialisasikan dan menghasilkan 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
}

Nama properti yang diatur oleh atribut ini:

Berlaku di kedua arah, untuk serialisasi dan deserialisasi.
Lebih diutamakan daripada kebijakan penamaan properti.
Tidak memengaruhi pencocokan nama parameter untuk konstruktor parameter.

Menggunakan kebijakan penamaan bawaan

Tabel berikut ini memperlihatkan kebijakan penamaan bawaan dan pengaruhnya terhadap nama properti.

Kebijakan penamaan	Deskripsi	Nama properti asli	Nama properti yang dikonversi
CamelCase	Kata pertama dimulai dengan karakter huruf kecil. Kata-kata berturut-turut dimulai dengan karakter huruf besar.	`TempCelsius`	`tempCelsius`
KebabCaseLower*	Kata-kata dipisahkan oleh tanda hubung. Semua karakter adalah huruf kecil.	`TempCelsius`	`temp-celsius`
KebabCaseUpper*	Kata-kata dipisahkan oleh tanda hubung. Semua karakter adalah huruf besar.	`TempCelsius`	`TEMP-CELSIUS`
SnakeCaseLower*	Kata-kata dipisahkan oleh garis bawah. Semua karakter adalah huruf kecil.	`TempCelsius`	`temp_celsius`
SnakeCaseUpper*	Kata-kata dipisahkan oleh garis bawah. Semua karakter adalah huruf besar.	`TempCelsius`	`TEMP_CELSIUS`

* Tersedia di .NET 8 dan versi yang lebih baru.

Contoh berikut menunjukkan cara menggunakan camel case untuk semua nama properti JSON dengan mengatur JsonSerializerOptions.PropertyNamingPolicy ke 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)

Berikut adalah contoh kelas untuk serialisasi dan output 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
}

Kebijakan penamaan:

Serialisasi dan deserialisasi zona waktu.
Digantikan oleh [JsonPropertyName] atribut. Inilah sebabnya mengapa nama Wind properti JSON dalam contoh bukan kasus camel.

Catatan

Tidak ada kebijakan penamaan bawaan yang mendukung huruf yang merupakan pasangan pengganti. Untuk informasi selengkapnya, lihat masalah dotnet/runtime 90352.

Menggunakan kebijakan penamaan properti JSON kustom

Untuk menggunakan kebijakan penamaan properti JSON kustom, buat kelas yang berasal dari JsonNamingPolicy dan ganti ConvertName metode, seperti yang ditunjukkan dalam contoh berikut:

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

Kemudian atur JsonSerializerOptions.PropertyNamingPolicy properti ke instans kelas kebijakan penamaan Anda:

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)

Berikut adalah contoh kelas untuk serialisasi dan output 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
}

Kebijakan penamaan properti JSON:

Serialisasi dan deserialisasi zona waktu.
Digantikan oleh [JsonPropertyName] atribut. Inilah sebabnya mengapa nama Wind properti JSON dalam contoh bukan kasus camel.

Menggunakan kebijakan penamaan untuk kunci kamus

Jika properti objek yang akan diserialisasikan berjenis Dictionary<string,TValue>, string kunci dapat dikonversi menggunakan kebijakan penamaan, seperti kasus camel. Untuk melakukannya, atur JsonSerializerOptions.DictionaryKeyPolicy ke kebijakan penamaan yang Anda inginkan. Contoh berikut menggunakan CamelCase kebijakan penamaan:

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)

Menserialisasikan objek dengan kamus bernama TemperatureRanges yang memiliki pasangan kunci-nilai "ColdMinTemp", 20 dan "HotMinTemp", 40 akan menghasilkan output JSON seperti contoh berikut:

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

Kebijakan penamaan untuk kunci kamus hanya berlaku untuk serialisasi. Jika Anda mendeserialisasi kamus, kunci akan cocok dengan file JSON meskipun Anda mengatur JsonSerializerOptions.DictionaryKeyPolicy ke kebijakan penamaan non-default.

Enum sebagai string

Secara default, enum didukung sebagai angka. Untuk menserialisasikan nama enum sebagai string, gunakan JsonStringEnumConverter atau JsonStringEnumConverter<TEnum> converter. Hanya JsonStringEnumConverter<TEnum> didukung oleh runtime AOT Asli.

Secara default, enum didukung sebagai angka. Untuk menserialisasikan nama enum sebagai string, gunakan JsonStringEnumConverter pengonversi.

Misalnya, Anda perlu membuat serial kelas berikut yang memiliki enum:

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

Jika Ringkasannya adalah Hot, secara default JSON yang diserialisasikan memiliki nilai numerik 3:

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

Kode sampel berikut menserialisasikan nama enum bukan nilai numerik, dan mengonversi nama menjadi kasus camel:

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 yang dihasilkan terlihat seperti contoh berikut:

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

Bawaan JsonStringEnumConverter juga dapat mendeserialisasi nilai string. Ini berfungsi dengan atau tanpa kebijakan penamaan tertentu. Contoh berikut menunjukkan deserialisasi menggunakan 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)

Anda juga dapat menentukan pengonversi yang akan digunakan dengan membuat anotasi enum Anda dengan JsonConverterAttribute. Contoh berikut menunjukkan cara menentukan JsonStringEnumConverter<TEnum> (tersedia di .NET 8 dan versi yang lebih baru) dengan menggunakan JsonConverterAttribute atribut . Misalnya, Anda perlu membuat serial kelas berikut yang memiliki enum:

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
}

Contoh kode berikut menserialisasikan nama enum alih-alih nilai numerik:

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

JSON yang dihasilkan terlihat seperti contoh berikut:

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

Untuk menggunakan pengonversi dengan pembuatan sumber, lihat Membuat serialisasi bidang enum sebagai string.

Mengonfigurasi urutan properti berseri

Secara default, properti diserialisasikan dalam urutan di mana properti didefinisikan di kelasnya. Atribut memungkinkan [JsonPropertyOrder] Anda menentukan urutan properti dalam output JSON dari serialisasi. Nilai Order default properti adalah nol. Atur Order ke angka positif untuk memposisikan properti setelah properti yang memiliki nilai default. Negatif Order memposisikan properti sebelum properti yang memiliki nilai default. Properti ditulis secara berurutan dari nilai terendah Order hingga tertinggi. Berikut contohnya:

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"
//}

Bagikan melalui