Bodu.Extensions.Configuration.Text 0.6.0

Bodu.Extensions.Configuration.Text

API stability — Stable. The public API surface is committed; breaking changes are reserved for a major-version bump per SemVer.

The EditorConfig-compatible Microsoft.Extensions.Configuration provider. This package bridges Bodu.Text.Configuration into the standard Microsoft.Extensions.Configuration pipeline so consumers can register a .boduconfig or bodu.config file with the same shape they already use for JSON, INI, or XML providers. It also ships read-only TOML (AddTomlFile / AddTomlStream) and Bencode (AddBencodeFile / AddBencodeStream) sources that flatten Bodu.Text.Toml and Bodu.Text.Bencode documents into the same colon-delimited key space.

Where to start

• Documentation index — high-level overview of how the bridge fits between the document model and IConfiguration.
• Concepts — what is preserved versus discarded when projecting a ConfigurationView into a Microsoft configuration dictionary (comments, source locations, key case, literal colons).
• Getting started — worked samples for the file, stream, and document overloads, plus reload-on-change.

Runnable samples

The repository ships an offline, dotnet run-able sample for this package — AddTextConfigurationFile with per-target cascade resolution, AddTomlFile flattening, and AddConfigurationOptions<T> into DI-resolved IOptions<T> — under samples/Text.Configuration/.

API matrix vs Microsoft.Extensions.Configuration.Json

Worked examples

Load a file by path

using Microsoft.Extensions.Configuration;
using Bodu.Extensions.Configuration.Text;

IConfiguration config = new ConfigurationBuilder()
    .AddTextConfiguration("app.boduconfig", optional: false, reloadOnChange: true)
    .Build();

string? indentSize = config["format:indent:size"];

The source uses dotted keys (format.indent.size), which the bridge translates into colon-delimited keys (format:indent:size) for Microsoft.Extensions.Configuration.

Load from a stream

using MemoryStream stream = new(Encoding.UTF8.GetBytes("""
service.name = Bodu
service.port = 8080
"""));

IConfiguration config = new ConfigurationBuilder()
    .AddTextConfiguration(stream)
    .Build();

Stream sources are one-shot — the stream is read once when the builder is built and no file watcher is attached.

Load with an explicit IFileProvider

using Microsoft.Extensions.FileProviders;

var fileProvider = new PhysicalFileProvider(repoRoot);

IConfiguration config = new ConfigurationBuilder()
    .AddTextConfiguration(fileProvider, "app.boduconfig")
    .Build();

Target paths and section resolution

Unlike JSON, the source format supports EditorConfig-style glob-anchored sections. Set TargetPath to choose which section a build resolves against:

new ConfigurationBuilder()
    .AddTextConfiguration(source =>
    {
        source.Path = "app.boduconfig";
        source.TargetPath = "src/Foo.cs";  // selects [src/**/*.cs] when present
    })
    .Build();

When TargetPath is null, only preamble (top-of-file) keys flow into the configuration view — anchored sections are skipped.

Array binding

Microsoft.Extensions.Configuration binds collection types (List<T>, T[]) when child keys are zero-based numeric segments. The Bodu source format produces those keys via the default dotted-segment notation:

items.0 = first
items.1 = second
items.2 = third

The resolved view exposes items:0, items:1, items:2, which bind through configuration.GetSection("items").Get<List<string>>() exactly the way JSON arrays bind in Microsoft.Extensions.Configuration.Json.

Default-filename convention

AddTextConfiguration() (no arguments) probes the builder's file provider for .boduconfig first, then falls back to bodu.config. To resolve the dot-prefixed name through PhysicalFileProvider, construct the provider with ExclusionFilters.None:

using Microsoft.Extensions.FileProviders;
using Microsoft.Extensions.FileProviders.Physical;

var builder = new ConfigurationBuilder();
builder.SetFileProvider(new PhysicalFileProvider(repoRoot, ExclusionFilters.None));
IConfiguration config = builder.AddTextConfiguration().Build();

bodu.config resolves through the default Sensitive exclusion filters without any further configuration.

IOptions<T> binding

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;

services.AddOptions();
services.AddTextConfigurationOptions<ServiceOptions>(config, sectionName: "service");

var options = provider.GetRequiredService<IOptions<ServiceOptions>>().Value;

The helper is a thin shim over services.Configure<TOptions>(config.GetSection(name)) — it exists for discoverability alongside the AddTextConfiguration API surface.