Skip to main content

Search OfficeIMO

Enter a topic, API type, or PowerShell command.

Documentation Search all OfficeIMO/

YAML Configuration Files in .NET

Edit on GitHub

Load appsettings.yaml into Microsoft.Extensions.Configuration with AddYamlFile: reload on change, merge keys, aliases and options binding.

Packages
Works with
  • .NET
Target frameworks
netstandard2.0, net8.0, net10.0, net472
Limits
One YAML document per file; a stream with several documents is rejected. Duplicate keys, including keys that differ only in case, are errors.
Verified
Examples compiled against the source on

OfficeIMO.Yaml.Configuration adds YAML files to Microsoft.Extensions.Configuration, so ASP.NET Core, the generic host and plain ConfigurationBuilder code read appsettings.yaml the way they read appsettings.json. It is a separate package because it depends on Microsoft.Extensions.Configuration.FileExtensions; OfficeIMO.Yaml itself stays dependency-free.

dotnet add package OfficeIMO.Yaml.Configuration

Add a YAML file

C#

using Microsoft.Extensions.Configuration;

var builder = WebApplication.CreateBuilder(args);
builder.Configuration
    .AddYamlFile("appsettings.yaml", optional: false, reloadOnChange: true)
    .AddYamlFile($"appsettings.{builder.Environment.EnvironmentName}.yaml", optional: true, reloadOnChange: true);
builder.Services.Configure<SmtpOptions>(builder.Configuration.GetSection("Smtp"));

AddYamlFile has the overloads of AddJsonFile: a path, optional, reloadOnChange, an IFileProvider, or an Action<YamlConfigurationSource> for every file-source setting. AddYamlStream(stream) reads YAML from a stream.

How keys and values map

defaults: &defaults
  Timeout: 30
  Retries: 3
Smtp:
  <<: *defaults
  Host: smtp.example.com
  UseTls: TRUE
  Recipients: [[email protected], [email protected]]
  ReplyTo: ~
KeyValue
Smtp:Hostsmtp.example.com
Smtp:Timeout30, from the merged defaults
Smtp:UseTlsTRUE, the file's spelling, which binds to bool
Smtp:Recipients:1[email protected]
Smtp:ReplyToempty string, as JSON null gives

Keys are case-insensitive and joined with :; sequence items use their zero-based index. Aliases and << merge keys resolve as in the document's resolved view, and the << key never appears. Empty collections are keys with a null value, as in the JSON provider.

Errors

Malformed YAML, duplicate keys, a root that is not a mapping and a stream with more than one document throw FormatException with the line; a file source wraps it in an InvalidDataException naming the file. The package README lists every rule and how to migrate from NetEscapades.Configuration.Yaml.

Example source