KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / C#

Eigen JSON-converters: tokengrenzen, fouten en cultuuronafhankelijke opmaak

Implementeer een converter die precies één JSON-waarde leest en schrijft, ongeldige invoer afwijst en cultuuronafhankelijke tekstopmaak scheidt van JSON-codering.

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

Syntax

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

In C# 12 en .NET 8 bepaalt JsonConverter<T> uit System.Text.Json.Serialization hoe je één waarde van het type T leest en schrijft. Utf8JsonReader, Utf8JsonWriter, JsonTokenType en JsonException staan in System.Text.Json. De reader doorloopt UTF-8-JSON-tokens alleen voorwaarts; TokenType geeft het soort token als een waarde van de enum JsonTokenType. Een Number is niet hetzelfde als een String met cijfers.

Bij het begin van Read staat de reader op het eerste token van de waarde. Geef voor een scalaire waarde het resultaat terug zonder reader.Read() aan te roepen; stop voor een object of array op het bijbehorende EndObject of EndArray. Te vroeg stoppen of te ver doorgaan schendt het contract. De reader is een veranderlijke ref struct: geef hem met ref door als de aanroeper de voortgang moet zien. Declareer hem in C# 12 niet als lokale variabele in een async-methode en gebruik geen views op tokenbytes nadat hun buffer aan een pool is teruggegeven.

Controleer Number vóór TryGetInt32(out int value): de methode gooit InvalidOperationException bij een ander soort token en retourneert false als ze het getal niet als int kan lezen. || slaat de rechteroperand over als de linker waar is. Gooi bij ongeschikte invoer JsonException; de serializer kan Path, LineNumber en BytePositionInLine invullen. Standaard ontvangt een converter voor een niet-nullbaar waardetype bij het lezen Null; voor referentietypen en Nullable<T> handelt de serializer null normaal zelf af, tenzij de converter HandleNull op true zet.

Write schrijft precies één waarde met de meegegeven writer, zonder die vrij te geven. WriteNumberValue(int) schrijft een getal zonder aanhalingstekens. WriteStringValue(string?) schrijft een tekenreeks die niet null is tussen aanhalingstekens en past de JSON-escaperegels toe. Is het argument null, dan schrijft de methode de JSON-literal null zonder aanhalingstekens. Stel geen JSON samen met interpolatie en schakel validatie niet uit om onbetrouwbare invoer door te laten.

System.FormattableString.Invariant(FormattableString) retourneert een string met argumenten die volgens de invariante cultuur zijn opgemaakt. Geef de interpolatie direct door of bewaar haar als FormattableString; een al opgemaakte string kun je zo niet opnieuw opmaken. F1 geeft één decimaal, hier 12.5. Dit is tekstopmaak, geen JSON-serialisatie of escaping.

Voorbeelden

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);
}

Resultaat

[125,-35]
temperature=12,5
temperature=12.5
rejected: "125"
rejected: 2147483648
rejected: null

`Tenths` bewaart de temperatuur in tienden van een graad. Twee elementen testen de leesgrens; cijfers tussen aanhalingstekens, overloop en `null` worden afgewezen. De expliciete kommaopmaak geeft `temperature=12,5`; de invariante opmaak geeft `temperature=12.5`. De JSON blijft `[125,-35]`.

Gerelateerde lessen

  • C# · Les 58 · Gevorderd · Versie: 3

Bronnen