Eigenschapsnamen en -waarden aanpassen met System.Text.Json

Artikel
10/18/2023

Standaard worden eigenschapsnamen en woordenlijstsleutels ongewijzigd in de JSON-uitvoer, inclusief hoofdletters en kleine letters. Opsommingswaarden worden weergegeven als getallen. En eigenschappen worden geserialiseerd in de volgorde waarin ze zijn gedefinieerd. U kunt dit gedrag echter aanpassen door:

Specifieke namen van geserialiseerde eigenschappen opgeven.
Het gebruik van een ingebouwd naamgevingsbeleid, zoals camelCase, snake_case of resource-case, voor eigenschapsnamen en woordenlijstsleutels.
Een aangepast naamgevingsbeleid gebruiken voor eigenschapsnamen en woordenlijstsleutels.
Opsommingswaarden serialiseren als tekenreeksen, met of zonder naamgevingsbeleid.
De volgorde van geserialiseerde eigenschappen configureren.

Notitie

Het standaardnaamgevingsbeleid voor het web is een kameel geval.

Voor andere scenario's waarvoor speciale verwerking van JSON-eigenschapsnamen en -waarden is vereist, kunt u aangepaste conversieprogramma's implementeren.

Afzonderlijke eigenschapsnamen aanpassen

Gebruik het kenmerk [JsonPropertyName] om de naam van afzonderlijke eigenschappen in te stellen.

Hier volgt een voorbeeldtype voor het serialiseren en resulterende 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
}

De eigenschapsnaam die door dit kenmerk is ingesteld:

Is in beide richtingen van toepassing voor serialisatie en deserialisatie.
Heeft voorrang op het naamgevingsbeleid voor eigenschappen.
Dit heeft geen invloed op de parameternaam die overeenkomt met parameters voor geparameteriseerde constructors.

Een ingebouwd naamgevingsbeleid gebruiken

In de volgende tabel ziet u het ingebouwde naamgevingsbeleid en hoe deze van invloed zijn op eigenschapsnamen.

Naamgevingsbeleid	Beschrijving	Oorspronkelijke eigenschapsnaam	Naam van geconverteerde eigenschap
CamelCase	Eerste woord begint met een kleine letter. Opeenvolgende woorden beginnen met een hoofdletter.	`TempCelsius`	`tempCelsius`
KebabCaseLower*	Woorden worden gescheiden door afbreekstreepjes. Alle tekens zijn kleine letters.	`TempCelsius`	`temp-celsius`
KebabCaseUpper*	Woorden worden gescheiden door afbreekstreepjes. Alle tekens zijn hoofdletters.	`TempCelsius`	`TEMP-CELSIUS`
SnakeCaseLower*	Woorden worden gescheiden door onderstrepingstekens. Alle tekens zijn kleine letters.	`TempCelsius`	`temp_celsius`
SnakeCaseUpper*	Woorden worden gescheiden door onderstrepingstekens. Alle tekens zijn hoofdletters.	`TempCelsius`	`TEMP_CELSIUS`

* Beschikbaar in .NET 8 en nieuwere versies.

In het volgende voorbeeld ziet u hoe u camel case gebruikt voor alle JSON-eigenschapsnamen door deze instelling in te JsonNamingPolicy.CamelCasestellen JsonSerializerOptions.PropertyNamingPolicy op:

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)

Hier volgt een voorbeeldklasse voor het serialiseren en JSON-uitvoer:

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
}

Het naamgevingsbeleid:

Van toepassing op serialisatie en deserialisatie.
Wordt overschreven door [JsonPropertyName] kenmerken. Daarom is de naam Wind van de JSON-eigenschap in het voorbeeld niet kameel.

Notitie

Geen van de ingebouwde naamgevingsbeleidsregels ondersteunen letters die surrogaatparen zijn. Zie dotnet/runtime-probleem 90352 voor meer informatie.

Een aangepast naamgevingsbeleid voor JSON-eigenschappen gebruiken

Als u een aangepast naamgevingsbeleid voor JSON-eigenschappen wilt gebruiken, maakt u een klasse die is afgeleid van JsonNamingPolicy en overschrijft u de ConvertName methode, zoals wordt weergegeven in het volgende voorbeeld:

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

