Comment personnaliser les noms et valeurs de propriétés avec System.Text.Json

Article
12/21/2024

Par défaut, les noms de propriétés et les clés de dictionnaire sont inchangés dans la sortie JSON, y compris la casse. Les valeurs d’énumération sont représentées sous forme de nombres. De plus, les propriétés sont sérialisées dans l’ordre dans lequel elles sont définies. Vous pouvez toutefois personnaliser ces comportements en :

Spécification des noms de propriété sérialisée et des noms de membres d’énumération spécifiques.
Utilisant une stratégie d’attribution de noms intégrée, telle que les mots en casse mixte (camelCase), les mots séparés par des caractères de soulignement (snake_case) ou par des tirets (kebab-case), pour les noms de propriétés et les clés de dictionnaire.
Utilisant une stratégie d’attribution de noms personnalisée pour les noms de propriétés et les clés de dictionnaire.
Sérialisant les valeurs d’énumération sous forme de chaînes, avec ou sans stratégie d’attribution de noms.
Configurant l’ordre des propriétés sérialisées.

Remarque

La stratégie d’attribution de noms des valeurs web par défaut est la casse mixte.

Conseil

Vous pouvez utiliser l’assistance AI pour personnaliser les noms et les valeurs des propriétés avec GitHub Copilot.

Pour les autres scénarios qui nécessitent une gestion spéciale des noms et des valeurs de propriétés JSON, vous pouvez implémenter des convertisseurs personnalisés.

Personnaliser les noms de propriétés individuelles

Pour définir le nom de propriétés individuelles, utilisez l’attribut [JsonPropertyName].

Voici un exemple de type à sérialiser et de JSON résultant :

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
}

Nom de propriété défini par cet attribut :

S’applique dans les deux sens, pour la sérialisation et la désérialisation.
Est prioritaire sur les stratégies d’affectation de noms de propriétés.
N’affecte pas la correspondance de nom de paramètre pour les constructeurs paramétrables.

Utiliser une stratégie d’attribution de noms intégrée

Le tableau ci-dessous montre les stratégies d’attribution de noms intégrées et leur impact sur les noms de propriétés.

Stratégie d’affectation de noms	Description	Nom de propriété d’origine	Nom de propriété converti
CamelCase	Le premier mot commence par un caractère minuscule. Les mots successifs commencent par un caractère majuscule.	`TempCelsius`	`tempCelsius`
KebabCaseLower*	Les mots sont séparés par des tirets. Tous les caractères sont minuscules.	`TempCelsius`	`temp-celsius`
KebabCaseUpper*	Les mots sont séparés par des tirets. Tous les caractères sont majuscules.	`TempCelsius`	`TEMP-CELSIUS`
SnakeCaseLower*	Les mots sont séparés par des traits de soulignement. Tous les caractères sont minuscules.	`TempCelsius`	`temp_celsius`
SnakeCaseUpper*	Les mots sont séparés par des traits de soulignement. Tous les caractères sont majuscules.	`TempCelsius`	`TEMP_CELSIUS`

* Disponible dans .NET 8 et versions ultérieures.

L’exemple ci-dessous montre comment utiliser la casse mixte pour tous les noms de propriétés JSON en définissant JsonSerializerOptions.PropertyNamingPolicy sur JsonNamingPolicy.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)

Voici un exemple de classe à sérialiser et une sortie 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
}

La stratégie d’attribution de noms :

S’applique à la sérialisation et à la désérialisation.
Est remplacé par des attributs [JsonPropertyName]. C’est pourquoi le nom de propriété JSON Wind dans l’exemple n’est pas en casse mixte.

Remarque

Aucune des stratégies d’attribution de noms intégrées ne prend en charge les lettres qui sont des paires de substitution. Pour plus d’informations, consultez le problème dotnet/runtime 90352.

Utiliser une stratégie de nommage de propriétés JSON personnalisée

Pour utiliser une stratégie de nommage de propriétés JSON personnalisée, créez une classe qui dérive de JsonNamingPolicy et remplace la méthode ConvertName, comme indiqué dans l’exemple suivant :

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

Définissez ensuite la propriété JsonSerializerOptions.PropertyNamingPolicy sur une instance de votre classe de stratégie d’affectation de noms :

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)

Voici un exemple de classe à sérialiser et une sortie 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
}

Stratégie de nommage de propriétés JSON :

S’applique à la sérialisation et à la désérialisation.
Est remplacé par des attributs [JsonPropertyName]. C’est pourquoi le nom de propriété JSON Wind dans l’exemple n’est pas en majuscules.

Utiliser une stratégie d’attribution de noms pour les clés de dictionnaire

Si une propriété d’un objet à sérialiser est de type Dictionary<string,TValue>, les clés string peuvent être converties à l’aide d’une stratégie d’attribution de noms (casse mixte, par exemple). Pour ce faire, définissez JsonSerializerOptions.DictionaryKeyPolicy votre stratégie d’attribution de noms souhaitée. L’exemple suivant utilise la stratégie d’attribution de noms CamelCase :

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)

