| 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
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.