Baubit.Configuration 2025.49.1

Baubit.Configuration

<br/> <br/>

Type-safe configuration builder for .NET with Result pattern error handling and environment variable expansion.

Features

• Type-Safe - Bind configuration to strongly-typed classes
• Result Pattern - Explicit error handling without exceptions
• Environment Variable Expansion - ${VAR} syntax in configuration values
• Multiple Sources - JSON files, embedded resources, raw strings, user secrets
• Validation - Custom validator pipeline support
• Fluent API - Chainable configuration methods

Installation

dotnet add package Baubit.Configuration

Quick Start

Basic Configuration

using Baubit.Configuration;

var result = ConfigurationBuilder.CreateNew()
    .Bind(b => b.WithRawJsonStrings("{\"Database\":\"Server=localhost\"}"))
    .Bind(b => b.Build());

if (result.IsSuccess)
{
    var value = result.Value["Database"]; // "Server=localhost"
}

Type-Safe Configuration

public class AppConfig : AConfiguration
{
    public string ConnectionString { get; init; }
    public int MaxRetries { get; init; }
}

var builder = ConfigurationBuilder<AppConfig>.CreateNew();
builder.WithRawJsonStrings("{\"ConnectionString\":\"...\",\"MaxRetries\":3}");
var result = builder.Build();

if (result.IsSuccess)
{
    var config = result.Value;
    Console.WriteLine(config.ConnectionString);
}

Environment Variable Expansion

public class PathConfig : AConfiguration
{
    [URI]
    public string LogPath { get; init; }
}

// With LogPath = "${HOME}/logs" in JSON
// Automatically expands to "/home/user/logs"
var builder = ConfigurationBuilder<PathConfig>.CreateNew();
builder.WithRawJsonStrings("{\"LogPath\":\"${HOME}/logs\"}");
var result = builder.Build();

Multiple Configuration Sources

var result = ConfigurationBuilder.CreateNew()
    .Bind(b => b.WithJsonUriStrings("file:///app/config.json"))
    .Bind(b => b.WithEmbeddedJsonResources("MyApp;Config.appsettings.json"))
    .Bind(b => b.WithLocalSecrets("MyApp-Secrets"))
    .Bind(b => b.WithRawJsonStrings("{\"Override\":\"Value\"}"))
    .Bind(b => b.Build());

Validation

using Baubit.Configuration.Validation;

public class AppConfigValidator : AValidator<AppConfig>
{
    public override Result Run(AppConfig config)
    {
        return Result.OkIf(
            config.MaxRetries > 0, 
            "MaxRetries must be positive"
        );
    }
}

var builder = ConfigurationBuilder<AppConfig>.CreateNew();
builder.WithRawJsonStrings("{\"ConnectionString\":\"test\",\"MaxRetries\":3}");
builder.WithValidators(new AppConfigValidator());
var result = builder.Build();

Configuration Sources

Environment Variable Expansion

Properties marked with [URI] attribute support automatic environment variable expansion using ${VAR} syntax:

public class Config : AConfiguration
{
    [URI]
    public string DatabasePath { get; init; }  // Expands ${DB_PATH}
    
    [URI]
    public List<string> SearchPaths { get; init; }  // Expands all items
    
    public string NormalPath { get; init; }  // No expansion
}

Syntax: ${VARIABLE_NAME} - Build fails with error if variable doesn't exist

API Reference

ConfigurationBuilder

// Factory
ConfigurationBuilder.CreateNew() : Result<ConfigurationBuilder>

// Constants
ConfigurationSectionKey : string = "configuration"  // Section key for configuration data

// Methods
WithJsonUriStrings(params string[] uris) : Result<ConfigurationBuilder>
WithEmbeddedJsonResources(params string[] resources) : Result<ConfigurationBuilder>
WithLocalSecrets(params string[] secrets) : Result<ConfigurationBuilder>
WithRawJsonStrings(params string[] json) : Result<ConfigurationBuilder>
WithAdditionalConfigurations(params IConfiguration[] configs) : Result<ConfigurationBuilder>
WithAdditionalConfigurationSourcesFrom(params IConfiguration[] configs) : Result<ConfigurationBuilder>
WithAdditionalConfigurationsFrom(params IConfiguration[] configs) : Result<ConfigurationBuilder>
WithAdditionalConfigurationSources(params ConfigurationSource[] sources) : Result<ConfigurationBuilder>
Build() : Result<IConfiguration>

