Table of Contents

TextConfigurationExtensions Class

Definition

Namespace
Bodu.Extensions.Configuration.Text
Assembly
Bodu.Extensions.Configuration.Text.dll
Package
Bodu.Extensions.Configuration.Text 1.0.0
Source
TextConfigurationExtensions.cs

Provides convenience extension methods for adding a Bodu Text Configuration source to an IConfigurationBuilder. The overload set mirrors Microsoft.Extensions.Configuration.Json's AddJsonFile / AddJsonStream shape so that consumers familiar with the JSON provider can swap in this provider with no learning curve.

public static class TextConfigurationExtensions
Inheritance
TextConfigurationExtensions
Inherited Members

Examples

// 1. Canonical ASP.NET / Generic Host registration in Program.cs.
var builder = WebApplication.CreateBuilder(args);
builder.Configuration
    .AddTextConfigurationFile("appsettings.boduconfig", optional: true, reloadOnChange: true)
    .AddTextConfigurationFile("appsettings.boduconfig", targetPath: "src/Foo.cs"); // path-aware view

// 2. Convention discovery - probes .boduconfig, then bodu.config.
builder.Configuration.AddTextConfiguration(optional: true, reloadOnChange: true);

// 3. Lambda overload - pin every option, including parse/resolve behaviour.
builder.Configuration.AddTextConfigurationFile(source =>
{
    source.Path           = "app.boduconfig";
    source.TargetPath     = "src/Web/Startup.cs";
    source.Optional       = false;
    source.ReloadOnChange = true;
    source.ParseOptions   = ConfigurationParseOptions.Strict;
    source.ResolveOptions = new ConfigurationResolveOptions
    {
        Profile = ConfigurationProfile.Bodu,
    };
});

// 4. In-memory stream - handy in unit tests.
using var ms = new MemoryStream(Encoding.UTF8.GetBytes("[*]\nLogging:Level=Debug\n"));
builder.Configuration.AddTextConfigurationStream(ms);

// 5. Pre-parsed document - share one parse across multiple builders.
ConfigurationDocument doc = ConfigurationDocument.Parse(text);
builder.Configuration.AddTextConfigurationDocument(doc, targetPath: "src/Foo.cs");

Remarks

Five overload shapes are available, mirroring the JSON provider's surface:

  • File path with optional reload-on-change - the everyday production shape.
  • File path with an explicit IFileProvider - useful when the file lives outside the default content root, in an embedded assembly resource, or under a virtual file system.
  • Lambda configure-source overload - the most flexible shape, exposes every TextConfigurationSource property.
  • Convention-discovery overload - probes for .boduconfig, then bodu.config, in that order.
  • Stream overload (and a lambda TextStreamConfigurationSource variant) - one-shot, no reload-on-change machinery; ideal for tests and synthetic configuration.

File-backed registrations honour the standard FileConfigurationSource behaviours (reload-on-change, optional-file, exception wrapping) and resolve path-relative paths through the supplied or builder-default IFileProvider. The convention overload uses the builder's default IFileProvider; note that IFileProvider implementations such as PhysicalFileProvider filter out dot-prefixed files by default - see the remarks on AddTextConfiguration(IConfigurationBuilder, bool, bool) for the workaround required to surface .boduconfig.

Methods

AddTextConfiguration(IConfigurationBuilder, bool, bool)

Adds a Bodu Text Configuration source backed by the conventional file name .boduconfig, falling back to bodu.config when the dot-prefixed name is absent. The file is resolved against the builder's default file provider.

public static IConfigurationBuilder AddTextConfiguration(this IConfigurationBuilder builder, bool optional = true, bool reloadOnChange = false)

Parameters

builder IConfigurationBuilder

The configuration builder.

optional bool

When true (the default), neither file is required to exist; when false, at least one of the two conventional names must resolve.

reloadOnChange bool

When true, the provider reloads the configuration when the underlying file changes.

Returns

IConfigurationBuilder

The supplied builder, for chaining.

Remarks

The default PhysicalFileProvider filters out dot-prefixed files via its ExclusionFilters ( Sensitive by default), so to make .boduconfig resolvable the caller must register a PhysicalFileProvider constructed with ExclusionFilters.None. The fallback bodu.config name is resolved by the default exclusion filters without further configuration.

Exceptions

ArgumentNullException

builder is null.

FileNotFoundException

Both conventional files are absent and optional is false.

AddTextConfigurationDocument(IConfigurationBuilder, IniDocumentBase, string?, ConfigurationResolveOptions?)

Adds an already-parsed IniDocumentBase (such as a ConfigurationDocument) to the configuration. The document is resolved against targetPath and the resulting key/value map is added via AddInMemoryCollection(IConfigurationBuilder, IEnumerable<KeyValuePair<string, string>>) .

public static IConfigurationBuilder AddTextConfigurationDocument(this IConfigurationBuilder builder, IniDocumentBase document, string? targetPath = null, ConfigurationResolveOptions? resolveOptions = null)

