OfficeIMO.Yaml.Configuration
3.6.2
Prefix Reserved
dotnet add package OfficeIMO.Yaml.Configuration --version 3.6.2
NuGet\Install-Package OfficeIMO.Yaml.Configuration -Version 3.6.2
<PackageReference Include="OfficeIMO.Yaml.Configuration" Version="3.6.2" />
<PackageVersion Include="OfficeIMO.Yaml.Configuration" Version="3.6.2" />
<PackageReference Include="OfficeIMO.Yaml.Configuration" />
paket add OfficeIMO.Yaml.Configuration --version 3.6.2
#r "nuget: OfficeIMO.Yaml.Configuration, 3.6.2"
#:package OfficeIMO.Yaml.Configuration@3.6.2
#addin nuget:?package=OfficeIMO.Yaml.Configuration&version=3.6.2
#tool nuget:?package=OfficeIMO.Yaml.Configuration&version=3.6.2
OfficeIMO.Yaml.Configuration
A YAML configuration provider for Microsoft.Extensions.Configuration, built on the OfficeIMO.Yaml engine. It targets .NET Standard 2.0, .NET Framework 4.7.2, .NET 8 and .NET 10, works in trimmed and NativeAOT applications, and depends only on OfficeIMO.Yaml and Microsoft.Extensions.Configuration.FileExtensions.
Install
dotnet add package OfficeIMO.Yaml.Configuration
Usage
using Microsoft.Extensions.Configuration;
IConfiguration configuration = new ConfigurationBuilder()
.SetBasePath(AppContext.BaseDirectory)
.AddYamlFile("appsettings.yaml", optional: false, reloadOnChange: true)
.AddYamlFile($"appsettings.{environment}.yaml", optional: true)
.Build();
string? level = configuration["Logging:LogLevel:Default"];
In ASP.NET Core and the generic host, add the file to the host's builder and bind sections as usual:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddYamlFile("appsettings.yaml", optional: true, reloadOnChange: true);
builder.Services.Configure<SmtpOptions>(builder.Configuration.GetSection("Smtp"));
Logging:
LogLevel:
Default: Information
Microsoft.AspNetCore: Warning
Smtp:
Host: smtp.example.com
Port: 587
Recipients:
- ops@example.com
- audit@example.com
The methods match the JSON provider's:
| Method | Reads |
|---|---|
AddYamlFile(path), AddYamlFile(path, optional), AddYamlFile(path, optional, reloadOnChange) |
A file relative to the builder's base path |
AddYamlFile(IFileProvider?, path, optional, reloadOnChange) |
A file from a file provider |
AddYamlFile(Action<YamlConfigurationSource>) |
A file, with every FileConfigurationSource setting (ReloadDelay, OnLoadException, ...) |
AddYamlStream(stream) |
A stream, read once when the configuration is built |
YamlConfigurationSource, YamlConfigurationProvider, YamlStreamConfigurationSource and YamlStreamConfigurationProvider are in the OfficeIMO.Yaml.Configuration namespace; the extension methods are in Microsoft.Extensions.Configuration.
How YAML becomes configuration
- Keys are flattened with
:, and sequence items use their zero-based index, as the JSON provider does:Smtp:Recipients:1isaudit@example.com. Keys are case-insensitive. - Scalars keep their decoded text, whatever their quoting or block style. A file's
TRUEstaysTRUEand0x1Fstays0x1F; the binder readsTRUEas abool. Timestamps such as2024-05-01T08:30:00Zbind toDateTimeandDateTimeOffset. - Nulls (
null,~or no value) become empty strings, as JSONnulldoes. A quoted"null"is the textnull. - Empty collections (
[],{}) are keys with anullvalue, as in the JSON provider. - Aliases read the anchored node, and merge keys (
<<: *defaults,<<: [*a, *b]) apply as in the document's resolved view: a mapping's own keys win, then the merged mappings in order. The<<key itself never appears. Merge keys work under the default Core schema and in%YAML 1.1documents. - One document per file. A stream with several documents (
---between them) is rejected with aFormatExceptionthat gives the line of the second document, because configuration has one set of keys and silently dropping the rest would hide settings. A single document may still start with---or end with.... A file that is empty or holds only comments adds no keys. - The root must be a mapping. A root sequence or scalar is a
FormatException.
Errors
The provider throws FormatException for input it cannot map; a file provider reports it as an InvalidDataException naming the file, with the FormatException as its inner exception, as the JSON provider does.
- Malformed YAML: the message gives the line and column, and the inner
YamlExceptioncarriesLine,Columnand a stableCode. - Duplicate keys, including keys that differ only in case and paths such as
a:bwritten both as a key and as nested mappings:A duplicate key 'Server:Port' was found at line 3. - Collection keys (
[a, b]: x) and merge keys whose value is not a mapping, with their line.
Files are loaded with the engine's default limits (nesting depth 256, 100,000 alias-expanded nodes per document), which bound alias expansion without rejecting normal configuration.
Migrating from NetEscapades.Configuration.Yaml
- Replace the package:
dotnet remove package NetEscapades.Configuration.Yaml, thendotnet add package OfficeIMO.Yaml.Configuration. - Calls to
AddYamlFilekeep compiling: the overloads and theMicrosoft.Extensions.Configurationnamespace are the same. Code that namesYamlConfigurationSourceorYamlConfigurationProviderdirectly changesusing NetEscapades.Configuration.Yaml;tousing OfficeIMO.Yaml.Configuration;. - Check the files against the rules above:
- YAML nulls are empty strings here, matching the JSON provider. Code that tested a value for
nullto detectkey: ~sees"". - A file with several documents is an error, rather than only its first document being read.
<<merge keys are resolved instead of appearing as a key named<<.- Keys that differ only in case in one mapping are an error.
- YAML nulls are empty strings here, matching the JSON provider. Code that tested a value for
NativeAOT and trimming
The provider uses no reflection. OfficeIMO.Yaml.AotSmoke reads configuration through it in a NativeAOT executable. Binding to options classes goes through Microsoft.Extensions.Configuration.Binder, whose source generator (EnableConfigurationBindingGenerator) covers trimmed and NativeAOT applications.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 is compatible. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 4.7.2
- Microsoft.Extensions.Configuration.FileExtensions (>= 8.0.1)
- OfficeIMO.Yaml (>= 3.6.2)
-
.NETStandard 2.0
- Microsoft.Extensions.Configuration.FileExtensions (>= 8.0.1)
- OfficeIMO.Yaml (>= 3.6.2)
-
net10.0
- Microsoft.Extensions.Configuration.FileExtensions (>= 8.0.1)
- OfficeIMO.Yaml (>= 3.6.2)
-
net8.0
- Microsoft.Extensions.Configuration.FileExtensions (>= 8.0.1)
- OfficeIMO.Yaml (>= 3.6.2)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 3.6.2 | 49 | 11/18/2026 |