Tomlyn是C#生态中唯一活跃维护、纯托管且支持.NET Standard 2.0+的TOML解析器；需严格匹配类型，推荐用TomlTable动态读取或POCO强绑定，注意语法错误多源于TOML文件本身。
用 Tomlyn 读取 TOML 文件最稳
目前 C# 生态里，Tomlyn 是唯一活跃维护、支持 .NET Standard 2.0+ 且不依赖原生库的纯托管 TOML 解析器。别碰 Tomlet（已归档）或手写正则——TOML 的表嵌套、数组混类型、注释位置等细节很容易翻车。
安装：dotnet add package Tomlyn
读取示例：
var toml = File.ReadAllText("app.toml");
var model = Toml.Parse<config>(toml);
// Config 是你定义的 POCO，字段名需与 TOML key 匹配（默认忽略大小写）</config>
- 字段必须是 public，且有 getter/setter；只读属性或
init-only 不被识别 - 嵌套表会自动映射为嵌套类，但数组里的对象必须类型一致，否则
Parse抛TomlException - 如果 TOML 里有
version = "1.2.3"，而你的Config.Version是int，解析直接失败——类型必须严格匹配或可隐式转换
Tomlyn 写入时注意键名转义和空值处理
Tomlyn 没有直接的“序列化到文件”方法，得先构造成 TomlTable，再调用 ToString() 输出字符串。手动拼接容易丢格式、漏引号、错缩进。
正确写法：
var table = new TomlTable();
table.Add("title", "My App");
table.Add("debug", true);
table.Add("ports", new TomlArray { 8080, 8443 });
File.WriteAllText("config.toml", table.ToString());
- key 含空格、点号或连字符（如
api.url）会被自动加引号，不用自己处理 -
null值不会写入输出——TOML 本身不支持 null，所以table.Add("log_path", null)等价于没加这一项 - 数组元素类型必须统一：不能混写
new TomlArray { "a", 123 }，会抛ArgumentException
遇到 TomlException: Expected '=' 别急着改代码
这个错误几乎全是 TOML 文件本身语法问题，不是 C# 层面的 bug。常见触发点：
- 行尾多了一个冒号：
database: # 错！TOML 用 =，不是 : - 字符串没闭合：
name = "Alice（缺右引号） - 注释出现在键值对中间：
timeout = 30 # sec是合法的，但timeout # comment = 30就非法 - 用制表符缩进表（
[server]下的字段），而 TOML 只认空格缩进——部分编辑器会把空格转成 tab，肉眼难辨
建议用 VS Code 装 TOML Language Support 插件实时校验，比在 C# 里捕获异常再排查快得多。
需要动态读取任意 key？别硬映射，用 Toml.Parse 返回 TomlTable
当配置结构不固定（比如插件系统要读用户自定义字段），强绑定 POCO 反而添麻烦。直接解析成树形结构更灵活：
var root = Toml.Parse(File.ReadAllText("plugin.toml"));
var timeout = root.Get("network")?.Get("timeout")?.AsInteger() ?? 30;
var features = root.Get("features")?.AsArray()?.Select(x => x.AsString()).ToArray();
-
Get(string)返回ITomlNode，安全链式调用，不存在的 key 返回null -
AsString()/AsInteger()等方法在类型不匹配时返回default（不是抛异常），适合宽松场景 - 注意：
AsArray()对非数组节点返回null，不是空数组——这点和 JSON 库习惯不同，容易漏判
真正麻烦的是跨层级的类型推导：比如 [[users]] 数组里每个 item 是表，但某个字段可能有时是字符串、有时是表（TOML 允许同 key 多次出现形成数组），这种就得手动遍历 ITomlNode.Children 判断节点类型，没法靠一行 AsXxx() 解决。
