Configuration and Options Pattern in ASP.NET Core

The Options Pattern is the way to map configuration to typed classes, instead of reading individual values as strings.

This gives us real types, autocomplete, validation, and code that’s easier to test. That’s no small thing, because configuration tends to be everywhere (and when it fails, it fails hard).

The problem with magic strings

Suppose we have this configuration in appsettings.json for sending emails:

{
  "SmtpSettings": {
    "Server": "smtp.gmail.com",
    "Port": 587,
    "SenderName": "No-Reply"
  }
}

The quick way to read this would be to inject IConfiguration and access the keys manually:

var server = configuration["SmtpSettings:Server"];
var port = int.Parse(configuration["SmtpSettings:Port"]);

It works, yes. But we’re paying several tolls:

1. Typographical errors: if we type Sever instead of Server, we get null and we’ll see where it blows up.
2. No real types: everything comes as text, so we have to convert integers, booleans, dates…
3. Harder maintenance: keys are scattered throughout the code like little landmines.

The solution: Options Pattern

The Options Pattern consists of creating a C# class that represents a configuration section. Then .NET takes care of binding the JSON values to that class.

This way we go from this:

configuration["SmtpSettings:Server"]

To this:

options.Value.Server

Create the configuration class

We create a simple class (a POCO, basically) whose properties match the JSON keys:

public class SmtpOptions
{
    public const string SectionName = "SmtpSettings";

    public string Server { get; set; } = string.Empty;
    public int Port { get; set; }
    public string SenderName { get; set; } = string.Empty;
}

Property names match the JSON ones. The binding is case-insensitive, so it doesn’t distinguish between uppercase and lowercase, although it’s normal to keep the same style to avoid confusion.

Register options in Program.cs

Now we tell the service container which section of the file to use to populate SmtpOptions.

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<SmtpOptions>(
    builder.Configuration.GetSection(SmtpOptions.SectionName)
);

var app = builder.Build();

We could also write the string "SmtpSettings" directly, but using a constant avoids repeating the section name throughout the project.

Inject and use IOptions

Here’s an important detail: we don’t inject SmtpOptions directly. We inject IOptions<SmtpOptions>, which is the wrapper .NET uses to give us access to those options.

using Microsoft.Extensions.Options;

app.MapGet("/send-email", (IOptions<SmtpOptions> options) =>
{
    var config = options.Value;

    return $"Connecting to {config.Server}:{config.Port} as {config.SenderName}";
});

IOptions vs IOptionsSnapshot vs IOptionsMonitor

There are three common interfaces for reading options. They look very similar, but they are not used for the same thing.

In most applications, IOptions<T> is enough. If we change configuration files on the fly or have long-lived services, then it makes sense to look at IOptionsSnapshot<T> or IOptionsMonitor<T>.

Validate configuration

There’s a rather treacherous failure: if we forget to put Port in the JSON, its value will be 0, because that’s the default value for an int.

We can validate the options at startup using Data Annotations.

using System.ComponentModel.DataAnnotations;

public class SmtpOptions
{
    public const string SectionName = "SmtpSettings";

    [Required]
    public string Server { get; set; } = string.Empty;

    [Range(1, 65535)]
    public int Port { get; set; }

    public string SenderName { get; set; } = string.Empty;
}

And we register the options with validation:

builder.Services.AddOptions<SmtpOptions>()
    .Bind(builder.Configuration.GetSection(SmtpOptions.SectionName))
    .ValidateDataAnnotations()
    .ValidateOnStart();

With ValidateOnStart(), the application fails at startup if the configuration is not valid.