tomlyn

name	tomlyn
description	how to use Tomlyn for serialization and deserialization of TOML files in C#

Tomlyn is a high-performance TOML 1.1 library for .NET, shaped like System.Text.Json. It provides two main layers:

• Object serialization - TomlSerializer maps TOML documents to .NET objects (POCOs, records, dictionaries) and back. Supports reflection and source generation. Does not preserve comments or formatting.
• Low-level parsing - TomlLexer, TomlParser, and SyntaxParser provide token streams, incremental events, and a full-fidelity syntax tree for tooling, analyzers, and formatters that need to preserve every character.

Where to start

Scenario	Start here
New to Tomlyn	Getting started
Familiar with System.Text.Json	Serialization - the API shape is intentionally similar
Need NativeAOT / trimming	Source generation
Want a dynamic model (no POCOs)	DOM model - TomlTable, TomlArray
Building tooling (formatters, analyzers)	Low-level APIs - SyntaxParser
Migrating from Tomlyn v0.x	Migration guide

Key concepts

[!IMPORTANT] Tomlyn v1 targets TOML 1.1.0 only. It does not support TOML 1.0 or earlier drafts. See the official TOML v1.1.0 specification for the full language reference.

• Diagnostics - parsing and mapping failures throw TomlException with precise source locations (Line, Column, Offset, Span).
• Immutable options - TomlSerializerOptions is a sealed record; cache and reuse instances.
• NativeAOT / trimming - use source generation (TomlSerializerContext) to avoid reflection. Reflection can be disabled via a feature switch.