dotnet-csharp-configuration

name	dotnet-csharp-configuration
category	fundamentals
subcategory	di-and-services
description	Configures Options pattern, user secrets, and feature flags. IOptions<T>, FeatureManagement.
license	MIT
targets	["*"]
tags	["csharp","dotnet","skill"]
version	0.0.1
author	dotnet-agent-harness
invocable	true
claudecode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
codexcli	{"short-description":".NET skill guidance for csharp tasks"}
opencode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
copilot	{}
geminicli	{}
antigravity	{}

dotnet-csharp-configuration

Configuration patterns for .NET applications using Microsoft.Extensions.Configuration and Microsoft.Extensions.Options. Covers the Options pattern (IOptions<T>, IOptionsMonitor<T>, IOptionsSnapshot<T>), validation, user secrets, environment-based configuration, and feature flags with Microsoft.FeatureManagement.

Scope

• Options pattern (IOptions, IOptionsMonitor, IOptionsSnapshot)
• Options validation and ValidateOnStart
• User secrets and environment-based configuration
• Feature flags with Microsoft.FeatureManagement
• Configuration source precedence

Out of scope

• DI container mechanics and service lifetimes -- see [skill:dotnet-csharp-dependency-injection]
• EditorConfig and analyzer rule configuration -- see [skill:dotnet-editorconfig]
• Structured logging pipeline configuration -- see [skill:dotnet-structured-logging]

Cross-references: [skill:dotnet-csharp-dependency-injection] for service registration patterns, [skill:dotnet-csharp-coding-standards] for naming conventions.

---

Configuration Sources and Precedence

Default configuration sources in WebApplication.CreateBuilder (last wins):

1. appsettings.json
2. appsettings.{Environment}.json
3. User secrets (Development only)
4. Environment variables
5. Command-line arguments

var builder = WebApplication.CreateBuilder(args);
// Sources above are loaded automatically. Add custom sources:
builder.Configuration.AddJsonFile("features.json", optional: true, reloadOnChange: true);

```csharp

---

## Options Pattern

Bind configuration sections to strongly typed classes and inject them via DI.

### Defining Options Classes

```csharp

public sealed class SmtpOptions
{
    public const string SectionName = ;

      Host { ; ; } = ;
      Port { ; ; } = ;
      FromAddress { ; ; } = ;
      UseSsl { ; ; } = ;
}

```text

> Options classes use `{ ; ; }` ( ``) because the configuration binder  `PostConfigure` need to mutate
> properties. Use `[Required]` via data annotations  mandatory fields instead.



```csharp

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

```text



```json

{
  : {
    : ,
    : ,
    : ,
    : 
  }
}

```text

---



| Interface             | Lifetime  | Reload Behavior                   | Use Case                        |
| --------------------- | --------- | --------------------------------- | ------------------------------- |
| `IOptions<T>`         | Singleton | Never reloads after startup       | Static config, most services    |
| `IOptionsSnapshot<T>` | Scoped    | Reloads per request/scope         | Per-request config  ASP.NET   |
| `IOptionsMonitor<T>`  | Singleton | Live reload + change notification | Singletons, background services |



```csharp



{
      SmtpOptions _smtp = options.Value;

    
    {
        
         Task.CompletedTask;
    }
}



{
    
        => monitor.CurrentValue.EnabledFeatures.Contains(feature);
}



{
     => snapshot.Value.MarkupPercent;
}

```text



```csharp

    : 
{
      IDisposable? _changeListener;
     CacheOptions _current;

    
    {
        _current = monitor.CurrentValue;
        _changeListener = monitor.OnChange(updated =>
        {
            _current = updated;
            
        });
    }

     => _changeListener?.Dispose();
}

```text

---





```csharp

 System.ComponentModel.DataAnnotations;

   
{
       SectionName = ;

    []
      Host { ; ; } = ;

    []
      Port { ; ; } = ;

    []
      FromAddress { ; ; } = ;
}

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

```text



Use  validation logic requires cross-property checks  external dependencies.

```csharp

    : <>
{
    
    {
         failures =  List<>();

         (options.UseSsl && options.Port == )
        {
            failures.Add();
        }

         (.IsNullOrWhiteSpace(options.Host))
        {
            failures.Add();
        }

         failures.Count > 
            ? ValidateOptionsResult.Fail(failures)
            : ValidateOptionsResult.Success;
    }
}


builder.Services.AddSingleton<IValidateOptions<SmtpOptions>, SmtpOptionsValidator>();

```text



Always use `.ValidateOnStart()` to surface configuration errors at startup instead of at first resolution. Without it,
invalid config only throws  `IOptions<T>.Value`  first accessed.

---



Store sensitive values outside source control during development.

```bash


dotnet user-secrets 


