‫پایان یک انتظار طولانی: اعتبارسنجی ناهمگام (Async Validation) در NET 11.

var builder = WebApplication.CreateBuilder(args);

// اضافه کردن سرویس‌های اعتبارسنجی توکار به کانتینر DI
builder.Services.AddValidation();
builder.Services.AddScoped<ICatalogService, CatalogService>();

var app = builder.Build();

// فریم‌ورک به طور خودکار قبل از اجرای اِندپوینت، ساختار ورودی را ناهمگام می‌سنجد
app.MapPost("/products", (Product product) => Results.Ok(product));

app.Run();

internal sealed class UniqueSkuAttribute : AsyncValidationAttribute
{
    // متد همگام عمداً خطا پرتاب می‌کند تا از دور زدن صامت اعتبارسنجی جلوگیری شود
    protected override ValidationResult? IsValid(object? value, ValidationContext validationContext) =>
        throw new InvalidOperationException($"اعتبارسنجی این اتریبیوت باید با متد '{nameof(IsValidAsync)}' انجام شود.");

    protected override async Task<ValidationResult?> IsValidAsync(
        object? value, ValidationContext validationContext, CancellationToken cancellationToken)
    {
        var catalogService = validationContext.GetRequiredService<ICatalogService>();
        
        if (value is string sku && await catalogService.SkuExistsAsync(sku, cancellationToken))
        {
            return new ValidationResult("محصولی با این شناسه کالا (SKU) از قبل وجود دارد.");
        }

        return ValidationResult.Success;
    }
}

using System.ComponentModel.DataAnnotations;
using System.Runtime.CompilerServices;

public record OrderRequest(
    [Range(1, int.MaxValue)] int ProductId,
    [Range(1, int.MaxValue)] int Quantity,
    string PromoCode) : IAsyncValidatableObject
{
    // پیاده‌سازی متد همگام و پرتاب استثنا برای امنیت بیشتر
    public IEnumerable<ValidationResult> Validate(ValidationContext context) =>
        throw new InvalidOperationException($"این نوع داده باید با متد '{nameof(ValidateAsync)}' سنجیده شود.");

    // پیاده‌سازی جریان ناهمگام خطاها
    public async IAsyncEnumerable<ValidationResult> ValidateAsync(
        ValidationContext context,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        var catalogService = context.GetRequiredService<ICatalogService>();

        // بررسی موجودی انبار به صورت ناهمگام
        if (!await catalogService.HasStockAsync(ProductId, Quantity, cancellationToken))
        {
            yield return new ValidationResult(
                $"محصول شناسه '{ProductId}' به تعداد '{Quantity}' واحد در انبار موجود نیست.",
                [nameof(Quantity)]);
        }

        // بررسی کد تخفیف به صورت ناهمگام
        if (!await catalogService.IsPromoCodeValidAsync(PromoCode, cancellationToken))
        {
            yield return new ValidationResult(
                $"کد تخفیف '{PromoCode}' معتبر نیست.",
                [nameof(PromoCode)]);
        }
    }
}

• اتریبیوت‌های ناهمگام بر روی یک عضو (Member): اگر روی یک ویژگی (Property) چند اتریبیوت ناهمگام تعریف شده باشد، فرآیند اجرای متدهای IsValidAsync آن‌ها همزمان آغاز می‌شود تا زمان انتظار کاهش یابد.
• اعتبارسنجی مجموعه‌ها (Collections): آیتم‌های موجود در داخل لیست‌ها و کالکشن‌ها به شکل موازی (Parallel) وارد خط لوله سنجش می‌شوند.
• حفظ اولویت سنتی: در عین اجرای همزمان و موازی، فریم‌ورک کماکان مرزها و ترتیب‌های منطقی را حفظ می‌کند؛ به این معنا که ابتدا اعتبارسنجی‌های مربوط به اعضا (Properties)، سپس کلاس (Type-Level) و در نهایت نمونه‌های IAsyncValidatableObject مورد ارزیابی قرار می‌گیرند تا ساختار اولویت‌بندی از بین نروید.

