Configuration & Options

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

// appsettings.json: "ConnectionStrings:Db": "local-connection"
// Environment variable ConnectionStrings__Db="prod-connection" overrides it

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 {
    private readonly SmtpSettings _settings;
    public EmailService(IOptions<SmtpSettings> options) => _settings = options.Value;
}

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

// IOptionsSnapshot: fresh value per HTTP request
public MyController(IOptionsSnapshot<FeatureSettings> options) { ... }

// IOptionsMonitor: live change notifications in a singleton service
public class MyBackgroundService : BackgroundService {
    public MyBackgroundService(IOptionsMonitor<WorkerSettings> monitor) {
        monitor.OnChange(settings => Console.WriteLine("Settings changed!"));
    }
}

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

// appsettings.json (base, all environments)
{ "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 a custom environment beyond the standard three?;What happens if ASPNETCORE_ENVIRONMENT isn't set at all?

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

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

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?

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 {
    public EmailService(IOptionsSnapshot<SmtpSettings> options) {
        var marketingSettings = options.Get("Marketing");
        var transactionalSettings = options.Get("Transactional");
    }
}

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

# 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?

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

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

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

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

// Automatically loaded in Development environment 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 in Production by default?