ile özellik adlarını ve değerlerini özelleştirme System.Text.Json
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 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ı:
- 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 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.
- Ö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 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.
- Ö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 CamelCase
seri 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"
//}