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

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ág és enumerált tagnevek 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.

Megjegyzés

A webes alapértelmezett elnevezési szabályzat camel case.

Tipp.

Az AI-segéd segítségével egyéni szerializálási tulajdonságokkal rendelkező objektumokat hozhat létre.

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

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 tulajdon neve	A tulajdonság konvertált 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ó a "camel case" az összes JSON tulajdonságnevéhez a JsonSerializerOptions.PropertyNamingPolicy beállításávalJsonNamingPolicy.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)

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

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
}

Az elnevezési szabályzat:

• Szerializálásra és deszerializálásra vonatkozik.
• Felül van írva a(z) [JsonPropertyName] attribútumok által. Ezért nem camel case a példában szereplő JSON-tulajdonság neve: Wind.

Megjegyzé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 JsonNamingPolicy osztályból származik, és felülbírálja a ConvertName metódust, ahogyan azt az alábbi példában láthatja.

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 be a JsonSerializerOptions.PropertyNamingPolicy tulajdonságot az elnevezési szabályokat képező osztá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 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
}

A JSON tulajdonságelnevezési szabályzata:

• Szerializálásra és deszerializálásra vonatkozik.
• Felül van írva a(z) [JsonPropertyName] attribútumok által. Ezért a JSON-tulajdonság neve a példában nem nagybetűs.

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

Ha egy szerializálandó objektum egyik tulajdonsága a Dictionary<string,TValue> típusba tartozik, a string kulcsok elnevezési szabályzat alkalmazásával, például camel case használatával konvertálhatók. Ehhez állítsa be a JsonSerializerOptions.DictionaryKeyPolicy elemet a kívánt megnevezési szabályra. 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 TemperatureRanges"ColdMinTemp", 20 tartalmazó szótárral "HotMinTemp", 40 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 a JsonStringEnumConverter vagy JsonStringEnumConverter<TEnum> konvertert. Csak a natív AOT-futtatókörnyezet támogatja a JsonStringEnumConverter<TEnum> elemet.

Tegyük fel például, hogy szerializálnia kell a következő, enumot tartalmazó 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 az enumeráció neveit szerializálja a számértékek helyett, és a neveket camelcase-re alakítja át.

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 CamelCase használatával történő deszerializálást mutatja be.

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

A használni kívánt konvertert úgy is megadhatja, hogy az enumot JsonConverterAttribute segítségével jelöli meg. Az alábbi példa bemutatja, hogyan adhatja meg a JsonStringEnumConverter<TEnum> attribútumot a JsonConverterAttribute (JsonConverterAttribute csak .NET 8 és újabb verziókban érhető el) használatával. Tegyük fel például, hogy szerializálnia kell a következő, enumot tartalmazó 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őképpen néz ki:

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

Egyedi enumerálási tagnevek

A .NET 9-től kezdve testre szabhatja az egyes enumerálási tagok nevét a sztringként szerializált típusok esetében. Az enum tag nevének testreszabásához jelölje meg a JsonStringEnumMemberName attribútummal.

Tegyük fel például, hogy szerializálnia kell a következő osztályt, amelynek van egy enumja egyedi tagnevű elemmel.

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
}

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őképpen néz ki:

{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Sky": "Partly cloudy"
}

Forráslétrehozás

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. Íme egy 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"
//}

A tulajdonságnevek szerializálásának testreszabása AI használatával

Az AI-eszközök, például a GitHub Copilot használatával módosítási mintákat alkalmazhat a kód szerializálására.

Tegyük fel, hogy az osztálydeklarációnak vannak az alábbi PascalCasingtulajdonságai, és a projekt JSON-szabványa.snake_casing Az AI használatával hozzáadhatja a szükséges [JsonPropertyName] attribútumokat az osztály minden tulajdonságához. A Copilot használatával a következőhöz hasonló csevegési kéréssel hajthatja végre ezeket a módosításokat:

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.

Íme a példa egy teljesebb verziója, amely egy egyszerű osztályt tartalmaz.

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.

Alkalmazásuk előtt tekintse át a Copilot javaslatait.

A GitHub Copilotról további információt a GitHub GYIK.

Lásd még

• System.Text.Json áttekintés
• JSON szerializálása és deszerializálása
• GitHub Copilot a Visual Studióban
• GitHub Copilot a VS Code-ban