Znalostná bázaCentrum skúšok
SKSlovenčina
Vybrať jazyk13

CKTIS / C#

Obojsmerný konvertor JSON: čítanie, zápis a overovanie tokenov

Vytvor konvertor System.Text.Json, ktorý číta a zapisuje jeden objekt JSON, odmieta neplatné tokeny a výslovne uplatňuje názvy v camelCase a vynechávanie hodnôt null.

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

Syntax

using System.Text.Json;
using System.Text.Json.Serialization;

// Members of JsonConverter<T>:
public abstract T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options);
public abstract void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options);

// Inspect reader.TokenType (a JsonTokenType) before reading a value.
// Reject incompatible input with new JsonException("Expected a JSON string.").

V C# 12 a .NET 8 definuje JsonConverter<T> z System.Text.Json.Serialization oba smery konverzie. Zaregistruj ho v options.Converters. Utf8JsonReader, Utf8JsonWriter, JsonTokenType a JsonException patria do System.Text.Json. Čítačka prechádza vstupom v UTF-8 iba dopredu. Je to meniteľný ref struct: odovzdávaj ho cez ref, aby si posúval pôvodný kurzor, nie jeho kópiu. Neukladaj ho do poľa triedy.

Metóda Read konvertora začína na prvom tokene hodnoty. Pri objekte over StartObject, prečítaj vlastnosti a vráť sa s kurzorom na zodpovedajúcom EndObject, nie za ním. Rovnaké pravidlo platí pre polia; pri skalárnej hodnote zostaň na jej tokene. reader.TokenType vracia člena výčtu JsonTokenType; over ho pred načítaním hodnoty. Number nezaručuje, že sa číslo zmestí do int, preto použi TryGetInt32. Pri nekompatibilnom vstupe vyhoď JsonException; serializátor môže doplniť Path, LineNumber a BytePositionInLine. Predčasné ukončenie čítania alebo čítanie za koniec hodnoty môže tiež vyvolať JsonException.

Write zapíše presne jednu úplnú hodnotu dodaným Utf8JsonWriter; nevolaj na ňom Dispose ani Flush. Serializátor uplatňuje PropertyNamingPolicy = JsonNamingPolicy.CamelCase a DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull na vlastnosti, ktoré sám spravuje, nie na ručné volania zapisovača. Príklad odvodzuje rovnaké názvy v oboch smeroch a vynecháva celé vlastnosti s hodnotou null iba pri WhenWritingNull; 0 sa zapíše. Rozlišuje veľké a malé písmená, odmieta neznáme a duplicitné názvy a implementuje pravidlá vynechávania Never a WhenWritingNull, nie všetky nastavenia serializátora.

string? je anotácia pre analýzu hodnôt null kompilátorom, nie nový typ za behu ani overovanie JSON. int? je samostatný hodnotový typ Nullable<int>, ktorý predstavuje celé číslo alebo neprítomnosť hodnoty. Serializátor štandardne spracúva hodnoty null pre referenčné typy a Nullable<T> bez volania ich konvertora. Ak ich má spracovať sám konvertor, prepíš HandleNull tak, aby vracalo true. Vynechávanie vlastností je samostatná vec: WhenWritingNull ovplyvňuje len zápis a kontrakt určuje, či čítanie pripúšťa chýbajúce vlastnosti alebo explicitné JSON null. Tu sú obe formy povolené pre Note a Rank, ale nie pre DisplayName.

Príklady

#nullable enable
using System;
using System.Collections.Generic;
using System.Text.Json;
using System.Text.Json.Serialization;

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
options.Converters.Add(new ProfileCardConverter());

var card = new ProfileCard("Ada", null, null);
Console.WriteLine(JsonSerializer.Serialize(card, options));
var keepNulls = new JsonSerializerOptions(options)
{
    DefaultIgnoreCondition = JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(card, keepNulls));

var read = JsonSerializer.Deserialize<ProfileCard>(
    """{"displayName":"Ada","note":null,"rank":0}""", options)
    ?? throw new JsonException("Expected a non-null profile card.");
Console.WriteLine(JsonSerializer.Serialize(read, options));

try
{
    _ = JsonSerializer.Deserialize<ProfileCard>("""{"displayName":42}""", options);
}
catch (JsonException)
{
    Console.WriteLine("Rejected: JsonException");
}

sealed record ProfileCard(string DisplayName, string? Note, int? Rank);

sealed class ProfileCardConverter : JsonConverter<ProfileCard>
{
    private static string Name(JsonSerializerOptions options, string clrName) =>
        options.PropertyNamingPolicy?.ConvertName(clrName) ?? clrName;

    public override ProfileCard Read(ref Utf8JsonReader reader, Type typeToConvert,
        JsonSerializerOptions options)
    {
        if (reader.TokenType != JsonTokenType.StartObject)
            throw new JsonException("Expected an object.");

        string displayNameKey = Name(options, nameof(ProfileCard.DisplayName));
        string noteKey = Name(options, nameof(ProfileCard.Note));
        string rankKey = Name(options, nameof(ProfileCard.Rank));
        var seen = new HashSet<string>(StringComparer.Ordinal);
        string? displayName = null;
        string? note = null;
        int? rank = null;

        while (reader.Read())
        {
            if (reader.TokenType == JsonTokenType.EndObject)
                return new ProfileCard(
                    displayName ?? throw new JsonException("Missing display name."), note, rank);

            if (reader.TokenType != JsonTokenType.PropertyName)
                throw new JsonException("Expected a property name.");
            string key = reader.GetString() ?? throw new JsonException("Missing property name.");
            if (!seen.Add(key))
                throw new JsonException("Duplicate property.");
            if (!reader.Read())
                throw new JsonException("Missing property value.");

            if (key == displayNameKey && reader.TokenType == JsonTokenType.String)
                displayName = reader.GetString();
            else if (key == noteKey && reader.TokenType is JsonTokenType.String or JsonTokenType.Null)
                note = reader.GetString();
            else if (key == rankKey && reader.TokenType == JsonTokenType.Null)
                rank = null;
            else if (key == rankKey && reader.TokenType == JsonTokenType.Number &&
                     reader.TryGetInt32(out int number))
                rank = number;
            else
                throw new JsonException("Unknown property or invalid value.");
        }

        throw new JsonException("Expected the end of the object.");
    }

    public override void Write(Utf8JsonWriter writer, ProfileCard value, JsonSerializerOptions options)
    {
        bool omitNulls = options.DefaultIgnoreCondition == JsonIgnoreCondition.WhenWritingNull;
        writer.WriteStartObject();
        writer.WriteString(Name(options, nameof(ProfileCard.DisplayName)), value.DisplayName);
        if (value.Note is not null || !omitNulls)
            writer.WriteString(Name(options, nameof(ProfileCard.Note)), value.Note);
        if (value.Rank is int rank)
            writer.WriteNumber(Name(options, nameof(ProfileCard.Rank)), rank);
        else if (!omitNulls)
            writer.WriteNull(Name(options, nameof(ProfileCard.Rank)));
        writer.WriteEndObject();
    }
}

Výsledok

{"displayName":"Ada"}
{"displayName":"Ada","note":null,"rank":null}
{"displayName":"Ada","rank":0}
Rejected: JsonException

Prvý riadok vynechá obe vlastnosti s hodnotou null, druhý ich obe zapíše ako null a tretí po prečítaní zachová hodnotu rank rovnú 0. Číslo namiesto textu v displayName vyvolá JsonException.

Súvisiace lekcie

  • C# · Lekcia 39 · Pokročilá · Verzia: 3

Zdroje