YamlDotNet实现YAML文档内省与修改保留原始格式

在YAML文档处理过程中，开发者经常需要既能读取文档内容又能保留原始格式特性（如标量样式、序列样式和注释）。本文将介绍如何使用YamlDotNet库实现类似System.Text.Json.JsonDocument的功能，实现对YAML文档的内省和格式保留式修改。

核心概念

YAML文档内省指的是在不丢失原始文档结构信息的情况下解析文档，包括：

• 保留注释信息
• 维持标量样式（单引号/双引号/普通样式）
• 保持序列样式（块式/流式）

实现方案

YamlDotNet通过YamlStream和节点树模型提供了完整的文档内省能力。以下是典型实现流程：

1. 文档加载阶段

var yamlContent = await File.ReadAllTextAsync(inputPath);
using var stringReader = new StringReader(yamlContent);
var yamlStream = new YamlStream();
yamlStream.Load(stringReader);

2. 文档内省处理 获取文档根节点后，可以遍历整个节点树进行内容检查：

var yamlDocument = yamlStream.Documents[0];
var rootNode = (YamlMappingNode)yamlDocument.RootNode;
foreach (var child in rootNode.Children)
{
    Console.WriteLine($"Key: {child.Key}, Value: {child.Value}");
}

3. 保留格式的修改 直接操作节点树而非反序列化为对象模型，可以最大程度保留原始格式：

rootNode.Children["name"] = new YamlScalarNode("TEST");

4. 序列化回写 使用SerializerBuilder配置序列化选项，保持格式一致性：

var serializer = new SerializerBuilder()
    .WithIndentedSequences()
    .Build();
await using var output = new StringWriter();
serializer.Serialize(output, rootNode);

最佳实践

1. 异常处理：始终对文件IO和YAML解析进行try-catch处理
2. 资源释放：确保StringReader和StringWriter正确关闭
3. 格式控制：
   • 使用WithIndentedSequences()保持序列缩进
   • 通过EmitDefaults()控制空值输出
4. 注释保留：虽然示例代码未展示，但可通过自定义事件处理器实现注释保留

高级技巧

对于需要深度保留原始格式的场景，可以考虑：

1. 继承YamlVisitor实现自定义访问器，记录原始格式信息
2. 在修改节点时，复制原始节点的样式属性
3. 使用YamlDocument的TagDirectives属性处理自定义标签

总结

YamlDotNet通过节点树模型提供了完整的YAML内省能力，相比直接反序列化为POCO对象，这种方式虽然代码量稍多，但提供了更精细的文档控制能力。开发者可以根据具体需求选择合适的方式，在需要严格保留原始格式的场景下，节点树操作是最可靠的选择。

通过本文介绍的方法，开发者可以实现YAML文档的安全修改，同时保持原始文档的格式特性，满足配置管理等需要精确控制文档输出的场景需求。