ConfigGuard 1.0.0

ConfigGuard

ConfigGuard is a .NET library that provides strongly-typed configuration validation with startup failure diagnostics, environment comparison tools, and CLI verification capabilities.

Features

• ✅ Strongly-typed configuration validation - Type-safe configuration with fluent validation rules
• ✅ Startup failure with diagnostics - Fail fast at startup with clear, human-readable error messages
• ✅ Environment comparison tool - Compare configurations across environments (Dev, Staging, Production)
• ✅ CLI tool - Command-line interface for validation and comparison (configguard command)

Installation

dotnet add package ConfigGuard

Quick Start

1. Define Your Configuration Class

public class DatabaseConfig
{
    public string ConnectionString { get; set; } = string.Empty;
    public int MaxRetries { get; set; }
    public int TimeoutSeconds { get; set; }
}

2. Create a Validator

using Mavusi.ConfigGuard;

public class DatabaseConfigValidator : ConfigValidator<DatabaseConfig>
{
    protected override void ValidateCore(DatabaseConfig config, ConfigValidationResult result)
    {
        RequireNonEmpty(result, config.ConnectionString, nameof(config.ConnectionString));
        RequireInRange(result, config.MaxRetries, 1, 10, nameof(config.MaxRetries));
        RequireInRange(result, config.TimeoutSeconds, 1, 300, nameof(config.TimeoutSeconds));
    }
}

3. Register in Your Application

ASP.NET Core / .NET Host

using Mavusi.ConfigGuard;

var builder = WebApplication.CreateBuilder(args);

// Register validated configuration
builder.Services.AddValidatedConfig<DatabaseConfig, DatabaseConfigValidator>(
    builder.Configuration);

var app = builder.Build();

// Validate all configurations on startup
app.Services.ValidateConfigurationsOnStartup();

app.Run();

Alternative: Using Host Builder Extension

using Mavusi.ConfigGuard;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.AddValidatedConfig<DatabaseConfig, DatabaseConfigValidator>(
            context.Configuration);
    })
    .ValidateConfigurationsOnStartup() // Automatic validation on startup
    .Build();

await host.RunAsync();

4. Add Configuration to appsettings.json

{
  "DatabaseConfig": {
    "ConnectionString": "Server=localhost;Database=MyDb;",
    "MaxRetries": 3,
    "TimeoutSeconds": 30
  }
}

Validation Helpers

The ConfigValidator<T> base class provides several helpful validation methods:

• RequireNonEmpty(result, value, propertyName) - Validates string is not null or whitespace
• RequireNotNull<T>(result, value, propertyName) - Validates object is not null
• RequireInRange(result, value, min, max, propertyName) - Validates numeric value is within range
• RequireValidUri(result, value, propertyName) - Validates string is a valid URI
• Require(result, condition, propertyName, errorMessage) - Custom validation condition

Error Messages

When validation fails, ConfigGuard provides clear, actionable error messages:

Configuration validation failed for 'DatabaseConfig':
[ConnectionString]: ConnectionString is required and cannot be empty.
[MaxRetries]: MaxRetries must be between 1 and 10. Current value: 15

Advanced Usage

Custom Validator Without Base Class

public class CustomValidator : IConfigValidator<MyConfig>
{
    public ConfigValidationResult Validate(MyConfig config)
    {
        var result = new ConfigValidationResult();

        if (config.ApiKey.Length < 32)
        {
            result.AddError(nameof(config.ApiKey), 
                "API key must be at least 32 characters long.");
        }

        return result;
    }
}

Register Validator Instance

var validator = new DatabaseConfigValidator();
services.AddValidatedConfig(builder.Configuration, validator);

Multiple Configuration Sections

services
    .AddValidatedConfig<DatabaseConfig, DatabaseConfigValidator>(
        builder.Configuration)
    .AddValidatedConfig<ApiConfig, ApiConfigValidator>(
        builder.Configuration)
    .AddValidatedConfig<CacheConfig, CacheConfigValidator>(
        builder.Configuration);

Environment Comparison

