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

Makale
11/08/2021
Okumak için 3 dakika

Varsayılan olarak, büyük/büyük harf de dahil olmak üzere JSON çıkışında özellik adları ve sözlük anahtarları değiştirilmez. Enum değerleri sayı olarak temsil eder. Bu makalede şunları yapmayı öğreneceksiniz:

Tek tek özellik adlarını özelleştirme
Tüm özellik adlarını büyük/büyük harfe dönüştürme
Özel özellik adlandırma ilkesi uygulama
Sözlük anahtarlarını büyük/büyük harfe dönüştürme
Enum'ları dizelere ve büyük/büyük harfe dönüştürme

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

Not

Web varsayılanı büyük harftir.

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

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

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

Seri hale getirme ve sonuçta elde edilen JSON için örnek bir tür:

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 ayarlanmış özellik adı:

Serileştirme ve seriden serileştirme 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ştirmesini etkilemez.

Tüm JSON özellik adları için büyük/büyük harf kullanın

Tüm JSON özellik adları için büyük/büyük harf kullanmak için, aşağıdaki JsonSerializerOptions.PropertyNamingPolicy örnekte gösterildiği gibi olarak JsonNamingPolicy.CamelCase ayarlayın:

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)

Ve JSON çıkışını serileştirmek için örnek bir sınıf aşağıdaki gibidir:

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
}

Büyük/büyük harf özellik adlandırma ilkesi:

Serileştirme ve seriden kaldır için geçerlidir.
Öznitelikler tarafından [JsonPropertyName] geçersiz kılınır. Bu nedenle örnekteki JSON özellik Wind adı büyük/büyük harf değildir.

Özel JSON özellik adlandırma ilkesi kullanma

Özel bir JSON özellik adlandırma ilkesi kullanmak için, aşağıdaki örnekte gösterildiği gibi yönteminden türetilen ve yöntemini geçersiz JsonNamingPolicy ConvertName kılan 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 JsonSerializerOptions.PropertyNamingPolicy adlandırma ilkesi sınıfınıza bir örnek olarak ayarlayın:

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)

Ve JSON çıkışını serileştirmek için örnek bir sınıf aşağıdaki gibidir:

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 seriden kaldır için geçerlidir.
Öznitelikler tarafından [JsonPropertyName] geçersiz kılınır. Bu nedenle örnekteki JSON Wind özellik adı büyük harf değildir.

Büyük/büyük harf sözlük anahtarları

Seri hale getirilecek bir nesnenin özelliği türünde Dictionary<string,TValue> ise, string anahtarlar küçük harfe dönüştürülür. Bunu yapmak için, DictionaryKeyPolicy aşağıdaki örnekte gösterildiği gibi olarak JsonNamingPolicy.CamelCase ayarlayın:

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 çiftleri olan ve aşağıdaki örnekte olduğu gibi JSON çıkışına neden olan adlı bir TemperatureRanges sözlük ile bir nesneyi seri hale "ColdMinTemp", 20 "HotMinTemp", 40 getirme:

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

Sözlük anahtarları için büyük/büyük harf adlandırma ilkesi yalnızca serileştirme için geçerlidir. Bir sözlüğünserialize, anahtarlar için belirtebilirsiniz bile JSON dosyası JsonNamingPolicy.CamelCase ile eşleşmez. DictionaryKeyPolicy

Dize olarak enum'lar

Varsayılan olarak, numaralar sayı olarak serileştirilmiştir. Enum adlarını dize olarak serileştirmek için JsonStringEnumConverter kullanın.

Örneğin, bir numaraya sahip aşağıdaki sınıfı serileştirmeye ihtiyacınız olduğunu 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 sahip olur:

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

Aşağıdaki örnek kod, sayısal değerler yerine enum adlarını seri hale getirer ve adları büyük/büyük harfe 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)

Sonuçta elde edilen JSON aşağıdaki örnekteki gibi olur:

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

Yerleşik dize değerleri JsonStringEnumConverter de dizisini de sildi. Belirtilen adlandırma ilkesi olmadan veya adlandırma CamelCase ilkesiyle çalışır. Büyük/büyük harf gibi diğer adlandırma ilkelerini desteklemez. Aşağıdaki örnekte, kullanılarak deserialization CamelCase gösterir:

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)

Bir büyük/küçük harf adlandırma ilkesi kullanılırken, diziden kaldırılan özel dönüştürücü kodu hakkında bilgi için bkz. Enum dizesi değerinin deserialization'sini destekleme.

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

özniteliği, [JsonPropertyOrder] serileştirmeden JSON çıkışında özelliklerin sıralamasını belirtmenize olanak sağlar. Özelliğin varsayılan Order değeri sıfırdır. Bir Order özelliği varsayılan değere sahip olanlardan sonra konumlandırmak için pozitif sayıya ayarlayın. Negatif, Order bir özelliği varsayılan değere sahip olanlardan önce konumlar. Özellikler en düşük değerden en yüksek Order değere doğru sırayla yazılır. Aşağıda bir örnek 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"
//}