When building modern .NET applications, clean and scalable configuration is not just a nice-to-have, it’s a necessity. And yet, many developers still rely heavily on IConfiguration injections scattered across their codebase, creating tight coupling and hard-to-test components.
That’s where the Options Pattern comes in.
This powerful pattern provides a clean way to map your configuration sections into strongly-typed classes, making your code easier to maintain, test, and reason about. And the best part? ASP.NET Core gives you multiple ways to configure it, each with its own use case and advantages.
Let’s dive in and answer the big question: What is the Options Pattern in .NET, and why should you use it?
What Is It?
The Options Pattern in .NET is a design approach that allows you to bind sections of your configuration (like appsettings.json, secrets, etc) to strongly-typed classes. Instead of reading raw values from IConfiguration directly throughout your code, you encapsulate configuration data into well-defined objects that can be injected via dependency injection.
This means:
Cleaner separation of concerns
Centralized configuration logic
Better testability
Strong compile-time type checking
It’s particularly useful in medium to large applications, where managing dozens of configuration values across multiple layers can quickly get messy.
How It Works?
The Options Pattern works by leveraging dependency injection and configuration binding in ASP.NET Core.
Here’s the general flow:
- Create a Options class that represents a section of your configuration:
public class SmtpOptions
{
public string Host { get; set; }
public int Port { get; set; }
public string Username { get; set; }
public string Password { get; set; }
}
- Add the configuration to appsettings.json:
"SmtpOptions": {
"Host": "smtp.mailserver.com",
"Port": 587,
"Username": "user@mail.com",
"Password": "securepassword"
}
- The most common way to implement is binding and registering the settings using services.Configure<T>():
builder.Services.Configure<SmtpOptions>(
builder.Configuration.GetSection("SmtpOptions"));
The simplest way to set up the Options Pattern is by using the IConfiguration instance available during service registration. Just call services.Configure<TOptions>() and pass the configuration section you want to bind.
However, one limitation here is that your options are tied strictly to what’s available in your application configuration files. The great news is that this can easily be extended to support environment variables, user secrets, or even custom configuration providers.
It’s quick and effective when your settings come straight from your configuration files without much processing.
But what if you want to:
Apply some custom validation or transformations on the configuration values?
Load or override some settings from environment variables or secure stores?
Compose your settings from multiple configuration sources dynamically?
In these cases, creating a class implementing IConfigureOptions<SmtpOptions> may be a better approach:
public class SmtpOptionsSetup : IConfigureOptions<SmtpOptions>
{
private readonly IConfiguration _configuration;
public SmtpOptionsSetup(IConfiguration configuration)
{
_configuration = configuration;
}
public void Configure(SmtpOptions options)
{
_configuration.GetSection(SectionName.Smtp).Bind(options);
// Custom logic
// You could also override with environment variables or secrets here
}
}
After creating our custom SmtpOptionsSetup class, we also need to let the application know that it should use this class to configure the options:
builder.Services.ConfigureOptions<SmtpOptionsSetup>();
With this registration in place, every time we inject IOptions<SmtpOptions> somewhere in the application, ASP.NET Core will first call the Configure method inside SmtpOptionsSetup to calculate and populate the correct values.
This gives us a single, centralized place to apply any logic or defaults before the options reach the services that depend on them.
How to Inject Options Into Your Services
Once your configuration is registered and bound using the Options Pattern, the next step is injecting those settings into your application components.
Luckily, ASP.NET Core makes this incredibly straightforward thanks to the built-in IOptions<T>, IOptionsSnapshot<T>, and IOptionsMonitor<T> interfaces.
Here’s how you can do it using our SMTP settings example:
public class SendEmailHandler : IEndpointHandler<SendEmailRequest>
{
private readonly SmtpOptions _options;
public SendEmailHandler(IOptions<SmtpOptions> options)
{
_options = options.Value;
}
public async Task HandleAsync(SendEmailRequest request)
{
// Use _options.SmtpServer, _options.Port, etc.
// ...
}
}
You inject the options directly into the handler or constructor of your slice.
Conclusion
The Options Pattern isn’t just a convenience, it’s a clean and scalable way to handle configuration in real-world .NET applications.
By binding settings into strongly-typed objects and injecting them through IOptions<T>, you create a more maintainable, testable, and loosely coupled architecture. Whether you’re working with simple config values or dynamic setups like SMTP or JWT, the Options Pattern adapts to your needs.
And remember: good architecture isn’t about complexity, it’s about clarity. These are patterns I personally apply to ensure long-term flexibility and cleaner code.
Thank you for reading.
See you next time!
