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