# YAML Configuration Files in .NET

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

**Packages**

- [OfficeIMO.Yaml.Configuration](https://www.nuget.org/packages/OfficeIMO.Yaml.Configuration) `dotnet add package OfficeIMO.Yaml.Configuration`

**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 2026-11-15

`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.

```sh
dotnet add package OfficeIMO.Yaml.Configuration
```

## Add a YAML file

### C#

```csharp
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

```yaml
defaults: &defaults
  Timeout: 30
  Retries: 3
Smtp:
  <<: *defaults
  Host: smtp.example.com
  UseTls: TRUE
  Recipients: [ops@example.com, audit@example.com]
  ReplyTo: ~
```

| Key | Value |
| --- | --- |
| `Smtp:Host` | `smtp.example.com` |
| `Smtp:Timeout` | `30`, from the merged `defaults` |
| `Smtp:UseTls` | `TRUE`, the file's spelling, which binds to `bool` |
| `Smtp:Recipients:1` | `audit@example.com` |
| `Smtp:ReplyTo` | empty 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](https://github.com/EvotecIT/OfficeIMO/blob/master/OfficeIMO.Yaml.Configuration/README.md) lists every rule and how to migrate from NetEscapades.Configuration.Yaml.

<!-- PowerForge markdown artifact sha256:D91FC3BBF9BCFADBAF6114B7185796B929C63E226BB3A02657ABDCA38B12DE2E -->
