Mastering ASP.NET Core Configuration System and Options Pattern: Sources, Priority, and Hot Reloading

ASP.NET Core's configuration system fundamentally replaces the traditional web.config / app.config approach with a unified IConfiguration interface that reads key-value pairs from any source — JSON files, environment variables, command-line arguments, user secrets, or custom providers. The core design principles are configuration-source agnosticism, runtime dynamism with hot reload, and strong-typed binding via the Options pattern.

Configuration Sources and Priority

WebApplication.CreateBuilder(args)

automatically adds sources in this order (later overrides earlier): appsettings.json (base) appsettings.{Environment}.json (environment-specific)

User Secrets (development only)

Environment variables

Command-line arguments (highest priority)

Environment variables are first-class citizens in cloud-native deployments. They use double-underscore ( __) as hierarchy separator, mapping Database:ConnectionString to Database__ConnectionString. Kubernetes ConfigMaps and Secrets inject via environment variables, making this mapping essential.

Dynamic loading is supported via

AddJsonFile("custom.json", optional: true, reloadOnChange: true)

— the reloadOnChange parameter enables file monitoring and automatic reload.

Internal Representation: Flattened Key-Value Dictionary

All sources merge into a flat dictionary. A nested JSON like:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Server=..."
  }
}

becomes:

Logging:LogLevel:Default = "Information"
Logging:LogLevel:Microsoft = "Warning"
ConnectionStrings:DefaultConnection = "Server=..."

Keys use colon ( :) as separator (double-underscore in env vars), are case-insensitive, and all values are stored as strings with type conversion occurring during strong-typed binding. Arrays use index keys like Items:0:Name.

Options Pattern: Three Interfaces, Different Lifecycles

Basic Usage

// 1. Define options class
public class DatabaseOptions {
  public string ConnectionString { get; set; }
  public int MaxRetryCount { get; set; }
  public bool EnableLogging { get; set; }
}

// 2. Register binding
builder.Services.Configure<DatabaseOptions>(
  builder.Configuration.GetSection("Database"));

// 3. Inject and use
public class OrderService {
  private readonly DatabaseOptions _options;
  public OrderService(IOptions<DatabaseOptions> options) {
    _options = options.Value;
  }
}

Configuration Validation

Validation runs at startup (with ValidateOnStart() in .NET 8+) or on first access:

builder.Services.AddOptions<DatabaseOptions>()
  .Bind(builder.Configuration.GetSection("Database"))
  .Validate(options => !string.IsNullOrEmpty(options.ConnectionString),
    "ConnectionString cannot be empty")
  .ValidateOnStart();

This prevents production misconfiguration — a leading cause of startup failures in cloud-native environments.

IOptions<T> — Singleton Snapshot

Behavior: Binds once at startup; Value never updates.

Lifecycle: Singleton (cached in root container).

Use cases: Immutable configs (encryption keys, fixed thresholds), high-performance scenarios, legacy migration.

IOptionsSnapshot<T> — Scoped Refresh

Behavior: Re-binds on every request scope creation; same instance within a scope.

Lifecycle: Scoped.

Use cases: Web apps needing config change awareness (feature flags, rate limits), multi-tenant apps with per-tenant config.

Caveats: Only valid in scoped context; injecting into Singleton throws captive dependency exception; each request triggers reload on first access.

IOptionsMonitor<T> — Active Listening Singleton

Behavior: Singleton accessor with CurrentValue always returning latest; supports OnChange callbacks.

Lifecycle: Singleton with dynamic underlying values.

Use cases: Background services, Worker Services, scenarios requiring immediate reaction (reinitialize connection pools, adjust log levels).

public class MyBackgroundService : BackgroundService {
  private readonly IOptionsMonitor<DatabaseOptions> _monitor;
  private IDisposable _listener;
  public MyBackgroundService(IOptionsMonitor<DatabaseOptions> monitor) {
    _monitor = monitor;
    _listener = _monitor.OnChange(newOpts => {
      Console.WriteLine($"Config updated: {newOpts.ConnectionString}");
      // Reinitialize connections, etc.
    });
  }
  protected override async Task ExecuteAsync(CancellationToken token) {
    while (!token.IsCancellationRequested) {
      var opts = _monitor.CurrentValue; // Always latest
      // Use opts...
      await Task.Delay(1000, token);
    }
  }
  public override void Dispose() {
    _listener?.Dispose();
    base.Dispose();
  }
}

