Configuration Sources & Providers

Configuration in .NET

appsettings.json

// appsettings.json
{
  "App": {
    "Name": "OrderService",
    "MaxRetries": 3
  },
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=orders"
  }
}

// appsettings.Production.json overrides the above:
{
  "ConnectionStrings": {
    "Default": "Server=prod-db;Database=orders;..."
  }
}

Reading Configuration Values

// Inject IConfiguration
public class OrderService
{
    private readonly IConfiguration _config;

    public OrderService(IConfiguration cfg) => _config = cfg;

    public void Configure()
    {
        string? name     = _config["App:Name"];           // "OrderService"
        int maxRetries   = _config.GetValue<int>("App:MaxRetries"); // 3
        string? connStr  = _config.GetConnectionString("Default");

        // Nested section
        var section = _config.GetSection("App");
        string? appName = section["Name"];
    }
}

Environment Variables

# Set via shell or docker-compose:
export App__Name="OrderService-Prod"
export App__MaxRetries=5
export ConnectionStrings__Default="Server=prod-db;..."

// Equivalent to:
{
  "App": { "Name": "OrderService-Prod", "MaxRetries": 5 },
  "ConnectionStrings": { "Default": "Server=prod-db;..." }
}

// Priority: env vars > appsettings.{Environment}.json > appsettings.json

Command-Line Arguments

# Override config when launching the app:
dotnet run --App:Name="CLI-Override" --App:MaxRetries=10

# Or:
dotnet run --App__Name="CLI-Override"

// The builder.Configuration.AddCommandLine() is called
// automatically by Host.CreateApplicationBuilder().

// Priority order (highest to lowest):
// 1. Command-line args
// 2. Environment variables
// 3. appsettings.{ASPNETCORE_ENVIRONMENT}.json
// 4. appsettings.json

User Secrets

# Initialize user secrets for the project:
dotnet user-secrets init

# Set a secret:
dotnet user-secrets set "Database:Password" "SuperSecret123"
dotnet user-secrets set "Jwt:SecretKey" "dev-only-key"

# List secrets:
dotnet user-secrets list

# Remove:
dotnet user-secrets remove "Database:Password"

# Stored in: ~/.microsoft/usersecrets/{projectId}/secrets.json
# Automatically loaded in Development environment only

Custom Configuration Providers

public class DbConfigProvider : ConfigurationProvider
{
    private readonly string _connStr;
    public DbConfigProvider(string connStr) => _connStr = connStr;

    public override void Load()
    {
        using var conn = new NpgsqlConnection(_connStr);
        conn.Open();
        using var cmd = new NpgsqlCommand(
            "SELECT key, value FROM app_config", conn);
        using var reader = cmd.ExecuteReader();
        while (reader.Read())
            Data[reader.GetString(0)] = reader.GetString(1);
    }
}

public class DbConfigSource : IConfigurationSource
{
    private readonly string _connStr;
    public DbConfigSource(string connStr) => _connStr = connStr;
    public IConfigurationProvider Build(IConfigurationBuilder b)
        => new DbConfigProvider(_connStr);
}

Registering a Custom Provider

var builder = Host.CreateApplicationBuilder(args);

// Add custom DB config provider after appsettings.json
builder.Configuration.Add(
    new DbConfigSource(
        builder.Configuration.GetConnectionString("Default")!));

// Or as an extension method:
public static class ConfigExtensions
{
    public static IConfigurationBuilder AddDatabaseConfig(
        this IConfigurationBuilder b, string connStr)
        => b.Add(new DbConfigSource(connStr));
}

// Usage:
builder.Configuration.AddDatabaseConfig(connStr);

Azure App Configuration

// dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
// dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

builder.Configuration.AddAzureAppConfiguration(options =>
    options
        .Connect(builder.Configuration["AzureAppConfig:ConnectionString"])
        .Select(KeyFilter.Any)                 // all keys
        .Select(KeyFilter.Any, "Production")   // label override
        .UseFeatureFlags(ff =>
            ff.CacheExpirationInterval = TimeSpan.FromMinutes(5))
        .ConfigureRefresh(r =>
            r.Register("App:Version", refreshAll: true)
             .SetCacheExpiration(TimeSpan.FromMinutes(1)))
);

app.UseAzureAppConfiguration(); // enable dynamic refresh

Reloading Configuration

// Enable JSON file reload on change:
builder.Configuration.AddJsonFile("appsettings.json",
    optional: false, reloadOnChange: true);

// In a service, use IOptionsMonitor (not IOptions) to get live values:
public class FeatureService
{
    private readonly IOptionsMonitor<FeatureFlags> _monitor;

    public FeatureService(IOptionsMonitor<FeatureFlags> m) => _monitor = m;

    public bool IsBetaEnabled
        => _monitor.CurrentValue.BetaEnabled; // always fresh

    // React to changes:
    public FeatureService(IOptionsMonitor<FeatureFlags> m)
    {
        _monitor = m;
        m.OnChange(flags => Console.WriteLine("Config changed!"));
    }
}

Quick Check

Real-World: Multi-Source Config

var builder = Host.CreateApplicationBuilder(args);

// Default: appsettings.json → appsettings.{env}.json → env vars → CLI
// Add user secrets in development:
if (builder.Environment.IsDevelopment())
    builder.Configuration.AddUserSecrets<Program>();

// Optionally add Azure Key Vault in production:
if (!builder.Environment.IsDevelopment())
{
    var keyVaultUri = builder.Configuration["Azure:KeyVaultUri"]!;
    builder.Configuration.AddAzureKeyVault(
        new Uri(keyVaultUri), new DefaultAzureCredential());
}

// Now all secrets are available transparently via IConfiguration
var jwtKey = builder.Configuration["Jwt:SecretKey"]!;

Recap: Configuration Sources & Providers