Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / C#

JsonSerializerOptions — configurer la lecture et l’écriture JSON

System.Text.Json.JsonSerializerOptions contrôle la conversion des objets .NET en JSON et leur lecture depuis du JSON. Cette classe permet de configurer les noms de propriétés, les commentaires, les propriétés inconnues, le traitement des nombres et l’omission des valeurs null. Configurez une instance avant sa première utilisation et réutilisez-la ensuite.

Version : .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Syntaxe

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, ReadCommentHandling = JsonCommentHandling.Skip, UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, NumberHandling = JsonNumberHandling.AllowReadingFromString, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
var value = JsonSerializer.Deserialize<T>(json, options);
string result = JsonSerializer.Serialize(value, options);

System.Text.Json.JsonSerializerOptions fournit une configuration à JsonSerializer.Serialize et JsonSerializer.Deserialize. L’exemple cible .NET 10 ; UnmappedMemberHandling est disponible depuis .NET 8. Aucune fonctionnalité de langage en préversion n’est nécessaire. new JsonSerializerOptions() sans autre configuration conserve les noms des propriétés, distingue les majuscules des minuscules lors de la lecture et applique un traitement strict des nombres ; les valeurs par défaut des applications web peuvent différer.

JsonNamingPolicy représente une règle de conversion des noms. PropertyNamingPolicy = JsonNamingPolicy.CamelCase convertit ItemCount en itemCount à l’écriture comme à la lecture. Cela n’active pas la correspondance insensible à la casse : utilisez PropertyNameCaseInsensitive pour cela. Un attribut [JsonPropertyName] est prioritaire sur cette règle.

ReadCommentHandling utilise JsonCommentHandling : la valeur par défaut Disallow rejette les commentaires, tandis que Skip les accepte et les ignore. La valeur Allow, destinée à un lecteur, n’est pas prise en charge par cette option du sérialiseur. UnmappedMemberHandling utilise JsonUnmappedMemberHandling : la valeur par défaut Skip ignore les propriétés JSON sans correspondance, sauf si elles sont recueillies comme données d’extension. Si le réglage effectif pour un type est Disallow, une propriété JSON sans correspondance déclenche une JsonException. La configuration propre à un type peut primer sur le réglage des options du sérialiseur. Si Disallow est défini uniquement dans les options, un membre annoté avec [JsonExtensionData] peut recueillir les propriétés sans correspondance sans qu’une exception soit levée. Ce réglage n’impose pas que toutes les propriétés du modèle soient présentes dans l’entrée.

NumberHandling utilise les indicateurs de JsonNumberHandling. La valeur par défaut Strict exige des jetons numériques ; AllowReadingFromString permet aussi de lire "3" comme un nombre, mais l’écrit toujours sous la forme 3. L’indicateur distinct WriteAsString écrit les nombres entre guillemets. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull omet à l’écriture les propriétés dont la valeur est null ; il n’omet ni 0 ni false et n’empêche pas la lecture de null.

Configurez les options avant la première sérialisation ou désérialisation : l’instance devient ensuite immuable. Réutilisez-la pour conserver ses caches de métadonnées ; son partage entre plusieurs threads est sûr. L’exemple ignore un commentaire, lit un nombre entre guillemets et écrit l’objet sans Note. Une propriété JSON sans correspondance déclencherait une JsonException lors de la désérialisation du type Payload de l’exemple.

Exemples

#nullable enable
using System;
using System.Text.Json;
using System.Text.Json.Serialization;

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    ReadCommentHandling = JsonCommentHandling.Skip,
    UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,
    NumberHandling = JsonNumberHandling.AllowReadingFromString,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

const string json = "{ /* input */ \"itemCount\": \"3\", \"note\": null }";
var value = JsonSerializer.Deserialize<Payload>(json, options)
    ?? throw new InvalidOperationException();
Console.WriteLine(JsonSerializer.Serialize(value, options));

public sealed class Payload
{
    public int ItemCount { get; set; }
    public string? Note { get; set; }
}

Résultat

{"itemCount":3}

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources