Implementing the Options Pattern in .NET Core: A Practical Architecture Note

Problem & Takeaway

In many .NET Core applications, configuration values are scattered across code, making it hard to maintain and test. The Options Pattern lets you map configuration sections to strongly‑typed POCOs, inject them through the built‑in dependency injection (DI) container, and keep business logic free from configuration details. The key takeaway: use the right Options implementation (IOptions, IOptionsSnapshot, or IOptionsMonitor) based on the lifetime and reload requirements of your services.

1. Requirements

• Target framework: .NET 6 or higher (ASP.NET Core 6/7).
• Configuration source: appsettings.json or environment variables.
• DI container – the default Microsoft.Extensions.DependencyInjection.
• Optional: DataAnnotations or IValidateOptions for validation.

2. Smallest Suitable Design

Define a POCO for each logical configuration group. For example, a payment gateway might need an API key and a timeout:

public class PaymentOptions
{
    public string ApiKey { get; set; } = string.Empty;
    public int TimeoutSeconds { get; set; }
}

In Program.cs register the options:

var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<PaymentOptions>(
    builder.Configuration.GetSection("Payment"));

Inject IOptions<PaymentOptions> into a service or controller:

public class PaymentService
{
    private readonly PaymentOptions _options;
    public PaymentService(IOptions<PaymentOptions> options)
    {
        _options = options.Value;
    }
    // Use _options.ApiKey / _options.TimeoutSeconds
}

3. Data Boundaries & Trust

• Keep POCOs thin and module‑specific; avoid a single monolithic AppSettings class.
• Validate required properties at startup using DataAnnotations:

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

Or implement IValidateOptions<T> for complex validation logic.

4. Operational Checks

• When the application starts, the DI container will throw if validation fails.
• Expose a diagnostic endpoint that returns the current options values for quick verification:

[ApiController]
[Route("/api/config")]
public class ConfigController : ControllerBase
{
    private readonly PaymentOptions _options;
    public ConfigController(IOptions<PaymentOptions> options)
    {
        _options = options.Value;
    }
    [HttpGet]
    public IActionResult Get() => Ok(_options);
}

Run the app and hit GET /api/config to confirm values match appsettings.json.

5. Failure Modes

• Missing required fields – startup fails with a clear validation error.
• Using IOptionsSnapshot in a singleton – the DI container throws a runtime exception because snapshot is scoped.
• Over‑reliance on IOptionsMonitor – a configuration change can occur between the start of a transaction and its completion, leading to inconsistent state.
• Case sensitivity differences – environment variable names are case‑insensitive on Windows but case‑sensitive on Linux; test the provider behavior.

6. When to Switch Options Implementations

Scenario	Recommended Option	Why
Configuration is static for the app lifetime	IOptions	Simple, singleton‑like access; no reload needed.
Configuration may change between HTTP requests but not within a request	IOptionsSnapshot	Creates a fresh instance per request scope.
Configuration may change at any time and services need to react immediately	IOptionsMonitor	Provides change notifications; use cautiously to avoid mid‑transaction changes.

7. Practical Verification Steps

1. Start the application: dotnet run in the project folder.
2. Navigate to https://localhost:5001/api/config and verify the JSON matches appsettings.json.
3. While the app is running, edit appsettings.json (e.g., change TimeoutSeconds).
4. Refresh the browser. If using IOptionsSnapshot, the new value appears on the next request; if using IOptions, the old value remains.
5. To test IOptionsMonitor, inject it and subscribe to OnChange to log updates.

8. Limitations

• Binding is case‑insensitive by default but can behave differently across OS providers; test environment variable mapping explicitly.
• Large configuration sections can become unwieldy; consider using nested POCOs or splitting into multiple classes.
• Runtime reloading via IOptionsMonitor does not automatically propagate to already running requests; design services to be stateless or use explicit locking if necessary.

Conclusion

By mapping configuration to small, validated POCOs and choosing the appropriate options interface, you decouple settings from business logic, simplify testing, and gain clear operational visibility. Start with IOptions for most services, switch to IOptionsSnapshot for per‑request freshness, and reserve IOptionsMonitor for truly dynamic scenarios where change notifications are essential.