Microsoft Extensions Configuration

aaronontheweb/dotnet-skills/skills/microsoft-extensions-configuration

作者 aarononthewebe426ed93a9f3無授權條款1.2K 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫3 週前更新

Microsoft.Extensions.Options patterns including IValidateOptions, strongly-typed settings, validation on startup, and the Options pattern for clean configuration management.

僅含說明Software Development
AI 產生的概覽

介紹 Microsoft.Extensions.Options 設定模式：強型別設定繫結、啟動時驗證，以及選項生命週期。

功能
此技能說明 .NET 中使用 Microsoft.Extensions.Options 的設定模式。內容涵蓋將 appsettings.json 設定區段繫結至強型別設定類別、透過資料註解與 IValidateOptions 在啟動時驗證設定，以及在 IOptions 、IOptionsSnapshot 與 IOptionsMonitor 之間做選擇。它也列出應避免的反模式，並指向一份參考檔案，說明帶相依性的驗證器與具名選項等進階模式。
適用情境
適用於在 .NET 應用程式中將設定繫結至強型別類別、在啟動時驗證設定，或實作複雜的跨屬性驗證規則。也適合用來判斷哪種選項介面符合服務的生命週期與設定重新載入需求。
執行需求
不需要指令碼或工具，僅為說明性內容。這些模式假定使用 .NET 應用程式與 Microsoft.Extensions.Options 及設定相關套件，設定通常來自 appsettings.json。

Microsoft.Extensions Configuration Patterns

When to Use This Skill

Use this skill when:

  • Binding configuration from appsettings.json to strongly-typed classes
  • Validating configuration at application startup (fail fast)
  • Implementing complex validation logic for settings
  • Designing configuration classes that are testable and maintainable
  • Understanding IOptions<T>, IOptionsSnapshot<T>, and IOptionsMonitor<T>

Reference Files

  • advanced-patterns.md [blocked]: Validators with dependencies, named options, complete production example (AkkaSettings), and testing validators

Why Configuration Validation Matters

The Problem: Applications often fail at runtime due to misconfiguration - missing connection strings, invalid URLs, out-of-range values. These failures happen deep in business logic, far from where configuration is loaded.

The Solution: Validate configuration at startup. If invalid, fail immediately with a clear error message.

csharp
// BAD: Fails at runtime when someone tries to use the servicepublic class EmailService{    public EmailService(IOptions<SmtpSettings> options)    {        var settings = options.Value;        // Throws NullReferenceException 10 minutes into production        _client = new SmtpClient(settings.Host, settings.Port);    }}
// GOOD: Fails at startup with clear error// "SmtpSettings validation failed: Host is required"

Pattern 1: Basic Options Binding

Define a Settings Class

csharp
public class SmtpSettings{    public const string SectionName = "Smtp";
    public string Host { get; set; } = string.Empty;    public int Port { get; set; } = 587;    public string? Username { get; set; }    public string? Password { get; set; }    public bool UseSsl { get; set; } = true;}

Bind from Configuration

csharp
builder.Services.AddOptions<SmtpSettings>()    .BindConfiguration(SmtpSettings.SectionName);
// appsettings.json{  "Smtp": {    "Host": "smtp.example.com",    "Port": 587,    "Username": "[email protected]",    "Password": "secret",    "UseSsl": true  }}

Consume in Services

csharp
public class EmailService{    private readonly SmtpSettings _settings;
    // IOptions<T> - singleton, read once at startup    public EmailService(IOptions<SmtpSettings> options)    {        _settings = options.Value;    }}

Pattern 2: Data Annotations Validation

For simple validation rules, use Data Annotations:

csharp
using System.ComponentModel.DataAnnotations;
public class SmtpSettings{    public const string SectionName = "Smtp";
    [Required(ErrorMessage = "SMTP host is required")]    public string Host { get; set; } = string.Empty;
    [Range(1, 65535, ErrorMessage = "Port must be between 1 and 65535")]    public int Port { get; set; } = 587;
    [EmailAddress(ErrorMessage = "Username must be a valid email address")]    public string? Username { get; set; }
    public string? Password { get; set; }    public bool UseSsl { get; set; } = true;}

Enable Data Annotations Validation

csharp
builder.Services.AddOptions<SmtpSettings>()    .BindConfiguration(SmtpSettings.SectionName)    .ValidateDataAnnotations()  // Enable attribute-based validation    .ValidateOnStart();         // Validate immediately at startup

Key Point: .ValidateOnStart() is critical. Without it, validation only runs when the options are first accessed.

Pattern 3: IValidateOptions<T> for Complex Validation

Data Annotations work for simple rules, but complex validation requires IValidateOptions<T>:

ScenarioData AnnotationsIValidateOptions
Required fieldYesYes
Range checkYesYes
Cross-property validationNoYes
Conditional validationNoYes
External service checksNoYes
Dependency injection in validatorNoYes

Implementing IValidateOptions

csharp
using Microsoft.Extensions.Options;
public class SmtpSettingsValidator : IValidateOptions<SmtpSettings>{    public ValidateOptionsResult Validate(string? name, SmtpSettings options)    {        var failures = new List<string>();
        if (string.IsNullOrWhiteSpace(options.Host))            failures.Add("Host is required");
        if (options.Port is < 1 or > 65535)            failures.Add($"Port {options.Port} is invalid. Must be between 1 and 65535");
        // Cross-property validation        if (!string.IsNullOrEmpty(options.Username) && string.IsNullOrEmpty(options.Password))            failures.Add("Password is required when Username is specified");
        // Conditional validation        if (options.UseSsl && options.Port == 25)            failures.Add("Port 25 is typically not used with SSL. Consider port 465 or 587");
        return failures.Count > 0            ? ValidateOptionsResult.Fail(failures)            : ValidateOptionsResult.Success;    }}

Register the Validator

csharp
builder.Services.AddOptions<SmtpSettings>()    .BindConfiguration(SmtpSettings.SectionName)    .ValidateDataAnnotations()    .ValidateOnStart();
builder.Services.AddSingleton<IValidateOptions<SmtpSettings>, SmtpSettingsValidator>();

Order matters: Data Annotations run first, then IValidateOptions validators. All failures are collected together.

See advanced-patterns.md [blocked] for validators with dependencies, named options, and a complete production example.

Pattern 4: Options Lifetime

InterfaceLifetimeReloads on ChangeUse Case
IOptions<T>SingletonNoStatic config, read once
IOptionsSnapshot<T>ScopedYes (per request)Web apps needing fresh config
IOptionsMonitor<T>SingletonYes (with callback)Background services, real-time updates

IOptionsMonitor for Background Services

csharp
public class BackgroundWorker : BackgroundService{    private readonly IOptionsMonitor<WorkerSettings> _optionsMonitor;    private WorkerSettings _currentSettings;
    public BackgroundWorker(IOptionsMonitor<WorkerSettings> optionsMonitor)    {        _optionsMonitor = optionsMonitor;        _currentSettings = optionsMonitor.CurrentValue;
        _optionsMonitor.OnChange(settings =>        {            _currentSettings = settings;        });    }
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)    {        while (!stoppingToken.IsCancellationRequested)        {            await DoWorkAsync();            await Task.Delay(_currentSettings.PollingInterval, stoppingToken);        }    }}

