Eigenschapsnamen en -waarden aanpassen met System.Text.Json

Artikel
10/22/2024

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.

Notitie

Het standaardnaamgevingsbeleid voor het web is een kameel geval.

Tip

U kunt AI-hulp gebruiken om eigenschapsnamen en -waarden aan te passen met GitHub Copilot.

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.

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

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

Github Copilot gebruiken om eigenschapsnamen en volgorde aan te passen

U kunt GitHub Copilot in uw IDE gebruiken om code te genereren om namen en volgorde van geserialiseerde eigenschappen aan te passen.

Als u Visual Studio 2022 versie 17.8 of hoger gebruikt, kunt u de AI-gestuurde GitHub Copilot in Visual Studio proberen om code te genereren die gebruikmaakt System.Text.Json van het aanpassen van eigenschapsnamen en volgorde in de JSON-uitvoer van serialisatie. Dien uw vraag in als prompt in het Copilot-chatvenster, zoals in het volgende voorbeeld. U kunt ook prompts verzenden via inlinechat in het editorvenster zelf.

Notitie

GitHub Copilot wordt mogelijk gemaakt door AI, dus verrassingen en fouten zijn mogelijk. Zorg ervoor dat u alle gegenereerde code of suggesties controleert. Zie de veelgestelde vragen over GitHub Copilot voor meer informatie over het algemene gebruik van GitHub Copilot, productimpact, menselijk toezicht en privacy.

In het volgende voorbeeld ziet u hoe u Copilot gebruikt om bestaande code te wijzigen om eigenschapsnamen en volgorde aan te passen bij het serialiseren naar JSON.

Voeg de volgende C#-voorbeeldcode toe aan een codebestand Example.cs in uw editor. In Visual Studio kunt u een C#-consoletoepassingsproject gebruiken om dit voorbeeld uit te proberen.

using System.Text.Json;

public class Person
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
    public int Age { get; set; }
    public string? Country { get; set; }
}

public class Program
{
    public static void Main()
    {
        var person = new Person
        {
            FirstName = "John",
            LastName = "Doe",
            Age = 30,
            Country = "USA"
        };

        string jsonString = JsonSerializer.Serialize(person);
        Console.WriteLine(jsonString);
    }
}

Example.cs code doet het volgende:

Hiermee maakt u een exemplaar van de Person klasse en initialiseert u de eigenschappen ervan met waarden.
Serialiseert het person object naar een JSON-tekenreeks met behulp van JsonSerializer.Serialize.
Hiermee wordt de volgende JSON-tekenreeks afgedrukt naar de console:

{"FirstName":"John","LastName":"Doe","Age":30,"Country":"USA"}

Voer in Copilot Chat de volgende prompt in om de code te wijzigen om namen en volgorde van de JSON-serialisatie-uitvoer aan te passen.

#Example.cs wijzig code die moet worden gebruikt System.Text.Json om eigenschapsnamen en volgorde van JSON-uitvoer van serialisatie aan te passen. Eigenschapsnamen instellen: Voornaam op first_name, Achternaam op last_name. Volgorde instellen op: Land, Voornaam, Achternaam, Leeftijd. Geef aangepaste serialisatie-uitvoer op.

#Example.cs in de prompt geeft een bestandsreferentie als context voor Copilot. U kunt de prompt aanpassen om een JSON-tekenreeks uit te voeren met eigenschapsnamen en -waarden die aan uw vereisten voldoen. Als u intenties wilt instellen en betere antwoorden wilt krijgen met contextbereik, kunt u chatfuncties zoals slash-opdrachten, verwijzingen naar bestanden, methoden of klassen en threads gebruiken.

In de volgende uitvoer ziet u een voorbeeld van een Copilot Chat-antwoord:

To customize the property names and order of the JSON output using System.Text.Json, you can use the JsonPropertyName attribute to rename properties and the JsonPropertyOrder attribute to set the order. Here's how you can modify your code:

using System.Text.Json;
using System.Text.Json.Serialization;

public class Person
{
    [JsonPropertyName("first_name")]
    [JsonPropertyOrder(2)]
    public string? FirstName { get; set; }

    [JsonPropertyName("last_name")]
    [JsonPropertyOrder(3)]
    public string? LastName { get; set; }

    [JsonPropertyOrder(4)]
    public int Age { get; set; }

    [JsonPropertyOrder(1)]
    public string? Country { get; set; }
}

public class Program
{
    public static void Main()
    {
        var person = new Person
        {
            FirstName = "John",
            LastName = "Doe",
            Age = 30,
            Country = "USA"
        };

        string jsonString = JsonSerializer.Serialize(person, new JsonSerializerOptions { WriteIndented = true });
        Console.WriteLine(jsonString);
    }
}

**Explanation:**

1. Renaming Properties: The JsonPropertyName attribute is used to rename FirstName to first_name and LastName to last_name.
2. Ordering Properties: The JsonPropertyOrder attribute is used to set the order of the properties in the JSON output. The order is set as:
   • Country (Order 1)
   • FirstName (Order 2)
   • LastName (Order 3)
   • Age (Order 4)
3. Indented JSON: The JsonSerializerOptions with WriteIndented = true is used to make the JSON output more readable.

**Customized Serialization Output:**
{
  "Country": "USA",
  "first_name": "John",
  "last_name": "Doe",
  "Age": 30
}

This ensures that the JSON output has the customized property names and the specified order.

Wanneer Copilot een codeblok retourneert, bevat het antwoord opties voor het kopiëren van de code, het invoegen van de code in een nieuw bestand of het bekijken van de code-uitvoer.

Notitie

Uw resultaten kunnen afwijken van wat wordt weergegeven in de voorbeeldantwoorden. AI-modellen zijn niet-deterministisch, wat betekent dat ze verschillende antwoorden kunnen retourneren wanneer ze dezelfde vraag stellen. Dit kan worden veroorzaakt door extra leer- en aanpassing in de loop van de tijd, taalvariatie, wijzigingen in context, zoals uw chatgeschiedenis en meer.

Delen via

Eigenschapsnamen en -waarden aanpassen met System.Text.Json

Afzonderlijke eigenschapsnamen aanpassen

Een ingebouwd naamgevingsbeleid gebruiken

Een aangepast naamgevingsbeleid voor JSON-eigenschappen gebruiken

Een naamgevingsbeleid gebruiken voor woordenlijstsleutels

Opsommingen als tekenreeksen

Json ConverterAttribute

Aangepaste namen van leden

Brongeneratie

De volgorde van geserialiseerde eigenschappen configureren

Github Copilot gebruiken om eigenschapsnamen en volgorde aan te passen

Zie ook

Aanvullende resources