Özellik adlarını ve değerlerini System.Text.Json ile nasıl özelleştirirsiniz

Varsayılan olarak, özellik adları ve sözlük anahtarları JSON çıkışında büyük/küçük harf de dahil olmak üzere değiştirilmez. Enum değerleri sayılar olarak temsil edilir. Ayrıca özellikler tanımlandıkları sırayla seri hale getirilir. Ancak, bu davranışları şu şekilde özelleştirebilirsiniz:

• Belirli serileştirilmiş özellik adlarını ve sabit listesi üye adlarını belirtme.
• Özellik adları ve sözlük anahtarları için camelCase, snake_case veya kebab-case gibi yerleşik bir adlandırma ilkesi kullanma.
• Özellik adları ve sözlük anahtarları için özel adlandırma ilkesi kullanma.
• Enum değerlerini bir adlandırma ilkesiyle veya ilke olmadan dize olarak serialize etmek.
• Serileştirilmiş özelliklerin sırasını yapılandırma.

Not

Web varsayılan adlandırma ilkesi deve örneğidir.

Tavsiye

Özel serileştirme özelliklerine sahip bir nesne oluşturmak için yapay zeka yardımı kullanabilirsiniz.

JSON özellik adlarının ve değerlerinin özel işlenmesini gerektiren diğer senaryolar için özel dönüştürücüler uygulayabilirsiniz.

Tek tek özellik adlarını özelleştirme

Tek tek özelliklerin adını ayarlamak için [JsonPropertyName] özniteliğini kullanın.

JSON'ı seri hale getirmek ve elde etmek için örnek bir tür aşağıda verilmiştir:

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
}

Bu öznitelik tarafından ayarlanan özellik adı:

• Seri hale getirme ve seri hale geri getirme işlemleri için her iki yönde de geçerlidir.
• Özellik adlandırma ilkelerinden daha önceliklidir.
• Parametreli oluşturucular için parametre adı eşleştirmeyi etkilemez.

Yerleşik adlandırma ilkesi kullanma

Aşağıdaki tabloda yerleşik adlandırma ilkeleri ve bunların özellik adlarını nasıl etkilediği gösterilmektedir.

Adlandırma ilkesi	Açıklama	Özgün özellik adı	Dönüştürülen özellik adı
CamelCase	İlk sözcük küçük harf karakteriyle başlar. Ardışık sözcüklerin her biri büyük harfle başlar.	TempCelsius	tempCelsius
KebabCaseLower*	Sözcükler kısa çizgilerle ayrılır. Tüm karakterler küçük harftir.	TempCelsius	temp-celsius
KebabCaseUpper*	Sözcükler kısa çizgilerle ayrılır. Tüm karakterler büyük harftir.	TempCelsius	TEMP-CELSIUS
SnakeCaseLower*	Sözcükler alt çizgilerle ayrılır. Tüm karakterler küçük harftir.	TempCelsius	temp_celsius
SnakeCaseUpper*	Sözcükler alt çizgilerle ayrılır. Tüm karakterler büyük harftir.	TempCelsius	TEMP_CELSIUS

* .NET 8 ve sonraki sürümlerde kullanılabilir.

Aşağıdaki örnek, JsonSerializerOptions.PropertyNamingPolicy olarak ayarlanarak tüm JSON özellik adlarında deve büyük/küçük harf kullanımının nasıl yapılacağını göstermektedir 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)

Seri hale getirmek için örnek bir sınıf ve JSON çıkışı aşağıda verilmiştir:

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
}

Adlandırma ilkesi:

• Serileştirme ve seri durumdan çıkarma için geçerlidir.
• [JsonPropertyName] öznitelikleri tarafından geçersiz kılınıyor. Bu nedenle örnekteki JSON özellik adı Wind deve örneği değildir.

Not

Yerleşik adlandırma ilkelerinin hiçbiri vekil çift olan harfleri desteklemez. Daha fazla bilgi için bkz . dotnet/runtime issue 90352.

Özel JSON özellik adlandırma ilkesi kullanma

Özel bir JSON özellik adı verme ilkesi kullanmak için, JsonNamingPolicy sınıfından türeyen ve ConvertName yöntemini geçersiz kılan bir sınıf oluşturun, aşağıdaki örnekte gösterildiği gibi:

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

Ardından özelliğini adlandırma ilkesi sınıfınızın bir örneğine ayarlayın 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)

Seri hale getirmek için örnek bir sınıf ve JSON çıkışı aşağıda verilmiştir:

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 özellik adlandırma ilkesi:

• Serileştirme ve seri durumdan çıkarma için geçerlidir.
• [JsonPropertyName] öznitelikleri tarafından geçersiz kılınıyor. Bu nedenle örnekteki JSON özellik adı Wind büyük harf değildir.

Sözlük anahtarları için adlandırma ilkesi kullanma

Serileştirilecek bir nesnenin özelliği Dictionary<string,TValue> türünde ise, string anahtarlar camel case gibi bir adlandırma ilkesi kullanılarak dönüştürülebilir. Bunu yapmak için istediğiniz adlandırma ilkesine ayarlayın JsonSerializerOptions.DictionaryKeyPolicy . Aşağıdaki örnekte adlandırma ilkesi kullanılır 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 anahtar-değer çiftlerine ve "ColdMinTemp", 20"HotMinTemp", 40 adına sahip bir sözlük kullanarak bir nesneyi seri hale getirmek, aşağıdaki örnekte olduğu gibi bir JSON çıktısına neden olacaktır.

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

