Configuration and the options pattern

IConfiguration is a flat set of string keys and string values. Nesting is spelled with :, so this JSON

{ "Payments": { "TimeoutSeconds": 30, "Hosts": ["a", "b"] } }

becomes Payments:TimeoutSeconds = "30", Payments:Hosts:0 = "a" and Payments:Hosts:1 = "b". Keys are case-insensitive.

Sources and precedence

WebApplication.CreateBuilder adds these sources, in this order:

1. appsettings.json
2. appsettings.{Environment}.json
3. user secrets, in the Development environment only
4. environment variables
5. command-line arguments

When two sources define the same key, the one added later wins. The environment name comes from ASPNETCORE_ENVIRONMENT (or DOTNET_ENVIRONMENT) and is Production when neither is set. Because : is not allowed in environment variable names on every platform, a double underscore stands for it: Payments__TimeoutSeconds sets Payments:TimeoutSeconds. The model below stands in for the configuration providers with one case-insensitive dictionary, filled source by source.

1public static class Solution2{3    public static List<string> Run()4    {5        var config = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);6        void Add(string source, Dictionary<string, string> values)7        {8            foreach (var (key, value) in values) config[key.Replace("__", ":")] = value;9        }10 11        Add("appsettings.json", new() { ["Payments:TimeoutSeconds"] = "30", ["Payments:ApiBase"] = "https://pay.example" });12        Add("appsettings.Production.json", new() { ["payments:timeoutseconds"] = "45" });13        Add("environment", new() { ["Payments__ApiBase"] = "https://pay-eu.example" });14 15        return new List<string>16        {17            "TimeoutSeconds=" + config["Payments:TimeoutSeconds"],18            "ApiBase=" + config["PAYMENTS:APIBASE"],19            "keys=" + config.Count,20        };21    }22}

The options pattern

Rather than reading strings out of IConfiguration everywhere, bind a section to a class once:

public class PaymentOptions
{
    [Range(1, 120)] public int TimeoutSeconds { get; set; }
    [Required] public string ApiBase { get; set; } = "";
}

builder.Services.AddOptions<PaymentOptions>()
    .Bind(builder.Configuration.GetSection("Payments"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

Then inject one of three interfaces:

• IOptions<T> is a singleton. Its Value is built on first access and never changes, even if the file is edited.
• IOptionsSnapshot<T> is scoped. It is rebuilt for each request, and stays fixed for the rest of that request. It cannot be injected into a singleton.
• IOptionsMonitor<T> is a singleton whose CurrentValue reflects the latest reload, with OnChange to react to one.

appsettings.json is loaded with reload-on-change enabled, so the difference shows up when the file is edited while the app runs. The model below reloads in the middle of a request.

1public static class Solution2{3    public static List<string> Run()4    {5        var file = new Dictionary<string, string> { ["Payments:TimeoutSeconds"] = "30" };6        int Bind() => int.Parse(file["Payments:TimeoutSeconds"]);7 8        var options = new Lazy<int>(Bind);   // IOptions<T>: built once9        int? monitorCache = null;           // IOptionsMonitor<T>: cached until a reload10        int Monitor() => monitorCache ??= Bind();11        void Reload(string value) { file["Payments:TimeoutSeconds"] = value; monitorCache = null; }12 13        var log = new List<string>();14        void Request(string name, Action? midway = null)15        {16            int? snapshot = null;            // IOptionsSnapshot<T>: one per request17            int Snapshot() => snapshot ??= Bind();18            log.Add($"{name} start: options={options.Value} snapshot={Snapshot()} monitor={Monitor()}");19            midway?.Invoke();20            log.Add($"{name} end: options={options.Value} snapshot={Snapshot()} monitor={Monitor()}");21        }22 23        Request("request 1", () => Reload("60"));24        Request("request 2");25        return log;26    }27}

Common mistakes

• Expecting IOptions<T> to pick up an edited appsettings.json. It was computed once; use IOptionsMonitor<T> or IOptionsSnapshot<T>.
• Misspelling a section or property name. The binder ignores keys with no matching property and leaves the property at its default, so the typo produces a silent 0 or empty string rather than an error.
• Writing Payments:TimeoutSeconds as an environment variable name in a container or CI system. Use Payments__TimeoutSeconds.
• Validating without ValidateOnStart(). Validation then runs when .Value is first read, so a bad deploy starts fine and fails on the first request that needs the setting.

What interviewers ask

• A setting is in appsettings.json, appsettings.Production.json and an environment variable. Which value does the app see? The environment variable: later sources override earlier ones.
• IOptions versus IOptionsSnapshot versus IOptionsMonitor? Lifetimes (singleton, scoped, singleton), when each recomputes, and that a singleton cannot take a snapshot.
• Validation (data annotations or ) plus .