ASP.NET Core integration library for Cascade hierarchical configuration management. Provides seamless integration with dependency injection, IOptionsMonitor pattern, and real-time configuration updates.
$ dotnet add package CascadeConfig.AspNetCoreASP.NET Core integration library for Cascade Configuration Management. This library provides seamless integration of Cascade's hierarchical configuration system with ASP.NET Core's IConfiguration and IOptions patterns.
IOptions<T>, IOptionsMonitor<T>, and IOptionsSnapshot<T>ILoggerIHostedServicedotnet add package Cascade.AspNetCore
In your Program.cs:
var builder = WebApplication.CreateBuilder(args);
// Add Cascade configuration
builder.Configuration.AddCascade(
apiKey: "your-cascade-api-key",
baseUrl: "http://localhost:5000", // Or your Cascade server URL
options =>
{
options.AddressBinding("AppSettings", "my-app.production");
options.AddressBinding("Database", "my-app.production.database");
});
// Add Cascade services (lifecycle management, logging)
builder.Services.AddCascadeServices();
var app = builder.Build();
// Direct access
var timeout = builder.Configuration["AppSettings:Timeout"];
var connectionString = builder.Configuration["Database:ConnectionString"];
public class AppSettings
{
public int Timeout { get; set; }
public string ApiEndpoint { get; set; }
public bool EnableDebug { get; set; }
}
// Configure options
builder.Services.Configure<AppSettings>(
builder.Configuration.GetSection("AppSettings"));
// Inject in your services
public class MyService
{
private readonly IOptionsMonitor<AppSettings> _settings;
public MyService(IOptionsMonitor<AppSettings> settings)
{
_settings = settings;
}
public void DoSomething()
{
var timeout = _settings.CurrentValue.Timeout;
// React to changes
_settings.OnChange(newSettings =>
{
Console.WriteLine($"Settings updated! New timeout: {newSettings.Timeout}");
});
}
}
Maps a configuration section name to a Cascade hierarchical address:
options.AddressBinding("SectionName", "cascade.address.path");
IConfiguration (e.g., "AppSettings")Customize where configuration is cached locally:
options.LocalCachePath = ".config/cascade";
Default: .cascade
Enable/disable automatic reloading when configurations change:
options.ReloadOnChange = true; // Default
Cascade.AspNetCore automatically reloads configuration when values change on the server:
public class MyController : ControllerBase
{
private readonly IOptionsMonitor<AppSettings> _settings;
public MyController(IOptionsMonitor<AppSettings> settings)
{
_settings = settings;
// Subscribe to changes
_settings.OnChange(newSettings =>
{
_logger.LogInformation("Configuration updated: {Timeout}", newSettings.Timeout);
});
}
[HttpGet]
public IActionResult GetSettings()
{
// Always returns current value, even after updates
return Ok(_settings.CurrentValue);
}
}
Bind different addresses for different environments:
var environment = builder.Environment.EnvironmentName;
builder.Configuration.AddCascade(
apiKey: "your-api-key",
baseUrl: "http://localhost:5000",
options =>
{
options.AddressBinding("AppSettings", $"my-app.{environment.ToLower()}");
});
options.AddressBinding("App", "my-app.production");
options.AddressBinding("Database", "my-app.production.database");
options.AddressBinding("Cache", "my-app.production.redis");
options.AddressBinding("Logging", "my-app.production.logging");
Each binding creates a root-level section in IConfiguration.
Cascade configurations are flattened into key-value pairs:
Cascade config at "my-app.production":
{
"timeout": 30,
"api": {
"endpoint": "https://api.example.com",
"retries": 3
}
}
Accessible as:
var timeout = configuration["AppSettings:timeout"]; // "30"
var endpoint = configuration["AppSettings:api:endpoint"]; // "https://api.example.com"
var retries = configuration["AppSettings:api:retries"]; // "3"
Arrays are indexed with numeric keys:
Cascade config:
{
"servers": ["server1", "server2", "server3"]
}
Accessible as:
var server1 = configuration["AppSettings:servers:0"]; // "server1"
var server2 = configuration["AppSettings:servers:1"]; // "server2"
Cascade.AspNetCore integrates with ASP.NET Core's logging:
// Logs appear with [Cascade] prefix
[Information] [Cascade] Connected to Cascade server at http://localhost:5000
[Debug] [Cascade] Config loaded for address: my-app.production
[Error] [Cascade] Failed to connect: Connection refused
Configure logging level in appsettings.json:
{
"Logging": {
"LogLevel": {
"Cascade.AspNetCore": "Information"
}
}
}
If Cascade server is unavailable at startup, the library will:
If connection is lost during runtime:
ValidateDataAnnotations().cascade directory is writable for offline fallbackusing Cascade.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
// Configure Cascade
builder.Configuration.AddCascade(
apiKey: builder.Configuration["Cascade:ApiKey"]!,
baseUrl: builder.Configuration["Cascade:BaseUrl"]!,
options =>
{
var env = builder.Environment.EnvironmentName.ToLower();
options.AddressBinding("AppSettings", $"my-app.{env}");
options.AddressBinding("Database", $"my-app.{env}.database");
options.LocalCachePath = ".config/cascade";
options.ReloadOnChange = true;
});
// Register Cascade services
builder.Services.AddCascadeServices();
// Bind to strongly-typed options
builder.Services.Configure<AppSettings>(
builder.Configuration.GetSection("AppSettings"));
builder.Services.Configure<DatabaseSettings>(
builder.Configuration.GetSection("Database"));
// Add data annotations validation
builder.Services.AddOptions<AppSettings>()
.Bind(builder.Configuration.GetSection("AppSettings"))
.ValidateDataAnnotations()
.ValidateOnStart();
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();
options.ReloadOnChange = trueIOptionsMonitor<T> instead of IOptions<T>Default cache: .cascade/ in application root. Ensure this directory is:
This library is part of the Cascade Configuration Management system.
For issues, questions, or contributions, please visit the main Cascade repository.