The options pattern
The options pattern turns sections of appsettings.json into strongly typed classes. This lesson binds settings to a class, validates them at startup so a typo fails fast, and explains IOptions, IOptionsSnapshot and IOptionsMonitor.
- Command-line argumentsHighest priority
- Environment variablesEmail__SmtpHost on the server
- User secretsDevelopment only, outside the project
- appsettings.{Environment}.jsonPer environment overrides
- appsettings.jsonDefaults, no secrets
From JSON to a class
Group related settings in a section and create a class with matching property names.
// appsettings.json
{
"Email": {
"FromAddress": "[email protected]",
"SmtpHost": "smtp.example.com",
"Port": 587,
"DailyLimit": 500
}
}Register, validate and use
public class EmailOptions
{
public const string Section = "Email";
[Required, EmailAddress] public string FromAddress { get; set; } = "";
[Required] public string SmtpHost { get; set; } = "";
[Range(1, 65535)] public int Port { get; set; } = 587;
[Range(1, 10_000)] public int DailyLimit { get; set; } = 500;
}
builder.Services.AddOptions<EmailOptions>()
.BindConfiguration(EmailOptions.Section)
.ValidateDataAnnotations()
.ValidateOnStart(); // app refuses to start with bad settings
public class EmailSender(IOptions<EmailOptions> options)
{
private readonly EmailOptions _o = options.Value;
public Task SendAsync(string to, string subject) { /* uses _o.SmtpHost, _o.Port */ return Task.CompletedTask; }
}Three interfaces
- IOptions<T>: read once at startup; a singleton. Use it by default.
- IOptionsSnapshot<T>: re-read per request, so edits to appsettings.json apply to new requests. Scoped, so not for singletons.
- IOptionsMonitor<T>: current value at any time plus an OnChange callback. Works in singletons and background services.
- Named options (Configure<T>("name", ...)) let you have several sets, such as two email accounts.
Where the values come from
Configuration is layered: appsettings.json, then appsettings.{Environment}.json, then user secrets in development, then environment variables, then command-line arguments. Later sources win. An environment variable Email__SmtpHost overrides the JSON value, which is how hosting platforms inject settings. Secrets never go in appsettings.json; the next lesson covers them.
Interview question
What is the difference between IOptions, IOptionsSnapshot and IOptionsMonitor?
IOptions<T> is a singleton that reads the configuration once, so changes need a restart. IOptionsSnapshot<T> is scoped and recomputes the values for each request, picking up file changes. IOptionsMonitor<T> is a singleton that always returns the current value and can notify you through OnChange, which makes it suitable for singletons and background services.
Want the full details? Read the official Microsoft documentation for this topic.