The Options Pattern in .NET: A Practical Before-and-After for API Developers

If you’ve ever found yourself tangled in configuration messes while building APIs in .NET hardcoding keys, juggling environment switches, or praying a typo doesn’t take down prod this one’s for you.

I’ll walk you through a real-world scenario I’ve seen (and lived through), showing how the Options Pattern turns chaos into clarity. You’ll see the “ugh, I’ve been there” moment, the cleaner fix, and why it’s worth it by the end of the day—both in code and ROI.

The “Before” Struggle: A Relatable Mess

you’re on a team building an API that talks to a payment gateway. You need an API key to authenticate requests, and it’s different for dev, staging, and prod. Day one, you’re rushing to get it working, so you slap this into your PaymentService:

//Sample Code For Mental Model
public class PaymentService
{
    private readonly string _apiKey = "dev-key-12345";

    public async Task<string> ProcessPaymentAsync(decimal amount)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {_apiKey}");
        var response = await client.PostAsync("https://api.paymentgateway.com/v1/payments", null);
        return await response.Content.ReadAsStringAsync();
    }
}

It works! You push it to dev, and everyone’s happy until reality hits:

• Prod deployment looms*: You need to swap _apiKey to prod-key-0930. That’s a code change, rebuild, and redeploy. Miss it? Payments fail.*

• Team chaos*: Another dev adds a second service using the same gateway. They copy-paste _apiKey. Now it’s in two places, and when it changes, good luck syncing it.*

• Security oops*: You accidentally commit prod-key-0930 to GitHub. Cue the panic.*

• Testing woes*: Unit tests use the hardcoded dev-key-12345. Want to mock it? You’re rewriting the class.*

Note: In production code, you'd typically use HttpClientFactory instead of creating new HttpClient instances directly, which helps with DNS changes and socket exhaustion issues.

By the end of the day, you’re debugging why staging has the dev key, cursing the duplication, and praying nobody saw that commit. Sound familiar?

The “After” Fix: Options Pattern Magic

Now, let’s flip this with the Options Pattern. Same scenario, but smarter. Here’s how it goes:

Step 1: Move Config to appsettings.json

Stick your API key in a config file—say, appsettings.Development.json for dev:

{
  "PaymentGateway": {
    "ApiKey": "dev-key-12345"
  }
}

And appsettings.Production.json for prod:

{
  "PaymentGateway": {
    "ApiKey": "prod-key-0930"
  }
}

Step 2: Define a Clean Options Class

Create a simple POCO to hold the settings:

public class PaymentGatewayOptions
{
    public string ApiKey { get; set; }
}

Step 3: Wire It Up in Program.cs

var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<PaymentGatewayOptions>(
    builder.Configuration.GetSection("PaymentGateway")
);
builder.Services.AddScoped<PaymentService>();
// Build and run the app

Step 4: Inject It Into Your Service

public class PaymentService
{
    private readonly string _apiKey;

    public PaymentService(IOptions<PaymentGatewayOptions> options)
    {
        _apiKey = options.Value.ApiKey;
    }

    public async Task<string> ProcessPaymentAsync(decimal amount)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {_apiKey}");
        var response = await client.PostAsync("https://api.paymentgateway.com/v1/payments", null);
        return await response.Content.ReadAsStringAsync();
    }
}

What Changed

Before vs. After: The Options Pattern in Action

By the end of the day, your code’s cleaner, your team’s not scrambling, and you’re not sweating a security breach.

The Flow

Configuration Sources: Your settings can come from various places JSON files, environment variables, secret stores, or command-line arguments. The best part is that your application code doesn't need to know or worry about which one is used.

The ROI

Here’s where it pays off—tangible wins you’ll notice fast:

• Time Saved: No more “why is this key wrong?” debugging. Config errors surface at startup, not mid-transaction.

• Team Win: New dev asks, “Where’s the API key?” You say, “Check appsettings.json.” Done.

• Future-Proof: Add a timeout or endpoint to PaymentGatewayOptions later? It’s one class tweak, not a service overhaul.

Security Benefits: More Than Just Convenience

While the Options Pattern organizes your configuration nicely, it also brings significant security advantages:

With this approach, your sensitive API keys never touch your codebase or even your appsettings.json files they're loaded directly from your secure vault at runtime.

• Local Development*: Developers use user secrets (dotnet user-secrets)*

• CI/CD Pipelines*: Build systems use pipeline variables*

• Production*: Deployed apps use managed identity to access Key Vault*

All without changing a single line of code in your services!

1. Credentials never exist in code

2. Each environment uses isolated configuration sources

3. Production secrets are managed through formal access controls

4. Configuration changes are versioned and logged

The Options Pattern transforms configuration from a security liability into a security asset.

Bonus: Validating Your Options

Here's another win making your app fail fast with invalid configuration. Let's add validation to catch problems at startup, not during a critical transaction:

// Update your options class with validation attributes
public class PaymentGatewayOptions
{
    [Required(ErrorMessage = "API Key is required")]
    [MinLength(10, ErrorMessage = "API Key must be at least 10 characters")]
    public string ApiKey { get; set; }

    [Range(1, 60, ErrorMessage = "Timeout must be between 1 and 60 seconds")]
    public int TimeoutSeconds { get; set; } = 30;
}

// Update your Program.cs to validate options
builder.Services.AddOptions<PaymentGatewayOptions>()
    .Bind(builder.Configuration.GetSection("PaymentGateway"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

With this simple change, your application will:

• Refuse to start if the API key is missing or too short

• Validate that timeout values are reasonable

• Fail clearly and immediately, not when a payment is being processed

When a validation error occurs, you'll get a detailed exception message like: "PaymentGatewayOptions.ApiKey: API Key is required." No more mysterious failures hours after deployment!

Going Deeper: Options Interfaces for Different Needs

// For settings that don't change during the app's lifetime
// Best for most cases, including our PaymentService
public PaymentService(IOptions<PaymentGatewayOptions> options)
{
    _apiKey = options.Value.ApiKey;
}

// For settings that might change with each request
// Perfect for controllers or request-scoped services
public PaymentController(IOptionsSnapshot<PaymentGatewayOptions> options)
{
    _options = options.Value; // Updated on every request
}

// For long-running services that need change notifications
public BackgroundProcessor(IOptionsMonitor<PaymentGatewayOptions> options)
{
    _options = options.CurrentValue;
    // Register for changes
    options.OnChange(updatedOptions => 
    {
        _options = updatedOptions;
        Console.WriteLine("Payment gateway options were updated!");
    });
}

Which one should you use?

• IOptions*: Simple singleton, best for most services*

• IOptionsSnapshot*: Updated per request, ideal for web controllers*

• IOptionsMonitor*: Singleton with change notifications for background services*

No extra complexity until you need it start with IOptions and graduate to the others when specific scenarios arise.

✨ Happy Coding!