百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
T

Tomlyn

> 编程语言
开源

Tomlyn 是一个用于 .NET Framework 和 .NET Core 的 TOML 解析器、验证器和编写库。

584 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

Tomlyn 是一个用于 .NET Framework 和 .NET Core 的 TOML 解析器、验证器和编写库。

Tomlyn

Tomlyn is a high-performance .NET TOML 1.1 parser, round-trippable syntax tree, and System.Text.Json-style object serializer - NativeAOT ready.

Looking for YAML support? Check out SharpYaml.

Note: Tomlyn v1 is a major redesign with breaking changes from earlier versions. It uses a System.Text.Json-style API with TomlSerializer, TomlSerializerOptions, and resolver-based metadata (ITomlTypeInfoResolver). See the migration guide for details.

✨ Features

  • System.Text.Json-style API: familiar surface with TomlSerializer, TomlSerializerOptions, TomlTypeInfo
  • TOML 1.1.0 only: Tomlyn v1 targets TOML 1.1.0 and does not support TOML 1.0
  • Source generation: NativeAOT / trimming friendly via TomlSerializerContext and [TomlSerializable] roots
  • Cross-project polymorphism: register derived types at runtime or on a source-generated context when base and derived types live in different assemblies
  • System.Text.Json attribute interop: reuse [JsonPropertyName], [JsonIgnore], [JsonRequired], [JsonConstructor], [JsonObjectCreationHandling], and polymorphism attributes
  • Flexible collection input: opt a collection member into accepting either a single TOML value or an array via [TomlSingleOrArray]
  • TOML formatting attributes: opt members/types into table-array, inline-table, string, mapping-order, and dotted-key formatting policies
  • Allocation-free parsing pipeline: incremental TomlLexer → TomlParser with precise spans for errors
  • Low-level access: full lexer/parser API plus a lossless, trivia-preserving syntax tree (SyntaxParser → DocumentSyntax)
  • Reflection control: reflection-based POCO mapping is available, but can be disabled for NativeAOT via a feature switch / MSBuild property

Requirements

Tomlyn targets net8.0, net10.0, and netstandard2.0.

  • Consuming the NuGet package works on any runtime that supports netstandard2.0 (including .NET Framework) or modern .NET (net8.0+).
  • Building Tomlyn from source requires the .NET 10 SDK.

Install

bash
dotnet add package Tomlyn

Tomlyn ships the source generator in-package (analyzers/dotnet/cs) - no extra package needed.

Quick Start

csharp
using Tomlyn;

// Serialize
var toml = TomlSerializer.Serialize(new { Name = "Ada", Age = 37 });

// Deserialize
var person = TomlSerializer.Deserialize(toml);

Untyped model (TomlTable)

csharp
using Tomlyn;
using Tomlyn.Model;

var toml = @"global = ""this is a string""
# This is a comment of a table
[my_table]
key = 1 # Comment a key
value = true
list = [4, 5, 6]
";

var model = TomlSerializer.Deserialize(toml)!;
var global = (string)model["global"]!;

Console.WriteLine(global);
Console.WriteLine(TomlSerializer.Serialize(model));

POCO properties can also use TomlObject when a member should accept any TOML model container (TomlTable, TomlArray, or TomlTableArray). This works with both reflection-based serialization and source-generated TomlSerializerContext metadata.

Options

csharp
using System.Text.Json;
using Tomlyn;

var options = new TomlSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    PreferredObjectCreationHandling = JsonObjectCreationHandling.Replace,
    WriteIndented = true,
    IndentSize = 4,
    MaxDepth = 64,
    DefaultIgnoreCondition = TomlIgnoreCondition.WhenWritingNull,
};

var toml = TomlSerializer.Serialize(config, options);
var model = TomlSerializer.Deserialize(toml, options);

By default, PropertyNamingPolicy is null, meaning CLR member names are used as-is for TOML mapping keys (same default as System.Text.Json). MaxDepth = 0 uses the built-in default of 64. PreferredObjectCreationHandling = JsonObjectCreationHandling.Replace matches System.Text.Json: read-only properties are not populated unless you opt into Populate via options or [JsonObjectCreationHandling].

Source Generation

csharp
using System.Text.Json.Serialization;
using Tomlyn.Serialization;

public sealed class MyConfig
{
    public string? Global { get; set; }
}

[TomlSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    PreferredObjectCreationHandling = JsonObjectCreationHandling.Replace)]
[TomlSerializable(typeof(MyConfig))]
internal partial class MyTomlContext : TomlSerializerContext
{
}

var config = TomlSerializer.Deserialize(toml, MyTomlContext.Default.MyConfig);
var tomlOut = TomlSerializer.Serialize(config, MyTomlContext.Default.MyConfig);

Cross-Project Polymorphism

When a base type lives in one project and derived types live in another, you can register derived types without putting [TomlDerivedType] on the base type.

Reflection path:

csharp
using Tomlyn;

var options = new TomlSerializerOptions
{
    PolymorphismOptions = new TomlPolymorphismOptions
    {
        TypeDiscriminatorPropertyName = "kind",
        DerivedTypeMappings = new Dictionary>
        {
            [typeof(Animal)] =
            [
                new(typeof(Cat), "cat"),
                new(typeof(Dog), "dog"),
            ],
        },
    },
};

Source generation path:

csharp
using Tomlyn.Serialization;

[TomlSerializable(typeof(Animal))]
[TomlDerivedTypeMapping(typeof(Animal), typeof(Cat), "cat")]
[TomlDerivedTypeMapping(typeof(Animal), typeof(Dog), "dog")]
internal partial class MyTomlContext : TomlSerializerContext
{
}

Use TomlPolymorphismOptions.DerivedTypeMappings and [TomlDerivedTypeMapping] additively with existing base-type attributes. Base-type registrations still take precedence when the same discriminator or derived type is registered more than once.

Single Value Or Array Collections

csharp
using System.Text.Json.Serialization;
using Tomlyn.Serialization;

public sealed class PackagingConfiguration
{
    public PackagingConfiguration()
    {
        RuntimeIdentifiers = new List();
    }

    [TomlSingleOrArray]
    [JsonPropertyName("rid")]
    public List RuntimeIdentifiers { get; }
}

With [TomlSingleOrArray], both of these TOML payloads are valid:

toml
rid = "win-x64"
toml
rid = ["win-x64", "linux-x64"]

For mutable read-only collection members, Tomlyn appends into the existing collection instance. Without [TomlSingleOrArray], collection members still require a TOML array.

Reflection Control

Reflection fallback can be disabled globally before first serializer use:

csharp
AppContext.SetSwitch("Tomlyn.TomlSerializer.IsReflectionEnabledByDefault", false);

When publishing with NativeAOT (PublishAot=true), the Tomlyn NuGet package disables reflection-based serialization by default. You can override the default by setting the following MSBuild property in your app project:

xml

  true

Documentation

  • User guide
  • Website (Lunet): https://xoofx.github.io/Tomlyn

License

This software is released under the BSD-Clause 2 license.

Author

Alexandre Mutel aka xoofx.

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

C#csharpdotnetdotnet-coretoml

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言