CKTIS / C#
Vlastné konvertory JSON: hranice hodnôt, chyby a invariantné formátovanie
Napíšte konvertor, ktorý číta a zapisuje presne jednu hodnotu JSON, odmieta nekompatibilný vstup a oddeľuje invariantné formátovanie textu od kódovania JSON.
Verzia: 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}")V C# 12 a .NET 8 určuje JsonConverter<T> z System.Text.Json.Serialization, ako čítať a zapisovať jednu hodnotu typu T. Utf8JsonReader, Utf8JsonWriter, JsonTokenType a JsonException patria do System.Text.Json. Čítačka prechádza tokenmi JSON v UTF-8 iba dopredu; TokenType označuje druh tokenu hodnotou výčtu JsonTokenType. Number nie je to isté ako String obsahujúci číslice.
Pri vstupe do Read stojí čítačka na prvom tokene hodnoty. Pri skalári vráťte výsledok bez volania reader.Read(); pri objekte alebo poli zastavte na príslušnom EndObject alebo EndArray. Predčasné zastavenie alebo čítanie za hranicou hodnoty porušuje kontrakt. Čítačka je meniteľný ref struct: odovzdajte ju cez ref, ak má volajúci vidieť jej posun. V C# 12 ju nedeklarujte ako lokálnu premennú v metóde async a nepoužívajte pohľady na bajty tokenov po vrátení ich vyrovnávacej pamäte do fondu.
Pred TryGetInt32(out int value) overte Number: pri inom druhu tokenu metóda vyvolá InvalidOperationException, pri čísle, ktoré nedokáže prečítať ako int, vráti false. Operátor || nevyhodnocuje pravý operand, ak je ľavý pravdivý. Pri nekompatibilnom vstupe vyvolajte JsonException; serializátor môže doplniť Path, LineNumber a BytePositionInLine. Pri čítaní konvertor hodnotového typu, ktorý nepripúšťa null, predvolene dostane Null; pri referenčných typoch a Nullable<T> sa o null obvykle postará serializátor, pokiaľ konvertor nenastaví HandleNull na true.
Write zapíše presne jednu hodnotu odovzdaným zapisovačom bez toho, aby ho uvoľnil. WriteNumberValue(int) zapíše číslo bez úvodzoviek. WriteStringValue(string?) zapíše reťazec, ktorý nie je null, do úvodzoviek a ošetrí špeciálne znaky podľa pravidiel JSON. Ak je argument null, zapíše literál JSON null bez úvodzoviek. Neskladajte JSON interpoláciou ani nevypínajte validáciu, aby ste prepustili nedôveryhodný vstup.
System.FormattableString.Invariant(FormattableString) vráti string s argumentmi naformátovanými podľa invariantnej kultúry. Odovzdajte interpoláciu priamo alebo ju uchovajte ako FormattableString; hotový string takto nemožno preformátovať. F1 dá jedno desatinné miesto, tu 12.5. Je to formátovanie textu, nie serializácia JSON ani ošetrovanie špeciálnych znakov.
Prí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ýsledok
[125,-35] temperature=12,5 temperature=12.5 rejected: "125" rejected: 2147483648 rejected: null
`Tenths` ukladá teplotu v desatinách stupňa. Dva prvky preverujú hranicu čítania; číslice v úvodzovkách, pretečenie a `null` sa odmietnu. Výslovne zadaný formát s čiarkou dá `temperature=12,5`, invariantný formát dá `temperature=12.5`. JSON zostáva `[125,-35]`.
Súvisiace lekcie
- C# · Lekcia 58 · Pokročilá · Verzia: 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)