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

CKTIS / C#

Convertisseur JSON bidirectionnel : lecture, écriture et validation des jetons

Créez un convertisseur System.Text.Json qui lit et écrit un objet JSON, rejette les jetons non valides et applique explicitement camelCase et l’omission des valeurs null.

Version : C# 12 and .NET 8; later runtimes may add compatible features

Syntaxe

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

// Members of JsonConverter<T>:
public abstract T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options);
public abstract void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options);

// Inspect reader.TokenType (a JsonTokenType) before reading a value.
// Reject incompatible input with new JsonException("Expected a JSON string.").

En C# 12 et .NET 8, un JsonConverter<T> de System.Text.Json.Serialization définit les deux sens de conversion. Enregistrez-le dans options.Converters. Utf8JsonReader, Utf8JsonWriter, JsonTokenType et JsonException appartiennent à System.Text.Json. Le lecteur parcourt l’entrée UTF-8 uniquement vers l’avant. C’est un ref struct mutable : passez-le par ref pour déplacer le curseur d’origine plutôt qu’une copie, et ne le stockez pas dans un champ de classe.

La méthode Read du convertisseur commence sur le premier jeton de la valeur. Pour un objet, vérifiez StartObject, lisez les propriétés et revenez avec le curseur sur le EndObject correspondant, pas après. La même règle vaut pour les tableaux ; pour un scalaire, restez sur son jeton. reader.TokenType renvoie une valeur de l’énumération JsonTokenType ; vérifiez-la avant d’extraire la valeur. Number ne garantit pas que le nombre tient dans un int : utilisez TryGetInt32. Levez JsonException si l’entrée est incompatible ; le sérialiseur peut renseigner Path, LineNumber et BytePositionInLine. Une lecture trop courte ou trop longue peut aussi provoquer une JsonException.

Write écrit exactement une valeur complète avec le Utf8JsonWriter fourni, sans appeler Dispose ni Flush. Le sérialiseur applique PropertyNamingPolicy = JsonNamingPolicy.CamelCase et DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull aux propriétés qu’il gère, mais pas aux appels manuels du writer. L’exemple calcule les mêmes noms dans les deux sens et omet les propriétés entières dont la valeur est null uniquement avec WhenWritingNull ; 0 est toujours écrit. Il respecte la casse, rejette les noms inconnus ou répétés et implémente les règles d’omission Never et WhenWritingNull, pas tous les réglages du sérialiseur.

string? est une annotation utilisée par le compilateur pour analyser les valeurs nulles, pas un nouveau type à l’exécution ni une validation JSON. int? est le type valeur distinct Nullable<int>, qui représente un entier ou une absence de valeur. Par défaut, le sérialiseur traite les valeurs nulles des types référence et de Nullable<T> sans appeler leur convertisseur. Pour que celui-ci les prenne en charge, redéfinissez HandleNull afin de renvoyer true. L’omission des propriétés est une autre question : WhenWritingNull ne concerne que l’écriture, et le contrat détermine si une propriété absente ou un null JSON explicite est accepté en lecture. Ici, les deux formes sont acceptées pour Note et Rank, mais pas pour DisplayName.

Exemples

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

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
options.Converters.Add(new ProfileCardConverter());

var card = new ProfileCard("Ada", null, null);
Console.WriteLine(JsonSerializer.Serialize(card, options));
var keepNulls = new JsonSerializerOptions(options)
{
    DefaultIgnoreCondition = JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(card, keepNulls));

var read = JsonSerializer.Deserialize<ProfileCard>(
    """{"displayName":"Ada","note":null,"rank":0}""", options)
    ?? throw new JsonException("Expected a non-null profile card.");
Console.WriteLine(JsonSerializer.Serialize(read, options));

try
{
    _ = JsonSerializer.Deserialize<ProfileCard>("""{"displayName":42}""", options);
}
catch (JsonException)
{
    Console.WriteLine("Rejected: JsonException");
}

sealed record ProfileCard(string DisplayName, string? Note, int? Rank);

sealed class ProfileCardConverter : JsonConverter<ProfileCard>
{
    private static string Name(JsonSerializerOptions options, string clrName) =>
        options.PropertyNamingPolicy?.ConvertName(clrName) ?? clrName;

    public override ProfileCard Read(ref Utf8JsonReader reader, Type typeToConvert,
        JsonSerializerOptions options)
    {
        if (reader.TokenType != JsonTokenType.StartObject)
            throw new JsonException("Expected an object.");

        string displayNameKey = Name(options, nameof(ProfileCard.DisplayName));
        string noteKey = Name(options, nameof(ProfileCard.Note));
        string rankKey = Name(options, nameof(ProfileCard.Rank));
        var seen = new HashSet<string>(StringComparer.Ordinal);
        string? displayName = null;
        string? note = null;
        int? rank = null;

        while (reader.Read())
        {
            if (reader.TokenType == JsonTokenType.EndObject)
                return new ProfileCard(
                    displayName ?? throw new JsonException("Missing display name."), note, rank);

            if (reader.TokenType != JsonTokenType.PropertyName)
                throw new JsonException("Expected a property name.");
            string key = reader.GetString() ?? throw new JsonException("Missing property name.");
            if (!seen.Add(key))
                throw new JsonException("Duplicate property.");
            if (!reader.Read())
                throw new JsonException("Missing property value.");

            if (key == displayNameKey && reader.TokenType == JsonTokenType.String)
                displayName = reader.GetString();
            else if (key == noteKey && reader.TokenType is JsonTokenType.String or JsonTokenType.Null)
                note = reader.GetString();
            else if (key == rankKey && reader.TokenType == JsonTokenType.Null)
                rank = null;
            else if (key == rankKey && reader.TokenType == JsonTokenType.Number &&
                     reader.TryGetInt32(out int number))
                rank = number;
            else
                throw new JsonException("Unknown property or invalid value.");
        }

        throw new JsonException("Expected the end of the object.");
    }

    public override void Write(Utf8JsonWriter writer, ProfileCard value, JsonSerializerOptions options)
    {
        bool omitNulls = options.DefaultIgnoreCondition == JsonIgnoreCondition.WhenWritingNull;
        writer.WriteStartObject();
        writer.WriteString(Name(options, nameof(ProfileCard.DisplayName)), value.DisplayName);
        if (value.Note is not null || !omitNulls)
            writer.WriteString(Name(options, nameof(ProfileCard.Note)), value.Note);
        if (value.Rank is int rank)
            writer.WriteNumber(Name(options, nameof(ProfileCard.Rank)), rank);
        else if (!omitNulls)
            writer.WriteNull(Name(options, nameof(ProfileCard.Rank)));
        writer.WriteEndObject();
    }
}

Résultat

{"displayName":"Ada"}
{"displayName":"Ada","note":null,"rank":null}
{"displayName":"Ada","rank":0}
Rejected: JsonException

La première ligne omet les deux propriétés dont la valeur est null, la deuxième les écrit toutes deux comme null et la troisième conserve rank à 0 après lecture. Un nombre à la place d’un texte dans displayName provoque une JsonException.

Leçons associées

  • C# · Leçon 39 · Avancé · Version : 3

Sources