Så här anpassar du egenskapsnamn och värden med System.Text.Json
Som standard ändras egenskapsnamn och ordlistenycklar i JSON-utdata, inklusive skiftläge. Uppräkningsvärden representeras som tal. Och egenskaperna serialiseras i den ordning de definieras. Du kan dock anpassa dessa beteenden genom att:
- Ange specifika serialiserade egenskapsnamn.
- Använda en inbyggd namngivningsprincip, till exempel camelCase, snake_case eller kebab-case, för egenskapsnamn och ordlistenycklar.
- Använda en anpassad namngivningsprincip för egenskapsnamn och ordlistenycklar.
- Serialisera uppräkningsvärden som strängar, med eller utan en namngivningsprincip.
- Konfigurera ordningen på serialiserade egenskaper.
Kommentar
Webbplatsens standardnamngivningsprincip är kamelfall.
För andra scenarier som kräver särskild hantering av JSON-egenskapsnamn och -värden kan du implementera anpassade konverterare.
Anpassa enskilda egenskapsnamn
Om du vill ange namnet på enskilda egenskaper använder du attributet [JsonPropertyName].
Här är en exempeltyp för serialisering och resulterande JSON:
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
}
Egenskapsnamnet som anges av det här attributet:
- Gäller i båda riktningarna för serialisering och deserialisering.
- Har företräde framför namngivningsprinciper för egenskaper.
- Påverkar inte matchning av parameternamn för parametriserade konstruktorer.
Använda en inbyggd namngivningsprincip
I följande tabell visas de inbyggda namngivningsprinciperna och hur de påverkar egenskapsnamn.
Namngivningsprincip | beskrivning | Ursprungligt egenskapsnamn | Namn på konverterad egenskap |
---|---|---|---|
CamelCase | Första ordet börjar med ett gemener. Efterföljande ord börjar med ett versaler. |
TempCelsius |
tempCelsius |
KebabCaseLower* | Ord avgränsas med bindestreck. Alla tecken är gemener. |
TempCelsius |
temp-celsius |
KebabCaseUpper* | Ord avgränsas med bindestreck. Alla tecken är versaler. |
TempCelsius |
TEMP-CELSIUS |
SnakeCaseLower* | Ord avgränsas med understreck. Alla tecken är gemener. |
TempCelsius |
temp_celsius |
SnakeCaseUpper* | Ord avgränsas med understreck. Alla tecken är versaler. |
TempCelsius |
TEMP_CELSIUS |
* Tillgänglig i .NET 8 och senare versioner.
I följande exempel visas hur du använder kamelfall för alla JSON-egenskapsnamn genom att ange JsonSerializerOptions.PropertyNamingPolicy till 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)
Här är en exempelklass för serialisering och JSON-utdata:
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
}
Namngivningsprincipen:
- Gäller för serialisering och deserialisering.
- Åsidosättas av
[JsonPropertyName]
attribut. Det är därför JSON-egenskapsnamnetWind
i exemplet inte är kamelfall.
Kommentar
Ingen av de inbyggda namngivningsprinciperna stöder bokstäver som är surrogatpar. Mer information finns i dotnet/runtime issue 90352.
Använda en anpassad namngivningsprincip för JSON-egenskaper
Om du vill använda en anpassad namngivningsprincip för JSON-egenskaper skapar du en klass som härleds från JsonNamingPolicy och åsidosätter ConvertName metoden, som du ser i följande exempel:
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
Ange JsonSerializerOptions.PropertyNamingPolicy sedan egenskapen till en instans av din namngivningsprincipklass:
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)
Här är en exempelklass för serialisering och JSON-utdata:
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
}
Namngivningsprincipen för JSON-egenskap:
- Gäller för serialisering och deserialisering.
- Åsidosättas av
[JsonPropertyName]
attribut. Det är därför JSON-egenskapsnamnetWind
i exemplet inte är versaler.
Använda en namngivningsprincip för ordlistenycklar
Om en egenskap för ett objekt som ska serialiseras är av typen Dictionary<string,TValue>
string
kan nycklarna konverteras med hjälp av en namngivningsprincip, till exempel kamelfall. Det gör du genom att ange JsonSerializerOptions.DictionaryKeyPolicy önskad namngivningsprincip. I följande exempel används CamelCase
namngivningsprincipen:
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)
Serialisering av ett objekt med en ordlista med namnet TemperatureRanges
som har nyckel/värde-par "ColdMinTemp", 20
och "HotMinTemp", 40
skulle resultera i JSON-utdata som i följande exempel:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "Hot",
"TemperatureRanges": {
"coldMinTemp": 20,
"hotMinTemp": 40
}
}
Namngivningsprinciper för ordlistenycklar gäller endast för serialisering. Om du deserialiserar en ordlista matchar nycklarna JSON-filen även om du anger JsonSerializerOptions.DictionaryKeyPolicy en namngivningsprincip som inte är standard.
Räkna upp som strängar
Som standard serialiseras uppräkningar som tal. Om du vill serialisera uppräkningsnamn som strängar använder du JsonStringEnumConverter konverteraren eller JsonStringEnumConverter<TEnum> . Endast JsonStringEnumConverter<TEnum> stöds av den interna AOT-körningen.
Som standard serialiseras uppräkningar som tal. Om du vill serialisera uppräkningsnamn som strängar använder du JsonStringEnumConverter konverteraren.
Anta till exempel att du behöver serialisera följande klass som har en uppräkning:
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
Om sammanfattningen är Hot
har den serialiserade JSON som standard det numeriska värdet 3:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": 3
}
Följande exempelkod serialiserar uppräkningsnamnen i stället för de numeriska värdena och konverterar namnen till kamelfall:
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)
Den resulterande JSON:en ser ut som i följande exempel:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "hot"
}
De inbyggda JsonStringEnumConverter kan även deserialisera strängvärden. Den fungerar med eller utan en angiven namngivningsprincip. I följande exempel visas deserialisering med hjälp av 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)
Du kan också ange vilken konverterare som ska användas genom att kommentera uppräkningen med JsonConverterAttribute. I följande exempel visas hur du anger JsonStringEnumConverter<TEnum> (tillgängliga i .NET 8 och senare versioner) med hjälp JsonConverterAttribute av attributet . Anta till exempel att du behöver serialisera följande klass som har en uppräkning:
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
}
Följande exempelkod serialiserar uppräkningsnamnen i stället för de numeriska värdena:
var options = new JsonSerializerOptions
{
WriteIndented = true,
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);
Den resulterande JSON:en ser ut som i följande exempel:
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Precipitation": "Sleet"
}
Information om hur du använder konverteraren med källgenerering finns i Serialisera uppräkningsfält som strängar.
Konfigurera ordningen för serialiserade egenskaper
Som standard serialiseras egenskaperna i den ordning de definieras i sin klass. Med [JsonPropertyOrder]
attributet kan du ange ordningen på egenskaperna i JSON-utdata från serialiseringen. Standardvärdet för Order
egenskapen är noll. Ange Order
ett positivt tal för att placera en egenskap efter de som har standardvärdet. En negativ Order
positionerar en egenskap före de som har standardvärdet. Egenskaperna skrivs i ordning från det lägsta Order
värdet till det högsta. Här är ett exempel:
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"
//}
Se även
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för