Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / C#

Vlastní převodníky JSON: hranice hodnot, chyby a invariantní formátování

Napište převodník, který čte a zapisuje právě jednu hodnotu JSON, odmítá nekompatibilní vstup a odděluje invariantní formátování textu od kódování JSON.

Verze: 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}")

V C# 12 a .NET 8 určuje JsonConverter<T> z System.Text.Json.Serialization, jak číst a zapisovat jednu hodnotu typu T. Utf8JsonReader, Utf8JsonWriter, JsonTokenType a JsonException patří do System.Text.Json. Čtečka postupuje tokeny JSON v UTF-8 pouze vpřed; TokenType udává druh tokenu hodnotou výčtu JsonTokenType. Number není totéž co String obsahující číslice.

Při vstupu do Read je čtečka na prvním tokenu hodnoty. U skaláru vraťte výsledek bez volání reader.Read(); u objektu či pole zastavte na odpovídajícím EndObject či EndArray. Předčasné zastavení nebo čtení za hranici hodnoty porušuje kontrakt. Čtečka je měnitelný ref struct: předejte ji pomocí ref, pokud má volající vidět posun. V C# 12 ji nedeklarujte jako lokální proměnnou v metodě async a nepoužívejte pohledy na bajty tokenů po vrácení jejich vyrovnávací paměti do fondu.

Před TryGetInt32(out int value) ověřte Number: u jiného druhu tokenu metoda vyvolá InvalidOperationException, zatímco u čísla, které nelze přečíst jako int, vrátí false. Operátor || nevyhodnotí pravý operand, je-li levý pravdivý. Při nekompatibilním vstupu vyvolejte JsonException; serializátor může doplnit Path, LineNumber a BytePositionInLine. Při čtení převodník pro hodnotový typ nepřipouštějící null standardně dostane Null; u referenčních typů a Nullable<T> obvykle obsluhuje null sám serializátor, pokud převodník nenastaví HandleNull na true.

Write zapíše právě jednu hodnotu předaným zapisovačem a neuvolňuje ho. WriteNumberValue(int) zapíše číslo bez uvozovek. WriteStringValue(string?) zapíše řetězec, který není null, do uvozovek a ošetří speciální znaky podle pravidel JSON. Je-li argument null, zapíše literál JSON null bez uvozovek. Nesestavujte JSON interpolací a nevypínejte validaci, abyste propustili nedůvěryhodný vstup.

System.FormattableString.Invariant(FormattableString) vrací string s argumenty naformátovanými podle invariantní kultury. Předejte interpolaci přímo nebo ji uchovejte jako FormattableString; hotový string takto přeformátovat nelze. F1 dává jedno desetinné místo, zde 12.5. Jde o formátování textu, nikoli o serializaci JSON či ošetření speciálních znaků.

Příklady

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

Výsledek

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

`Tenths` ukládá teplotu v desetinách stupně. Dva prvky prověřují hranici čtení; číslice v uvozovkách, přetečení a `null` se odmítnou. Výslovně zadaný formát s čárkou dává `temperature=12,5`, invariantní formát `temperature=12.5`. JSON zůstává `[125,-35]`.

Související lekce

  • C# · Lekce 58 · Pokročilá · Verze: 3

Zdroje