OfficeIMO.Toml.Configuration
3.6.2
Prefix Reserved
dotnet add package OfficeIMO.Toml.Configuration --version 3.6.2
NuGet\Install-Package OfficeIMO.Toml.Configuration -Version 3.6.2
<PackageReference Include="OfficeIMO.Toml.Configuration" Version="3.6.2" />
<PackageVersion Include="OfficeIMO.Toml.Configuration" Version="3.6.2" />
<PackageReference Include="OfficeIMO.Toml.Configuration" />
paket add OfficeIMO.Toml.Configuration --version 3.6.2
#r "nuget: OfficeIMO.Toml.Configuration, 3.6.2"
#:package OfficeIMO.Toml.Configuration@3.6.2
#addin nuget:?package=OfficeIMO.Toml.Configuration&version=3.6.2
#tool nuget:?package=OfficeIMO.Toml.Configuration&version=3.6.2
OfficeIMO.Toml.Configuration
A TOML configuration provider for Microsoft.Extensions.Configuration, built on the OfficeIMO.Toml engine. It reads TOML 1.1, 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.Toml and Microsoft.Extensions.Configuration.FileExtensions.
Install
dotnet add package OfficeIMO.Toml.Configuration
Usage
using Microsoft.Extensions.Configuration;
IConfiguration configuration = new ConfigurationBuilder()
.SetBasePath(AppContext.BaseDirectory)
.AddTomlFile("appsettings.toml", optional: false, reloadOnChange: true)
.AddTomlFile($"appsettings.{environment}.toml", optional: true)
.Build();
int port = int.Parse(configuration["Smtp:Port"]!);
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.AddTomlFile("appsettings.toml", 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"]
[[Smtp.Relays]]
Host = "relay-1.example.com"
[[Smtp.Relays]]
Host = "relay-2.example.com"
The methods match the JSON provider's:
| Method | Reads |
|---|---|
AddTomlFile(path), AddTomlFile(path, optional), AddTomlFile(path, optional, reloadOnChange) |
A file relative to the builder's base path |
AddTomlFile(IFileProvider?, path, optional, reloadOnChange) |
A file from a file provider |
AddTomlFile(Action<TomlConfigurationSource>) |
A file, with every FileConfigurationSource setting (ReloadDelay, OnLoadException, ...) |
AddTomlStream(stream) |
A stream, read once when the configuration is built |
TomlConfigurationSource, TomlConfigurationProvider, TomlStreamConfigurationSource and TomlStreamConfigurationProvider are in the OfficeIMO.Toml.Configuration namespace; the extension methods are in Microsoft.Extensions.Configuration.
How TOML becomes configuration
- Keys are flattened with
:, and the items of arrays and arrays of tables use their zero-based index:Smtp:Recipients:1andSmtp:Relays:0:Host. Keys are case-insensitive. - Tables flatten the same way however the file writes them:
[a.b]headers, dotted keys (a.b.c = 1) and inline tables (a = { b = { c = 1 } }) all givea:b:c. - Strings keep their decoded text, from any of the four quoting styles.
- Integers keep their decimal spelling; hexadecimal, octal, binary,
+-signed and_-grouped integers are written as invariant decimals (0xFFis255,1_000is1000), so they bind to numeric types. - Floats keep their spelling (
3.0,6.626e-34) unless it has_or a leading+, which are written as invariant round-trip text.inf,-infandnanbecomeInfinity,-InfinityandNaN, whichdoubleparses. - Booleans are
trueandfalse. - Date-times are ISO 8601 with a
T, whatever the file's separator:1979-05-27T07:32:00.5-07:00binds toDateTimeOffsetandDateTime, a local date1979-05-27toDateTime, and a local time07:32:00toTimeSpan. - Empty arrays, tables and array-of-tables items are keys with a
nullvalue, as in the JSON provider. - A file that is empty or holds only comments adds no keys.
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 TOML and duplicate keys (which TOML forbids): the message gives the line and column, and the inner
TomlExceptioncarriesLine,Columnand a stableCodesuch asToml.Load.DuplicateKey. - Keys that differ only in case, which TOML allows but configuration would merge:
A duplicate key 'server:port' was found at line 3.
Files are loaded with the engine's default limits (nesting depth 256, 1,000,000 nodes, 16 MiB strings), which do not reject normal configuration.
Migrating from Tomlyn.Extensions.Configuration
- Replace the package:
dotnet remove package Tomlyn.Extensions.Configuration, thendotnet add package OfficeIMO.Toml.Configuration. - Calls to
AddTomlFilekeep compiling: the overloads follow the JSON provider and live in theMicrosoft.Extensions.Configurationnamespace. Code that names the source or provider types directly switches itsusingtoOfficeIMO.Toml.Configuration. - Values bind the same way to typed options. Code that compares raw configuration strings should expect the spellings above, such as
truefor booleans and ISO 8601 for date-times. - The provider reads TOML 1.1: newlines and trailing commas in inline tables,
\eand\xHHescapes, and times without seconds are accepted.
NativeAOT and trimming
The provider uses no reflection. OfficeIMO.Toml.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.Toml (>= 3.6.2)
-
.NETStandard 2.0
- Microsoft.Extensions.Configuration.FileExtensions (>= 8.0.1)
- OfficeIMO.Toml (>= 3.6.2)
-
net10.0
- Microsoft.Extensions.Configuration.FileExtensions (>= 8.0.1)
- OfficeIMO.Toml (>= 3.6.2)
-
net8.0
- Microsoft.Extensions.Configuration.FileExtensions (>= 8.0.1)
- OfficeIMO.Toml (>= 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 | 52 | 11/18/2026 |