Description

This PR adds async form validation support to Blazor's EditContext. Validator components can subscribe to a new async event, run async validators (database lookups, remote API calls, etc.), and have their work tracked, cancelled, and surfaced to the UI as pending/faulted per-field state. The existing sync Validate() continues to work and is extended to invoke async handlers as well, so async validators can never be silently skipped.

Fixes #7680
API proposal: #66381

What this enables

Today, a form developer who needs async validation has to block on async work (deadlock-prone, broken on WebAssembly), or run validation outside the form pipeline and reconcile the result by hand. Libraries with first-class async support (FluentValidation) cannot integrate with EditContext because the event model is synchronous.

After this change:

• EditForm form-submit validation awaits async validators end-to-end. OnValidSubmit only fires once async validators have settled.
• Validators can register per-field async tasks via EditContext.AddValidationTask(field, task, cts). The framework tracks them, cancels superseded tasks, and exposes pending/faulted state via IsValidationPending(field) and IsValidationFaulted(field).
• Components can show "validating..." spinners and "infrastructure error" UI without writing their own bookkeeping.
• InputBase automatically emits "pending" or "faulted" CSS classes via FieldCssClassProvider so plain CSS can react to async state.
• The DataAnnotationsValidator component routes through the new async pipeline when a Microsoft.Extensions.Validation IValidatableInfo is registered for the model, so async [ValidationAttribute]s flow through automatically.

How it works

flowchart LR
    EditForm["EditForm.HandleSubmitAsync"]
    ValAsync["EditContext.ValidateAsync"]
    SyncEvt(["OnValidationRequested<br/>(sync event)"])
    AsyncEvt(["OnValidationRequestedAsync<br/>(async event)"])
    AddTask["EditContext.AddValidationTask<br/>(per-field tracking)"]

    Validators["Validator components<br/>(DataAnnotationsValidator,<br/>FluentValidation, etc.)"]

    EditForm -->|calls| ValAsync
    ValAsync -->|raises| SyncEvt
    ValAsync -->|raises and awaits| AsyncEvt
    Validators -.->|subscribes| SyncEvt
    Validators -.->|subscribes| AsyncEvt
    Validators -->|calls on field change| AddTask

    classDef event fill:#fff3cd,stroke:#aa8800
    class SyncEvt,AsyncEvt event

Legend: solid arrow = method call; dashed arrow = event subscription.

There are two cooperating workflows:

1. Form-level validation (e.g., on submit) is driven by EditContext.ValidateAsync(CancellationToken). It cancels any in-flight per-field tasks, fires the sync event, then fans out and awaits all async event handlers concurrently.
2. Per-field validation (e.g., as the user edits) is driven by validator components calling EditContext.AddValidationTask(field, task, cts). Each field gets a single tracked slot; new tasks supersede older ones via cancellation.

Validate() (the existing sync API) is not marked [Obsolete]. It is extended to also invoke OnValidationRequestedAsync handlers, but throws InvalidOperationException if any handler returns an incomplete Task. This keeps the .NET 10 behavior (DataAnnotationsValidator running through Validate()) intact for fully-sync validators while preventing silent skip of async ones.

Solution details

The change touches four areas:

Public surface in Microsoft.AspNetCore.Components.Forms. EditContext gains the OnValidationRequestedAsync event, the ValidateAsync(CancellationToken) method, the AddValidationTask(field, task, cts) registration entry point, and three pairs of pending/faulted query overloads (per-field via FieldIdentifier / expression and parameterless form-level). ValidationRequestedEventArgs gains a CancellationToken constructor and property used to surface caller cancellation to async handlers.

EditContext internals. Two new private fields (_isFormValidationPending, _isFormValidationFaulted) drive the parameterless form-level queries. Each FieldState gains three internal slots (PendingValidationTask, PendingValidationCts, IsValidationFaulted) representing the per-field tracked task. ObserveValidationTaskAsync is a fire-and-forget helper that watches each registered task to its terminal state and updates the slot, with ReferenceEquals guards so a superseded task never stomps a newer slot.

