CKTIS / C#
Convertisseurs JSON personnalisés : limites des valeurs, erreurs et format invariant
Implémentez un convertisseur qui lit et écrit exactement une valeur JSON, refuse les entrées incompatibles et distingue le format invariant de l’encodage JSON.
Version : C# 12 and .NET 8; later runtimes may add compatible features
Syntaxe
// C# 12 / .NET 8 — override signatures inside a JsonConverter<T> subclass
using System;
using System.Text.Json;
using System.Text.Json.Serialization;
public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options)
// Typical expressions inside method bodies:
reader.TokenType == JsonTokenType.Number
reader.TryGetInt32(out int value)
throw new JsonException("Expected an Int32 JSON number.");
writer.WriteNumberValue(value);
FormattableString.Invariant($"temperature={value / 10m:F1}")En C# 12 et .NET 8, JsonConverter<T>, dans System.Text.Json.Serialization, définit la lecture et l’écriture d’une seule valeur de type T. Utf8JsonReader, Utf8JsonWriter, JsonTokenType et JsonException se trouvent dans System.Text.Json. Le lecteur parcourt les jetons JSON UTF-8 sans revenir en arrière ; TokenType indique leur catégorie sous forme de valeur de l’énumération JsonTokenType. Un Number n’est pas un String contenant des chiffres.
À l’entrée de Read, le lecteur est placé sur le premier jeton de la valeur. Pour un scalaire, retournez le résultat sans appeler reader.Read() ; pour un objet ou un tableau, arrêtez-vous au EndObject ou au EndArray correspondant. S’arrêter trop tôt ou aller trop loin enfreint le contrat. Le lecteur est un ref struct mutable : passez-le par ref si l’appelant doit voir son avancement. En C# 12, ne le déclarez pas comme variable locale dans une méthode async et n’utilisez pas les vues sur les octets des jetons après restitution de leur tampon à un pool.
Vérifiez Number avant TryGetInt32(out int value) : la méthode lève InvalidOperationException pour un jeton d’une autre catégorie et renvoie false si le nombre ne peut pas être lu comme int. || n’évalue pas son opérande droit si le gauche est vrai. Pour une entrée incompatible, levez JsonException ; le sérialiseur peut renseigner Path, LineNumber et BytePositionInLine. Par défaut, à la lecture, le convertisseur d’un type valeur non nullable reçoit Null ; pour les types référence et Nullable<T>, le sérialiseur traite normalement null lui-même, sauf si le convertisseur définit HandleNull à true.
Write émet exactement une valeur avec le writer fourni, sans le libérer. WriteNumberValue(int) écrit un nombre sans guillemets. WriteStringValue(string?) écrit une chaîne non nulle entre guillemets en appliquant les règles d’échappement JSON ; si l’argument est null, la méthode écrit le littéral JSON null sans guillemets. Ne construisez pas du JSON par interpolation et ne désactivez pas la validation pour laisser passer des entrées non fiables.
System.FormattableString.Invariant(FormattableString) renvoie un string dont les arguments sont formatés selon la culture invariante. Passez l’interpolation directement ou conservez-la dans un FormattableString ; un string déjà formaté ne peut pas être reformaté ainsi. F1 donne une décimale, ici 12.5. C’est du formatage de texte, pas de la sérialisation ni de l’échappement JSON.
Exemples
using System;
using System.Globalization;
using System.Text.Json;
using System.Text.Json.Serialization;
var options = new JsonSerializerOptions();
options.Converters.Add(new TenthsConverter());
Tenths[] values = JsonSerializer.Deserialize<Tenths[]>("[125,-35]", options)!;
Console.WriteLine(JsonSerializer.Serialize(values, options));
FormattableString text = $"temperature={values[0].Value / 10m:F1}";
var commaFormat = new NumberFormatInfo { NumberDecimalSeparator = "," };
Console.WriteLine(text.ToString(commaFormat));
Console.WriteLine(FormattableString.Invariant(text));
foreach (string bad in new[] { "\"125\"", "2147483648", "null" })
{
try
{
_ = JsonSerializer.Deserialize<Tenths>(bad, options);
throw new InvalidOperationException("Expected JsonException.");
}
catch (JsonException)
{
Console.WriteLine($"rejected: {bad}");
}
}
readonly record struct Tenths(int Value);
sealed class TenthsConverter : JsonConverter<Tenths>
{
public override Tenths Read(ref Utf8JsonReader reader, Type typeToConvert,
JsonSerializerOptions options)
{
if (reader.TokenType != JsonTokenType.Number || !reader.TryGetInt32(out int value))
throw new JsonException("Expected an Int32 JSON number.");
return new Tenths(value);
}
public override void Write(Utf8JsonWriter writer, Tenths value,
JsonSerializerOptions options) => writer.WriteNumberValue(value.Value);
}Résultat
[125,-35] temperature=12,5 temperature=12.5 rejected: "125" rejected: 2147483648 rejected: null
`Tenths` stocke la température en dixièmes de degré. Deux éléments mettent à l’épreuve la limite de lecture ; les chiffres entre guillemets, le dépassement de capacité et `null` sont rejetés. Le format explicite à virgule donne `temperature=12,5`, le format invariant `temperature=12.5`. Le JSON reste `[125,-35]`.
Leçons associées
- C# · Leçon 58 · Avancé · Version : 3
Sources
- How to write custom converters for JSON serialization
- How to use Utf8JsonReader in System.Text.Json
- Utf8JsonWriter Class (System.Text.Json)
- JsonTokenType Enum (System.Text.Json)
- Utf8JsonReader.TryGetInt32(Int32) Method (System.Text.Json)
- JsonException Class (System.Text.Json)
- FormattableString.Invariant(FormattableString) Method (System)
- String interpolation using $
- ref structure types (C# reference)
- How to use Utf8JsonWriter in System.Text.Json
- NumberFormatInfo Class (System.Globalization)