Skip to main content

Search OfficeIMO

Enter a topic, API type, or PowerShell command.

Documentation Search all OfficeIMO/

TOML Configuration Files in .NET

Edit on GitHub

Load appsettings.toml into Microsoft.Extensions.Configuration with AddTomlFile: reload on change, arrays of tables and ISO 8601 date-times.

Packages
Works with
  • .NET
Target frameworks
netstandard2.0, net8.0, net10.0, net472
Limits
Keys that differ only in case are rejected, because configuration keys are case-insensitive while TOML keys are not.
Verified
Examples compiled against the source on

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

dotnet add package OfficeIMO.Toml.Configuration

Add a TOML file

C#

using Microsoft.Extensions.Configuration;

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

AddTomlFile has the overloads of AddJsonFile: a path, optional, reloadOnChange, an IFileProvider, or an Action<TomlConfigurationSource> for every file-source setting. AddTomlStream(stream) reads TOML from a stream.

How keys and values map

[Smtp]
Host = "smtp.example.com"
Port = 0x24B
Retry = { Count = 3, Delay = "00:00:05" }
Since = 2024-05-01 08:30:00Z

[[Smtp.Relays]]
Host = "relay-1.example.com"
KeyValue
Smtp:Hostsmtp.example.com
Smtp:Port587: hexadecimal, octal, binary and _-grouped integers become decimals
Smtp:Retry:Count3: inline tables and dotted keys flatten like [tables]
Smtp:Since2024-05-01T08:30:00Z, ISO 8601, which binds to DateTimeOffset
Smtp:Relays:0:Hostrelay-1.example.com: arrays of tables use indexes

Keys are case-insensitive and joined with :. Floats keep their spelling, and inf and nan become Infinity and NaN. Empty arrays and tables are keys with a null value, as in the JSON provider.

Errors

Malformed TOML and duplicate keys throw FormatException with the line and column; keys that differ only in case are rejected with their line. A file source wraps the exception in an InvalidDataException naming the file. The package README lists every rule and how to migrate from Tomlyn.Extensions.Configuration.

Example source