Tomlyn is a high-performance TOML 1.1 library for .NET, shaped like System.Text.Json.
It provides two main layers:
TomlSerializer maps TOML documents to .NET objects (POCOs, records, dictionaries) and back.
Supports reflection and source generation. Does not preserve comments or formatting.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.| 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 |
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.
TomlException with precise source locations (Line, Column, Offset, Span).TomlSerializerOptions is a sealed record; cache and reuse instances.TomlSerializerContext) to avoid reflection. Reflection can be disabled via a feature switch.