ASwistowski/Voyager.Configuration.MountPathv2.0.1-preview.1

.NET FW4.8.NET3.1.NET 6.0.NET 8.0

Organize ASP.NET Core configuration into separate JSON files by concern (database, logging, services, etc.) and load them conditionally based on environment variables. Pass file names (without extensions) as parameters, and the library automatically loads base files plus environment-specific overrides (e.g., database.json + database.Production.json). Designed for containerized environments (Docker, Kubernetes) with mount paths. Optional encryption support for sensitive values. Follows SOLID principles with separate extension classes by responsibility.

License

MIT

Deps

8

Install Size

—

Vulns

✓ 0

Published

Feb 10, 2026

Get Started

$ dotnet add package Voyager.Configuration.MountPath

Readme

Voyager.Configuration.MountPath

An ASP.NET Core extension for organizing JSON configuration files with support for environment-specific settings, encrypted values, and Docker/Kubernetes mount paths.

About

This library provides a simple way to organize JSON configuration files by file name (without extensions) and load them conditionally based on environment variables. Designed for containerized environments like Docker and Kubernetes, it allows you to:

Organize configuration by concern: Separate files for database, logging, services, etc.
Load files conditionally: Automatically loads environment-specific variants (e.g., database.json + database.Production.json)
Mount at runtime: Keep configuration outside container images using volume mounts
Update without rebuilding: Change configuration without rebuilding or redeploying

⚠️ DEPRECATION NOTICE: Built-in Encryption The built-in encryption feature is deprecated and will be removed in version 3.0. We recommend migrating to external secret management tools like Mozilla SOPS, Kubernetes Secrets, or cloud providers (Azure Key Vault, AWS Secrets Manager). See ADR-003: Encryption Delegation for migration guidance and rationale.

Features

📁 File-based organization: Pass file names (without extensions) as parameters
🎯 Conditional loading: Automatic environment-based file selection
🐳 Container-friendly: Mount configuration from external volumes

dotnet add package Voyager.Configuration.MountPath

using Microsoft.Extensions.DependencyInjection;

var builder = Host.CreateDefaultBuilder(args);

builder.ConfigureAppConfiguration((context, config) =>
{
    var provider = context.HostingEnvironment.GetSettingsProvider();

    // Loads: appsettings.json + appsettings.{Environment}.json
    config.AddMountConfiguration(provider, "appsettings");
});

YourApp/
├── bin/
│   └── config/
│       ├── appsettings.json           # Base configuration
│       └── appsettings.Production.json # Environment-specific overrides

builder.ConfigureAppConfiguration((context, config) =>
{
    config.AddMountConfiguration(settings =>
    {
        settings.FileName = "myconfig";           // File name without extension
        settings.ConfigMountPath = "configuration"; // Default: "config"
        settings.HostingName = "Production";      // Override environment detection
        settings.Optional = false;                // Require environment file
    });
});

builder.ConfigureAppConfiguration((context, config) =>
{
    // Throws exception if appsettings.Production.json doesn't exist
    config.AddMountConfiguration(context.HostingEnvironment.GetSettingsProviderForce());
});

builder.ConfigureAppConfiguration((context, config) =>
{
    var provider = context.HostingEnvironment.GetSettingsProvider();

    // Each file name is loaded as: {name}.json + {name}.{Environment}.json
    config.AddMountConfiguration(provider, "appsettings");  // App settings
    config.AddMountConfiguration(provider, "database");     // Database config
    config.AddMountConfiguration(provider, "logging");      // Logging config
    config.AddMountConfiguration(provider, "services");     // External services
});

config/
├── appsettings.json
├── appsettings.Production.json
├── database.json
├── database.Production.json
├── logging.json
├── logging.Production.json
├── services.json
└── services.Production.json

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY bin/Release/net8.0/publish .

# Configuration will be mounted at runtime
ENTRYPOINT ["dotnet", "YourApp.dll"]

services:
  myapp:
    image: myapp:latest
    volumes:
      - ./config:/app/config:ro  # Mount config folder
    environment:
      - ASPNETCORE_ENVIRONMENT=Production

config/
├── database.json              # Base database config
├── database.Production.json   # Production overrides
├── logging.json               # Base logging config
└── logging.Production.json    # Production logging settings

apiVersion: v1
kind: ConfigMap
metadata:
  name: database-config
data:
  database.json: |
    {
      "ConnectionStrings": {
        "Default": "Server=db;Database=myapp;..."
      }
    }

apiVersion: v1
kind: ConfigMap
metadata:
  name: logging-config
data:
  logging.json: |
    {
      "Logging": {
        "LogLevel": {
          "Default": "Information"
        }
      }
    }

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: myapp
        image: myapp:latest
        volumeMounts:
        - name: database-config
          mountPath: /app/config/database.json
          subPath: database.json
        - name: logging-config
          mountPath: /app/config/logging.json
          subPath: logging.json
      volumes:
      - name: database-config
        configMap:
          name: database-config
      - name: logging-config
        configMap:
          name: logging-config

// Register settings provider
builder.Services.AddVoyagerConfiguration();

// Register custom settings provider
builder.Services.AddVoyagerConfiguration<MyCustomSettingsProvider>();

// Use in your services
public class MyService
{
    private readonly ISettingsProvider _settingsProvider;

    public MyService(ISettingsProvider settingsProvider)
    {
        _settingsProvider = settingsProvider;
    }
}

public class MySettingsProvider : ISettingsProvider
{
    public Settings GetSettings(string filename = "appsettings")
    {
        return new Settings
        {
            FileName = filename,
            ConfigMountPath = "/custom/path",
            HostingName = "Production"
        };
    }
}

// Register in DI
builder.Services.AddVoyagerConfiguration<MySettingsProvider>();

builder.ConfigureAppConfiguration((context, config) =>
{
    var provider = context.HostingEnvironment.GetSettingsProvider();
    var encryptionKey = Environment.GetEnvironmentVariable("ENCRYPTION_KEY");

    // Regular files (plain text)
    config.AddMountConfiguration(provider, "logging");
    config.AddMountConfiguration(provider, "appsettings");

    // ⚠️ DEPRECATED - Use SOPS instead
    config.AddEncryptedMountConfiguration(encryptionKey, provider, "secrets");
    config.AddEncryptedMountConfiguration(encryptionKey, provider, "connectionstrings");
});

# Encrypt files with SOPS (one-time setup)
sops -e config/secrets.json > config/secrets.json

# Decrypt in your deployment script or init container
sops -d /config-encrypted/secrets.json > /config/secrets.json

// Load decrypted files normally - no code changes needed!
builder.ConfigureAppConfiguration((context, config) =>
{
    var provider = context.HostingEnvironment.GetSettingsProvider();

    config.AddMountConfiguration(provider, "logging");
    config.AddMountConfiguration(provider, "secrets");     // Already decrypted by SOPS
    config.AddMountConfiguration(provider, "appsettings");
});