Options

Pass a TomlSerializerOptions to Serialize, Deserialize and TryDeserialize:

var options = new TomlSerializerOptions
{
    PropertyNamingPolicy = TomlNamingPolicy.SnakeCaseLower,
    PreferredObjectCreationHandling = TomlObjectCreationHandling.Replace,
    WriteIndented = true,
    IndentSize = 4,
    MaxDepth = 64,
    DefaultIgnoreCondition = TomlIgnoreCondition.WhenWritingNull,
};

var config = new ServerConfig { Host = "example.com" };
var toml = TomlSerializer.Serialize(config, options);
Assert.Equal("""
    host = "example.com"
    port = 8080

    """, toml);

TomlSerializerOptions is an immutable record: use a with expression to derive an instance from another one. It caches the metadata of your types on first use, so create an instance once, for example in a static readonly field, and reuse it.

With the source generator, set the options with [TomlSourceGenerationOptions] on the context instead: see Source generation.

Name the keys

The naming policies are TomlNamingPolicy.CamelCase, PascalCase, SnakeCaseLower, SnakeCaseUpper, KebabCaseLower and KebabCaseUpper. To write your own, derive from TomlNamingPolicy. [TomlPropertyName] sets the key of one member and wins over the policy.

Choose what is written

TOML has no null: a null member that is not skipped throws a TomlException. [TomlIgnore(Condition = ...)] overrides DefaultIgnoreCondition for one member, including with Never.

Choose how strict reading is

RespectNullableAnnotations applies before DefaultIgnoreCondition: a null in a non-nullable member throws instead of being skipped, unless the member itself has [TomlIgnore(Condition = TomlIgnoreCondition.WhenWritingNull)] or WhenWritingDefault.

For the limits to set for files you don't trust, see Handling errors.

Layout of the output

Declaration order lists the members of the base types first, then, in each type, the fields and then the properties.

DottedKeyHandling does not change reading: with Expand, the keys are read back as nested tables, so such a model does not round-trip. The keys of a TomlTable are always written as they are.

String styles

StringStylePreferences sets how strings are written:

• DefaultStyle: Basic ("text", the default), Literal ('text'), MultilineBasic or MultilineLiteral.
• PreferLiteralWhenNoEscapes: writes a literal string when the value needs no escape.
• AllowHexEscapes: escapes control characters with the TOML 1.1 \e and \xHH instead of \uXXXX. TOML 1.0 readers reject them; see TOML 1.0 and 1.1.

Formatting attributes

Attributes set the layout of one type or member. They only change how values are written:

[TomlMappingOrder(TomlMappingOrderPolicy.Alphabetical)]
[TomlDottedKeyHandling(TomlDottedKeyHandling.Expand)]
public sealed class FormattedConfig
{
    [TomlTableArrayStyle(TomlTableArrayStyle.Headers)]
    public Package[] Package { get; set; } = [];

    [TomlInlineTable(TomlInlineTablePolicy.Always)]
    public Owner Owner { get; set; } = new();

    [TomlStringStyle(TomlStringStyle.Literal, PreferLiteralWhenNoEscapes = TomlBooleanPreference.True)]
    public string Description { get; set; } = "plain text";
}

public sealed class Owner
{
    public string Name { get; set; } = "";
}

var toml = TomlSerializer.Serialize(new FormattedConfig
{
    Package = [new Package { Name = "core" }],
    Owner = new Owner { Name = "Ada" },
});

Assert.Equal("""
    Description = 'plain text'
    Owner = {Name = "Ada"}
    [[Package]]
    Name = "core"

    """, toml);

Other options

options.GetTypeInfo<T>() returns the metadata the options resolve for a type, from the converters, the TypeInfoResolver, the built-in types or reflection. TryGetTypeInfo<T>() returns false when there is none.