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

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 properti terserialisasi tertentu dan nama anggota enum.
• 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-properti yang ter-serialisasi.

Catatan

Kebijakan penamaan standar web adalah CamelCase.

Petunjuk

Anda dapat menggunakan bantuan AI untuk membuat objek dengan properti serialisasi kustom.

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

Menyesuaikan nama properti tersendiri

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

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

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 berparameter.

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

Kebijakan penamaan:

• Berlaku untuk serialisasi dan deserialisasi.
• Digantikan oleh [JsonPropertyName] atribut. Inilah sebabnya mengapa nama properti JSON Wind dalam contoh ini tidak menggunakan camel case.

Catatan

Tidak ada kebijakan penamaan bawaan yang mendukung huruf yang merupakan pasangan pengganti. Untuk informasi selengkapnya, lihat isu 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 tetapkan properti JsonSerializerOptions.PropertyNamingPolicy 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 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
}

Kebijakan penamaan properti JSON:

• Berlaku untuk serialisasi dan deserialisasi.
• Digantikan oleh [JsonPropertyName] atribut. Inilah sebabnya mengapa nama Wind properti JSON dalam contoh tidak menggunakan huruf besar.

Menggunakan kebijakan penamaan untuk kunci kamus

Jika properti dari objek yang akan diserialisasikan bertipe Dictionary<string,TValue>, kunci string dapat dikonversi menggunakan aturan penamaan, seperti camel case. 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 bawaan, enumerasi diserialisasi sebagai angka. Untuk menserialisasikan nama enum sebagai string, gunakan JsonStringEnumConverter atau JsonStringEnumConverter<TEnum> converter. Hanya JsonStringEnumConverter<TEnum> didukung oleh runtime Native AOT.

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 memenseri nama enum alih-alih nilai numerik, dan mengubah nama menjadi format camel case.

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)

JsonConverterAttribute

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 ini:

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

Nama anggota enum kustom

Mulai dari .NET 9, Anda dapat menyesuaikan nama anggota enum individual untuk jenis yang diserialisasikan sebagai string. Untuk menyesuaikan nama anggota enum, anotasi dengan atribut JsonStringEnumMemberName.

Misalnya, Anda perlu membuat serialisasi kelas berikut yang memiliki enum dengan nama anggota kustom:

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
}

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 ini:

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

Pembuatan kode sumber

Untuk menggunakan pengonversi dengan generasi kode, lihat Serialisasi bidang enum sebagai string.

Mengonfigurasi urutan properti terserialisasi

Secara default, properti diserialisasikan dalam urutan di mana properti didefinisikan di kelasnya. Fitur atribut [JsonPropertyOrder] memungkinkan Anda menentukan urutan properti dalam output JSON serialisasi. Nilai Order default properti adalah nol. Atur Order ke angka positif untuk memposisikan properti setelah properti yang memiliki nilai default. Posisi negatif Order menempatkan suatu properti sebelum 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"
//}

Menggunakan AI untuk menyesuaikan bagaimana nama properti diserialisasikan

Anda dapat menggunakan alat AI, seperti GitHub Copilot, untuk menerapkan pola perubahan pada cara kode Anda diserialisasikan.

Misalkan deklarasi kelas Anda memiliki properti yang mengikuti PascalCasing, dan standar JSON untuk proyek Anda adalah snake_casing. Anda dapat menggunakan AI untuk menambahkan atribut [JsonPropertyName] yang diperlukan ke setiap properti di kelas Anda. Anda dapat menggunakan Copilot untuk membuat perubahan ini dengan perintah obrolan seperti ini:

Update #ClassName:
when the property name contains more than one word,
change the serialized property name to use underscores between words.
Use built-in serialization attributes.

Berikut adalah versi contoh yang lebih lengkap yang menyertakan kelas sederhana.

Take this C# class:
public class WeatherForecast
{
    public DateTime Date { get; set; }
    public int TemperatureC { get; set; }
    public int TemperatureF { get; set; }
    public string? Summary { get; set; }
    public int WindSpeed { get; set; }
}
When the property name contains more than one word,
change the serialized property name to use underscores between words.
Use built-in serialization attributes.

Tinjau saran Copilot sebelum menerapkannya.

Untuk informasi selengkapnya tentang GitHub Copilot, lihat FAQ GitHub.

Lihat juga

• System.Text.Json ringkasan
• Cara menserialisasi dan mendeserialisasi JSON
• GitHub Copilot di Visual Studio
• GitHub Copilot di Visual Studio Code