Configuration & Options Pattern

// Precedence (later overrides earlier):
// appsettings.json -> appsettings.Production.json -> environment variables -> command-line args

// appsettings.json: "ConnectionStrings:Db": "local-connection"
// Environment variable ConnectionStrings__Db overrides it at deploy time

Common follow-ups: Why does the environment variable provider use double underscores instead of colons for nested keys?;How would you add a custom configuration source, like a database provider?

public class SmtpSettings {
    public string Host { get; set; } = "";
    public int Port { get; set; }
}

builder.Services.Configure<SmtpSettings>(builder.Configuration.GetSection("Smtp"));

public class EmailService(IOptions<SmtpSettings> options) {
    private readonly SmtpSettings _settings = options.Value;
}

Common follow-ups: What's the difference between IOptions, IOptionsSnapshot, and IOptionsMonitor?;How do you validate options at startup using ValidateOnStart?

// Safe in a singleton: reacts to changes via OnChange
public class MyBackgroundService(IOptionsMonitor<WorkerSettings> monitor) : BackgroundService {
    protected override Task ExecuteAsync(CancellationToken ct) {
        monitor.OnChange(settings => _logger.LogInformation("Settings changed!"));
        return Task.CompletedTask;
    }
}

Common follow-ups: Why can't a singleton service safely use IOptionsSnapshot?;What triggers the OnChange callback in IOptionsMonitor specifically?

// appsettings.json (base)
{ "Logging": { "LogLevel": { "Default": "Information" } } }

// appsettings.Development.json (overrides base only in Development)
{ "Logging": { "LogLevel": { "Default": "Debug" } } }

// Set via: ASPNETCORE_ENVIRONMENT=Development

Common follow-ups: How do you add support for a custom environment name beyond the standard three?;What happens if ASPNETCORE_ENVIRONMENT isn't set at all?

public class SmtpSettings {
    [Required] public string Host { get; set; } = "";
    [Range(1, 65535)] public int Port { get; set; }
}

builder.Services.AddOptions<SmtpSettings>()
    .Bind(builder.Configuration.GetSection("Smtp"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

Common follow-ups: How do you write custom validation logic beyond DataAnnotations using IValidateOptions?;What happens without ValidateOnStart -- when does validation actually run?

builder.Services.Configure<SmtpSettings>("Marketing", builder.Configuration.GetSection("Smtp:Marketing"));
builder.Services.Configure<SmtpSettings>("Transactional", builder.Configuration.GetSection("Smtp:Transactional"));

public class EmailService(IOptionsSnapshot<SmtpSettings> options) {
    public void SendMarketing() => Send(options.Get("Marketing"));
    public void SendTransactional() => Send(options.Get("Transactional"));
}

Common follow-ups: How does the default (unnamed) options instance relate to named ones?;Can you validate each named instance independently?

builder.Configuration.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);

// A service using IOptionsMonitor sees updated values automatically:
public MyService(IOptionsMonitor<FeatureSettings> monitor) {
    monitor.OnChange(settings => _logger.LogInformation("Config reloaded"));
}

Common follow-ups: Why doesn't IOptions<T> reflect hot-reloaded changes?;What are the risks of enabling hot-reload for security-sensitive settings?

# Setting a nested configuration value via environment variable
export ConnectionStrings__DefaultConnection="Server=prod;Database=MyApp;"

# Equivalent to this in appsettings.json:
# { "ConnectionStrings": { "DefaultConnection": "Server=prod;Database=MyApp;" } }

Common follow-ups: Does this convention apply consistently across Windows, Linux, and macOS?;How do you configure array values via environment variables?

// appsettings.json
{
  "Settings": {
    "MaxRetries": 3,
    "Endpoints": ["https://a.com", "https://b.com"]
  }
}

public class Settings {
    public int MaxRetries { get; set; }
    public List<string> Endpoints { get; set; } = new();
}

Common follow-ups: How does binding handle configuration keys that don't match any property?;Can the binder populate a Dictionary<string, T> from configuration?

dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:Db" "Server=local;Database=Dev;"

// Automatically loaded in Development via:
// builder.Configuration.AddUserSecrets<Program>();  (added by default host builder in dev)

Common follow-ups: Where are user secrets actually stored on disk?;Why is user secrets specifically excluded from being enabled by default in Production?