CKTIS / C#
JsonSerializerOptions — konfiguracja odczytu i zapisu JSON
System.Text.Json.JsonSerializerOptions określa sposób mapowania obiektów .NET na JSON i odwrotnie. Pozwala ustawić nazwy właściwości, obsługę komentarzy, nieznanych pól i liczb oraz pomijanie null. Skonfiguruj instancję przed pierwszym użyciem i używaj jej ponownie.
Wersja: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Składnia
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 przekazuje konfigurację do JsonSerializer.Serialize i JsonSerializer.Deserialize. Przykład jest przeznaczony dla .NET 10; UnmappedMemberHandling jest dostępne od .NET 8. Nie wymaga funkcji języka w wersji preview. Zwykłe new JsonSerializerOptions() zachowuje nazwy właściwości, rozróżnia wielkość liter przy odczycie i stosuje ścisłą obsługę liczb; ustawienia aplikacji internetowych mogą być inne.
JsonNamingPolicy opisuje regułę przekształcania nazw. PropertyNamingPolicy = JsonNamingPolicy.CamelCase mapuje ItemCount na itemCount przy zapisie i odczycie. Nie włącza dopasowania bez rozróżniania wielkości liter: służy do tego PropertyNameCaseInsensitive. Atrybut [JsonPropertyName] ma pierwszeństwo przed regułą.
ReadCommentHandling korzysta z JsonCommentHandling: domyślne Disallow odrzuca komentarze, a Skip je akceptuje i pomija. Wartość Allow, przeznaczona dla czytnika, nie jest obsługiwana przez tę opcję serializatora. UnmappedMemberHandling korzysta z JsonUnmappedMemberHandling: domyślne Skip ignoruje niezamapowane właściwości JSON, o ile nie zostaną przechwycone jako dane rozszerzenia. Jeśli dla danego typu obowiązuje Disallow, niezamapowana właściwość JSON powoduje JsonException. Konfiguracja typu może mieć pierwszeństwo przed ustawieniem w opcjach serializatora. Jeśli Disallow ustawiono tylko w opcjach, składowa oznaczona atrybutem [JsonExtensionData] może przechwycić niezamapowane właściwości zamiast zgłaszania wyjątku. Ustawienie to nie oznacza, że wszystkie właściwości modelu muszą wystąpić w danych wejściowych.
NumberHandling używa flag JsonNumberHandling. Domyślne Strict wymaga tokenów liczbowych; AllowReadingFromString pozwala także odczytać "3" jako liczbę, ale nadal zapisuje ją jako 3. Osobne WriteAsString zapisuje liczby w cudzysłowach. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull pomija właściwości o wartości null podczas zapisu; nie pomija 0 ani false i nie blokuje odczytu null.
Skonfiguruj opcje przed pierwszą serializacją lub deserializacją: potem instancja staje się niemodyfikowalna. Używaj jej ponownie, aby zachować pamięć podręczną metadanych; współdzielenie między wątkami jest bezpieczne. Przykład pomija komentarz, odczytuje liczbę w cudzysłowach i zapisuje obiekt bez Note. Przy odczycie przykładowego typu Payload niezamapowana właściwość JSON spowodowałaby JsonException.
Przykłady
#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; }
}
Wynik
{"itemCount":3}Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.
Źródła
- .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