Built-in DataAnnotationsValidator. DataAnnotationsEventSubscriptions subscribes to OnFieldChanged and OnValidationRequestedAsync. Inside the async handler it routes between sync- and async-only execution based on whether the model has an IValidatableInfo registered via Microsoft.Extensions.Validation. Because the sync routing path completes synchronously inside the async handler, calling Validate() continues to work for models without MEV-registered async validators. The new [Experimental("ASP0029")] ValidationOptions.TryGetValidatablePropertyInfo(Type, string, out IValidatableInfo?) public API on Microsoft.Extensions.Validation is used to look up per-property validation metadata when OnFieldChanged fires, so async per-field validation can run without re-validating the whole object graph. The lookup walks base types so inherited properties are resolved correctly.

Web-side updates (Microsoft.AspNetCore.Components.Web). EditForm.HandleSubmitAsync calls ValidateAsync() instead of Validate(). FieldCssClassProvider.GetFieldCssClass is extended to emit "pending" (while EditContext.IsValidationPending(field) is true) or "faulted" (while EditContext.IsValidationFaulted(field) is true), both with the existing "modified " prefix when applicable. These CSS classes supersede "valid"/"invalid" since neither outcome is known while pending or after a fault.

Form-level validation: ValidateAsync

sequenceDiagram
    participant Caller
    participant EC as EditContext
    participant Handlers as Async handlers

    Caller->>EC: ValidateAsync(ct)
    EC->>EC: cancel pending per-field tasks<br/>set _isFormValidationPending = true
    EC->>EC: raise OnValidationRequested (sync)
    EC->>Handlers: raise OnValidationRequestedAsync
    Handlers-->>EC: Task.WhenAll
    EC->>EC: classify outcome<br/>set _isFormValidationFaulted<br/>clear _isFormValidationPending
    EC-->>Caller: bool (or rethrow OCE)

Behavior details (each handled in code, not shown in diagram for clarity):

