
# C# Configuration & Options Pattern — Cheatsheet

A quick, scannable one-page reference for configuration sources, Options pattern registration, lifetime decisions, and common patterns in ASP.NET Core.

## Configuration Sources (Last Wins)

```
1. appsettings.json
2. appsettings.{Environment}.json  (e.g., appsettings.Development.json)
3. User Secrets (Development only)
4. Environment Variables
5. Command-line arguments
```

## Quick Start — Register & Consume

**Register in Program.cs:**
```csharp
builder.Services.Configure<EmailSettings>(
    builder.Configuration.GetSection("EmailSettings"));
```

**Inject & use:**
```csharp
public class EmailSender
{
    private readonly EmailSettings _settings;
    public EmailSender(IOptions<EmailSettings> options) => _settings = options.Value;
    
    public void Send(string to) { /* use _settings */ }
}
```

## Options Interfaces — Choose Your Lifetime

| Interface | Lifetime | Reloads | Use For |
|---|---|---|---|
| `IOptions<T>` | Singleton | No | Static settings (secrets, connection strings) |
| `IOptionsSnapshot<T>` | Scoped | Per-request | Changing settings in scoped services (feature flags) |
| `IOptionsMonitor<T>` | Singleton | Live + callback | Singletons that react to config changes |

## Named Options — Multiple Configs of Same Type

```csharp
// Register
builder.Services.Configure<BlobStorageSettings>("Images", 
    builder.Configuration.GetSection("Storage:Images"));
builder.Services.Configure<BlobStorageSettings>("Documents", 
    builder.Configuration.GetSection("Storage:Documents"));

// Consume
public class StorageService
{
    public StorageService(IOptionsSnapshot<BlobStorageSettings> options)
    {
        var imageContainer = options.Get("Images").ContainerName;
        var docContainer = options.Get("Documents").ContainerName;
    }
}
```

## Validation — Always Use `.ValidateOnStart()`

```csharp
builder.Services
    .AddOptions<EmailSettings>()
    .BindConfiguration("EmailSettings")
    .ValidateDataAnnotations()
    .ValidateOnStart();  // ← Catches errors at startup, not first request
```

**With data annotations:**
```csharp
public class EmailSettings
{
    [Required]
    public string SmtpHost { get; init; } = string.Empty;
    
    [Range(1, 65535)]
    public int SmtpPort { get; init; } = 587;
    
    [EmailAddress]
    public string FromAddress { get; init; } = string.Empty;
}
```

**Custom inline validation:**
```csharp
builder.Services
    .AddOptions<EmailSettings>()
    .BindConfiguration("EmailSettings")
    .Validate(s => !string.IsNullOrEmpty(s.SmtpHost) && s.SmtpPort is >= 1 and <= 65535, 
              "Invalid SMTP settings")
    .ValidateOnStart();
```

## Environment Variables

Use double underscore (`__`) as section separator:

```bash
export EmailSettings__SmtpHost=smtp.example.com
export EmailSettings__SmtpPort=587
export ConnectionStrings__Default="Server=prod;Database=MyApp"
```

## PostConfigure — Computed Defaults

```csharp
builder.Services.PostConfigure<EmailSettings>(settings =>
{
    if (string.IsNullOrEmpty(settings.FromAddress))
        settings.FromAddress = $"noreply@{settings.SmtpHost}";
});
```

## User Secrets (Development Only)

```bash
# Initialize
dotnet user-secrets init

# Set a secret
dotnet user-secrets set "EmailSettings:ApiKey" "my-secret-key"

# Access via IConfiguration (no code change needed)
var apiKey = configuration["EmailSettings:ApiKey"];
```

## Binding Patterns

**Method 1 — Simple (no validation):**
```csharp
builder.Services.Configure<EmailSettings>(builder.Configuration.GetSection("EmailSettings"));
```

**Method 2 — With validation (recommended):**
```csharp
builder.Services
    .AddOptions<EmailSettings>()
    .BindConfiguration("EmailSettings")
    .ValidateDataAnnotations()
    .ValidateOnStart();
```

**Method 3 — Immediate binding (no DI):**
```csharp
var settings = builder.Configuration.GetSection("EmailSettings").Get<EmailSettings>()!;
```

## IOptionsMonitor with Change Callback

