Baza znanjaIzpitno središče
SLSlovenščina
Izberi jezik13

CKTIS / C#

Dvosmerni pretvorniki JSON: branje, pisanje in preverjanje žetonov

Ustvari pretvornik System.Text.Json, ki prebere in zapiše en objekt JSON, zavrne neveljavne žetone ter izrecno uporabi imena v camelCase in izpuščanje vrednosti null.

Različica: C# 12 and .NET 8; later runtimes may add compatible features

Sintaksa

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 in .NET 8 JsonConverter<T> iz System.Text.Json.Serialization določa obe smeri pretvorbe. Registriraj ga v options.Converters. Utf8JsonReader, Utf8JsonWriter, JsonTokenType in JsonException so v System.Text.Json. Bralnik se po vhodu UTF-8 pomika samo naprej. Je spremenljiv ref struct: podaj ga z ref, da premakneš izvirni kazalec in ne njegove kopije, in ga ne shrani v polje razreda.

Metoda Read pretvornika začne na prvem žetonu vrednosti. Pri objektu preveri StartObject, preberi lastnosti in se vrni s kazalcem na pripadajočem EndObject, ne za njim. Enako pravilo velja za tabele; pri skalarni vrednosti ostani na njenem žetonu. reader.TokenType vrne člana naštevanja JsonTokenType; preveri ga pred pridobivanjem vrednosti. Number ne zagotavlja, da je število mogoče predstaviti z int, zato uporabi TryGetInt32. Pri nezdružljivem vhodu sproži JsonException; serializator lahko dopolni Path, LineNumber in BytePositionInLine. Tudi prekratko branje ali branje čez konec vrednosti lahko sproži JsonException.

Write zapiše natanko eno popolno vrednost s posredovanim Utf8JsonWriter; na njem ne kliči Dispose ali Flush. Serializator uporabi PropertyNamingPolicy = JsonNamingPolicy.CamelCase in DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull za lastnosti, ki jih sam upravlja, ne pa za ročne klice zapisovalnika. Primer izračuna ista imena v obeh smereh in izpusti celotne lastnosti z vrednostjo null samo pri WhenWritingNull; 0 še vedno zapiše. Razlikuje med velikimi in malimi črkami, zavrača neznana in podvojena imena ter izvaja pravili izpuščanja Never in WhenWritingNull, ne vseh nastavitev serializatorja.

string? je oznaka za analizo vrednosti null v prevajalniku, ne nov tip med izvajanjem ali preverjanje JSON. int? je ločen vrednostni tip Nullable<int>, ki predstavlja celo število ali odsotnost vrednosti. Serializator privzeto obravnava vrednosti null za referenčne tipe in Nullable<T>, ne da bi poklical njihov pretvornik. Če jih mora obravnavati pretvornik sam, prepiši HandleNull, da vrne true. Izpuščanje lastnosti je ločeno: WhenWritingNull velja samo pri pisanju, pogodba pa določa, ali branje sprejme manjkajoče lastnosti ali izrecni JSON null. Tukaj sta obe obliki dovoljeni za Note in Rank, ne pa za DisplayName.

Primeri

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

Rezultat

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

Prva vrstica izpusti obe lastnosti z vrednostjo null, druga obe zapiše kot null, tretja pa po branju ohrani rank z vrednostjo 0. Število namesto besedila v displayName sproži JsonException.

Povezane lekcije

  • C# · Lekcija 39 · Napredna · Različica: 3

Viri