• Per-field supersession. The first step cancels any pending per-field tasks so submit-time validation always wins over in-flight per-field validation.
• Token surface. When the caller passes a cancellable token, ValidateAsync builds a ValidationRequestedEventArgs carrying it; otherwise it reuses ValidationRequestedEventArgs.Empty. Async handlers should observe args.CancellationToken for downstream I/O. The token bounds the in-flight pass only -- per-field tasks started independently during the awaited window are not linked to it.
• Outcome classification after Task.WhenAll:
  • Caller-cancelled (token tripped) → rethrow OperationCanceledException; previous _isFormValidationFaulted preserved.
  • Handler-internal OperationCanceledException (caller's token not cancelled) → contained, not treated as fault.
  • Any task faulted with a non-OperationCanceledException → faultedThisPass = true.
  • Otherwise → success; pass returns !GetValidationMessages().Any().
• Set-at-completion fault flag. _isFormValidationFaulted is assigned once at the end of the pass, so IsValidationFaulted() does not flicker when a new pass starts.

Per-field validation: AddValidationTask

AddValidationTask is the entry point validators use to register an in-flight async validation for a single field. The contract:

• Each field has at most one tracked slot.
• Calling AddValidationTask again cancels the previous slot's CTS before installing the new one.
• The EditContext takes ownership of the supplied CancellationTokenSource -- it is cancelled if a subsequent task supersedes this one, and disposed once the task completes.
• A faulted task surfaces field-level fault via IsValidationFaulted(field). Cancellation is silent.
• A task that is already completed at registration time is settled synchronously without parking the slot (a faulted completed task still surfaces the field-level fault).

Field state machine

The per-field tracking in FieldState is driven by three fields:

internal Task? PendingValidationTask { get; set; }
internal CancellationTokenSource? PendingValidationCts { get; set; }
internal bool IsValidationFaulted { get; set; }

The framework's observer clears PendingValidationTask once the task settles, so a field is in one of three observable states:

Transitions:

stateDiagram-v2
    [*] --> Idle
    Idle --> Pending: AddValidationTask
    Pending --> Idle: task succeeded or cancelled
    Pending --> Faulted: task threw (non-OCE)
    Faulted --> Pending: AddValidationTask
    Pending --> Pending: AddValidationTask<br/>(supersede)
    Faulted --> Idle: form-level pass starts
    Pending --> Idle: form-level pass starts

Edge cases handled in code (not shown in the diagram):

• Completed task at registration. If the supplied task is already completed, the slot is not parked. A completed faulted task surfaces field-level fault directly (Idle/Pending/Faulted → Faulted); a completed successful or cancelled task is a no-op.
• Supersession. A new AddValidationTask cancels the prior CTS and replaces the slot. The prior observer will eventually fire but the ReferenceEquals(state.PendingValidationTask, task) guard makes it a no-op so it cannot stomp the new slot.
• CTS ownership. Each parked task's CTS is always disposed by its own observer when the task settles -- never by AddValidationTask for a still-pending task -- so a validator can never observe a disposed token.
• Form-level reset. ValidateAsync calls CancelAllPendingValidationTasks which cancels every per-field CTS and also clears any lingering IsValidationFaulted flag from a prior pass, so each new form-level pass starts from a clean per-field baseline.

Form-level state queries

EditContext also exposes parameterless IsValidationPending() / IsValidationFaulted() queries that are explicitly not unions over field-level state:

Splitting per-field and form-level state means apps can build a "submit button disabled while submit-validation runs" indicator without it flickering on every keystroke that triggers a per-field task, and vice versa.

Validate() behavior change

Validate() (the existing sync API) is kept and extended rather than marked [Obsolete]. Each call:

1. Raises OnValidationRequested. Sync exceptions propagate to the caller, matching prior behavior.
2. If any OnValidationRequestedAsync handler is subscribed, invokes each in turn:
   • If the returned Task is not yet completed, throws InvalidOperationException directing the caller to ValidateAsync().
   • Otherwise calls task.GetAwaiter().GetResult() to surface any synchronous fault.
3. Returns !GetValidationMessages().Any().

This is the .NET 10 routing pattern between EditForm.Validate and DataAnnotationsValidator extended to all async handlers. Sync-only validation paths keep working as long as no async handler is registered (which was previously not supported). The advantage over [Obsolete] is that callers retaining the sync API cannot silently lose async validation results -- they get a loud runtime exception pointing at ValidateAsync instead.

Built-in DataAnnotationsValidator routing

DataAnnotationsEventSubscriptions (the engine behind <DataAnnotationsValidator>) subscribes to OnFieldChanged and OnValidationRequestedAsync only. The async handler routes internally based on whether the model has an IValidatableInfo registered via Microsoft.Extensions.Validation:

Because the no-IValidatableInfo form-level path completes synchronously inside the async handler, calling EditContext.Validate() continues to work for sync-only models. Models with MEV async validators require ValidateAsync(); Validate() throws InvalidOperationException in that case.

The OnFieldChanged path uses ValidationOptions.TryGetValidatablePropertyInfo(modelType, propertyName, out var info) (new public API on Microsoft.Extensions.Validation) to look up per-property metadata without re-validating the whole object graph. The lookup walks base types so inherited properties are resolved correctly.

Cancellation propagation

flowchart LR
    Caller["caller token"] -->|"ValidateAsync(ct)"| EC["EditContext"]
    EC -->|"args.CancellationToken"| Handler["async handler"]
    Handler -->|"linked / pass-through"| IO["DB / HTTP / etc."]

    EC -.->|"per-field CTS<br/>(separate lifetime)"| FieldState["FieldState"]
    Edit["next user edit"] -->|"AddValidationTask"| FieldState
    FieldState -->|"cancel prior cts"| OldTask["prior validator task"]

• The caller's token bounds the form-level pass only. If the caller cancels, the awaited handlers receive cancellation through args.CancellationToken and ValidateAsync rethrows OperationCanceledException after running the pending-flag cleanup.
• Per-field tasks are cancelled by their own CTS, owned by EditContext. They are independent of the caller's token. This keeps per-field validation lifecycles tied to user edits / form submission, not to the lifetime of any particular ValidateAsync call.

EditForm integration

EditForm.HandleSubmitAsync now calls EditContext.ValidateAsync() instead of Validate(). Forms using OnValidSubmit / OnInvalidSubmit automatically benefit -- OnValidSubmit only fires after async validators have settled. Forms using OnSubmit continue to call Validate() or migrate to await context.ValidateAsync() at the developer's discretion.

New public API surface

Microsoft.AspNetCore.Components.Forms

public sealed class EditContext
{
    // Async counterpart to the existing sync OnValidationRequested event.
    // For a given validator, subscribe to one of the two events, not both.
    public event Func<object, ValidationRequestedEventArgs, Task>? OnValidationRequestedAsync;

    // Async counterpart to Validate(). Cancels in-flight per-field tasks, raises the sync
    // and async events, awaits all async handlers, and returns whether validation succeeded.
    // The caller's token is surfaced to handlers via ValidationRequestedEventArgs.CancellationToken
    // and bounds the in-flight pass only.
    public Task<bool> ValidateAsync(CancellationToken cancellationToken = default);

    // Registers an in-flight async validation task for a specific field. If a task is
    // already tracked for the field, the prior CTS is cancelled and the new task replaces it.
    // EditContext owns the supplied CTS and disposes it when the task settles.
    public void AddValidationTask(
        in FieldIdentifier fieldIdentifier,
        Task task,
        CancellationTokenSource cts);

    public bool IsValidationPending(in FieldIdentifier fieldIdentifier);
    public bool IsValidationPending<TField>(Expression<Func<TField>> accessor);
    public bool IsValidationPending();   // true while a form-level ValidateAsync pass is in flight

    public bool IsValidationFaulted(in FieldIdentifier fieldIdentifier);
    public bool IsValidationFaulted<TField>(Expression<Func<TField>> accessor);
    public bool IsValidationFaulted();   // most recent form-level pass observed a handler exception
}

public sealed class ValidationRequestedEventArgs : EventArgs
{
    public ValidationRequestedEventArgs(CancellationToken cancellationToken);
    public CancellationToken CancellationToken { get; }
}

Microsoft.Extensions.Validation

public class ValidationOptions
{
    // Looks up the IValidatableInfo for a named property on a containing type, walking base
    // types so inherited properties are resolved. Used by DataAnnotationsValidator for
    // per-field async validation. Returns IValidatableInfo? (in practice the implementation
    // is a ValidatablePropertyInfo).
    [Experimental("ASP0029", UrlFormat = "https://aka.ms/aspnet/analyzer/{0}")]
    public bool TryGetValidatablePropertyInfo(
        Type type,
        string propertyName,
        [NotNullWhen(true)] out IValidatableInfo? validatablePropertyInfo);
}

Microsoft.AspNetCore.Components.Web

No new types. FieldCssClassProvider.GetFieldCssClass returns the additional values "pending", "modified pending", "faulted", and "modified faulted" (no public API change, but observable from CSS). Custom subclasses can override this to map the new states to framework-specific class names.

Usage

Implicit submit validation. No code change required for forms that already use OnValidSubmit:

<EditForm Model="registration" OnValidSubmit="HandleValidSubmit">
    <DataAnnotationsValidator />
    <InputText @bind-Value="registration.Username" />
    <button type="submit">Register</button>
    <ValidationSummary />
</EditForm>

@code {
    private async Task HandleValidSubmit(EditContext context)
    {
        // Only fires after ALL validation (including async) has passed.
        await UserService.CreateAsync(registration);
    }
}

Explicit submit validation. Apps using OnSubmit call ValidateAsync:

<EditForm Model="registration" OnSubmit="HandleSubmit">
    <DataAnnotationsValidator />
    <!-- ... -->
</EditForm>

@code {
    private async Task HandleSubmit(EditContext context)
    {
        if (await context.ValidateAsync())
        {
            await UserService.CreateAsync(registration);
        }
    }
}

Per-field pending / faulted UI. The expression-based overloads match ValidationMessage syntax:

<InputText @bind-Value="registration.Username" />

@if (editContext.IsValidationPending(() => registration.Username))
{
    <span class="spinner">Checking availability…</span>
}
else if (editContext.IsValidationFaulted(() => registration.Username))
{
    <span>An error occurred while validating. Please try again.</span>
}
else
{
    <ValidationMessage For="() => registration.Username" />
}

<button type="submit">Register</button>

See the full example of a validation status component.

Third-party validator integration. Library authors subscribe to the async event and use AddValidationTask for field-level tracking:

public class FluentValidationValidator : ComponentBase
{
    [CascadingParameter] EditContext EditContext { get; set; } = default!;

    protected override void OnInitialized()
    {
        EditContext.OnValidationRequestedAsync += async (sender, args) =>
        {
            var validator = GetValidatorForModel(EditContext.Model);
            var result = await validator.ValidateAsync(EditContext.Model, args.CancellationToken);
            // Populate ValidationMessageStore with results
        };

        EditContext.OnFieldChanged += (sender, args) =>
        {
            var cts = new CancellationTokenSource();
            var task = RunFieldValidationAsync(args.FieldIdentifier, cts.Token);
            EditContext.AddValidationTask(args.FieldIdentifier, task, cts);
        };
    }
}

See the full example of FluentValidation-based form validation.

Testing

EditContextAsyncTest (50 unit tests in src/Components/Forms/test) covers:

• Form-level workflow: invocation order (sync handlers before async), multicast fan-out via Task.WhenAll, Validate() throwing on incomplete async handlers, ValidateAsync returning false when handlers fault, faulted-pass set-at-completion semantics, _isFormValidationPending lifecycle.
• Cancellation: caller token rethrows OperationCanceledException, handler-internal OCE is contained, fault state preserved across caller-cancel, token surfaced to handlers via ValidationRequestedEventArgs.CancellationToken, per-field tasks superseded at the start of every form-level pass.
• Per-field state machine: every transition in the table above, including the completed-task short-circuits, the ReferenceEquals guards in the observer, CTS ownership / disposal, and lingering-fault clear at the start of the next form-level pass.
• NotifyValidationStateChanged notifications: that a state transition produces exactly one notification per pass / transition, no flicker on faulted set-at-completion.

EditFormAsyncSubmitTest (4 component tests in src/Components/Web/test) covers the EditForm.HandleSubmitAsync integration: OnValidSubmit firing only after async validators settle, OnInvalidSubmit firing when an async validator reports an error, and that submitting cancels in-flight per-field tasks before running submit validation.

Out of scope / follow-ups

• ValidateFieldAsync(FieldIdentifier) on EditContext. Today, re-running per-field validation requires calling NotifyFieldChanged, which has the side effect of flipping IsModified. A dedicated ValidateFieldAsync would let callers re-validate a single field on demand without simulating an edit, returning a Task. We chose not to ship this in the initial PR; a follow-up can add it once we've validated the broader API surface.
• Validator.TryValidateObjectAsync / Validator.TryValidatePropertyAsync in the BCL. The async DataAnnotations path for plain models (without AddValidation()) depends on these APIs (dotnet/runtime#121536). Until they ship, the Microsoft.Extensions.Validation path via AddValidation() is required for async validators. Sync [ValidationAttribute]s work unchanged.