Soenneker.Utils.Yaml 11.0.255

Soenneker.Utils.Yaml

YAML serialization, typed and untyped deserialization, JSON conversion, validation, normalization, and file conversion through YamlDotNet.

Installation

dotnet add package Soenneker.Utils.Yaml

Registration

using Soenneker.Utils.Yaml.Registrars;

services.AddYamlUtilAsSingleton();

Use AddYamlUtilAsScoped() when a scoped lifetime is preferred. The serializer and deserializer are shared static instances; the utility instance primarily supplies file access.

Serialize and deserialize

string yaml = yamlUtil.ToYaml(new
{
    DisplayName = "Ada",
    RetryCount = 3
});

Settings? settings = yamlUtil.FromYaml<Settings>(yaml);
object? graph = yamlUtil.FromYaml(yaml);

Serialization uses camel-case member names. ToYaml(null) returns an empty string. Typed and untyped deserialization return default/null for blank input; malformed or incompatible YAML otherwise throws.

Typed deserialization also uses camel-case naming, attempts to infer types for unquoted scalars, and ignores YAML properties that do not exist on the target type. If rejecting unknown fields matters, validate the input separately before binding.

Convert YAML and JSON

string yaml = yamlUtil.JsonToYaml(json);
string json = yamlUtil.YamlToJson(yaml);

Blank JSON becomes an empty YAML string. Blank YAML becomes {}. Invalid input propagates parser or serializer exceptions.

YAML mappings can have non-string keys, aliases, and recursive object graphs that JSON cannot represent directly. During YAML-to-JSON conversion:

• mapping keys are converted with ToString() and collisions overwrite earlier values;
• sequences become JSON arrays;
• recursive references become null;
• repeated non-recursive aliases are expanded as repeated values.

YamlToJson(yaml, options) uses caller-supplied JsonSerializerOptions. The overload without options uses the package's web-oriented System.Text.Json configuration.

Both YamlToJson overloads validate the normalized YAML as a single document. Duplicate mapping keys, additional documents, and deserialization recursion beyond 128 levels throw. Scalar repair and indentation normalization still apply before parsing. The same checks apply to SaveAsJson, which calls YamlToJson.

FixForJson normalizes YAML, converts its object graph to a JSON-safe shape, and serializes the result back to YAML. It can therefore change scalar types, mapping-key representation, and alias structure; it is not a text-only cleanup. The stricter document checks described above apply to YamlToJson, not FixForJson.

Validate and try-deserialize

bool syntaxIsValid = yamlUtil.IsValidYaml(yaml);
bool bound = yamlUtil.TryFromYaml<Settings>(yaml, out Settings? settings);

IsValidYaml returns whether non-blank input can be deserialized as an untyped YAML value. Most plain text is valid YAML, so this is not schema or business validation. TryFromYaml<T> returns false and default when deserialization throws.

Normalize indentation and line endings

string normalized = yamlUtil.Normalize(yaml);

Normalize and FixTabsInIndentation remove a leading BOM, convert CRLF or CR line endings to LF, and replace each tab encountered in leading indentation with two spaces. Tabs inside scalar content are preserved. These methods do not parse or reformat the YAML and return an empty string for blank input.

Convert files

await yamlUtil.SaveAsYaml("settings.json", "settings.yaml", cancellationToken: cancellationToken);
await yamlUtil.SaveAsJson("settings.yaml", "settings.json", cancellationToken: cancellationToken);

File conversion reads the complete source, converts it in memory, and writes the destination through IFileUtil. The destination write is not transactional; use a temporary destination and replace the target after validation when partial or failed conversions must not overwrite an existing file.

YamlToJson and SaveAsJson enforce a 128-level deserialization recursion limit. Other operations retain the underlying parsers' limits; no operation adds an input-size or alias-count limit.