Microsoft's IConfiguration works, but configuration deserves better. Here's what you get:
Zero ceremony – Define a class, add a rule, inject it. No Configure<T>() calls, no IOptions<T> wrappers.
Atomic multi-config updates – IReactiveConfig<(T1, T2, T3)> means multiple configs stay in sync. Never see inconsistent state.
Config-aware rules – Rules can access earlier config to make decisions. Perfect for multi-tenant and dynamic scenarios.
Reactive by default – Subscribe to changes automatically. No manual IOptionsMonitor wiring.
Explicit layering – Rules execute in order, last write wins. No hidden merge logic.
Interface deserialization – Support for interface-typed properties in config classes with explicit mapping.
Built-in health monitoring – Track provider status and config changes with IConfigurationHealthService.
Memory-safe secrets [Developer Preview] – Secret<T> with automatic zeroization and pre-encrypted envelope support.
First-class testing support – Override configuration in integration tests with zero ceremony using CocoarTestConfiguration. Works with direct instantiation, DI, AspNetCore, and WebApplicationFactory. See Testing Documentation.
Compile-time validation – Roslyn analyzers catch configuration errors while you code with red squiggles, automatic quick fixes, and CI/CD integration. Zero runtime cost. See Analyzer Documentation for details on diagnostics (COCFG001-006).
DI Lifetimes: Concrete config types are registered as Scoped (stable snapshot per request), while IReactiveConfig<T> is Singleton (continuous live updates). These defaults can be customized via the setup parameter.
Migration from IOptions
Before (IConfiguration + IOptions):
// Startup configuration
builder.Services.Configure<AppSettings>(builder.Configuration.GetSection("App"));
// Injection - requires wrapper
public class MyService(IOptions<AppSettings> options)
{
var settings = options.Value; // Unwrap every time
}
After (Cocoar.Configuration):
// Startup configuration
builder.Services.AddCocoarConfiguration(rule => [
rule.For<AppSettings>().FromFile("appsettings.json").Select("App")
]);
// Direct injection - no wrapper
public class MyService(AppSettings settings)
{
// Just use it
}
// Or reactive
public class MyService(IReactiveConfig<AppSettings> config)
{
config.Subscribe(newSettings => /* handle changes */);
}
Quick Example
var builder = WebApplication.CreateBuilder(args);
// Define your configuration rules
builder.Services.AddCocoarConfiguration(rule => [
rule.For<AppSettings>().FromFile("appsettings.json").Select("App"),
rule.For<AppSettings>().FromEnvironment("APP_"),
rule.For<DatabaseConfig>().FromFile("appsettings.json").Select("Database")
]);
var app = builder.Build();
// Direct injection - just use your POCO
app.MapGet("/api/status", (AppSettings settings) =>
new { settings.Version, settings.FeatureFlags });
app.Run();
For reactive scenarios (long-lived services):
public class CacheWarmer : BackgroundService
{
private readonly IReactiveConfig<AppSettings> _config;
public CacheWarmer(IReactiveConfig<AppSettings> config)
{
_config = config;
// Subscribe once - rebuild cache when settings change
_config.Subscribe(newSettings =>
{
Console.WriteLine($"Config changed, rebuilding cache...");
RebuildCache(newSettings);
});
}
protected override Task ExecuteAsync(CancellationToken stoppingToken) => Task.CompletedTask;
}
SignalR hub that streams atomic multi-config updates
public class ConfigHub : Hub
{
private readonly IReactiveConfig<(AppSettings App, DatabaseConfig Db)> _configs;
public ConfigHub(IReactiveConfig<(AppSettings App, DatabaseConfig Db)> configs)
{
_configs = configs;
// Stream config changes to connected clients - always atomic
_configs.Subscribe(async tuple =>
{
var (app, db) = tuple;
await Clients.All.SendAsync("ConfigUpdated", new { app.Version, db.ConnectionString });
});
}
}
What You Can Do
Layer Configuration Sources
builder.Services.AddCocoarConfiguration(rule => [
rule.For<AppSettings>().FromFile("appsettings.json"), // Base
rule.For<AppSettings>().FromFile("appsettings.Production.json"), // Environment
rule.For<AppSettings>().FromEnvironment("APP_"), // Overrides
rule.For<AppSettings>().FromCommandLine() // Final overrides (highest priority)
]);
// Rules execute in order - last write wins
Environment variable mapping:
Hierarchical keys use __ (double underscore):
APP_Database__Host=localhost
APP_Database__Port=5432
# Maps to: AppSettings.Database.Host and AppSettings.Database.Port
Command-line argument mapping:
Hierarchical keys use : or __:
dotnet run --Database:Host=localhost --Database:Port=5432 --Verbose
# Maps to: AppSettings.Database.Host, AppSettings.Database.Port, and AppSettings.Verbose (true)
Flexible switch prefixes for command-line arguments:
Use any prefix style (--, -, /, @, #, %) - even multiple at once:
# Mix different styles in the same command line
dotnet run --host=localhost -port=8080 /verbose
# Or use semantic prefixes for self-documenting CLIs
invoke.exe @target=server #issue=123 %env=prod
Prefix filtering for command-line arguments:
Map arguments to specific configuration types:
// Required - fails fast if missing, rolls back entire recompute
rule.For<CoreSettings>().FromFile("required.json").Required()
// Optional - graceful degradation (default)
// Returns empty object with C# defaults on failure, tracks failure in health
rule.For<OptionalSettings>().FromFile("optional.json")
Behavior:
Required rules: Provider failures cause the entire recompute to roll back, preserving all previous configurations. Health status becomes Unhealthy.
Optional rules: Provider failures return an empty JSON object {}, configuration gets C# property defaults, and the failure is tracked via health monitoring with status Degraded. The application continues running with defaults while the source is unavailable.
Example - Optional rule with missing file:
public class FeatureConfig
{
public bool EnableNewUI { get; set; } = false; // C# default
public int MaxItems { get; set; } = 10; // C# default
}
rule.For<FeatureConfig>().FromFile("features.json") // File doesn't exist
var config = manager.GetConfig<FeatureConfig>();
// config is NOT null - returns instance with defaults (EnableNewUI=false, MaxItems=10)
// Health status is Degraded, LastFailureException tracks FileNotFoundException
This enables graceful degradation - your application continues with safe defaults while monitoring alerts on the health status change.
GetConfig vs GetRequiredConfig:
GetConfig<T>() returns configuration if rules are defined for type T, never null when rules exist (returns empty object with defaults on first-time failures)
GetRequiredConfig<T>() throws if no rules are defined for type T - it's a static configuration check, not a runtime availability check. Use this in config-aware rules to ensure dependent configuration is properly defined.
Conditional Rules
rule.For<TenantSettings>().FromFile("tenant.json"),
rule.For<PremiumFeatures>().FromFile("premium.json")
.When(accessor => accessor.GetRequiredConfig<TenantSettings>().IsPremium)
// Rules can access earlier config to make decisions
Dynamic Configuration
rule.For<TenantSettings>().FromFile("tenant.json"),
rule.For<ApiSettings>().FromHttpPolling(accessor =>
{
var tenant = accessor.GetRequiredConfig<TenantSettings>();
return new HttpPollingRuleOptions(
$"https://{tenant.Region}.api.example.com/config",
pollInterval: TimeSpan.FromMinutes(5)
);
})
// Rules can derive behavior from earlier rules
Interface Exposure
builder.Services.AddCocoarConfiguration(rule => [
rule.For<AppSettings>().FromFile("appsettings.json")
], setup => [
setup.ConcreteType<AppSettings>().ExposeAs<IAppSettings>()
]);
// Both AppSettings and IAppSettings are injectable
public class MyService(IAppSettings settings) { }
Interface Deserialization
When your configuration classes have interface-typed properties, you need to map them to concrete types for JSON deserialization:
// Configuration with interface properties
public class AppSettings
{
public string AppName { get; set; }
public ILoggingConfig Logging { get; set; } // Interface property!
}
builder.Services.AddCocoarConfiguration(rule => [
rule.For<AppSettings>().FromEnvironment() // or FromFile, FromHttpPolling, etc.
], setup => [
// Map interface to concrete type for deserialization
setup.Interface<ILoggingConfig>().DeserializeTo<LoggingConfig>()
]);
Why is this needed? When loading configuration from JSON sources (files, environment variables, HTTP), properties typed as interfaces cannot be deserialized directly. This mapping tells the deserializer which concrete type to instantiate.
Visual Studio hot reload injecting logging configuration
Modular configuration with abstracted dependencies
Supports nested interfaces: If your interface properties contain other interface properties, just register all the mappings and they'll work at any depth.
Providers
File – JSON files with automatic change detection and reload
Environment Variables – Prefix-based with hierarchical mapping (__ for nesting)
Command-Line Arguments – POSIX-style parsing with prefix support and nested configuration
HTTP Polling – Remote config with polling; providers emit bytes and central dedup avoids churn (Cocoar.Configuration.HttpPolling)
Static/Observable – In-memory for testing and development
Secrets Management [Developer Preview]
⚠️ Developer Preview: API may change in future releases based on feedback. Production-ready but subject to refinement.
Cocoar.Configuration.Secrets provides memory-safe handling of sensitive configuration data — a unique capability in open-source configuration libraries:
Secret<T> type – Automatic zeroization of sensitive data in memory
Pre-encrypted envelope support – Secrets encrypted at rest in configuration files
On-demand decryption – Secret<T>.Open() provides controlled exposure windows
CLI tools – Certificate management and secret encryption workflows
// Configuration with encrypted secrets
public class AppSettings
{
public string AppName { get; set; }
public Secret<DatabaseCredentials> DatabaseSecret { get; set; }
}
// Use secrets safely
using var exposed = settings.DatabaseSecret.Open();
var connectionString = BuildConnectionString(exposed.Value);
// Secret automatically zeroized when disposed
Cocoar.Configuration provides first-class testing support with CocoarTestConfiguration:
[Fact]
public async Task TestWithOverriddenConfig()
{
// Set test configuration BEFORE creating WebApplicationFactory
CocoarTestConfiguration.ReplaceAllRules(rule => [
rule.For<DbConfig>().FromStatic(_ => testDbConfig)
]);
await using var factory = new WebApplicationFactory<Program>();
// Original rules are skipped - only test rules execute
}