ConfigurationBuilder<TConfiguration>

// Inherits all ConfigurationBuilder methods plus:
WithValidators(params IValidator<TConfiguration>[] validators) : Result<ConfigurationBuilder<TConfiguration>>
Build() : Result<TConfiguration>  // Returns typed config

ConfigurationSourceBuilder

// Factory
ConfigurationSourceBuilder.CreateNew() : Result<ConfigurationSourceBuilder>

// Constants
ConfigurationSourceSectionKey : string = "configurationSource"  // Section key for configuration sources

// Methods
WithRawJsonStrings(params string[] json) : Result<ConfigurationSourceBuilder>
WithJsonUriStrings(params string[] uris) : Result<ConfigurationSourceBuilder>
WithEmbeddedJsonResources(params string[] resources) : Result<ConfigurationSourceBuilder>
WithLocalSecrets(params string[] secrets) : Result<ConfigurationSourceBuilder>
WithAdditionalConfigurationSources(params ConfigurationSource[] sources) : Result<ConfigurationSourceBuilder>
Build() : Result<ConfigurationSource>

Error Handling

All operations return Result<T> from FluentResults:

var result = builder.Build();

if (result.IsFailed)
{
    foreach (var error in result.Errors)
    {
        Console.WriteLine(error.Message);
    }
}

Best Practices

• Use typed configuration classes inheriting AConfiguration
• Validate configuration with IValidator<T>
• Handle Result failures explicitly
• Use [URI] attribute for environment-specific values
• Avoid storing sensitive data in code
• Use WithAdditionalConfigurationSourcesFrom to load configuration sources from external configurations
• Use WithAdditionalConfigurationsFrom to load configuration data from external configurations

Examples

Production Configuration

public class ProductionConfig : AConfiguration
{
    [URI]
    public string DatabaseConnection { get; init; }
    
    [URI]
    public string LogDirectory { get; init; }
    
    public int PoolSize { get; init; }
}

var builder = ConfigurationBuilder<ProductionConfig>.CreateNew();
builder.WithJsonUriStrings("file:///etc/app/config.json");
builder.WithLocalSecrets("ProductionSecrets");
builder.WithValidators(new ProductionValidator());
var result = builder.Build();

Testing Configuration

var builder = ConfigurationBuilder<AppConfig>.CreateNew();
builder.WithRawJsonStrings(@"{
    ""ConnectionString"": ""Server=localhost;Database=test"",
    ""MaxRetries"": 3
}");
var result = builder.Build();

if (result.IsSuccess)
{
    var testConfig = result.Value;
}

Loading Configuration from External Sources

// Load configuration sources from another configuration
var externalConfig = new Microsoft.Extensions.Configuration.ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string> 
    {
        { "configurationSource:RawJsonStrings:0", "{\"Key\":\"Value\"}" }
    })
    .Build();

var builder = ConfigurationBuilder.CreateNew();
builder.WithAdditionalConfigurationSourcesFrom(externalConfig);
var result = builder.Build();

Composing Configuration Sources

// Create and reuse configuration sources
var baseSource = ConfigurationSourceBuilder.CreateNew()
    .Bind(b => b.WithRawJsonStrings("{\"BaseKey\":\"BaseValue\"}"))
    .Bind(b => b.Build())
    .Value;

var builder = ConfigurationBuilder.CreateNew();
builder.WithAdditionalConfigurationSources(baseSource);
builder.WithRawJsonStrings("{\"AdditionalKey\":\"AdditionalValue\"}");
var result = builder.Build();

if (result.IsSuccess)
{
    var config = result.Value;
    var baseValue = config["BaseKey"];           // "BaseValue"
    var additionalValue = config["AdditionalKey"]; // "AdditionalValue"
}

Loading Configuration Data from External Sources

// Load configuration data from another configuration
var externalConfig = new Microsoft.Extensions.Configuration.ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string> 
    {
        { "configuration:Database", "Server=localhost" }
    })
    .Build();

var builder = ConfigurationBuilder.CreateNew();
builder.WithAdditionalConfigurationsFrom(externalConfig);
var result = builder.Build();

if (result.IsSuccess)
{
    var value = result.Value["Database"]; // "Server=localhost"
}

License

Licensed under the terms specified in LICENSE.

Contributing

Contributions welcome! This project uses:

• Result pattern for error handling
• Comprehensive XML documentation

Author: Prashant Nagoorkar
Repository: https://github.com/pnagoorkar/Baubit.Configuration