• انجام عملیات I/O به‌صورت همگام: توسعه‌دهندگان برای بررسی اتصالات خارجی (مانند اعتبارسنجی DNS یا پینگ یک API) ناچار به استفاده از الگوهای ضدطراحی مانند task.Result یا task.Wait() می‌شدند که خطر رخ‌داد Sync-over-Async و بن‌بست رشته‌ها (Thread Pool Starvation / Deadlock) را به همراه داشت.
• چرخه حیات ناهمگام در هاست دات‌نت: با توجه به اینکه متد IHost.StartAsync() ناهمگام است، عدم پشتیبانی چرخه حیات اعتبارسنجی از فراخوانی‌های Asynchronous یک خلاء معماری به‌شمار می‌رفت.

public interface IAsyncValidateOptions<TOptions> where TOptions : class
{
    Task<ValidateOptionsResult> ValidateAsync(
        string? name, 
        TOptions options, 
        CancellationToken cancellationToken = default);
}

• کدهای قدیمی که همچنان از اعتبارسنجی همگام استفاده می‌کنند بدون مشکل کار کنند.
• فراخوانی‌های مدرن زمان شروع هاست مستقیماً از مسیر ناهمگام بهره ببرند.

#:sdk Microsoft.NET.Sdk.Web

using System.Net;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

// پیکربندی و فعال‌سازی اعتبارسنجی در فاز راه‌اندازی
builder.Services
    .AddOptions<BackendOptions>()
    .Configure(options =>
    {
        options.HostName = "api.internal.network";
    })
    .Validate<BackendOptionsValidator>()
    .ValidateOnStart();

using IHost host = builder.Build();
await host.StartAsync();

public sealed class BackendOptions
{
    public string HostName { get; set; } = string.Empty;
}

public sealed class BackendOptionsValidator : 
    IAsyncValidateOptions<BackendOptions>, 
    IValidateOptions<BackendOptions>
{
    public async Task<ValidateOptionsResult> ValidateAsync(
        string? name,
        BackendOptions options,
        CancellationToken cancellationToken = default)
    {
        if (string.IsNullOrWhiteSpace(options.HostName))
        {
            return ValidateOptionsResult.Fail("نام میزبان سرویس بک‌اند مشخص نشده است.");
        }

        // بررسی ناهمگام آدرس IP متناظر با هاست
        DnsResult<AddressRecord> result =
            await Dns.ResolveAddressesAsync(options.HostName, cancellationToken);

        return result.ResponseCode == DnsResponseCode.NoError && result.Records.Count > 0
            ? ValidateOptionsResult.Success
            : ValidateOptionsResult.Fail(
                $"امکان ارزیابی آدرس IP برای دامنه '{options.HostName}' وجود ندارد.");
    }

    // متد همگام به منظور ممانعت از فراخوانی همگام غیراصولی خطای معنادار صادر می‌کند
    public ValidateOptionsResult Validate(string? name, BackendOptions options) =>
        ValidateOptionsResult.Fail("اعتبارسنجی این تنظیمات صرفاً باید به صورت ناهمگام اجرا شود.");
}

• متد ValidateOnStart(): در طول فراخوانی host.StartAsync()، سامانه هاست ارائه‌دهنده IAsyncStartupValidator را فراخوانی کرده و متد ValidateAsync را با CancellationToken مجاز اجرا می‌کند.
• رفتار متد Validate همگام: در صورتی که بخشی از کدهای قدیمی یا کتابخانه‌های ثالث سعی کنند با متد همگام این نمونه را ارزیابی کنند، به‌جای بلاک کردن ترد با خطای صریح مواجه می‌شوند تا توسعه‌دهنده به استفاده از مدل ناهمگام هدایت شود.

using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
cts.CancelAfter(TimeSpan.FromSeconds(3));

• اعتبارسنجی ناهمگام گزینه‌ها: برای بررسی درستی اولیه فرمت و دسترسی‌پذیری حداقلی پیش‌نیازها در فاز اجرای هاست است (مثل وجود رکورد DNS یا خواندن گواهینامه از Key Vault).
• بررسی سلامت (Health Checks): برای نظارت مداوم و دوره‌ای در چرخه حیات زنده بودن (Liveness) و آمادگی (Readiness) سیستم است. عملیات سنگین مثل اجرای تراکنش‌های تستی در پایگاه داده نباید به اعتبارسنجی Options منتقل شوند.