TextConfigurationExtensions Class
Definition
- Namespace
- Bodu.Extensions.Configuration.Text
- Assembly
- Bodu.Extensions.Configuration.Text.dll
- Package
- Bodu.Extensions.Configuration.Text 1.3.0
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 = ConfigurationResolveOptions.Bodu;
});
// 4. In-memory stream - handy in unit tests. With no target path only the preamble applies, so the key sits
// before any section.
using var ms = new MemoryStream(Encoding.UTF8.GetBytes("Logging: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, thenbodu.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 honor the standard FileConfigurationSource behaviors (reload-on-change,
optional-file, exception wrapping), resolve a relative path through the supplied or builder-default
IFileProvider, and, when no provider is supplied, read a rooted path from the file system, as
AddJsonFile does. 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
builderIConfigurationBuilderThe configuration builder.
optionalboolWhen true (the default), neither file is required to exist; when false, at least one of the two conventional names must resolve.
reloadOnChangeboolWhen 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
builderis null.- FileNotFoundException
Both conventional files are absent and
optionalis 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
builderIConfigurationBuilderThe configuration builder.
documentIniDocumentBaseThe pre-parsed configuration document.
targetPathstringThe optional target path used for glob-anchored resolution.
resolveOptionsConfigurationResolveOptionsThe 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 behavior - subsequent edits to the document or its backing file are not
reflected in the built configuration.
Exceptions
- ArgumentNullException
builderordocumentis 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
builderIConfigurationBuilderThe configuration builder.
providerIFileProviderThe file provider that locates
path, or null to defer to the builder's default file provider.pathstringThe configuration file path, relative to
provider, or, when no provider is supplied, rooted or relative to the builder's file provider.targetPathstringThe optional target path used for glob-anchored resolution.
optionalboolWhen true, the file is permitted to be missing.
reloadOnChangeboolWhen true, the provider reloads the configuration when the underlying file changes.
Returns
- IConfigurationBuilder
The supplied
builder, for chaining.
Remarks
With provider set to null, the file is located as AddJsonFile
locates it: a rooted path is read from the file system, and any other path through the builder's file provider.
Exceptions
- ArgumentNullException
builderis null.- ArgumentException
pathis 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
builderIConfigurationBuilderThe configuration builder.
configureSourceAction<TextConfigurationSource>A callback that configures the source.
Returns
- IConfigurationBuilder
The supplied
builder, for chaining.
Remarks
The source locates the file as AddJsonFile does, a rooted path included; see
Build(IConfigurationBuilder).
Exceptions
- ArgumentNullException
builderorconfigureSourceis 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
builderIConfigurationBuilderThe configuration builder.
pathstringThe configuration file path, rooted or relative to the builder's file provider.
targetPathstringThe optional target path used for glob-anchored resolution.
optionalboolWhen true, the file is permitted to be missing.
reloadOnChangeboolWhen true, the provider reloads the configuration when the underlying file changes.
Returns
- IConfigurationBuilder
The supplied
builder, for chaining.
Remarks
The file is located as AddJsonFile locates it: a rooted path is read from the file system, and any other
path through the builder's file provider, which is the provider SetFileProvider sets, the base path
SetBasePath sets, or by default the application's base directory.
Exceptions
- ArgumentNullException
builderis null.- ArgumentException
pathis 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
builderIConfigurationBuilderThe configuration builder.
configureSourceAction<TextStreamConfigurationSource>A callback that configures the source.
Returns
- IConfigurationBuilder
The supplied
builder, for chaining.
Exceptions
- ArgumentNullException
builderorconfigureSourceis 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
builderIConfigurationBuilderThe configuration builder.
streamStreamThe stream containing configuration text.
targetPathstringThe optional target path used for glob-anchored resolution.
parseOptionsConfigurationParseOptionsThe parse options, or null for the defaults.
resolveOptionsConfigurationResolveOptionsThe resolve options, or null for the defaults.
Returns
- IConfigurationBuilder
The supplied
builder, for chaining.
Exceptions
- ArgumentNullException
builderorstreamis null.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |