Eigenschapsnamen en -waarden aanpassen met System.Text.Json

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 geserialiseerde eigenschaps- en opsommingsnamen 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.

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

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.

* 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 JsonSerializerOptions.PropertyNamingPolicystellen JsonNamingPolicy.CamelCase 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 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
}

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.

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

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.

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)

Json ConverterAttribute

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 er als volgt uit:

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

Aangepaste namen van leden

Vanaf .NET 9 kunt u de namen van afzonderlijke enumleden aanpassen voor typen die als tekenreeksen worden geserialiseerd. Als u een naam van een enum-lid wilt aanpassen, maakt u er aantekeningen van met het kenmerk JsonStringEnumMemberName.

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

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
}

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 er als volgt uit:

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

Brongeneratie

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

AI gebruiken om aan te passen hoe eigenschapsnamen worden geserialiseerd

U kunt AI-hulpprogramma's, zoals GitHub Copilot, gebruiken om patronen van wijzigingen toe te passen op de wijze waarop uw code serialiseert.

Stel dat uw klassedeclaratie eigenschappen bevat die volgen PascalCasingen dat de JSON-standaard voor uw project is snake_casing. U kunt AI gebruiken om de benodigde [JsonPropertyName] -kenmerken toe te voegen aan elke eigenschap in uw klasse. U kunt Copilot gebruiken om deze wijzigingen aan te brengen met een chatprompt als volgt:

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.

Hier volgt een volledigere versie van het voorbeeld met een eenvoudige klasse.

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.

Bekijk de suggesties van Copilot voordat u ze toepast.

Zie de veelgestelde vragen over GitHub Copilot voor meer informatie over GitHub.

Zie ook

• System.Text.Json-overzicht
• JSON serialiseren en deserialiseren
• GitHub Copilot in Visual Studio
• GitHub Copilot in VS Code