Selection Decision Tree

Key factors: service lifetime (Singleton vs Scoped) and config-change response needs (none, per-request, real-time with callbacks). IOptionsMonitor is most powerful; IOptionsSnapshot is lighter for web requests when callbacks aren't needed.

Custom Configuration Providers

When built-in sources are insufficient (database, remote config center, encrypted storage), implement two core classes:

ConfigurationProvider: Loads data via Load(), stores in Data dictionary, calls OnReload() on change.

ConfigurationSource: Implements IConfigurationSource.Build() to create the provider.

Example — Database provider with periodic refresh:

public class DatabaseConfigurationProvider : ConfigurationProvider {
  private readonly string _connectionString;
  private readonly string _tableName;
  private readonly Timer _refreshTimer;
  public DatabaseConfigurationProvider(string connStr, string table) {
    _connectionString = connStr;
    _tableName = table;
    _refreshTimer = new Timer(Refresh, null, TimeSpan.Zero, TimeSpan.FromMinutes(1));
  }
  public override void Load() {
    var data = new Dictionary<string, string>();
    using var conn = new SqlConnection(_connectionString);
    conn.Open();
    using var cmd = new SqlCommand($"SELECT Key, Value FROM {_tableName}", conn);
    using var reader = cmd.ExecuteReader();
    while (reader.Read()) {
      data[reader.GetString(0)] = reader.GetString(1);
    }
    Data = data;
  }
  private void Refresh(object state) {
    Load();
    OnReload(); // Notifies listeners (IOptionsMonitor, etc.)
  }
  public override void Dispose() {
    _refreshTimer?.Dispose();
    base.Dispose();
  }
}

public class DatabaseConfigurationSource : IConfigurationSource {
  private readonly string _connectionString;
  private readonly string _tableName;
  public DatabaseConfigurationSource(string connStr, string table) {
    _connectionString = connStr;
    _tableName = table;
  }
  public IConfigurationProvider Build(IConfigurationBuilder builder) =>
    new DatabaseConfigurationProvider(_connectionString, _tableName);
}

// Extension method for fluent registration
public static class DatabaseConfigurationExtensions {
  public static IConfigurationBuilder AddDatabase(
    this IConfigurationBuilder builder, string connStr, string table = "AppConfig") =>
    builder.Add(new DatabaseConfigurationSource(connStr, table));
}

Usage (added last for highest priority):

var builder = WebApplication.CreateBuilder(args);
builder.Configuration
  .AddJsonFile("appsettings.json")
  .AddEnvironmentVariables();
builder.Configuration.AddDatabase(
  builder.Configuration.GetConnectionString("ConfigDb"), "AppConfig");

Best Practices for Custom Providers

Priority design: Order of Add calls determines override behavior (last wins).

Performance: Cache remote calls; choose sensible refresh intervals.

Hot reload: Implement IDisposable for timers; call OnReload() after Load().

Error handling: Fail loudly with clear messages, not silently.

Thread safety: Load() may be called concurrently; protect shared state.

Real-World Scenarios

Multi-tenant config: load per-tenant settings from DB.

Config center integration: Apollo, Nacos, Consul.

Encrypted config: decrypt secrets on load.

Remote config: HTTP API, Redis.

Common Pitfalls

Secrets in appsettings.json: Never store passwords/API keys in source-controlled files. Use env vars, Azure Key Vault, or Kubernetes Secrets.

Priority confusion: Later sources override earlier; misunderstanding this causes unexpected values. Debug by checking merge order.

IOptionsSnapshot in Singleton: Captive dependency exception. Use IOptionsMonitor in Singletons.

Silent binding failures: Configure<T> ignores unmatched properties. Add ValidateDataAnnotations() and ValidateOnStart().

Stale state after hot reload: Objects initialized with old config retain outdated values. Use IOptionsMonitor.OnChange to reinitialize dependent services.

Interview Focus Points

Environment file coexistence: appsettings.json loads first, then appsettings.{Environment}.json overrides based on ASPNETCORE_ENVIRONMENT.

Refresh mechanisms: IOptions = never; IOptionsSnapshot = per scope (per request); IOptionsMonitor = real-time via CurrentValue + OnChange.

Env vars in Docker/K8s: Standard injection via ConfigMap/Secret; double-underscore supports hierarchy.

Hot reload setup: reloadOnChange: true on file sources + IOptionsSnapshot or IOptionsMonitor consumers.