Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / C#

JsonSerializerOptions — configuring JSON reading and writing

System.Text.Json.JsonSerializerOptions controls how .NET objects map to JSON and back. Configure property naming, comments, unknown properties, number handling, and omission of null values. Set up an instance before its first use and reuse it for subsequent operations.

Version: .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 supplies configuration to JsonSerializer.Serialize and JsonSerializer.Deserialize. The example targets .NET 10; UnmappedMemberHandling is available starting in .NET 8. No preview language feature is required. Plain new JsonSerializerOptions() preserves property names, matches case-sensitively when reading, and uses strict number handling; web application defaults can differ.

JsonNamingPolicy represents a name conversion rule. PropertyNamingPolicy = JsonNamingPolicy.CamelCase maps ItemCount to itemCount for both writing and reading. It does not enable case-insensitive matching: use PropertyNameCaseInsensitive for that. A [JsonPropertyName] attribute takes precedence over the policy.

ReadCommentHandling uses JsonCommentHandling: the default Disallow rejects comments, while Skip accepts and ignores them. The reader-oriented Allow value is not supported by this serializer option. UnmappedMemberHandling uses JsonUnmappedMemberHandling: the default Skip ignores unmapped JSON properties unless they are captured as extension data. If the effective setting for a type is Disallow, an unmapped JSON property causes a JsonException. Per-type configuration can override the options-level setting. If Disallow is set only on the options, a member marked with [JsonExtensionData] can capture otherwise unmapped properties instead of an exception being thrown. This setting does not require every model property to appear in the input.

NumberHandling uses the JsonNumberHandling flags. The default Strict requires number tokens; AllowReadingFromString also permits reading "3" as a number but still writes it as 3. The separate WriteAsString flag writes numbers in quotes. DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull omits null-valued properties when writing; it does not omit 0 or false or prevent reading null.

Configure options before the first serialization or deserialization: the instance becomes immutable afterward. Reuse it to retain its metadata caches; sharing it across threads is safe. The example skips a comment, reads a quoted number, and writes the object without Note. An unmapped JSON property would cause a JsonException when deserializing the example's Payload.

Examples

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

Result

{"itemCount":3}

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources