CKTIS / C#
JsonSerializerOptions — konfigurace čtení a zápisu JSON
System.Text.Json.JsonSerializerOptions řídí převod objektů .NET na JSON a jejich čtení z JSON. Umožňuje nastavit názvy vlastností, komentáře, neznámé vlastnosti, zpracování čísel a vynechávání hodnot null. Instanci nastavte před prvním použitím a při dalších operacích ji znovu používejte.
Verze: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Syntaxe
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 předává konfiguraci metodám JsonSerializer.Serialize a JsonSerializer.Deserialize. Příklad cílí na .NET 10; UnmappedMemberHandling je dostupné od .NET 8. Není potřeba žádná jazyková funkce ve verzi preview. Prosté new JsonSerializerOptions() zachovává názvy vlastností, při čtení rozlišuje velká a malá písmena a používá striktní zpracování čísel; výchozí nastavení webových aplikací se může lišit.
JsonNamingPolicy představuje pravidlo pro převod názvů. PropertyNamingPolicy = JsonNamingPolicy.CamelCase převádí ItemCount na itemCount při zápisu i čtení. Nezapíná porovnávání bez rozlišení velikosti písmen: k tomu slouží PropertyNameCaseInsensitive. Atribut [JsonPropertyName] má před tímto pravidlem přednost.
ReadCommentHandling používá JsonCommentHandling: výchozí hodnota Disallow komentáře odmítá, zatímco Skip je přijímá a ignoruje. Hodnota Allow, určená pro reader, není touto možností serializátoru podporována. UnmappedMemberHandling používá JsonUnmappedMemberHandling: výchozí hodnota Skip ignoruje nenamapované vlastnosti JSON, pokud se nezachytí jako rozšiřující data. Pokud pro daný typ platí Disallow, nenamapovaná vlastnost JSON vyvolá výjimku JsonException. Konfigurace konkrétního typu může mít přednost před nastavením v možnostech serializátoru. Pokud je Disallow nastaveno pouze v možnostech, člen označený atributem [JsonExtensionData] může nenamapované vlastnosti zachytit, aniž by došlo k výjimce. Toto nastavení nevyžaduje, aby ve vstupu byla každá vlastnost modelu.
NumberHandling používá příznaky JsonNumberHandling. Výchozí hodnota Strict vyžaduje číselné tokeny; AllowReadingFromString navíc dovoluje přečíst "3" jako číslo, ale při zápisu se stále použije 3. Samostatný příznak WriteAsString zapisuje čísla v uvozovkách. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull při zápisu vynechá vlastnosti s hodnotou null; nevynechává 0 ani false a nebrání čtení null.
Možnosti nastavte před první serializací nebo deserializací: poté se instance stane neměnnou. Znovu ji používejte, abyste zachovali její mezipaměti metadat; sdílení mezi vlákny je bezpečné. Příklad přeskočí komentář, přečte číslo v uvozovkách a zapíše objekt bez Note. Při deserializaci typu Payload z příkladu by nenamapovaná vlastnost JSON vyvolala výjimku JsonException.
Příklady
#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; }
}
Výsledek
{"itemCount":3}Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.
Zdroje
- .NET API browser
- JsonSerializerOptions Class
- How to instantiate JsonSerializerOptions instances with System.Text.Json
- How to customize property names and values with System.Text.Json
- JsonSerializerOptions.ReadCommentHandling Property
- Handle unmapped members during deserialization
- JsonNumberHandling Enum
- JsonIgnoreCondition Enum