KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / C#

JsonSerializerOptions — JSON lezen en schrijven configureren

System.Text.Json.JsonSerializerOptions bepaalt hoe .NET-objecten naar JSON worden omgezet en daaruit worden gelezen. Je kunt er eigenschapsnamen, opmerkingen, onbekende eigenschappen, getalverwerking en het weglaten van null-waarden mee instellen. Configureer een exemplaar vóór het eerste gebruik en hergebruik het daarna.

Versie: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Syntax

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, ReadCommentHandling = JsonCommentHandling.Skip, UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, NumberHandling = JsonNumberHandling.AllowReadingFromString, DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull };
var value = JsonSerializer.Deserialize<T>(json, options);
string result = JsonSerializer.Serialize(value, options);

System.Text.Json.JsonSerializerOptions levert configuratie voor JsonSerializer.Serialize en JsonSerializer.Deserialize. Het voorbeeld is bedoeld voor .NET 10; UnmappedMemberHandling is beschikbaar vanaf .NET 8. Er is geen previewtaalfunctie nodig. new JsonSerializerOptions() zonder verdere instellingen behoudt eigenschapsnamen, maakt bij het lezen onderscheid tussen hoofdletters en kleine letters en gebruikt strikte getalverwerking; standaardinstellingen voor webtoepassingen kunnen anders zijn.

JsonNamingPolicy staat voor een regel om namen om te zetten. PropertyNamingPolicy = JsonNamingPolicy.CamelCase zet ItemCount bij zowel schrijven als lezen om naar itemCount. Dit schakelt hoofdletterongevoelige vergelijking niet in: gebruik daarvoor PropertyNameCaseInsensitive. Een [JsonPropertyName]-attribuut heeft voorrang op de regel.

ReadCommentHandling gebruikt JsonCommentHandling: de standaardwaarde Disallow wijst opmerkingen af, terwijl Skip ze accepteert en negeert. De op readers gerichte waarde Allow wordt niet ondersteund door deze serializeroptie. UnmappedMemberHandling gebruikt JsonUnmappedMemberHandling: de standaardwaarde Skip negeert niet-toegewezen JSON-eigenschappen, tenzij ze als uitbreidingsgegevens worden opgevangen. Als voor een type Disallow geldt, leidt een niet-toegewezen JSON-eigenschap tot een JsonException. Een typespecifieke configuratie kan de instelling in de serializeropties overschrijven. Als Disallow alleen in de opties is ingesteld, kan een lid met het attribuut [JsonExtensionData] de niet-toegewezen eigenschappen opvangen zonder dat er een uitzondering wordt gegenereerd. Deze instelling vereist niet dat elke modeleigenschap in de invoer aanwezig is.

NumberHandling gebruikt de flags van JsonNumberHandling. De standaardwaarde Strict vereist getaltokens; AllowReadingFromString staat ook toe om "3" als getal te lezen, maar schrijft het nog steeds als 3. De aparte flag WriteAsString schrijft getallen tussen aanhalingstekens. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull laat eigenschappen met de waarde null weg bij het schrijven; 0 en false worden niet weggelaten en het lezen van null wordt niet verhinderd.

Configureer de opties vóór de eerste serialisatie of deserialisatie: daarna wordt het exemplaar onveranderlijk. Hergebruik het om de metadatacaches te behouden; delen tussen threads is veilig. Het voorbeeld slaat een opmerking over, leest een getal tussen aanhalingstekens en schrijft het object zonder Note. Bij het deserialiseren van het voorbeeldtype Payload zou een niet-toegewezen JSON-eigenschap een JsonException veroorzaken.

Voorbeelden

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

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    ReadCommentHandling = JsonCommentHandling.Skip,
    UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,
    NumberHandling = JsonNumberHandling.AllowReadingFromString,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

const string json = "{ /* input */ \"itemCount\": \"3\", \"note\": null }";
var value = JsonSerializer.Deserialize<Payload>(json, options)
    ?? throw new InvalidOperationException();
Console.WriteLine(JsonSerializer.Serialize(value, options));

public sealed class Payload
{
    public int ItemCount { get; set; }
    public string? Note { get; set; }
}

Resultaat

{"itemCount":3}

De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.

Bronnen