```csharp
public class CacheService : IDisposable
{
    private CacheSettings _settings;
    private readonly IDisposable? _changeListener;

    public CacheService(IOptionsMonitor<CacheSettings> monitor)
    {
        _settings = monitor.CurrentValue;
        _changeListener = monitor.OnChange(newSettings =>
        {
            _settings = newSettings;
            Console.WriteLine($"Cache updated: TTL={_settings.TtlMinutes}m");
        });
    }

    public void Dispose() => _changeListener?.Dispose();
}
```

## Anti-Patterns & Fixes

| Problem | Fix |
|---|---|
| `IConfiguration` everywhere (magic strings) | Use `IOptions<T>` for type safety |
| Secrets in `appsettings.json` | Use User Secrets (dev) or env vars (prod) |
| No validation on options | Use `ValidateDataAnnotations()` + `ValidateOnStart()` |
| `IOptions<T>` in Singleton needing live reload | Use `IOptionsMonitor<T>` |
| `IOptionsSnapshot<T>` in Singleton | **Runtime error** — use `IOptionsMonitor<T>` |

## Quick Checklist

- [ ] Config is in `appsettings.json` with environment overrides
- [ ] Options class created with `public const string SectionName`
- [ ] Registered in Program.cs with `Configure<T>()` or `AddOptions<T>().BindConfiguration()`
- [ ] Validation configured with `ValidateDataAnnotations()` and `ValidateOnStart()`
- [ ] Secrets stored in User Secrets (dev) or env vars (prod)
- [ ] Correct interface chosen: `IOptions<T>`, `IOptionsSnapshot<T>`, or `IOptionsMonitor<T>`
- [ ] `PostConfigure<T>()` used for computed defaults if needed

---

