Tulajdonságnevek és értékek testreszabása a System.Text.Json

Cikk
10/18/2023

Alapértelmezés szerint a tulajdonságnevek és a szótárkulcsok nem változnak a JSON-kimenetben, beleértve a kis- és nagybetűket is. Az enumerálási értékek számokként jelennek meg. A tulajdonságok pedig a definiált sorrendben vannak szerializálva. Ezeket a viselkedéseket azonban a következőkkel szabhatja testre:

Adott szerializált tulajdonságnevek megadása.
A tulajdonságnevekhez és a szótárkulcsokhoz beépített elnevezési szabályzatot (például camelCase, snake_case vagy kebab-case) használ.
Egyéni elnevezési szabályzat használata a tulajdonságnevekhez és a szótárkulcsokhoz.
Az enumerálási értékek sztringekként való szerializálása elnevezési szabályzattal vagy anélkül.
A szerializált tulajdonságok sorrendjének konfigurálása.

Feljegyzés

A webes alapértelmezett elnevezési szabályzat tevees eset.

A JSON-tulajdonságnevek és -értékek speciális kezelését igénylő egyéb forgatókönyvek esetében egyéni konvertereket is implementálhat.

Egyéni tulajdonságnevek testreszabása

Az egyes tulajdonságok nevének beállításához használja a [JsonPropertyName] attribútumot.

Íme egy példatípus a JSON szerializálására és eredményére:

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
}

Az attribútum által beállított tulajdonságnév:

Mindkét irányban alkalmazható szerializálásra és deszerializálásra.
Elsőbbséget élvez a tulajdonságelnevezési szabályzatokkal szemben.
Nincs hatással a paraméteres konstruktorok paraméternevének egyeztetésére.

Beépített elnevezési szabályzat használata

Az alábbi táblázat bemutatja a beépített elnevezési szabályzatokat, valamint azt, hogy ezek hogyan befolyásolják a tulajdonságneveket.

Elnevezési szabályzat	Leírás	Eredeti tulajdonságnév	Konvertált tulajdonság neve
CamelCase	Az első szó kisbetűvel kezdődik. Az egymást követő szavak nagybetűvel kezdődnek.	`TempCelsius`	`tempCelsius`
KebabCaseLower*	A szavakat kötőjelek választják el egymástól. Minden karakter kisbetűs.	`TempCelsius`	`temp-celsius`
KebabCaseUpper*	A szavakat kötőjelek választják el egymástól. Minden karakter nagybetűs.	`TempCelsius`	`TEMP-CELSIUS`
SnakeCaseLower*	A szavakat aláhúzásjelek választják el egymástól. Minden karakter kisbetűs.	`TempCelsius`	`temp_celsius`
SnakeCaseUpper*	A szavakat aláhúzásjelek választják el egymástól. Minden karakter nagybetűs.	`TempCelsius`	`TEMP_CELSIUS`

* .NET 8 és újabb verziókban érhető el.

Az alábbi példa bemutatja, hogyan használható tevees eset az összes JSON-tulajdonságnévhez a következő JsonNamingPolicy.CamelCasebeállítássalJsonSerializerOptions.PropertyNamingPolicy:

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)

Íme egy példaosztály szerializálásra és JSON-kimenetre:

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
}

Az elnevezési szabályzat:

Szerializálásra és deszerializálásra vonatkozik.
Az attribútumok felülírják [JsonPropertyName] . Ezért nem tevees eset a példában szereplő JSON-tulajdonság neve Wind .

Feljegyzés

A beépített elnevezési szabályzatok egyike sem támogatja a helyettesítő párokat tartalmazó betűket. További információ: dotnet/runtime issue 90352.

Egyéni JSON-tulajdonságelnevezési szabályzat használata

Egyéni JSON-tulajdonságelnevezési szabályzat használatához hozzon létre egy osztályt, amely a metódusból JsonNamingPolicy származik, és felülbírálja azt ConvertName az alábbi példában látható módon:

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

Ezután állítsa a tulajdonságot az JsonSerializerOptions.PropertyNamingPolicy elnevezési szabályzatosztály egy példányára:

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)