ConfigGuard can compare configurations across different environments to catch discrepancies before deployment.

Basic Comparison

using Mavusi.ConfigGuard.Comparison;

// Load configurations from different environments
var devConfig = LoadConfig("appsettings.Development.json");
var prodConfig = LoadConfig("appsettings.Production.json");

// Create snapshots
var snapshotBuilder = new ConfigSnapshotBuilder();
var devSnapshot = snapshotBuilder.CreateSnapshot(devConfig, "Development");
var prodSnapshot = snapshotBuilder.CreateSnapshot(prodConfig, "Production");

// Compare
var comparer = new ConfigComparer();
var result = comparer.Compare(devSnapshot, prodSnapshot);

// Display results
if (result.IsIdentical)
{
    Console.WriteLine("✓ Configurations are identical");
}
else
{
    Console.WriteLine($"⚠ Found {result.DifferenceCount} differences");
    Console.WriteLine(result.ToConsoleReport());
}

Generate Reports

ConfigGuard supports multiple report formats:

// Console-friendly report
Console.WriteLine(result.ToConsoleReport());

// JSON report for automation
File.WriteAllText("comparison.json", result.ToJsonReport());

// Markdown report for documentation
File.WriteAllText("comparison.md", result.ToMarkdownReport());

// Or use the helper method
result.SaveToFile("comparison.txt", ReportFormat.Console);
result.SaveToFile("comparison.json", ReportFormat.Json);
result.SaveToFile("comparison.md", ReportFormat.Markdown);

Compare Multiple Environments

var baseline = snapshotBuilder.CreateSnapshot(devConfig, "Development");
var staging = snapshotBuilder.CreateSnapshot(stagingConfig, "Staging");
var production = snapshotBuilder.CreateSnapshot(prodConfig, "Production");

var results = comparer.CompareMultiple(baseline, staging, production);

// Generate multi-environment report
Console.WriteLine(results.ToConsoleReport());
File.WriteAllText("all-environments.json", results.ToJsonReport());

Difference Types

ConfigGuard identifies several types of configuration differences:

• ValueChanged - The value of a property changed between environments
• MissingInTarget - A property exists in the source but not in the target
• MissingInSource - A property was added in the target environment
• TypeMismatch - The property has different types (e.g., string vs. int)

Severity Levels

You can assign severity levels to differences:

foreach (var diff in result.Differences)
{
    if (diff.PropertyName.Contains("Password"))
    {
        diff.Severity = ConfigDifferenceSeverity.Critical;
    }
}

Command-Line Interface (CLI)

ConfigGuard includes a powerful CLI tool for validation and comparison.

Installation

Install as a global .NET tool:

dotnet tool install --global Mavusi.ConfigGuard.CLI

Usage

Validate Configuration

# Basic validation
configguard validate -f appsettings.json

# Strict validation (fails on warnings)
configguard validate -f appsettings.Production.json --strict

Compare Configurations

# Compare two environments
configguard compare -s appsettings.Development.json -t appsettings.Production.json

# Generate JSON report
configguard compare -s dev.json -t prod.json -f json -o report.json

# Compare specific section
configguard compare -s dev.json -t prod.json --section DatabaseConfig

# Generate Markdown for documentation
configguard compare -s dev.json -t prod.json -f markdown -o changes.md

CI/CD Integration

# Exit with error code if differences found (default behavior)
configguard compare -s staging.json -t production.json

# Don't fail on differences (informational only)
configguard compare -s dev.json -t prod.json --fail-on-diff false

Exit Codes:

• 0 - Success
• 1 - Validation failed
• 2 - Differences found (when --fail-on-diff=true)
• 11 - File not found
• 12 - Invalid format

See CLI README for complete documentation.

Roadmap

• Strongly-typed configuration validation
• Startup failure diagnostics
• Environment comparison tool
• Multiple report formats (Console, JSON, Markdown)
• CLI tool for pre-deployment validation
• Data annotation support
• FluentValidation integration
• YAML and JSON schema generation
• Azure Key Vault comparison support

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.