[API Proposal]: Async DataAnnotations bridge for Microsoft.Extensions.Options

[ViveliDuCh]

Background and motivation

Microsoft.Extensions.Options validation integrates with System.ComponentModel.DataAnnotations through DataAnnotationValidateOptions<T> and ValidateDataAnnotations(), which wire Validator.TryValidateObject into the Options pipeline. This is the most common way .NET Aspire, ASP.NET Core, and other consumers apply DataAnnotations-based validation to configuration types at startup.

#128096 added AsyncValidationAttribute, IAsyncValidatableObject, and Validator.TryValidateObjectAsync to System.ComponentModel.DataAnnotations. #128100 added the async Options pipeline — IAsyncValidateOptions<T>, AsyncValidateOptions<T,...>, and ValidateOnStart async execution — to Microsoft.Extensions.Options.

This proposal completes the bridge by making the existing DataAnnotationValidateOptions<T> async-aware: it now also implements IAsyncValidateOptions<T>, and ValidateDataAnnotations() registers the same instance for both sync and async validation. No new public types or extension methods are needed — a single ValidateDataAnnotations() call covers both sync per-access validation and async startup validation.

Notable consumer: .NET Aspire is a significant consumer of ValidateDataAnnotations() + ValidateOnStart(). Making the existing bridge async-aware directly benefits Aspire-hosted services that need I/O-bound configuration validation (e.g., connection string reachability checks) at startup — with zero code changes for existing consumers.

Related: dotnet/runtime#128096, dotnet/runtime#128100, dotnet/aspnetcore#46349

API Proposal

Microsoft.Extensions.Options.DataAnnotations

namespace Microsoft.Extensions.Options;

// Existing class — gains IAsyncValidateOptions<T>
public partial class DataAnnotationValidateOptions<TOptions> :
    IAsyncValidateOptions<TOptions>
{
    // implicitly implement the interface
}

The existing DataAnnotationValidateOptions<T> adds IAsyncValidateOptions<T> to its interface list. The ValidateAsync method is implicitly implemented — it mirrors the sync Validate() recursive walk but delegates to Validator.TryValidateObjectAsync, which evaluates both sync attributes (Phase 1) and AsyncValidationAttributes (Phase 2).

No new public types. No new extension methods. ValidateDataAnnotations() registers the same instance as both IValidateOptions<T> and IAsyncValidateOptions<T>.

API Usage

Scenario 1: Async DataAnnotations at startup (zero code changes)

Existing ValidateDataAnnotations() calls automatically gain async startup validation. Users with AsyncValidationAttribute-decorated types get async validation without any API change.

public class TenantDatabaseSettings
{
    [Required]
    public string TenantName { get; set; } = "";

    [Required]
    [AsyncConnectionStringValid] // AsyncValidationAttribute: tests DB connectivity
    public string ConnectionString { get; set; } = "";

    [Range(1, 300)]
    public int CommandTimeoutSeconds { get; set; } = 60;
}

// Program.cs — UNCHANGED from existing code
builder.Services.AddOptions<TenantDatabaseSettings>()
    .Bind(builder.Configuration.GetSection("Database"))
    .ValidateDataAnnotations()   // now registers BOTH:
                                 //   - IValidateOptions<T>      → sync per-access
                                 //   - IAsyncValidateOptions<T>  → async startup
    .ValidateOnStart();

// Recommended: bound async validators with a startup timeout
builder.Services.Configure<HostOptions>(opts =>
    opts.StartupTimeout = TimeSpan.FromSeconds(30));

// What happens at startup (Host.StartAsync):
//   Stage 1 (sync): IStartupValidator.Validate()
//     → OptionsFactory.Create() → Validate() → Validator.TryValidateObject
//   Stage 2 (async): IAsyncStartupValidator.ValidateAsync(ct)
//     → ValidateAsync() → Validator.TryValidateObjectAsync
//       → sync attributes (Phase 1), then [AsyncConnectionStringValid] (Phase 2)
//     → OptionsValidationException if validation fails → app won't start
//
// After startup:
//   Validate() runs on every IOptions.Value / IOptionsSnapshot.Get() access ✅
//   ValidateAsync() does NOT run after startup (by design)

