ile özellik adlarını ve değerlerini özelleştirme System.Text.Json

Makale
10/18/2023

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. Numaralandırma değerleri sayı 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ı 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.
Numaralandırma değerlerini bir adlandırma ilkesiyle veya ilke olmadan dize olarak seri hale getirme.
Serileştirilmiş özelliklerin sırasını yapılandırma.

Not

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

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

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

Serileştirme ve seri durumdan çıkarma için her iki yönde de geçerlidir.
Özellik adlandırma ilkelerine göre ö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ükler büyük harf karakterle 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 örnekte, olarak ayarlanarak JsonSerializerOptions.PropertyNamingPolicy tüm JSON özellik adları için deve büyük/küçük harf kullanımının nasıl kullanılacağı gösterilmektedir 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 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
}

Adlandırma ilkesi:

Serileştirme ve seri durumdan çıkarma için geçerlidir.
Öznitelikler tarafından [JsonPropertyName] 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 JSON özellik adlandırma ilkesi kullanmak için, aşağıdaki örnekte gösterildiği gibi yönteminden JsonNamingPolicy türetilen ve geçersiz kılan ConvertName bir sınıf oluşturun:

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

Serileştirme ve seri durumdan çıkarma için geçerlidir.
Öznitelikler tarafından [JsonPropertyName] 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 türündeyseDictionary<string,TValue>string, anahtarlar deve olayı 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)

Anahtar-değer çiftlerine "ColdMinTemp", 20 sahip olan ve "HotMinTemp", 40 aşağıdaki örnekte olduğu gibi JSON çıkışına neden olacak adlı TemperatureRanges bir sözlükle bir nesneyi seri hale getirme:

{
  "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, varsayılan olmayan bir adlandırma ilkesine ayarlasanız JsonSerializerOptions.DictionaryKeyPolicy bile anahtarlar JSON dosyasıyla eşleşecektir.

Dize olarak numaralandırmalar

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

Sabit listeleri varsayılan olarak sayı olarak serileştirilir. Sabit listesi adlarını dize olarak serileştirmek için dönüştürücüsü JsonStringEnumConverter kullanın.

Örneğin, sabit listesi olan aşağıdaki sınıfı seri hale getirmeniz 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 , dize değerlerini de seri durumdan çıkarabilir. Belirtilen bir adlandırma ilkesiyle veya bu ilke olmadan çalışır. Aşağıdaki örnekte kullanarak CamelCaseseri durumdan çıkarma gösterilmektedir:

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)

Ayrıca, ile sabit JsonConverterAttributelistenize ek açıklama ekleyerek kullanılacak dönüştürücü de belirtebilirsiniz. Aşağıdaki örnekte özniteliğini kullanarak JsonConverterAttribute öğesinin JsonStringEnumConverter<TEnum> nasıl belirtileceğini (.NET 8 ve sonraki sürümlerde kullanılabilir) gösterir. Örneğin, sabit listesi olan aşağıdaki sınıfı seri hale getirmeniz 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);

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

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

Dönüştürücüsü kaynak oluşturma ile kullanmak için bkz . Sabit listesi alanlarını dize olarak seri hale getirme.

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