CascadeConfig.AspNetCore 0.1.1

Cascade.AspNetCore

ASP.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.

Features

• IConfiguration Integration: Cascade configurations are loaded into ASP.NET Core's configuration system
• Real-Time Updates: Configuration changes are automatically reloaded without restarting your application
• IOptions Pattern Support: Use IOptions<T>, IOptionsMonitor<T>, and IOptionsSnapshot<T>
• Offline Resilience: Falls back to local cache if Cascade server is unavailable
• Structured Logging: Integrates with ASP.NET Core's ILogger
• Graceful Lifecycle: Proper startup and shutdown via IHostedService

Installation

dotnet add package Cascade.AspNetCore

Quick Start

1. Add Cascade to Configuration

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();

2. Access Configuration

Via IConfiguration

// Direct access
var timeout = builder.Configuration["AppSettings:Timeout"];
var connectionString = builder.Configuration["Database:ConnectionString"];

Via Options Pattern

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}");
        });
    }
}

Configuration Options

AddressBinding

Maps a configuration section name to a Cascade hierarchical address:

options.AddressBinding("SectionName", "cascade.address.path");

• SectionName: The root key in IConfiguration (e.g., "AppSettings")
• Address: The hierarchical path in Cascade (e.g., "my-app.staging.server1")

Local Cache Path

Customize where configuration is cached locally:

options.LocalCachePath = ".config/cascade";

Default: .cascade

Reload on Change

Enable/disable automatic reloading when configurations change:

options.ReloadOnChange = true;  // Default

Real-Time Updates

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);
    }
}

Multiple Environments

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()}");
    });

Advanced Usage

Multiple Address Bindings

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.

Hierarchical Configuration

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"

Array Support

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"

Logging

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"
    }
  }
}

Error Handling

Startup Failures

If Cascade server is unavailable at startup, the library will:

1. Log an error
2. Attempt to load from local cache
3. Allow the application to start

Runtime Failures

If connection is lost during runtime:

1. Local cache continues to be used
2. Automatic reconnection attempts via SignalR
3. Configuration updates resume when connection is restored

Best Practices

1. Use IOptionsMonitor: For services that need to react to configuration changes
2. Use IOptions: For services that read configuration once at startup
3. Validate Configuration: Use data annotations and ValidateDataAnnotations()
4. Environment-Specific Addresses: Use different Cascade addresses per environment
5. Cache Locally: Ensure .cascade directory is writable for offline fallback

Example: Complete Setup

using 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();

Troubleshooting

Configuration Not Loading

1. Verify API key is correct
2. Check Cascade server is accessible
3. Ensure address exists in Cascade
4. Check logs for error messages

Updates Not Reloading

1. Ensure options.ReloadOnChange = true
2. Use IOptionsMonitor<T> instead of IOptions<T>
3. Check SignalR connection is established (check logs)

Cache Location

Default cache: .cascade/ in application root. Ensure this directory is:

• Writable by the application
• Not in .gitignore if you want to commit cache
• Excluded from deployment if cache should be server-specific

License

This library is part of the Cascade Configuration Management system.

Support

For issues, questions, or contributions, please visit the main Cascade repository.