CKTIS / C#
Własne konwertery JSON: tokeny, błędy i formatowanie niezależne od kultury
Zaimplementuj konwerter, który odczytuje i zapisuje dokładnie jedną wartość JSON, zgłasza błędne dane i formatuje tekst niezależnie od bieżącej kultury.
Wersja: C# 12 and .NET 8; later runtimes may add compatible features
Składnia
// 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}")W C# 12 i .NET 8 JsonConverter<T> z System.Text.Json.Serialization definiuje sposób odczytu i zapisu jednego T. Utf8JsonReader, Utf8JsonWriter, JsonTokenType i JsonException należą do System.Text.Json. Czytnik przechodzi przez tokeny UTF-8 tylko do przodu; TokenType wskazuje rodzaj tokenu jako wartość wyliczenia JsonTokenType. Number to nie to samo co String zawierający cyfry.
Read dostaje czytnik ustawiony na pierwszym tokenie wartości. Dla wartości skalarnej zwróć wynik bez wywołania reader.Read(); dla obiektu lub tablicy zatrzymaj się na odpowiadającym EndObject lub EndArray. Zbyt wczesne zatrzymanie lub odczyt za daleko narusza kontrakt konwertera. Czytnik to mutowalny ref struct: przekazuj go przez ref, gdy postęp ma być widoczny u wywołującego. W C# 12 nie deklaruj go jako zmiennej lokalnej w metodzie async; nie używaj też widoków bajtów tokenu po zwróceniu bufora do puli.
Sprawdź Number przed TryGetInt32(out int value): dla innego rodzaju tokenu metoda rzuca InvalidOperationException, a dla liczby, której nie da się odczytać jako int, zwraca false. Operator || pomija prawą stronę, gdy lewa jest prawdziwa. Dla niepoprawnych danych rzuć JsonException; serializator może uzupełnić Path, LineNumber i BytePositionInLine. Domyślnie token Null trafia przy odczycie do konwertera typu wartościowego niedopuszczającego null; dla typów referencyjnych i Nullable<T> serializator zwykle sam obsługuje null, chyba że konwerter ustawi HandleNull na true.
Write zapisuje dokładnie jedną wartość przy użyciu przekazanego writera, bez zwalniania go. WriteNumberValue(int) emituje liczbę bez cudzysłowów. WriteStringValue(string?) zapisuje ciąg znaków inny niż null w cudzysłowie i stosuje reguły ucieczki znaków JSON, a dla argumentu null zapisuje literał JSON null bez cudzysłowów. Nie składaj JSON-u przez interpolację ani nie wyłączaj walidacji, aby przepuścić niezaufane dane.
System.FormattableString.Invariant(FormattableString) zwraca string z argumentami sformatowanymi według kultury niezmiennej. Przekaż interpolację bezpośrednio albo zachowaj ją jako FormattableString; gotowego string nie da się tak ponownie sformatować. F1 daje jedno miejsce po separatorze dziesiętnym, tu 12.5. To formatowanie tekstu, nie serializacja JSON ani mechanizm ucieczki znaków.
Przykłady
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);
}Wynik
[125,-35] temperature=12,5 temperature=12.5 rejected: "125" rejected: 2147483648 rejected: null
`Tenths` przechowuje temperaturę w dziesiątych częściach stopnia. Dwa elementy sprawdzają granice odczytu; liczba w cudzysłowie, przepełnienie i `null` są odrzucane. Jawny format z przecinkiem daje `temperature=12,5`, a format niezmienny `temperature=12.5`. JSON pozostaje `[125,-35]`.
Powiązane lekcje
- C# · Lekcja 58 · Zaawansowany · Wersja: 3
Źródła
- 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)