TomlSerializerOptions Class

Definition

Namespace

Bodu.Text.Toml

Assembly

Bodu.Text.Toml.dll

Package

Bodu.Text.Toml 1.0.0

Source

SerializerOptions.Resolution.cs

Configures how values are serialized to and deserialized from TOML: the converters to use, the property naming policy, the default ignore condition, and the maximum nesting depth.

public sealed class TomlSerializerOptions

Inheritance

object

TomlSerializerOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Examples

// Configure once and reuse across calls; resolved converters are cached on the instance.
var options = new TomlSerializerOptions
{
    PropertyNamingPolicy = NamingPolicy.SnakeCaseLower,
    DefaultIgnoreCondition = IgnoreCondition.WhenWritingDefault,
};
options.Converters.Add(new TomlStringEnumConverter(NamingPolicy.SnakeCaseLower, allowIntegerValues: false));

string text = TomlSerializer.Serialize(config, options);

Remarks

An options instance becomes read-only the first time it is used to serialize or deserialize a value; subsequent attempts to change a setting throw. Resolved converters and type metadata are cached on the instance, so reusing one configured options object across many operations is the efficient pattern.

DefaultIgnoreCondition governs when a member is omitted on write. Because TOML has no null token, a member whose value is null is omitted regardless of that setting.

Constructors

TomlSerializerOptions()

Initializes a new instance of the TomlSerializerOptions class with default (general-purpose) settings.

public TomlSerializerOptions()

TomlSerializerOptions(TomlSerializerDefaults)

Initializes a new instance of the TomlSerializerOptions class with a base set of defaults appropriate for the specified usage scenario.

public TomlSerializerOptions(TomlSerializerDefaults defaults)

Parameters

defaults TomlSerializerDefaults

The base defaults to apply.

Remarks

Web selects camel-case property naming and case-insensitive property-name matching; General leaves the defaults unchanged.

Exceptions

ArgumentOutOfRangeException

Thrown when defaults is not a defined TomlSerializerDefaults value.

Fields

DefaultMaxDepth

The default maximum container nesting depth applied when MaxDepth is left at zero. It is also the library's hard ceiling (Bodu.Text.Toml.TomlLimits.AbsoluteMaxDepth): a configured depth is never effective beyond this value, because the recursive reader, writer, and serializer must stay within a safe call-stack budget.

public const int DefaultMaxDepth = 64

Field Value

int

Properties

ByteArrayHandling

Gets or sets the representation used when writing a byte array.

public TomlByteArrayHandling ByteArrayHandling { get; set; }

Property Value

TomlByteArrayHandling

The byte-array handling; IntegerArray by default.

Remarks

The setting controls only how a byte array is written; on read the serializer accepts both an array of integers and a Base64 basic string regardless of this value.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined.

InvalidOperationException

Thrown when the options are read-only.

Converters

Gets the list of user-registered converters, consulted in order before the built-in converters.

public IList<TomlConverter> Converters { get; }

Property Value

IList<TomlConverter>

The mutable converter list while the options are mutable.

DecimalHandling

Gets or sets the representation used when writing a decimal value.

public TomlDecimalHandling DecimalHandling { get; set; }

Property Value

TomlDecimalHandling

The decimal handling; Float by default.

Remarks

The setting controls only how a decimal is written; on read the serializer accepts a TOML float, integer, or string regardless of this value. Float maps to TOML's native float form but loses precision beyond what an IEEE 754 binary64 value can hold; String preserves the value exactly at the cost of a quoted representation.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined.

InvalidOperationException

Thrown when the options are read-only.

DefaultIgnoreCondition

Gets or sets the default condition that determines when a member is omitted on write, applied to every member that does not carry its own IgnoreAttribute.

public IgnoreCondition DefaultIgnoreCondition { get; set; }

Property Value

IgnoreCondition

The default ignore condition; Never by default.

Remarks

Because TOML has no null token, a member whose value is null is omitted from the output regardless of this setting, so Never behaves like WhenWritingNull for null values specifically.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined, or when it is Always, which is not a valid default.

InvalidOperationException

Thrown when the options are read-only.

IncludeFields

Gets or sets a value indicating whether public fields are surfaced as serializable members alongside properties.

public bool IncludeFields { get; set; }

Property Value

bool

true to serialize and deserialize public fields; otherwise false. The default is false.

Remarks

A public field annotated with IncludeAttribute participates regardless of this setting. Fields honor the property naming policy, name and order attributes, ignore conditions, and required-member enforcement exactly like properties; a readonly field is written but never assigned on read.

Exceptions

InvalidOperationException

Thrown when the options are read-only.

IsReadOnly

Gets a value indicating whether the options have become read-only.

