CascadeConfig.Ninject 0.1.1

Cascade.Ninject

Ninject integration library for Cascade Configuration Management. This library provides seamless integration of Cascade's hierarchical configuration system with Ninject dependency injection.

Features

• Ninject Integration: Simple fluent API for binding Cascade configurations to your kernel
• Real-Time Updates: Configuration changes are automatically propagated to ICascadeConfig<T>
• Offline Resilience: Falls back to local cache if Cascade server is unavailable
• Strongly-Typed Configurations: Bind configuration classes with full type safety
• Singleton Lifecycle: Configurations are registered as singletons for optimal performance

Installation

dotnet add package CascadeConfig.Ninject

Quick Start

1. Bind Cascade to Your Kernel

using Cascade.Ninject;
using Ninject;

var kernel = new StandardKernel();

// Bind Cascade configurations
kernel.BindCascade(
    apiKey: "your-cascade-api-key",
    baseUrl: "http://localhost:5000",  // Or your Cascade server URL
    options =>
    {
        options.Bind<AppSettings>("my-app.production");
        options.Bind<DatabaseConfig>("my-app.production.database");
    });

2. Define Your Configuration Classes

public class AppSettings
{
    public int Timeout { get; set; }
    public string ApiEndpoint { get; set; }
    public bool EnableDebug { get; set; }
}

public class DatabaseConfig
{
    public string ConnectionString { get; set; }
    public int MaxConnections { get; set; }
}

3. Inject Configurations

public class MyService
{
    private readonly ICascadeConfig<AppSettings> _appConfig;
    private readonly ICascadeConfig<DatabaseConfig> _dbConfig;

    public MyService(
        ICascadeConfig<AppSettings> appConfig,
        ICascadeConfig<DatabaseConfig> dbConfig)
    {
        _appConfig = appConfig;
        _dbConfig = dbConfig;
    }

    public void DoSomething()
    {
        // Access current configuration value
        var timeout = _appConfig.Value.Timeout;
        var connectionString = _dbConfig.Value.ConnectionString;

        Console.WriteLine($"Timeout: {timeout}");
        Console.WriteLine($"Connection: {connectionString}");
    }
}

// Resolve your service
var myService = kernel.Get<MyService>();
myService.DoSomething();

Configuration Options

Local Cache Path

Customize where configuration is cached locally:

kernel.BindCascade(
    apiKey: "your-api-key",
    baseUrl: "http://localhost:5000",
    options =>
    {
        options.Bind<AppSettings>("my-app.production");
        options.LocalCachePath = ".config/cascade";
    });

Default: .cascade

Default Cloud Base URL

If using Cascade Cloud, you can omit the base URL:

kernel.BindCascade(
    apiKey: "your-api-key",
    options =>
    {
        options.Bind<AppSettings>("my-app.production");
    });

This uses https://cascade-cloud.com as the default base URL.

Real-Time Updates

Cascade configurations automatically update when values change on the server:

public class MyService
{
    private readonly ICascadeConfig<AppSettings> _config;

    public MyService(ICascadeConfig<AppSettings> config)
    {
        _config = config;

        // Subscribe to changes
        _config.OnChange(newSettings =>
        {
            Console.WriteLine($"Configuration updated! New timeout: {newSettings.Timeout}");
        });
    }

    public void CheckConfig()
    {
        // Always returns the current value, even after updates
        var currentTimeout = _config.Value.Timeout;
    }
}

Multiple Bindings

You can bind multiple configuration types to different Cascade addresses:

kernel.BindCascade(
    apiKey: "your-api-key",
    baseUrl: "http://localhost:5000",
    options =>
    {
        options.Bind<AppSettings>("my-app.production");
        options.Bind<DatabaseConfig>("my-app.production.database");
        options.Bind<CacheConfig>("my-app.production.redis");
        options.Bind<LoggingConfig>("my-app.production.logging");
    });

Each configuration type is independently resolved and updated.

Environment-Specific Configuration

Use different Cascade addresses for different environments:

var environment = Environment.GetEnvironmentVariable("ENVIRONMENT") ?? "development";

kernel.BindCascade(
    apiKey: "your-api-key",
    baseUrl: "http://localhost:5000",
    options =>
    {
        options.Bind<AppSettings>($"my-app.{environment}");
        options.Bind<DatabaseConfig>($"my-app.{environment}.database");
    });

Hierarchical Configuration

Cascade's hierarchical system allows child configurations to override parent values:

Parent config at "my-app":

{
  "timeout": 30,
  "retries": 3,
  "enableDebug": false
}

Child config at "my-app.production":

{
  "timeout": 60,
  "enableDebug": false
}

Resolved config at "my-app.production":

{
  "timeout": 60,        // Overridden by child
  "retries": 3,         // Inherited from parent
  "enableDebug": false  // Overridden by child
}

ICascadeConfig<T> API

The ICascadeConfig<T> interface provides:

public interface ICascadeConfig<T> where T : class, new()
{
    // Current configuration value (always up-to-date)
    T Value { get; }

    // Subscribe to configuration changes
    IDisposable OnChange(Action<T> onChange);

    // Address this config is bound to
    string Address { get; }
}

Disposing Change Subscriptions

var subscription = _config.OnChange(newValue =>
{
    Console.WriteLine("Config changed!");
});

// Unsubscribe when done
subscription.Dispose();

Error Handling

Startup Failures

If the 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 continue

Runtime Failures

If the 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. Register Early: Call BindCascade() before binding other services that depend on configuration
2. Use Singletons: Configurations are already singletons; services depending on them should typically be singletons too
3. Subscribe to Changes: Use OnChange() for services that need to react to configuration updates
4. Environment-Specific Addresses: Use different Cascade addresses per environment
5. Cache Locally: Ensure the cache directory is writable for offline fallback

Complete Example

using Cascade.Ninject;
using Ninject;

// Define configuration classes
public class AppSettings
{
    public int Timeout { get; set; }
    public string ApiEndpoint { get; set; }
}

public class MyService
{
    private readonly ICascadeConfig<AppSettings> _config;

    public MyService(ICascadeConfig<AppSettings> config)
    {
        _config = config;
    }

    public void Run()
    {
        Console.WriteLine($"Using endpoint: {_config.Value.ApiEndpoint}");
    }
}

// Setup Ninject
var kernel = new StandardKernel();

// Bind Cascade
kernel.BindCascade(
    apiKey: "cascade_asdsd5pWArZ26UGmECmFKVzIT2DHQxZKM",
    baseUrl: "http://localhost:5000",
    options =>
    {
        options.Bind<AppSettings>("my-app.production");
        options.LocalCachePath = ".cascade-demo";
    });

// Bind your services
kernel.Bind<MyService>().ToSelf().InSingletonScope();

// Resolve and run
var service = kernel.Get<MyService>();
service.Run();

Troubleshooting

Configuration Not Loading

1. Verify API key is correct
2. Check Cascade server is accessible at the specified base URL
3. Ensure the address exists in Cascade
4. Check application logs for error messages

Updates Not Propagating

1. Ensure you're accessing _config.Value each time (not caching it locally)
2. Check SignalR connection is established (visible in Cascade client logs)
3. Verify the address being updated matches the bound address

Cache Location

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

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

License

MIT License - This library is part of the Cascade Configuration Management system.

Support

For issues, questions, or contributions, please visit the main Cascade repository at http://cascade-cloud.com/