Íme egy példaosztály szerializálásra és JSON-kimenetre:

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
}

A JSON tulajdonságelnevezési szabályzata:

Szerializálásra és deszerializálásra vonatkozik.
Az attribútumok felülírják [JsonPropertyName] . Ezért nem nagybetűs a példában szereplő JSON-tulajdonság neve Wind .

Elnevezési szabályzat használata szótárkulcsokhoz

Ha egy szerializálandó objektum tulajdonsága típus Dictionary<string,TValue>, a string kulcsok elnevezési házirenddel, például tevees esetekkel konvertálhatók. Ehhez állítsa be JsonSerializerOptions.DictionaryKeyPolicy a kívánt elnevezési szabályzatot. Az alábbi példa az elnevezési CamelCase szabályzatot használja:

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)

Egy kulcs-érték párokat "ColdMinTemp", 20"HotMinTemp", 40 tartalmazó szótárral TemperatureRanges rendelkező objektum szerializálása JSON-kimenetet eredményez, mint az alábbi példa:

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

A szótárkulcsok elnevezési szabályzatai csak a szerializálásra vonatkoznak. Ha deszerializál egy szótárt, a kulcsok akkor is megegyeznek a JSON-fájllal, ha nem alapértelmezett elnevezési szabályzatot állít be JsonSerializerOptions.DictionaryKeyPolicy .

Sztringek számbavétele

Alapértelmezés szerint a számokat számként szerializálja a rendszer. Az enumerálási nevek sztringekként való szerializálásához használja az vagy JsonStringEnumConverter<TEnum> konvertertJsonStringEnumConverter. Csak JsonStringEnumConverter<TEnum> a natív AOT-futtatókörnyezet támogatja.

Alapértelmezés szerint a számokat számként szerializálja a rendszer. Az enumerálási nevek sztringekként való szerializálásához használja a JsonStringEnumConverter konvertert.

Tegyük fel például, hogy szerializálnia kell a következő, enumerálással rendelkező osztályt:

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

Ha az összegzés az Hot, a szerializált JSON alapértelmezés szerint 3 numerikus értékkel rendelkezik:

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

Az alábbi mintakód szerializálja a számértékek helyett az enumerikus neveket, és a neveket tevees esetté alakítja:

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)

Az eredményként kapott JSON a következő példához hasonlóan néz ki:

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

A beépített függvény JsonStringEnumConverter a sztringértékeket is deszerializálhatja. Egy megadott elnevezési szabályzattal vagy anélkül működik. Az alábbi példa a deszerializálást mutatja be a következő használatával 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)

A használni kívánt konvertert úgy is megadhatja, hogy az enumerálást a következővel jegyzeteli JsonConverterAttribute: . Az alábbi példa bemutatja, hogyan adhatja meg a JsonStringEnumConverter<TEnum> (.NET 8 és újabb verziókban elérhető) JsonConverterAttribute attribútumot. Tegyük fel például, hogy szerializálnia kell a következő, enumerálással rendelkező osztályt:

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
}

Az alábbi mintakód a számértékek helyett szerializálja a számneveket:

var options = new JsonSerializerOptions
{
    WriteIndented = true,
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

Az eredményként kapott JSON a következő példához hasonlóan néz ki:

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

Ha a konvertert forrásgenerálással szeretné használni, olvassa el az enumerálási mezők sztringként való szerializálását.

Szerializált tulajdonságok sorrendjének konfigurálása

A tulajdonságok alapértelmezés szerint abban a sorrendben vannak szerializálva, amelyben az osztályban vannak definiálva. Az [JsonPropertyOrder] attribútum lehetővé teszi a tulajdonságok sorrendjének megadását a szerializálásból származó JSON-kimenetben. A tulajdonság alapértelmezett értéke Order nulla. Pozitív számra állítva Order helyezzen el egy tulajdonságot az alapértelmezett értékkel rendelkezők után. A negatív Order értékek az alapértelmezett értékkel rendelkezők elé helyezik a tulajdonságot. A tulajdonságok a legalacsonyabb Order értéktől a legmagasabbig vannak megírva. Példa:

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

Share via