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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OfficeIMO.Toml.Configuration" Version="3.6.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OfficeIMO.Toml.Configuration" Version="3.6.2" />
                    
Directory.Packages.props
<PackageReference Include="OfficeIMO.Toml.Configuration" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OfficeIMO.Toml.Configuration --version 3.6.2
                    
#r "nuget: OfficeIMO.Toml.Configuration, 3.6.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OfficeIMO.Toml.Configuration@3.6.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OfficeIMO.Toml.Configuration&version=3.6.2
                    
Install as a Cake Addin
#tool nuget:?package=OfficeIMO.Toml.Configuration&version=3.6.2
                    
Install as a Cake Tool

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:1 and Smtp: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 give a: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 (0xFF is 255, 1_000 is 1000), 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, -inf and nan become Infinity, -Infinity and NaN, which double parses.
  • Booleans are true and false.
  • Date-times are ISO 8601 with a T, whatever the file's separator: 1979-05-27T07:32:00.5-07:00 binds to DateTimeOffset and DateTime, a local date 1979-05-27 to DateTime, and a local time 07:32:00 to TimeSpan.
  • Empty arrays, tables and array-of-tables items are keys with a null value, 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 TomlException carries Line, Column and a stable Code such as Toml.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

  1. Replace the package: dotnet remove package Tomlyn.Extensions.Configuration, then dotnet add package OfficeIMO.Toml.Configuration.
  2. Calls to AddTomlFile keep compiling: the overloads follow the JSON provider and live in the Microsoft.Extensions.Configuration namespace. Code that names the source or provider types directly switches its using to OfficeIMO.Toml.Configuration.
  3. Values bind the same way to typed options. Code that compares raw configuration strings should expect the spellings above, such as true for booleans and ISO 8601 for date-times.
  4. The provider reads TOML 1.1: newlines and trailing commas in inline tables, \e and \xHH escapes, 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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