Stel de JsonSerializerOptions.PropertyNamingPolicy eigenschap vervolgens in op een exemplaar van uw naamgevingsbeleidsklasse:

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)

Hier volgt een voorbeeldklasse voor het serialiseren en JSON-uitvoer:

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
}

Het naamgevingsbeleid voor JSON-eigenschappen:

Van toepassing op serialisatie en deserialisatie.
Wordt overschreven door [JsonPropertyName] kenmerken. Daarom is de naam Wind van de JSON-eigenschap in het voorbeeld niet hoofdletters.

Een naamgevingsbeleid gebruiken voor woordenlijstsleutels

Als een eigenschap van een object dat moet worden geserialiseerd van het type Dictionary<string,TValue>is, kunnen de string sleutels worden geconverteerd met behulp van een naamgevingsbeleid, zoals kameel geval. Hiervoor stelt u het JsonSerializerOptions.DictionaryKeyPolicy gewenste naamgevingsbeleid in. In het volgende voorbeeld wordt het CamelCase naamgevingsbeleid gebruikt:

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)

Het serialiseren van een object met een woordenlijst met TemperatureRanges sleutel-waardeparen "ColdMinTemp", 20 en "HotMinTemp", 40 resulteert in JSON-uitvoer zoals in het volgende voorbeeld:

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

Naamgevingsbeleid voor woordenlijstsleutels is alleen van toepassing op serialisatie. Als u een woordenlijst deserialiseert, komen de sleutels overeen met het JSON-bestand, zelfs als u JsonSerializerOptions.DictionaryKeyPolicy een niet-standaard naamgevingsbeleid instelt.

Opsommingen als tekenreeksen

Opsommingen worden standaard geserialiseerd als getallen. Als u opsommingsnamen als tekenreeksen wilt serialiseren, gebruikt u het JsonStringEnumConverter of JsonStringEnumConverter<TEnum> conversieprogramma. Alleen JsonStringEnumConverter<TEnum> wordt ondersteund door de native AOT-runtime.

Opsommingen worden standaard geserialiseerd als getallen. Als u opsommingsnamen als tekenreeksen wilt serialiseren, gebruikt u het JsonStringEnumConverter conversieprogramma.

Stel dat u de volgende klasse met een opsomming moet serialiseren:

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

Als de samenvatting is, heeft Hotde geserialiseerde JSON standaard de numerieke waarde 3:

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

Met de volgende voorbeeldcode worden de enumnamen geserialiseerd in plaats van de numerieke waarden en worden de namen geconverteerd naar kameelgebruik:

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)

De resulterende JSON ziet eruit als in het volgende voorbeeld:

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

De ingebouwde JsonStringEnumConverter tekenreekswaarden kunnen ook deserialiseren. Het werkt met of zonder een opgegeven naamgevingsbeleid. In het volgende voorbeeld ziet u deserialisatie met behulp van 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)

U kunt ook het conversieprogramma opgeven dat moet worden gebruikt door aantekeningen te maken bij uw opsomming.JsonConverterAttribute In het volgende voorbeeld ziet u hoe u de JsonStringEnumConverter<TEnum> (beschikbaar in .NET 8 en latere versies) opgeeft met behulp van het JsonConverterAttribute kenmerk. Stel dat u de volgende klasse met een opsomming moet serialiseren:

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
}

Met de volgende voorbeeldcode worden de enumnamen geserialiseerd in plaats van de numerieke waarden:

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

De resulterende JSON ziet eruit als in het volgende voorbeeld:

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

Zie Opsommingsvelden serialiseren als tekenreeksen om het conversieprogramma met brongeneratie te gebruiken.

De volgorde van geserialiseerde eigenschappen configureren

Standaard worden eigenschappen geserialiseerd in de volgorde waarin ze in hun klasse worden gedefinieerd. [JsonPropertyOrder] Met het kenmerk kunt u de volgorde van eigenschappen in de JSON-uitvoer van serialisatie opgeven. De standaardwaarde van de Order eigenschap is nul. Ingesteld Order op een positief getal om een eigenschap te positioneren na de eigenschappen met de standaardwaarde. Een negatieve Order positie geeft een eigenschap voor de eigenschappen met de standaardwaarde. Eigenschappen worden geschreven in volgorde van de laagste Order waarde naar de hoogste. Hier volgt een voorbeeld:

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