Sérialiser un objet avec un dictionnaire nommé TemperatureRanges qui a des paires clé-valeur "ColdMinTemp", 20 et "HotMinTemp", 40 entraînerait une sortie JSON semblable à l’exemple suivant :

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

Les stratégies d’attribution de noms pour les clés de dictionnaire s’appliquent uniquement à la sérialisation. Si vous désérialisez un dictionnaire, les clés correspondent au fichier JSON même si vous définissez JsonSerializerOptions.DictionaryKeyPolicy sur une stratégie d’attribution de noms autre que par défaut.

Énumérations sous forme de chaînes

Par défaut, les énumérations sont sérialisées en tant que nombres. Pour sérialiser des noms d’énumération sous forme de chaînes, utilisez le convertisseur JsonStringEnumConverter ou JsonStringEnumConverter<TEnum>. Seul JsonStringEnumConverter<TEnum> est pris en charge par le runtime AOT natif.

Par exemple, supposons que vous deviez sérialiser la classe suivante qui a une énumération :

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

Si le résumé est Hot, par défaut, le JSON sérialisé a la valeur numérique 3 :

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

L’exemple de code suivant sérialise les noms d’énumération au lieu des valeurs numériques et convertit les noms en casse mixte :

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)

Le JSON obtenu ressemble à l’exemple suivant :

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

Le composant intégré JsonStringEnumConverter peut également désérialiser les valeurs de chaîne. Il fonctionne avec ou sans stratégie d’attribution de noms spécifiée. L’exemple suivant illustre la désérialisation à l’aide de 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)

JsonConverterAttribute

Vous pouvez également spécifier le convertisseur à utiliser en annotant votre énumération avec JsonConverterAttribute. L’exemple ci-dessous montre comment spécifier JsonStringEnumConverter<TEnum> (disponible dans .NET 8 et versions ultérieures) à l’aide de l’attribut JsonConverterAttribute. Par exemple, supposons que vous deviez sérialiser la classe suivante qui a une énumération :

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
}

L’exemple de code suivant sérialise les noms d’énumération au lieu des valeurs numériques :

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

Le code JSON obtenu ressemble à ce qui suit :

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

Noms personnalisés des membres d’énumération

À partir de .NET 9, vous pouvez personnaliser les noms des membres individuels d’énumération pour les types qui sont sérialisés sous forme de chaînes. Pour personnaliser le nom d’un membre d’énumération, annotez-le avec l’attribut JsonStringEnumMemberName.

Par exemple, supposons que vous devez sérialiser la classe suivante qui possède une énumération avec un nom de membre personnalisé :

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
}

L’exemple de code suivant sérialise les noms d’énumération au lieu des valeurs numériques :

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

Le code JSON obtenu ressemble à ce qui suit :

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

Génération de la source

Pour utiliser le convertisseur avec la génération de source, consultez la section Sérialiser les champs d’énumération sous forme de chaînes.

Configurer l’ordre des propriétés sérialisées

Par défaut, les propriétés sont sérialisées dans l’ordre dans lequel elles sont définies dans leur classe. L’attribut [JsonPropertyOrder] vous permet de spécifier l’ordre des propriétés dans la sortie JSON de la sérialisation. La valeur par défaut de la propriété Order est zéro. Définissez Order sur un nombre positif pour positionner une propriété après celles qui ont la valeur par défaut. Une valeur négative Order positionne une propriété avant celles qui ont la valeur par défaut. Les propriétés sont écrites dans l’ordre, de la valeur Order la plus faible à la plus élevée. Voici un exemple :

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

Utilisez GitHub Copilot pour personnaliser les noms et l’ordre des propriétés

Vous pouvez utiliser GitHub Copilot dans votre IDE pour générer du code permettant de personnaliser les noms et l’ordre des propriétés sérialisées. Vous pouvez personnaliser l’invite pour produire une chaîne JSON avec des noms de propriétés et des valeurs qui correspondent à vos besoins.

L’exemple suivant montre comment utiliser Copilot pour modifier du code existant afin de personnaliser les noms et l’ordre des propriétés lors de la sérialisation en JSON.

Ajoutez l’exemple de code C# suivant dans un fichier de code Example.cs dans votre éditeur. Dans Visual Studio, vous pouvez utiliser un projet d’application console C# pour essayer cet exemple.

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 le code fait ce qui suit :

Crée une instance de la classe Person et initialise ses propriétés avec des valeurs.
Sérialise l’objet person en une chaîne JSON en utilisant JsonSerializer.Serialize.
Affiche la chaîne JSON suivante dans la console :

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

Dans Copilot Chat, entrez l’invite suivante pour modifier le code afin de personnaliser les noms et l’ordre de la sortie de la sérialisation JSON.

#Example.cs modify code to use System.Text.Json to customize property names and order of JSON output from serialization.
Set property names: FirstName to first_name, LastName to last_name.
Set order to: Country, FirstName, LastName, Age.
Provide customized serialization output.

GitHub Copilot est alimenté par l’IA, donc des surprises et des erreurs sont possibles. Pour plus d’informations, consultez FAQ copilot.

En savoir plus sur GitHub Copilot dans Visual Studio et GitHub Copilot dans VS Code.

Partager via