public bool IsReadOnly { get; }

Property Value

bool

true once the options have been used or frozen; otherwise false.

MaxDepth

Gets or sets the maximum container nesting depth permitted while serializing or deserializing.

public int MaxDepth { get; set; }

Property Value

int

The maximum depth; DefaultMaxDepth when set to zero.

Remarks

The limit bounds how deeply tables and arrays may nest. It is reached when serializing an object graph - or deserializing a document - whose containers nest more levels deep than the effective limit, for example a chain of objects each holding the next, a dictionary of dictionaries, or arrays within arrays. Crossing it is reported as a catchable failure: TomlSerializationException while serializing, or TomlFormatException while deserializing. A reference cycle (an object reachable from itself) is a distinct condition reported separately as a TomlSerializationException identifying the cycle, not as a depth-limit failure.

Although any non-negative value is accepted here, the effective limit is clamped to the library's hard ceiling, Bodu.Text.Toml.TomlLimits.AbsoluteMaxDepth (64); setting a larger value - even MaxValue - does not raise it. The ceiling exists because the serializer and parser recurse one call-stack frame per nested container, so an unbounded depth on hostile or malformed input would exhaust the call stack and terminate the process with an uncatchable StackOverflowException. Clamping converts that into the catchable exceptions above. Lowering this value below the default tightens the limit; raising it has no effect beyond the ceiling.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is negative.

InvalidOperationException

Thrown when the options are read-only.

PreferredObjectCreationHandling

Gets or sets the serializer-wide preference for whether a member's value is replaced with a freshly created instance or populated when reading, applied to every type and member that does not carry its own ObjectCreationHandlingAttribute.

public ObjectCreationHandling PreferredObjectCreationHandling { get; set; }

Property Value

ObjectCreationHandling

The preferred object-creation handling; Replace by default.

Remarks

Populate applies only to collection and dictionary members whose existing value is non-null; in every other case the serializer replaces the value.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined.

InvalidOperationException

Thrown when the options are read-only.

PropertyNameCaseInsensitive

Gets or sets a value indicating whether property-name matching ignores case when reading.

public bool PropertyNameCaseInsensitive { get; set; }

Property Value

bool

true to match case-insensitively; otherwise false. The default is false for general options and true under Web.

Exceptions

InvalidOperationException

Thrown when the options are read-only.

PropertyNamingPolicy

Gets or sets the policy that translates member names to their serialized dictionary-key form.

public NamingPolicy? PropertyNamingPolicy { get; set; }

Property Value

NamingPolicy

The naming policy, or null to use member names unchanged.

Exceptions

InvalidOperationException

Thrown when the options are read-only.

SpecVersion

Gets or sets the TOML specification version whose grammar is accepted when deserializing.

public TomlSpecVersion SpecVersion { get; set; }

Property Value

TomlSpecVersion

The specification version; V1_0 by default.

Remarks

The version affects only parsing; the writer always emits text that is valid under both supported versions.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined.

InvalidOperationException

Thrown when the options are read-only.

UnmappedMemberHandling

Gets or sets the serializer-wide handling for a dictionary key that maps to no member of the target type when reading, applied to every type that does not carry its own UnmappedMemberHandlingAttribute.

public UnmappedMemberHandling UnmappedMemberHandling { get; set; }

Property Value

UnmappedMemberHandling

The unmapped-member handling; Skip by default.

Remarks

A type that declares an extension-data member captures unmapped keys into that member, which takes precedence over this setting, so a key absorbed by extension data never triggers Disallow.

Exceptions

ArgumentOutOfRangeException

Thrown when the value is undefined.

InvalidOperationException

Thrown when the options are read-only.

Methods

GetConverter(Type)

Resolves the converter that handles the specified type, applying the type-level converter attribute, the registered converters, and finally the built-in converters, in that order.

[RequiresUnreferencedCode("TOML serialization and deserialization reflect over the serialized types and their members, which trimming may remove. Ensure the required types and members are preserved.")]
[RequiresDynamicCode("TOML serialization and deserialization construct converters for collection, dictionary, and nullable types at runtime, which native AOT cannot do without runtime code generation.")]
public TomlConverter GetConverter(Type typeToConvert)

Parameters

typeToConvert Type

The type to resolve a converter for.

Returns

TomlConverter

The concrete converter for the type.

Exceptions

ArgumentNullException

Thrown when typeToConvert is null.

NotSupportedException

Thrown when no converter handles the type.

MakeReadOnly()

Freezes the options so their settings can no longer change, capturing the converter list. Called automatically before the first serialization or deserialization.

public void MakeReadOnly()

Applies to

Product	Versions
.NET	8, 10