dotnet user-secrets   
dotnet user-secrets   


dotnet user-secrets list


dotnet user-secrets clear

```text

User secrets are stored  `~/.microsoft/usersecrets/<UserSecretsId>/secrets.json`   `appsettings.json`
values  Development.

**Key rules:**

- Never use user secrets  production -- use environment variables, Azure Key Vault,  other vault providers
- User secrets are loaded automatically  `ASPNETCORE_ENVIRONMENT=Development`
- For non-web hosts, explicitly : `builder.Configuration.AddUserSecrets<Program>()`

---





```csharp





```csharp



```text

appsettings.json                 
appsettings.Development.json     
appsettings.Staging.json         
appsettings.Production.json      

```json

```csharp



 env = builder.Environment.EnvironmentName; 

```csharp



```
{
    builder.Services.AddSingleton<IEmailSender, ConsoleEmailSender>();
}

{
    builder.Services.AddSingleton<IEmailSender, SmtpEmailSender>();
}

```text

---



`Microsoft.FeatureManagement.AspNetCore` provides structured feature flag support  filters, targeting,  gradual
rollout.



```bash

dotnet  package Microsoft.FeatureManagement.AspNetCore

```bash

```csharp

builder.Services.AddFeatureManagement();

```csharp



```json

{
  : {
    : ,
    : {
      : [
        {
          : ,
          : { :  }
        }
      ]
    },
    : {
      : [
        {
          : ,
          : {
            : {
              : [],
              : [{ : , :  }],
              : 
            }
          }
        }
      ]
    }
  }
}

```text



```csharp



{
    []
    
    {
         ( featureManager.IsEnabledAsync())
        {
             Ok( { version = , dashboard =  });
        }

         Ok( { version = , dashboard =  });
    }
}

```text



```csharp


[]
[]

{
     results =  _searchService.SearchAsync(query, ct);
     Ok(results);
}

```text



| Filter       | Purpose                                                  |
| ------------ | -------------------------------------------------------- |
| `Percentage` | Enable  N% 
{
    
    {
         userAgent = accessor.HttpContext?.Request.Headers.UserAgent.ToString() ?? ;
         settings = context.Parameters.Get<BrowserFilterSettings>();

         Task.FromResult(
            settings?.AllowedBrowsers?.Any(b =>
                userAgent.Contains(b, StringComparison.OrdinalIgnoreCase)) ?? );
    }
}

   
{
     [] AllowedBrowsers { ; ; } = [];
}


builder.Services.AddFeatureManagement()
    .AddFeatureFilter<BrowserFeatureFilter>();

```text

---



;

builder.Services
    .AddOptions<ApiClientOptions>()
    .BindConfiguration();



{
    
    {
         options = snapshot.Get(name); 
          HttpClient { BaseAddress =  Uri(options.BaseUrl) };
    }
}

```text

---



Apply defaults  overrides after all configuration sources have been processed.

```csharp

builder.Services.PostConfigure<SmtpOptions>(options =>
{
    
     (options.Port == )
    {
        options.Port = options.UseSsl ?  : ;
    }
});

```text

---



```csharp

[]

{
     options =  SmtpOptions
    {
        Host = ,
        FromAddress = ,
        Port = ,
        UseSsl = 
    };

     validator =  SmtpOptionsValidator();
     result = validator.Validate(, options);

    Assert.True(result.Failed);
    Assert.Contains(, result.FailureMessage);
}

[]

{
     config =  ConfigurationBuilder()
        .AddInMemoryCollection( Dictionary<, ?>
        {
            [] = ,
            [] = ,
            [] = ,
        })
        .Build();

     options =  SmtpOptions();
    config.GetSection().Bind(options);

    Assert.Equal(, options.Host);
    Assert.Equal(, options.Port);
}

```text

---





**Primary approach:** Use Serena symbol operations  efficient code navigation:

 **Find definitions**: `serena_find_symbol` instead of text search
 **Understand structure**: `serena_get_symbols_overview`   organization
 **Track references**: `serena_find_referencing_symbols`  impact analysis
 **Precise edits**: `serena_replace_symbol_body`  clean modifications

**When to use Serena vs traditional tools:**
- ✅ **Use Serena**: Navigation, refactoring, dependency analysis, precise edits
- ✅ **Use Read/Grep**: Reading full files, pattern matching, simple text operations
- ✅ **Fallback**: If Serena unavailable, traditional tools work fine

**Example workflow:**
```text

Read: src/Services/OrderService.cs
Grep: 


serena_find_symbol: 
serena_get_symbols_overview: 
```


- [Options pattern  .NET](https:
- [Configuration  .NET](https:
- [User secrets  development](https:
- [Feature management  .NET](https:
- [IValidateOptions](https:
- [.NET Framework Design Guidelines](https: