0Pricing
C# Academy · レッスン

Optionsの検証と名前付きOptions

DataAnnotationsまたはFluentValidationで起動時にOptionsを検証し、複数のインスタンスには名前付きOptionsを使います。

「Optionsの検証と名前付きOptions」はCoddyKit上の無料C# Academyレッスンです。 これはレッスン3/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはC# Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 C# Academyコースには全4レッスンが含まれています。

オプションを検証する理由

構成の欠落や形式不正は、追跡が難しい実行時エラーを引き起こします。起動時にオプションを検証すれば、ひそかな構成バグを、リクエストの処理を開始する前に、明確な説明付きの例外として表面化できます。

ValidateOnStart

ValidateOnStart()は、最初に使用するときに遅延して検証するのではなく、アプリの起動時に直ちに検証を実行します。これにより、構成ミスのあるデプロイは数時間後ではなく即座に失敗します。

builder.Services
    .AddOptions<DatabaseOptions>()
    .BindConfiguration("Database")
    .ValidateDataAnnotations()
    .ValidateOnStart(); // throw OptionsValidationException on startup

// Without ValidateOnStart:
// - Validation only runs on first IOptions<T>.Value access
// - A rarely-used service could run for hours before failing

// With ValidateOnStart:
// - App fails at Host.Run() if config is invalid
// - Health checks and probes never report healthy for bad config

DataAnnotationsによる検証

オプションクラスで標準のSystem.ComponentModel.DataAnnotations属性を使用します。ValidateDataAnnotations()によって自動的に評価されます。

using System.ComponentModel.DataAnnotations;

public class EmailOptions
{
    [Required(ErrorMessage = "SMTP host is required")]
    [MinLength(3)]
    public string SmtpHost { get; set; } = string.Empty;

    [Range(1, 65535, ErrorMessage = "Port must be 1-65535")]
    public int SmtpPort { get; set; } = 587;

    [Required]
    [EmailAddress(ErrorMessage = "Invalid sender address")]
    public string SenderAddress { get; set; } = string.Empty;

    [Range(1, 30)]
    public int TimeoutSeconds { get; set; } = 10;
}

builder.Services
    .AddOptions<EmailOptions>()
    .BindConfiguration("Email")
    .ValidateDataAnnotations()
    .ValidateOnStart();

カスタム検証デリゲート

Validate(Func<T, bool>, string)オーバーロードを使用すると、属性では表現できないルール（複数プロパティにまたがる制約など）に対応するラムダを追加できます。

builder.Services
    .AddOptions<ConnectionPoolOptions>()
    .BindConfiguration("ConnectionPool")
    .ValidateDataAnnotations()
    .Validate(
        opts => opts.MaxSize >= opts.MinSize,
        "MaxSize must be greater than or equal to MinSize")
    .Validate(
        opts => opts.ConnectionTimeoutMs > 0,
        "ConnectionTimeoutMs must be positive")
    .ValidateOnStart();

public class ConnectionPoolOptions
{
    [Range(1, 100)] public int MinSize { get; set; } = 2;
    [Range(1, 500)] public int MaxSize { get; set; } = 20;
    public int ConnectionTimeoutMs { get; set; } = 5000;
}

複雑なルールに対するIValidateOptions

複数のエラーメッセージを伴う複雑なロジックには、IValidateOptions<T>を実装します。オプションのインスタンスを受け取り、詳細な失敗メッセージを含む結果を返します。

public class PaymentOptionsValidator : IValidateOptions<PaymentOptions>
{
    public ValidateOptionsResult Validate(string? name, PaymentOptions opts)
    {
        var failures = new List<string>();

        if (opts.Provider == "Stripe" && string.IsNullOrWhiteSpace(opts.StripeSecretKey))
            failures.Add("StripeSecretKey is required when Provider is Stripe");

        if (opts.Provider == "PayPal" && string.IsNullOrWhiteSpace(opts.PayPalClientId))
            failures.Add("PayPalClientId is required when Provider is PayPal");

        if (opts.RetryCount < 0 || opts.RetryCount > 5)
            failures.Add("RetryCount must be between 0 and 5");

        return failures.Count == 0
            ? ValidateOptionsResult.Success
            : ValidateOptionsResult.Fail(failures);
    }
}

builder.Services.AddSingleton<IValidateOptions<PaymentOptions>, PaymentOptionsValidator>();

名前付きオプションの概念

名前付きオプションを使用すると、同じオプション型について複数の構成を登録できます。一般的な用途は、ベースURLやタイムアウトがそれぞれ異なる複数の外向きHTTPクライアントです。

// appsettings.json:
{
  "HttpClients": {
    "Orders": {
      "BaseUrl": "https://orders-service",
      "TimeoutSeconds": 30
    },
    "Inventory": {
      "BaseUrl": "https://inventory-service",
      "TimeoutSeconds": 10
    }
  }
}

public class HttpClientOptions
{
    public string BaseUrl { get; set; } = string.Empty;
    public int TimeoutSeconds { get; set; } = 30;
}