Pattern 5: Post-Configuration

Modify options after binding but before validation:

csharp
builder.Services.AddOptions<ApiSettings>()    .BindConfiguration("Api")    .PostConfigure(options =>    {        if (!string.IsNullOrEmpty(options.BaseUrl) && !options.BaseUrl.EndsWith('/'))            options.BaseUrl += '/';
        options.Timeout ??= TimeSpan.FromSeconds(30);    })    .ValidateDataAnnotations()    .ValidateOnStart();

Anti-Patterns to Avoid

1. Manual Configuration Access

csharp
// BAD: Bypasses validation, hard to testpublic class MyService{    public MyService(IConfiguration configuration)    {        var host = configuration["Smtp:Host"]; // No validation!    }}
// GOOD: Strongly-typed, validatedpublic class MyService{    public MyService(IOptions<SmtpSettings> options)    {        var host = options.Value.Host; // Validated at startup    }}

2. Validation in Constructor

csharp
// BAD: Validation happens at runtime, not startuppublic class MyService{    public MyService(IOptions<Settings> options)    {        if (string.IsNullOrEmpty(options.Value.Required))            throw new ArgumentException("Required is missing"); // Too late!    }}
// GOOD: Validation at startup via IValidateOptions + ValidateOnStart()

3. Forgetting ValidateOnStart

csharp
// BAD: Validation only runs when first accessedbuilder.Services.AddOptions<Settings>()    .ValidateDataAnnotations(); // Missing ValidateOnStart!
// GOOD: Fails immediately if invalidbuilder.Services.AddOptions<Settings>()    .ValidateDataAnnotations()    .ValidateOnStart();

4. Throwing in IValidateOptions

csharp
// BAD: Throws exception, breaks validation chainpublic ValidateOptionsResult Validate(string? name, Settings options){    if (options.Value < 0)        throw new ArgumentException("Value cannot be negative"); // Wrong!    return ValidateOptionsResult.Success;}
// GOOD: Return failure resultpublic ValidateOptionsResult Validate(string? name, Settings options){    if (options.Value < 0)        return ValidateOptionsResult.Fail("Value cannot be negative");    return ValidateOptionsResult.Success;}

Summary

PrincipleImplementation
Fail fast.ValidateOnStart()
Strongly-typedBind to POCO classes
Simple validationData Annotations
Complex validationIValidateOptions<T>
Cross-property rulesIValidateOptions<T>
Environment-awareInject IHostEnvironment
TestableValidators are plain classes

來源與署名

來源：aaronontheweb/dotnet-skills位於skills/microsoft-extensions-configuration提交e426ed9

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 aaronontheweb/dotnet-skills 的技能

Snapshot Testing

aaronontheweb

說明如何在 .NET 中使用 Verify 進行快照測試，用來審核 API 介面、HTTP 回應、郵件與序列化輸出。

Software Development1.2K3 週前更新

Serialization

aaronontheweb

指導 .NET 開發者選擇序列化格式，並移轉到以結構描述為基礎、相容於 AOT 的序列化方式。

Software Development1.2K3 週前更新

Package Management

aaronontheweb

指導使用 dotnet CLI 命令與集中套件管理（CPM）來管理 .NET 專案中的 NuGet 套件。

Software Development1.2K3 週前更新

Mjml Email Templates

aaronontheweb

建置可編譯為跨用戶端 HTML 的響應式 MJML 郵件範本，包含 .NET 渲染器與變數替換。

Communication1.2K3 週前更新

Efcore Patterns

aaronontheweb

Entity Framework Core 模式指引：預設不追蹤查詢、移轉、查詢分割與大量作業。

Software Development1.2K3 週前更新

Csharp Concurrency Patterns

aaronontheweb

指導 .NET 開發者選擇並行抽象，從 async/await 到 Channel 與 Akka.NET actor。

Software Development1.2K3 週前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新