ASP.NET Core MVC Intermediate

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.

Where a setting's value comes from
  1. Command-line argumentsHighest priority
  2. Environment variablesEmail__SmtpHost on the server
  3. User secretsDevelopment only, outside the project
  4. appsettings.{Environment}.jsonPer environment overrides
  5. appsettings.jsonDefaults, no secrets

From JSON to a class

Group related settings in a section and create a class with matching property names.

JSON
// appsettings.json
{
  "Email": {
    "FromAddress": "[email protected]",
    "SmtpHost": "smtp.example.com",
    "Port": 587,
    "DailyLimit": 500
  }
}

Register, validate and use

C#
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.

Your progress is saved only in this browser.

Want the full details? Read the official Microsoft documentation for this topic.