Noctusoft.EzLocalKeyVault.Configuration

EzLocalKeyVault

A lightweight, flexible key vault solution for .NET applications that provides seamless integration with Azure Key Vault for production environments and local key vault files for development.

Features

• Hybrid Key Vault Integration: Automatically use Azure Key Vault in production and local key vault in development
• Typed Configuration: Strongly-typed configuration classes with validation support
• Direct Injection: Register configuration as concrete types or via the IOptions<T> pattern
• Validation Support: Validate configuration using data annotations with strict or lenient modes
• Fallback Behavior: Automatic fallback between Azure Key Vault and local key vault

Quick Start

1. Install the Package

# For local key vault only
dotnet add package Noctusoft.EzLocalKeyVault

# For hybrid Azure/Local key vault
dotnet add package Noctusoft.EzAzureLocalKeyVault

2. Create a Local Key Vault File

Create a .local-vault.json file in your project root:

{
  "API_KEY": "your-api-key",
  "CONNECTION_STRING": "Server=localhost;Database=YourDb;User Id=dev_user;Password=dev_password;"
}

3. Configure Your Application

Option 1: Local Key Vault Only

// Program.cs
builder.Configuration.AddEzLocalKeyVault();

Option 2: Hybrid Azure/Local Key Vault

// Program.cs
builder.Configuration.AddEzAzureLocalKeyVault(options => {
    options.AzureKeyVaultUri = "https://your-vault.vault.azure.net/";
    
    // This setting is optional - if not specified, it will use Azure Key Vault
    // If the local key vault file doesn't exist, it will automatically fall back to Azure Key Vault
    options.UseLocalKeyVault = builder.Environment.IsDevelopment();
    
    // You can also specify which environments should use local key vault
    // options.LocalKeyVaultEnvironments = new[] { "Development", "Staging" };
});

4. Use Typed Configuration

Define a configuration class:

using System.ComponentModel.DataAnnotations;
using Noctusoft.EzLocalKeyVault.Configuration;
using Noctusoft.EzLocalKeyVault.Configuration.Validation;

// Method 1: Property-level validation
// Only specific properties are required
public class AppSettings : IKeyVaultConfiguration
{
    // [ConfigurationRequired] will validate during configuration binding
    // Null or zero-length strings will raise errors
    [ConfigurationRequired(ErrorMessage = "API Key is required and cannot be empty")]
    public string ApiKey { get; set; } = string.Empty;
    
    // No annotation means this field won't be validated
    public string ConnectionString { get; set; } = string.Empty;
    
    // Standard validation attributes also work
    [Range(1, 3600, ErrorMessage = "Timeout must be between 1 and 3600 seconds")]
    public int Timeout { get; set; } = 30;
}

// Method 2: Class-level validation
// All properties in the class must have values
[ConfigurationRequired]
public class CriticalSettings : IKeyVaultConfiguration
{
    // All string properties must be non-null and non-empty
    public string ApiKey { get; set; } = string.Empty;
    public string ServiceUrl { get; set; } = string.Empty;
    
    // Nullable properties are optional (won't be validated)
    public string? OptionalSetting { get; set; }
    
    // But nullable properties WITH [ConfigurationRequired] WILL be validated
    [ConfigurationRequired]
    public string? RequiredNullableSetting { get; set; }
    
    // Value types are always considered valid
    public int Timeout { get; set; } = 30;
    
    // Reference types must be non-null
    public DatabaseSettings Database { get; set; } = new();
}

// Method 3: Class-level validation with nullable properties
// All non-nullable properties in the class must have values
[ConfigurationRequired]
public class CriticalSettingsWithNullable : IKeyVaultConfiguration
{
    // All string properties must be non-null and non-empty
    public string ApiKey { get; set; } = string.Empty;
    public string ServiceUrl { get; set; } = string.Empty;
    
    // Nullable properties are optional (won't be validated)
    public string? OptionalSetting { get; set; }
    
    // But nullable properties WITH [ConfigurationRequired] WILL be validated
    [ConfigurationRequired]
    public string? RequiredNullableSetting { get; set; }
    
    // Value types are always considered valid
    public int Timeout { get; set; } = 30;
    
    // Reference types must be non-null
    public DatabaseSettings? Database { get; set; }
}

Register and use the typed configuration:

// Option 1: Register without explicit validation
// Will automatically validate any [ConfigurationRequired] attributes
// For class-level validation, all errors will be aggregated into a single exception
builder.Services.AddTypedConfiguration<AppSettings>(builder.Configuration, "AppSettings");

// Option 2: Register with direct injection (also validates [ConfigurationRequired] attributes)
// Allows injecting AppSettings directly without IOptions wrapper
builder.Services.AddKeyVaultConfiguration<AppSettings>(builder.Configuration, "AppSettings");

// Option 3: Register with strict validation for all validation attributes
// Will throw ValidationException immediately after key vault evaluation if validation fails
// Use this in production to fail fast if configuration is invalid
builder.Services.AddValidatedConfiguration<AppSettings>(builder.Configuration, "AppSettings", strict: true);

// Option 4: Register with lenient validation for all validation attributes
// Will log validation errors but won't throw exceptions
// Useful for development environments
builder.Services.AddValidatedConfiguration<AppSettings>(builder.Configuration, "AppSettings", strict: false);

// Inject in your services
public class MyService
{
    private readonly AppSettings _settings;
    
    // Option 1: Inject via IOptions pattern
    public MyService(IOptions<AppSettings> options)
    {
        _settings = options.Value;
    }
    
    // Option 2: Inject directly (requires AddKeyVaultConfiguration)
    public MyService(AppSettings settings)
    {
        _settings = settings;
    }
}

5. Use in Configuration Files

In your appsettings.json:

{
  "AppSettings": {
    "ApiKey": "$(API_KEY)",
    "ConnectionString": "$(CONNECTION_STRING)",
    "Timeout": "$(TIMEOUT)"
  }
}

Documentation

• Advanced Usage Guide
• Hybrid Key Vault Integration
• Typed Configuration
• Validation
• CLI Tool
• Packaging and Publishing

Sample Applications

• TypedConfigurationSample: Demonstrates typed configuration with local key vault
• AzureKeyVaultSample: Demonstrates hybrid Azure/Local key vault integration
• ValidationSample: Demonstrates validation capabilities

Security Notice

This library is designed for development and testing scenarios. When using in production:

1. Never commit .local-vault.json to source control
2. Use Azure Key Vault for production secrets
3. Follow security best practices for managing Azure Key Vault access

License

MIT