Scenario 2: Sync-only types — no behavioral change

For types with only sync attributes, the fold adds async infrastructure at startup but with negligible overhead (per API review board consensus):

public class SimpleSettings
{
    [Required]
    public string Name { get; set; } = "";

    [Range(1, 100)]
    public int MaxRetries { get; set; } = 3;
}

// Existing code — unchanged, still works identically
builder.Services.AddOptions<SimpleSettings>()
    .ValidateDataAnnotations()   // registers both interfaces (same instance)
    .ValidateOnStart();

// At startup:
//   Stage 1 (sync): [Required], [Range] validated ✅
//   Stage 2 (async): TryValidateObjectAsync runs sync attrs again — negligible overhead,
//     no AsyncValidationAttributes present → completes synchronously
// Per-access: Validate() runs as before ✅

Alternative Designs (considered and rejected)

A. Standalone async class + ValidateDataAnnotationsAsync() method

A new standalone class implementing only IAsyncValidateOptions<T>, with a new ValidateDataAnnotationsAsync() extension method. Users must call both methods for full coverage.

public class AsyncDataAnnotationValidateOptions<TOptions>
    : IAsyncValidateOptions<TOptions> where TOptions : class { ... }

// Usage — requires TWO calls
builder.Services.AddOptions<SmtpSettings>()
    .ValidateDataAnnotations()         // sync per-access
    .ValidateDataAnnotationsAsync()    // async startup
    .ValidateOnStart();

Rejected: Pit of failure — users who add AsyncValidationAttribute but forget ValidateDataAnnotationsAsync() get silent non-validation; two calls for the most common case.

B. Inheritance: AsyncDataAnnotationValidateOptions<T> : DataAnnotationValidateOptions<T>

A derived class that inherits sync validation and adds async, registered via a new ValidateDataAnnotationsAsync() method.

public class AsyncDataAnnotationValidateOptions<TOptions>
    : DataAnnotationValidateOptions<TOptions>, IAsyncValidateOptions<TOptions> { ... }

Rejected: Still requires discovering a new method; calling both ValidateDataAnnotations() + ValidateDataAnnotationsAsync() registers two IValidateOptions<T> entries causing double sync validation per access; introduces a new public class unnecessarily.

C. Fold into ValidateDataAnnotations() — chosen by API review

Adding IAsyncValidateOptions<T> to the existing DataAnnotationValidateOptions<T> class. The API review board concluded the startup overhead from double sync-attribute evaluation is negligible — Validator.TryValidateObjectAsync runs sync attributes in Phase 1 before async attributes in Phase 2, so they run both in Stage 1 (sync) and Stage 2 (async), but this is a cheap reflection pass that only happens once at startup.

Chosen because:

• Zero API discovery needed — existing ValidateDataAnnotations() calls automatically gain async support
• No new types or methods — minimal API surface change
• No pit of failure — AsyncValidationAttribute on any type is always picked up
• Sync per-access path is completely unchanged
• Startup overhead is negligible per review board consensus

Cross-references

• #128096 — AsyncValidationAttribute, IAsyncValidatableObject, Validator.TryValidateObjectAsync (approved, merged Add async validation support for System.ComponentModel.DataAnnotations #128656)
• #128100 — IAsyncValidateOptions<T>, AsyncValidateOptions<T,...>, ValidateOnStart async pipeline (approved)

Risks

• Startup timeout for I/O-bound validators — Async validators (e.g., database reachability checks) run at Host.StartAsync() with the CancellationToken from HostOptions.StartupTimeout. The default timeout is Timeout.InfiniteTimeSpan (no limit). Applications using I/O-bound async validators should configure a startup timeout:

  builder.Services.Configure<HostOptions>(opts =>
      opts.StartupTimeout = TimeSpan.FromSeconds(30));

• CancellationToken propagation — The token flows: Host.StartAsync(ct) → linked CTS (ct ∪ ApplicationStopping ∪ StartupTimeout) → IAsyncStartupValidator.ValidateAsync(ct) → DataAnnotationValidateOptions<T>.ValidateAsync(ct) → Validator.TryValidateObjectAsync(..., ct). No gaps in propagation — async validators receive the combined token and can be cancelled by any of the three sources.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-componentmodel-dataannotations
See info in area-owners.md if you want to be subscribed.

[tarekgh]

A few pieces of feedback after lining this up against the existing sync bridge and the async Validator APIs.

1. Transitive validation ([ValidateObjectMembers] / [ValidateEnumeratedItems]) needs to be handled explicitly

The sync DataAnnotationValidateOptions<T> is not a thin wrapper over Validator.TryValidateObject. It implements its own recursive walk (TryValidateOptions) that honors [ValidateObjectMembers] (nested option objects) and [ValidateEnumeratedItems] (collection items), with cycle detection via a visited set.

Validator.TryValidateObjectAsync validates only a single object's own properties, its type-level attributes, and IAsyncValidatableObject/IValidatableObject. It does not recurse into [ValidateObjectMembers]/[ValidateEnumeratedItems], since that recursion is a Microsoft.Extensions.Options.DataAnnotations feature rather than a Validator feature.

As written, the flow (ValidateAsync calling a single TryValidateObjectAsync) would silently drop validation on nested members and enumerated items, which is a behavioral asymmetry with the sync bridge. For example, an [AsyncConnectionStringValid] on a nested options type reachable through [ValidateObjectMembers] would never run. Please either replicate the recursive walk in async form, or explicitly scope nested/enumerated async validation out of v1 and document that limitation.

2. DataAnnotationValidateOptionsAsync<T> should annotate its type parameter for trimming

The sync class annotates TOptions:

public class DataAnnotationValidateOptions<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] TOptions>

The proposed async class declares DataAnnotationValidateOptionsAsync<TOptions> with no [DynamicallyAccessedMembers] on the class type parameter (only the extension method has it). For trim correctness and parity with the sync type, the async class type parameter should carry the same annotation.

3. Naming consistency with the async Options pipeline

The async Options pipeline uses Async as a prefix (IAsyncValidateOptions, AsyncValidateOptions), while this proposes it as a suffix (DataAnnotationValidateOptionsAsync). The method ValidateDataAnnotationsAsync() correctly follows the TAP suffix convention, but the class name diverges from its sibling AsyncValidateOptions. Worth a deliberate decision (AsyncDataAnnotationValidateOptions vs the suffix form) rather than arriving at it by accident.

4. ValidateDataAnnotationsAsync() already validates the synchronous attributes at startup, which makes Scenario 2 double-validate them

Validator.TryValidateObjectAsync evaluates synchronous ValidationAttributes first and then AsyncValidationAttributes. So at startup, ValidateDataAnnotationsAsync() + ValidateOnStart() already validates both the sync and the async attributes in one pass; a user with a mix who only needs startup validation does not also need ValidateDataAnnotations().

The two registrations remain non-redundant because they cover different lifecycles:

• sync IValidateOptions<T> runs inside OptionsFactory.Create(), i.e. on every IOptions.Value/IOptionsSnapshot.Get() access (reload, lazily created named options),
• async IAsyncValidateOptions<T> runs once at startup and cannot run from the synchronous .Value getter.

The consequence worth calling out: Scenario 2 in the proposal registers both and adds ValidateOnStart(). Its inline comments imply the sync method owns [Required]/[Range] and the async method owns the async attribute, but in fact the async validator runs [Required]/[Range] as well (Step 1 of TryValidateObjectAsync). So at startup those synchronous attributes are validated twice, producing a redundant reflection walk and duplicate error entries for the same member. Two suggestions:

• Document ValidateDataAnnotationsAsync() explicitly as also validating synchronous attributes at startup, so the common case stays a single call.
• Reconsider Scenario 2 as a recommended pattern (or note the double validation), since calling both is only needed when ongoing per-access sync validation is also desired.

Minor

The example motivates I/O-bound checks (DB reachability). It would help to spell out which CancellationToken flows from Host.StartAsync through ValidateOnStart into ValidateAsync, and whether any startup timeout applies.

[bartonjs]

Video

• Let's just add IAsyncValidateOptions to the existing DataAnnotationValidateOptions<TOptions>

namespace Microsoft.Extensions.Options
{
    public partial class DataAnnotationValidateOptions<TOptions> :
        IAsyncValidateOptions<TOptions>
    {
        // implicitly implement the interface
    }
}