Poznámka
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Ve výchozím nastavení se názvy vlastností a klíče slovníku ve výstupu JSON nemění, včetně případu. Hodnoty výčtu jsou představovány jako čísla. Vlastnosti jsou serializovány v pořadí, v jakém jsou definovány. Toto chování ale můžete přizpůsobit takto:
- Stanovení konkrétní serializované vlastnosti a názvů členů výčtového typu.
- Použití předdefinovaných zásad pojmenování, jako jsou camelCase, snake_case nebo kebab-case, pro názvy vlastností a klíče slovníku.
- Použití vlastních zásad pojmenování pro názvy vlastností a klíče slovníku.
- Serializace hodnot výčtu jako řetězce, se zásadami pojmenování nebo bez nich.
- Konfigurace pořadí serializovaných vlastností
Poznámka:
Výchozí zásada pojmenování pro web je styl psaní CamelCase.
Návod
Pomoc s AI můžete použít k vytvoření objektu s vlastními vlastnostmi serializace.
V jiných scénářích, které vyžadují speciální zpracování názvů a hodnot vlastností JSON, můžete implementovat vlastní převaděče.
Přizpůsobit názvy jednotlivých vlastností
Pokud chcete nastavit název jednotlivých vlastností, použijte atribut [JsonPropertyName].
Tady je příklad typu serializace a výsledného formátu 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
}
Název vlastnosti nastavený tímto atributem:
- Platí v obou směrech pro serializaci a deserializaci.
- Má přednost před zásadami pojmenování vlastností.
- Nemá vliv na porovnávání názvů parametrů pro parametrizované konstruktory.
Použití předdefinovaných zásad pojmenování
Následující tabulka ukazuje předdefinované zásady pojmenování a jejich vliv na názvy vlastností.
Zásady pojmenovávání | Popis | Původní název vlastnosti | Převedený název vlastnosti |
---|---|---|---|
CamelCase | První slovo začíná znakem malého písmena. Po sobě jdoucí slova začínají velkými písmeny. |
TempCelsius |
tempCelsius |
KebabCaseLower* | Slova jsou oddělená pomlčkami. Všechny znaky jsou malými písmeny. |
TempCelsius |
temp-celsius |
KebabCaseUpper* | Slova jsou oddělená pomlčkami. Všechny znaky jsou velké. |
TempCelsius |
TEMP-CELSIUS |
SnakeCaseLower* | Slova jsou oddělená podtržítky. Všechny znaky jsou malými písmeny. |
TempCelsius |
temp_celsius |
SnakeCaseUpper* | Slova jsou oddělená podtržítky. Všechny znaky jsou velké. |
TempCelsius |
TEMP_CELSIUS |
* K dispozici v .NET 8 a novějších verzích.
Následující příklad ukazuje, jak použít camel case pro všechny názvy vlastností JSON nastavením JsonSerializerOptions.PropertyNamingPolicy na 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)
Tady je příklad třídy pro serializaci a výstup 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
}
Zásady pojmenování:
- Platí pro serializaci a deserializaci.
- Přepíše se atributy
[JsonPropertyName]
. To je důvod, proč názevWind
vlastnosti JSON v příkladu není camel case.
Poznámka:
Žádná z předdefinovaných zásad pojmenování nepodporuje písmena, která jsou náhradními páry. Další informace naleznete na dotnet/runtime problém 90352.
Použití vlastních zásad pojmenování vlastností JSON
Pokud chcete použít vlastní zásady pojmenování vlastností JSON, vytvořte třídu odvozenou od JsonNamingPolicy a přepište metodu ConvertName, jak je znázorněno v následujícím příkladu.
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
Pak nastavte JsonSerializerOptions.PropertyNamingPolicy vlastnost na instanci vaší třídy zásad pojmenová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)
Tady je příklad třídy pro serializaci a výstup 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
}
Zásady pojmenování vlastností JSON:
- Platí pro serializaci a deserializaci.
- Přepíše se atributy
[JsonPropertyName]
. Proto název vlastnostiWind
JSON v příkladu není velkými písmeny.
Použití zásad pojmenování pro klíče slovníku
Pokud je vlastnost objektu, který má být serializován, typu Dictionary<string,TValue>
, lze klíče string
převést pomocí zásad pojmenování, jako je camel case. Uděláte to tak, že nastavíte JsonSerializerOptions.DictionaryKeyPolicy na požadovanou zásadu pojmenování. Následující příklad používá zásadu CamelCase
pojmenová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)
Serializace objektu pomocí slovníku s názvem TemperatureRanges
, který má páry "ColdMinTemp", 20
klíč-hodnota, a "HotMinTemp", 40
výsledkem by byl výstup JSON podobný následujícímu příkladu:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "Hot",
"TemperatureRanges": {
"coldMinTemp": 20,
"hotMinTemp": 40
}
}
Zásady pojmenování pro klíče slovníku se vztahují pouze na serializaci. Pokud deserializujete slovník, klíče se shodují se souborem JSON, i když nastavíte JsonSerializerOptions.DictionaryKeyPolicy jiné než výchozí zásady pojmenování.
Výčty jako řetězce
Ve výchozím nastavení jsou výčty serializovány jako čísla. Chcete-li serializovat názvy výčtů jako řetězce, použijte konvertor JsonStringEnumConverter nebo JsonStringEnumConverter<TEnum>. Nativní modul runtime AOT podporuje pouze JsonStringEnumConverter<TEnum> .
Předpokládejme například, že potřebujete serializovat následující třídu, která má výčet:
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
Pokud je souhrn Hot
, má serializovaný JSON ve výchozím nastavení číselnou hodnotu 3:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": 3
}
Následující ukázkový kód serializuje názvy výčtů místo číselných hodnot a převede názvy na *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)
Výsledný json vypadá jako v následujícím příkladu:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "hot"
}
Předdefinované JsonStringEnumConverter můžou deserializovat i řetězcové hodnoty. Funguje s zadanou zásadou pojmenování nebo bez ní. Následující příklad ukazuje deserializaci pomocí 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
Můžete také určit převaděč, který se má použít, anotací výčtu pomocí JsonConverterAttribute. Následující příklad ukazuje, jak pomocí atributu JsonStringEnumConverter<TEnum> určit JsonConverterAttribute (dostupné v .NET 8 a novějších verzích). Předpokládejme například, že potřebujete serializovat následující třídu, která má výčet:
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
}
Následující vzorový kód serializuje názvy výčtů místo číselných hodnot:
var options = new JsonSerializerOptions
{
WriteIndented = true,
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);
Výsledný json vypadá takto:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Precipitation": "Sleet"
}
Vlastní názvy členů výčtu
Počínaje rozhraním .NET 9 můžete přizpůsobit názvy jednotlivých členů výčtu pro typy, které jsou serializovány jako řetězce. Pokud chcete přizpůsobit název člena výčtu, označte jej atributem JsonStringEnumMemberName.
Předpokládejme například, že potřebujete serializovat následující třídu, která má výčt s vlastním názvem člena:
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
}
Následující vzorový kód serializuje názvy výčtů místo číselných hodnot:
var options = new JsonSerializerOptions
{
WriteIndented = true,
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);
Výsledný json vypadá takto:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Sky": "Partly cloudy"
}
Generování zdrojového kódu
Chcete-li použít převaděč s generováním zdroje, viz Serializovat výčtová pole jako řetězce.
Konfigurace pořadí serializovaných vlastností
Ve výchozím nastavení jsou vlastnosti serializovány v pořadí, ve kterém jsou definovány ve své třídě. Atribut [JsonPropertyOrder]
umožňuje zadat pořadí vlastností ve výstupu JSON ze serializace. Výchozí hodnota Order
vlastnosti je nula. Nastavte Order
na kladné číslo, aby se vlastnost umístila za vlastnostmi, které mají výchozí hodnotu. Záporná hodnota Order
umístí vlastnost před ty, které mají výchozí hodnotu. Vlastnosti se zapisují v pořadí od nejnižší Order
hodnoty po nejvyšší. Tady je příklad:
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"
//}
Použití AI k přizpůsobení způsobu serializace názvů vlastností
Pomocí nástrojů AI, jako je GitHub Copilot, můžete použít vzory změn na způsob serializace kódu.
Předpokládejme, že deklarace třídy má následující PascalCasing
vlastnosti a standard JSON pro váš projekt je snake_casing
. AI můžete použít k přidání potřebných atributů [JsonPropertyName] ke každé vlastnosti ve vaší třídě. Pomocí Copilotu můžete provádět tyto změny pomocí výzvy chatu, například takto:
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.
Tady je kompletní verze příkladu, která obsahuje jednoduchou třídu.
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.
GitHub Copilot využívá technologii AI, takže jsou možná překvapení a chyby. Další informace najdete v nejčastějších dotazech ke copilotu.