Parameters

builder IConfigurationBuilder

The configuration builder.

document IniDocumentBase

The pre-parsed configuration document.

targetPath string

The optional target path used for glob-anchored resolution.

resolveOptions ConfigurationResolveOptions

The resolve options, or null for the defaults.

Returns

IConfigurationBuilder

The supplied builder, for chaining.

Remarks

This overload takes a one-shot snapshot of document as it stands when called: the document is resolved immediately and the flattened values are added in-memory. Unlike the file-based overloads, it has no reload-on-change behaviour - subsequent edits to the document or its backing file are not reflected in the built configuration.

Exceptions

ArgumentNullException

builder or document is null.

AddTextConfigurationFile(IConfigurationBuilder, IFileProvider?, string, string?, bool, bool)

Adds a Bodu Text Configuration source backed by the file at path using the supplied IFileProvider. Mirrors AddJsonFile(IConfigurationBuilder, IFileProvider, string, bool, bool).

public static IConfigurationBuilder AddTextConfigurationFile(this IConfigurationBuilder builder, IFileProvider? provider, string path, string? targetPath = null, bool optional = false, bool reloadOnChange = false)

Parameters

builder IConfigurationBuilder

The configuration builder.

provider IFileProvider

The file provider that locates path, or null to defer to the builder's default file provider.

path string

The configuration file path, relative to provider.

targetPath string

The optional target path used for glob-anchored resolution.

optional bool

When true, the file is permitted to be missing.

reloadOnChange bool

When true, the provider reloads the configuration when the underlying file changes.

Returns

IConfigurationBuilder

The supplied builder, for chaining.

Exceptions

ArgumentNullException

builder is null.

ArgumentException

path is null, empty, or whitespace.

AddTextConfigurationFile(IConfigurationBuilder, Action<TextConfigurationSource>)

Adds a Bodu Text Configuration source configured via the supplied callback.

public static IConfigurationBuilder AddTextConfigurationFile(this IConfigurationBuilder builder, Action<TextConfigurationSource> configureSource)

Parameters

builder IConfigurationBuilder

The configuration builder.

configureSource Action<TextConfigurationSource>

A callback that configures the source.

Returns

IConfigurationBuilder

The supplied builder, for chaining.

Exceptions

ArgumentNullException

builder or configureSource is null.

AddTextConfigurationFile(IConfigurationBuilder, string, string?, bool, bool)

Adds a Bodu Text Configuration source backed by the file at path.

public static IConfigurationBuilder AddTextConfigurationFile(this IConfigurationBuilder builder, string path, string? targetPath = null, bool optional = false, bool reloadOnChange = false)

Parameters

builder IConfigurationBuilder

The configuration builder.

path string

The configuration file path, relative to the builder's file provider.

targetPath string

The optional target path used for glob-anchored resolution.

optional bool

When true, the file is permitted to be missing.

reloadOnChange bool

When true, the provider reloads the configuration when the underlying file changes.

Returns

IConfigurationBuilder

The supplied builder, for chaining.

Exceptions

ArgumentNullException

builder is null.

ArgumentException

path is null, empty, or whitespace.

AddTextConfigurationStream(IConfigurationBuilder, Action<TextStreamConfigurationSource>)

Adds a Bodu Text Configuration stream source configured via the supplied callback.

public static IConfigurationBuilder AddTextConfigurationStream(this IConfigurationBuilder builder, Action<TextStreamConfigurationSource> configureSource)

Parameters

builder IConfigurationBuilder

The configuration builder.

configureSource Action<TextStreamConfigurationSource>

A callback that configures the source.

Returns

IConfigurationBuilder

The supplied builder, for chaining.

Exceptions

ArgumentNullException

builder or configureSource is null.

AddTextConfigurationStream(IConfigurationBuilder, Stream, string?, ConfigurationParseOptions?, ConfigurationResolveOptions?)

Adds a Bodu Text Configuration source backed by the supplied Stream. The stream is read once when the configuration is built; no reload-on-change machinery is attached. Mirrors AddJsonStream(IConfigurationBuilder, Stream).

public static IConfigurationBuilder AddTextConfigurationStream(this IConfigurationBuilder builder, Stream stream, string? targetPath = null, ConfigurationParseOptions? parseOptions = null, ConfigurationResolveOptions? resolveOptions = null)

Parameters

builder IConfigurationBuilder

The configuration builder.

stream Stream

The stream containing configuration text.

targetPath string

The optional target path used for glob-anchored resolution.

parseOptions ConfigurationParseOptions

The parse options, or null for the defaults.

resolveOptions ConfigurationResolveOptions

The resolve options, or null for the defaults.

Returns

IConfigurationBuilder

The supplied builder, for chaining.

Exceptions

ArgumentNullException

builder or stream is null.

Applies to

ProductVersions
.NET8, 10