Sözlük anahtarları için adlandırma ilkeleri yalnızca serileştirme için geçerlidir. Bir sözlüğü seri durumdan çıkardığınızda, JsonSerializerOptions.DictionaryKeyPolicy'yi varsayılandan farklı bir adlandırma ilkesine ayarlasanız bile, anahtarlar JSON dosyasıyla eşleşir.

String olarak enumlar

Sabit listeleri varsayılan olarak sayı olarak serileştirilir. Sabit listesi adlarını dize olarak serileştirmek için JsonStringEnumConverter veya JsonStringEnumConverter<TEnum> dönüştürücülerini kullanın. Yalnızca JsonStringEnumConverter<TEnum> Yerel AOT çalışma zamanı tarafından desteklenir.

Örneğin, sabit içeren aşağıdaki sınıfı serileştirmeniz gerektiğini varsayalım.

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

Özet ise Hot, serileştirilmiş JSON varsayılan olarak 3 sayısal değerine sahiptir:

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

Aşağıdaki örnek kod, sayısal değerler yerine sabit listesi adlarını serileştirir ve adları deve olayına dönüştürür:

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)

Elde edilen JSON aşağıdaki örneğe benzer:

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

Yerleşik JsonStringEnumConverter, metin değerlerini de çözümleyebilir. Belirtilen bir adlandırma ilkesiyle veya bu ilke olmadan çalışır. Aşağıdaki örnek, CamelCase kullanarak serileştirmeden çıkarma işlemini göstermektedir.

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

Ayrıca, enum'unuzu JsonConverterAttribute ile açıklayarak kullanılacak dönüştürücüyü belirleyebilirsiniz. Aşağıdaki örnek, JsonStringEnumConverter<TEnum> özniteliğini kullanarak, .NET 8 ve sonraki sürümlerde kullanılabilen JsonConverterAttribute öğesinin nasıl belirtileceğini gösterir. Örneğin, sabit içeren aşağıdaki sınıfı serileştirmeniz gerektiğini varsayalım.

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
}

Aşağıdaki örnek kod, sayısal değerler yerine sabit listesi adlarını serileştirir:

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

Sonuçta elde edilen JSON şöyle görünür:

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

Özel sabit listesi üye adları

.NET 9'dan başlayarak, dize olarak serileştirilen türler için bireysel enum üyelerinin adlarını özelleştirebilirsiniz. Bir sabit liste üyesi adını özelleştirmek için, JsonStringEnumMemberName özniteliği ile açıklayın.

Örneğin, özel üye adına sahip bir enum içeren aşağıdaki sınıfı seri hale getirmeniz gerektiğini varsayalım:

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
}

Aşağıdaki örnek kod, sayısal değerler yerine sabit listesi adlarını serileştirir:

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

Sonuçta elde edilen JSON şöyle görünür:

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

Kaynak oluşturma

Kaynak oluşturma ile dönüştürücüyü kullanmak için Enum alanlarını dizge olarak serileştirme konusuna bakın.

Serileştirilmiş özelliklerin sırasını yapılandırma

Varsayılan olarak, özellikler kendi sınıflarında tanımlanma sırasına göre serileştirilir. özniteliği, [JsonPropertyOrder] JSON çıkışında serileştirmeden özelliklerin sırasını belirtmenize olanak tanır. özelliğinin Order varsayılan değeri sıfırdır. Bir özelliği varsayılan değere sahip olanlardan sonra konumlandırmak için pozitif bir sayıya ayarlayın Order . Negatif Order bir özellik, varsayılan değere sahip olanlardan önce konumlandırıldı. Özellikler en düşük Order değerden en yüksek değere sırasıyla yazılır. Bir örnek aşağıda verilmiştir:

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

Özellik adlarının seri hale getirilmeyi özelleştirmek için yapay zekayı kullanma

Kodunuzun seri hale getirme şekline değişiklik desenleri uygulamak için GitHub Copilot gibi yapay zeka araçlarını kullanabilirsiniz.

Sınıf bildiriminizin PascalCasing takip eden özellikleri olduğunu ve projeniz için JSON standardının snake_casing olduğunu varsayalım. Sınıfınızdaki her özelliğe gerekli [JsonPropertyName] özniteliklerini eklemek için yapay zekayı kullanabilirsiniz. Copilot'u kullanarak aşağıdaki gibi bir sohbet istemiyle bu değişiklikleri yapabilirsiniz:

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.

Aşağıda, basit bir sınıf içeren örneğin daha eksiksiz bir sürümü verilmiştir.

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.

Uygulamadan önce Copilot'un önerilerini gözden geçirin.

GitHub Copilot hakkında daha fazla bilgi için bkz. GitHub'ın SSS'leri.

Ayrıca bkz.

• System.Text.Json genel bakış
• JSON'un serileştirilmesi ve seri durumdan çıkarılması
• Visual Studio'da GitHub Copilot
• VS Code'da GitHub Copilot