Keep extra plugin settings when you change a known field. This preserves values, not comments or layout.
dotnet add package OneYamlTargets .NET 8 and .NET 10 (used in the download).
using System; using System.Collections.Generic; using OneYaml; var plugin = YamlSerializer.Deserialize<Plugin>(""" name: lint level: strict paths: [src, tests] """)!; plugin.Name = "check"; Console.Write( YamlSerializer.Serialize(plugin)); class Plugin { public string Name { get; set; } = ""; [YamlExtensionData] public Dictionary<string, object?> Extras { get; set; } = []; }
Unzip the example, then dotnet run.
The name changes to check; level and paths stay in the output.
name: check level: strict paths: - src - tests
The full program
The download writes two YAML documents, separated by ---: first with the captured level, then with level changed to warn. A duplicate key in the input is a YamlException, not an extra setting.
using System; using System.Collections.Generic; using OneYaml; var plugin = YamlSerializer.Deserialize<Plugin>(""" name: lint level: strict paths: [src, tests] """)!; plugin.Name = "check"; Console.WriteLine("# After changing the name"); Console.Write( YamlSerializer.Serialize(plugin)); plugin.Extras["level"] = "warn"; Console.WriteLine("--- # After changing the level"); Console.Write( YamlSerializer.Serialize(plugin)); class Plugin { public string Name { get; set; } = ""; [YamlExtensionData] public Dictionary<string, object?> Extras { get; set; } = []; }
dotnet run prints:
# After changing the name name: check level: strict paths: - src - tests --- # After changing the level name: check level: warn paths: - src - tests
Variations
Drop one extra setting. To remove paths while keeping level, replace the Console.Write in the snippet at the top with:
plugin.Extras.Remove("paths"); Console.Write( YamlSerializer.Serialize(plugin));
name: check level: strict
Related recipes
The short answer
Put [YamlExtensionData] on a Dictionary<string, object?> property. When you call Deserialize<Plugin>, OneYaml binds name to Name and collects the other keys in the dictionary. After you change Name, Serialize writes those keys back at the same mapping level. There’s no extras: wrapper.
How do I deserialize YAML with known and unknown fields?
Give the fields you expect their own typed properties. In the example, Name is a string, so code that uses it doesn’t need to inspect a dictionary. The remaining fields are extension data: keys that belong to the plugin configuration but not to the current C# model. OneYaml also supports IDictionary<string, object?> for the extension member. The extension data guide shows the same arrangement.
Inspect the dictionary when you need one of the extras. The entries aren’t all strings: in this recipe level is a string, but paths is a List<object?> of two strings. Nested mappings become dictionaries. The untyped values guide lists the other possible values, including booleans and integers. If you promote a setting to a typed property later, it becomes a known key when you read the file with the new model.
What happens to unmapped YAML fields when I write the file back?
Without an extension data member, OneYaml skips unmatched keys by default, so a read-and-write can drop settings the application doesn’t know about. The dictionary keeps those settings in the object so they can be written later. The output has level: strict and both paths even though the C# class has no Level or Paths property.
This is a value round trip, not a text round trip. Notice how the inline list [src, tests] comes back as a list on separate lines, and how the known property is written before the extra settings. Use the in-place editing API instead if the task is to edit a hand-maintained file while keeping its comments and layout.