0Pricing
C# Academy · Lekcja

Walidacja opcji i opcje nazwane

Waliduj opcje podczas uruchamiania za pomocą DataAnnotations lub FluentValidation oraz używaj opcji nazwanych dla wielu instancji.

Walidacja opcji i opcje nazwane to bezpłatna lekcja C# Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej C# Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs C# Academy zawiera 4 lekcji w sumie.

Dlaczego warto walidować opcje?

Brakująca lub nieprawidłowo sformatowana konfiguracja powoduje błędy w czasie działania, które trudno prześledzić. Walidacja opcji podczas uruchamiania zamienia ciche błędy konfiguracji w jednoznaczne, szczegółowe wyjątki, zanim zostanie obsłużone jakiekolwiek żądanie.

ValidateOnStart

ValidateOnStart() uruchamia walidację natychmiast podczas startu aplikacji, a nie dopiero przy pierwszym użyciu. Dzięki temu nieprawidłowo skonfigurowane wdrożenie kończy się błędem od razu, zamiast dopiero po kilku godzinach.

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

Walidacja za pomocą DataAnnotations

Użyj standardowych atrybutów System.ComponentModel.DataAnnotations w klasie opcji. Są one automatycznie sprawdzane przez 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();

Delegat niestandardowej walidacji

Przeciążenie Validate(Func<T, bool>, string) dodaje lambdę dla reguł, których nie można wyrazić za pomocą atrybutów, takich jak ograniczenia dotyczące wielu właściwości.

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 dla złożonych reguł

W przypadku złożonej logiki obejmującej wiele komunikatów o błędach zaimplementuj IValidateOptions<T>. Otrzymuje ono instancję opcji i zwraca wynik zawierający szczegółowe komunikaty o niepowodzeniu.

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>();

Opcje nazwane — koncepcja

Opcje nazwane umożliwiają zarejestrowanie wielu konfiguracji tego samego typu opcji. Typowy przypadek użycia to wiele wychodzących klientów HTTP, z których każdy ma inny bazowy adres URL i limity czasu.

// 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;
}

Rejestrowanie opcji nazwanych

Przekaż ciąg nazwy jako pierwszy argument do Configure<T>. Użyj IOptionsMonitor<T>.Get(name), aby pobrać konkretną instancję.

// 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
}

Opcje nazwane z walidacją

Waliduj opcje nazwane osobno, wywołując AddOptions<T>(name) dla każdej nazwanej rejestracji.

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

API OptionsBuilder

OptionsBuilder<T> (zwracane przez AddOptions<T>()) to płynne API, które pozwala przejrzyście łączyć wszystkie kroki rejestrowania, wiązania i walidacji.

// 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

Praktyczny przykład: opcje zasad ponawiania

Kompletna konfiguracja opcji ponawiania z walidacją zależności między polami i nazwanymi zasadami dla różnych usług.

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();
}

Szybkie sprawdzenie

Jaka jest korzyść z wywołania ValidateOnStart() podczas rejestrowania opcji?

Podsumowanie: walidacja opcji i opcje nazwane

Najważniejsze informacje:

  • ValidateOnStart(): błąd podczas uruchamiania zamiast przy pierwszym użyciu
  • DataAnnotations: [Required], [Range] itd. + ValidateDataAnnotations()
  • Validate(Func, message): wbudowana lambda dla reguł dotyczących wielu właściwości
  • IValidateOptions<T>: pełna programowa walidacja z obsługą wielu błędów
  • Opcje nazwane: Configure<T>(name, ...) + IOptionsMonitor<T>.Get(name)
  • OptionsBuilder<T>: płynne API do łączenia wszystkich kroków rejestrowania

Często zadawane pytania

Czy lekcja „Walidacja opcji i opcje nazwane” jest bezpłatna?

Tak — pełny tekst „Walidacja opcji i opcje nazwane” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu C# Academy, przejdź na CoddyKit PRO. Kurs C# Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Walidacja opcji i opcje nazwane”?

Waliduj opcje podczas uruchamiania za pomocą DataAnnotations lub FluentValidation oraz używaj opcji nazwanych dla wielu instancji. Ćwiczysz C# Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć C# Academy?

Nie wymagamy żadnego doświadczenia. C# Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Walidacja opcji i opcje nazwane”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji C# Academy?

Tak. Każda lekcja C# Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Źródła i dostawcy konfiguracji
  2. Silnie typowane opcje z IOptions
  3. Walidacja opcji i opcje nazwane
  4. Zarządzanie sekretami
← Powrót do C# Academy