名前付きオプションの登録

Configure<T>の最初の引数として名前文字列を渡します。特定のインスタンスを解決するには、IOptionsMonitor<T>.Get(name)を使用します。

// Register:
builder.Services.Configure<HttpClientOptions>("Orders",
    builder.Configuration.GetSection("HttpClients:Orders"));
builder.Services.Configure<HttpClientOptions>("Inventory",
    builder.Configuration.GetSection("HttpClients:Inventory"));

// Consume:
public class ApiGateway
{
    private readonly HttpClientOptions _orders;
    private readonly HttpClientOptions _inventory;

    public ApiGateway(IOptionsMonitor<HttpClientOptions> monitor)
    {
        _orders    = monitor.Get("Orders");
        _inventory = monitor.Get("Inventory");
    }

    // IOptions<T>.Value always returns the unnamed (default) instance
    // IOptionsMonitor<T>.Get(name) returns the named instance
}

検証付き名前付きオプション

名前付き登録ごとにAddOptions<T>(name)を呼び出すことで、名前付きオプションを個別に検証できます。

foreach (var clientName in new[] { "Orders", "Inventory", "Auth" })
{
    builder.Services
        .AddOptions<HttpClientOptions>(clientName)
        .BindConfiguration($"HttpClients:{clientName}")
        .ValidateDataAnnotations()
        .Validate(
            opts => Uri.IsWellFormedUriString(opts.BaseUrl, UriKind.Absolute),
            $"HttpClients:{clientName}:BaseUrl must be a valid absolute URI")
        .ValidateOnStart();
}

// If any named instance fails, the app refuses to start

OptionsBuilder API

AddOptions<T>()によって返されるOptionsBuilder<T>は、登録、バインド、検証の各手順をきれいにチェーンできる流暢なAPIです。

// Full OptionsBuilder chain:
builder.Services
    .AddOptions<DatabaseOptions>()        // create builder
    .BindConfiguration("Database")         // bind JSON section
    .Configure(opts =>                     // manual override
    {
        if (builder.Environment.IsDevelopment())
            opts.EnableDetailedErrors = true;
    })
    .PostConfigure(opts =>                 // runs after all Configure
    {
        opts.ConnectionString ??= "default-fallback";
    })
    .ValidateDataAnnotations()             // attribute rules
    .Validate(o => o.MaxPoolSize > 0,
              "MaxPoolSize must be positive")
    .ValidateOnStart();                    // eager validation

実例：再試行ポリシーのオプション

フィールド間の検証と、サービスごとの名前付きポリシーを備えた、完全な再試行オプションの構成例です。

public class RetryOptions
{
    [Range(0, 10)] public int MaxAttempts { get; set; } = 3;
    [Range(100, 60000)] public int BaseDelayMs { get; set; } = 500;
    public bool UseExponentialBackoff { get; set; } = true;
    [Range(1, 120000)] public int MaxDelayMs { get; set; } = 30000;
}

foreach (var policy in new[] { "Database", "HttpClient", "MessageBus" })
{
    builder.Services
        .AddOptions<RetryOptions>(policy)
        .BindConfiguration($"RetryPolicies:{policy}")
        .Validate(o => !o.UseExponentialBackoff || o.MaxDelayMs > o.BaseDelayMs,
                  "MaxDelayMs must exceed BaseDelayMs when using exponential backoff")
        .ValidateOnStart();
}

クイックチェック

オプションの登録時にValidateOnStart()を呼び出す利点は何ですか？

まとめ：オプションの検証と名前付きオプション

重要なポイント：

  • ValidateOnStart()：最初の使用時ではなく、起動時に失敗させます
  • DataAnnotations：[Required]、[Range]などとValidateDataAnnotations()を使用します
  • Validate(Func, message)：複数プロパティにまたがるルールのためのインラインラムダです
  • IValidateOptions<T>：複数のエラーに対応する、プログラムによる完全な検証です
  • 名前付きオプション：Configure<T>(name, ...)とIOptionsMonitor<T>.Get(name)を使用します
  • OptionsBuilder<T>：すべての登録手順をチェーンする流暢なAPIです

よくある質問

「Optionsの検証と名前付きOptions」レッスンは無料ですか？

はい。「Optionsの検証と名前付きOptions」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、C# Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 C# Academyコースには全4レッスンが含まれています。

「Optionsの検証と名前付きOptions」で何を学びますか？

DataAnnotationsまたはFluentValidationで起動時にOptionsを検証し、複数のインスタンスには名前付きOptionsを使います。 ブラウザで直接実行するハンズオンコードでC# Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

C# Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのC# Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン3/4です。

「Optionsの検証と名前付きOptions」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このC# Academyレッスンでコードを書いて実行できますか？

はい。すべてのC# Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. 構成ソースとプロバイダー
  2. IOptionsによる強く型付けされたOptions
  3. Optionsの検証と名前付きOptions
  4. シークレット管理
← C# Academyに戻る