Configuration و Options Pattern

.NET 10 | appsettings، Environment و Strongly Typed Options

Configuration مجموعه‌ای از Providerهاست که تنظیمات را از فایل، Environment Variable، Secret Store و منابع دیگر ترکیب می‌کند. Options Pattern دسترسی Strongly Typed و قابل Validation به تنظیمات می‌دهد.

این فصل با تمرکز بر قراردادهای قابل اتکا، مرزبندی مسئولیت‌ها و رفتار قابل پیش‌بینی در محیط واقعی تنظیم شده است. مثال‌ها بر پایه ASP.NET Core و .NET 10 نوشته شده‌اند.

1. چارچوب موضوع و مفاهیم اصلی

Configuration مجموعه‌ای از Providerهاست که تنظیمات را از فایل، Environment Variable، Secret Store و منابع دیگر ترکیب می‌کند. Options Pattern دسترسی Strongly Typed و قابل Validation به تنظیمات می‌دهد.

واژگان و قراردادهای این بخش باید در سراسر پروژه یکدست بمانند؛ تفاوت میان لایه HTTP، منطق برنامه و زیرساخت زمانی روشن می‌ماند که مسئولیت هر جزء به‌صورت صریح تعریف شود.

2. ساختار پیشنهادی در پروژه

برای هر گروه تنظیمات یک Class مشخص تعریف می‌شود. Registration با BindConfiguration انجام و قواعد Validation هنگام Startup اجرا می‌شوند تا خطای پیکربندی زود آشکار شود.

public sealed class JwtOptions
{
    public const string SectionName = "Jwt";
    public string Issuer { get; init; } = string.Empty;
    public string Audience { get; init; } = string.Empty;
    public string Key { get; init; } = string.Empty;
}

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

3. سناریوی اجرایی

در Production مقدار Jwt:Key از Environment Variable یا Secret Store تأمین می‌شود و در فایل قابل Commit قرار نمی‌گیرد. Service مصرف‌کننده IOptions یا IOptionsMonitor متناسب با نیاز دریافت می‌کند.

در این سناریو، قرارداد ورودی و خروجی، مسیر شکست و رفتار قابل مشاهده سرویس باید پیش از جزئیات پیاده‌سازی مشخص شود. این رویکرد باعث می‌شود تغییرات بعدی بدون وابستگی پنهان و با امکان تست دقیق انجام شوند.

public sealed class TokenService(IOptions<JwtOptions> options)
{
    private readonly JwtOptions _options = options.Value;
}

// Environment variable example
// Jwt__Key=<secure-secret>

4. اصول طراحی و نگهداری

پیاده‌سازی قابل نگهداری تنها به درست کار کردن در مسیر موفق محدود نیست. مرزهای مسئولیت، قابلیت مشاهده، امنیت، رفتار در خطا و امکان توسعه تدریجی باید هم‌زمان بررسی شوند.

• Secret و Configuration عمومی از هم تفکیک شوند.
• کل Section به Object Strongly Typed Bind شود.
• مقادیر حیاتی در Startup Validate شوند.
• نام Environment و اولویت Providerها مستند باشد.

5. خطاهای رایج و کنترل آن‌ها

بخش مهمی از کیفیت یک API در نحوه جلوگیری از خطاهای تکرارشونده مشخص می‌شود. موارد زیر باید در بازبینی کد و تست‌های قبل از انتشار کنترل شوند.

• Hard-code کردن Secret در Source.
• خواندن Configuration با Stringهای پراکنده در تمام پروژه.
• استفاده از مقدار پیشفرض ناامن برای Secret.
• فرض Reload آنی برای Optionهایی که IOptions استفاده می‌کنند.

6. چک‌لیست نهایی فصل

• Options Class برای تنظیمات اصلی وجود دارد.
• Validation Startup فعال است.
• Secret در Repository ثبت نشده است.
• Development و Production Configuration از هم قابل تفکیک‌اند.

7. جمع‌بندی

مفاهیم این فصل زمانی کامل محسوب می‌شوند که هم مسیر موفق و هم مسیر خطا قابل پیش‌بینی، قابل تست و قابل مشاهده باشند. طراحی نهایی باید با Contract API، امنیت و نیازهای نگهداری پروژه هماهنگ بماند.