**See the full guide:** [C# Configuration & Options Pattern](csharp-configuration-options-pattern.md)


One-page quick reference for ASP.NET Core configuration, Options pattern, and DI registration patterns.

C# Configuration & Options Pattern - Cheatsheet


# C# Configuration & Options Pattern

Configuration is core to building maintainable ASP.NET Core apps. This post walks through the built-in layered configuration model, the Options pattern for strongly-typed settings, the differences between `IOptions<T>`, `IOptionsSnapshot<T>` and `IOptionsMonitor<T>`, named options, validation, and common anti-patterns.

## Configuration in ASP.NET Core

- ASP.NET Core uses a layered configuration system: multiple sources are combined and later sources override earlier ones.
- Default configuration sources (last wins):

```
1. appsettings.json
2. appsettings.{Environment}.json  (e.g., appsettings.Development.json)
3. User Secrets                     (Development only)
4. Environment Variables
5. Command-line arguments
```

- `appsettings.json` is the primary, file-based config store:

```json
{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=MyApp;Trusted_Connection=true"
  },
  "Logging": { "LogLevel": { "Default": "Information" } },
  "EmailSettings": {
    "SmtpHost": "smtp.example.com",
    "SmtpPort": 587,
    "FromAddress": "noreply@example.com",
    "EnableSsl": true
  },
  "FeatureFlags": { "EnableNewCheckout": false, "MaxRetries": 3 }
}
```

- You can access configuration directly via `IConfiguration` but that is error-prone (magic strings, no type-safety). Prefer the Options pattern.

```csharp
// IConfiguration - raw access (not recommended for most scenarios)
var smtpHost = builder.Configuration["EmailSettings:SmtpHost"];
var port = builder.Configuration.GetValue<int>("EmailSettings:SmtpPort");
var connStr = builder.Configuration.GetConnectionString("Default");
```

#### Sample appsetting
Assume the following setup: `appsettings.json` is used for all environments, and `appsettings.dev.json` is used when the `ASPNETCORE_ENVIRONMENT` is set to `dev`.
appsettings.json
```
  "MyApp": {
    "ApiKey": "my-key-12345"
  }
```

appsettings.dev.json
```
  "MyApp": {
    "ApiKey": "my-key-10000"
  }
```


appsettings.prd.json
```
// No ApiKey for MyApp in this file
```


Now, if you run `dotnet run`, you'll see different values depending on the environment:

- If you run with `ASPNETCORE_ENVIRONMENT=dev`, you'll get `my-key-10000` for **ApiKey**.
- If you run with `ASPNETCORE_ENVIRONMENT=prd`, the config will return `my-key-12345`.


#### Use user-secrets
You can use `user-secrets` to override config values from appsettings. User secrets allow you to store sensitive values on your local development machine, so you don't need to check credentials into the repo. For development or production, you can inject these values into the application from a Vault or environment variables.


```
dotnet user-secrets init
dotnet user-secrets set "MyApp:ApiKey" "99999"
dotnet user-secrets list
```


#### A few other commands for `user-secrets`
```
# Remove a secret
dotnet user-secrets remove "MyApp:ApiKey"

# Clear all secrets
dotnet user-secrets clear
```


#### Use Environment Variables
Running the following PowerShell command will override both appsettings and user-secrets:
```
# Set and run in one command (PowerShell)
$env:MyApp__ApiKey="secret"; dotnet run
```


#### Use command-line arguments
Command-line arguments will override all other configuration sources:
```
dotnet run --MyApp:ApiKey="command-line-key-12345"
```


## The Options Pattern (`IOptions<T>`)

- The Options pattern binds configuration sections to strongly-typed classes. This gives type-safety, validation, and easier testing.

```csharp
public class EmailSettings
{
    public const string SectionName = "EmailSettings";
    public string SmtpHost { get; init; } = string.Empty;
    public int SmtpPort { get; init; } = 587;
    public string FromAddress { get; init; } = string.Empty;
    public bool EnableSsl { get; init; } = true;
}

// Register in Program.cs
builder.Services.Configure<EmailSettings>(
    builder.Configuration.GetSection(EmailSettings.SectionName));

// Consume via DI
public class EmailSender
{
    private readonly EmailSettings _settings;
    public EmailSender(IOptions<EmailSettings> options) => _settings = options.Value;

    public async Task SendAsync(string to, string body, CancellationToken ct)
    {
        using var client = new SmtpClient(_settings.SmtpHost, _settings.SmtpPort);
        client.EnableSsl = _settings.EnableSsl;
        await client.SendMailAsync(new MailMessage(_settings.FromAddress, to, "Subject", body), ct);
    }
}
```

## `IOptions<T>` vs `IOptionsSnapshot<T>` vs `IOptionsMonitor<T>`

| Interface             |  Lifetime | Reloads on Change | Use Case                                                      |
| --------------------- | --------: | ----------------: | ------------------------------------------------------------- |
| `IOptions<T>`         | Singleton |                No | Settings that never change at runtime                         |
| `IOptionsSnapshot<T>` |    Scoped | Yes (per-request) | Settings that may change and are consumed in scoped services  |
| `IOptionsMonitor<T>`  | Singleton |        Yes (live) | Singleton services that need live reload and change callbacks |

- `IOptions<T>`: read once at startup — simplest and fastest. Use for secrets or values that won't change during runtime.

- `IOptionsSnapshot<T>`: refreshed per request/scope. Useful for feature flags or settings you may update and expect to take effect on the next request. Cannot be injected into Singleton services.

- `IOptionsMonitor<T>`: supports live reload and `OnChange` callbacks. Use when a Singleton needs to react to config changes.

```csharp
// Example: IOptionsMonitor with change callback
public class CacheService : IDisposable
{
    private CacheSettings _settings;
    private readonly IDisposable? _changeListener;

    public CacheService(IOptionsMonitor<CacheSettings> monitor)
    {
        _settings = monitor.CurrentValue;
        _changeListener = monitor.OnChange(newSettings =>
        {
            _settings = newSettings;
            Console.WriteLine($"Cache updated: TTL={newSettings.TtlMinutes}m");
        });
    }

    public void Dispose() => _changeListener?.Dispose();
}
```

## Named Options — multiple configurations of the same type

When you need multiple instances of the same settings class with different values (e.g., two blob containers), use named options:

```json
{
  "Storage": {
    "Images": { "ConnectionString": "...", "ContainerName": "images" },
    "Documents": { "ConnectionString": "...", "ContainerName": "documents" }
  }
}
```

```csharp
public class BlobStorageSettings { public string ConnectionString { get; init; } = string.Empty; public string ContainerName { get; init; } = string.Empty; }

builder.Services.Configure<BlobStorageSettings>("Images", builder.Configuration.GetSection("Storage:Images"));
builder.Services.Configure<BlobStorageSettings>("Documents", builder.Configuration.GetSection("Storage:Documents"));

public class StorageService
{
    private readonly IOptionsSnapshot<BlobStorageSettings> _options;
    public StorageService(IOptionsSnapshot<BlobStorageSettings> options) => _options = options;

    public string GetImageContainer() => _options.Get("Images").ContainerName;
    public string GetDocumentContainer() => _options.Get("Documents").ContainerName;
}
```

## Options Validation

Always validate options to catch misconfiguration early. You can use data annotations, inline validation, or implement `IValidateOptions<T>`.

```csharp
public class EmailSettings
{
    [Required]
    public string SmtpHost { get; init; } = string.Empty;

    [Range(1, 65535)]
    public int SmtpPort { get; init; } = 587;

    [Required, EmailAddress]
    public string FromAddress { get; init; } = string.Empty;
}

builder.Services
    .AddOptions<EmailSettings>()
    .BindConfiguration(EmailSettings.SectionName)
    .ValidateDataAnnotations()
    .ValidateOnStart();
```

Inline validation example:

```csharp
builder.Services
  .AddOptions<EmailSettings>()
  .BindConfiguration("EmailSettings")
  .Validate(settings => !string.IsNullOrWhiteSpace(settings.SmtpHost) && settings.SmtpPort is >=1 and <=65535, "EmailSettings validation failed")
  .ValidateOnStart();
```

Or implement reusable validation via `IValidateOptions<T>` for complex checks.

Note: `.ValidateOnStart()` is recommended so the app fails fast on invalid config, that way can detect the error earlier.
For example: if you app configured kafka credential, you asked devOps to setup the value but by some reason the value if misconfigured, would you still want to app to running and fail the API calls? or not let it start-up after the deployment?

## PostConfigure

Use `PostConfigure<T>` to compute defaults or derived values after binding, use this when want fallback logic for a config.
```csharp
builder.Services.PostConfigure<EmailSettings>(settings =>
{
    if (string.IsNullOrEmpty(settings.FromAddress))
        settings.FromAddress = $"noreply@{settings.SmtpHost}";
});
```

## Configuration Sources Quick Tips

- User Secrets: development-only secure storage for secrets outside source control (`dotnet user-secrets`).
- Environment variables: preferred in production (use `__` double-underscore to separate sections).
- Command-line args: useful for short-lived overrides during startup.

## Common Anti-Patterns

| Anti-Pattern                                  | Problem                             | Fix                                               |
| --------------------------------------------- | ----------------------------------- | ------------------------------------------------- |
| `IConfiguration` everywhere                   | Magic strings, no type safety       | Use `IOptions<T>`                                 |
| Secrets in `appsettings.json`                 | Committed to source control         | Use User Secrets (dev) or env vars (prod)         |
| No validation on options                      | Bad config causes runtime errors    | `ValidateDataAnnotations()` + `ValidateOnStart()` |
| `IOptions<T>` in Singleton that needs reloads | Values never update                 | Use `IOptionsMonitor<T>`                          |
| `IOptionsSnapshot<T>` in Singleton            | Runtime error (Scoped in Singleton) | Use `IOptionsMonitor<T>`                          |

## Binding Patterns

- `Configure<T>`: common, simple registration.
- `AddOptions<T>().BindConfiguration(...)` — supports validation and `ValidateOnStart()`.
- `Get<T>()` on `IConfigurationSection` — immediate binding (no DI).

## Summary — Configuration Checklist

| Topic                 | Key Takeaway                                                               |
| --------------------- | -------------------------------------------------------------------------- |
| Configuration sources | `appsettings.json` → env JSON → User Secrets → env vars → CLI              |
| Options pattern       | Bind config to strong types for safety and testability                     |
| `IOptions<T>`         | Singleton, read once — for static settings                                 |
| `IOptionsSnapshot<T>` | Scoped, refreshed per request — for changing settings in scoped services   |
| `IOptionsMonitor<T>`  | Singleton, live reload + `OnChange` — for singletons that react to updates |
| Named options         | Use when you need multiple configurations of same type                     |
| Validation            | Use data annotations or `IValidateOptions<T>` and `ValidateOnStart()`      |
| Secrets               | Don't store in source control — use User Secrets (dev) or env vars (prod)  |

---


Practical guide to configuration in ASP.NET Core using the Options pattern, validation, named options and reload strategies.

aspnet-core

C# Configuration & Options Pattern - Cheatsheet

C# Configuration & Options Pattern

Subscribe for Updates