[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: the Microsoft.Extensions.Options.DataAnnotations convenience layer that connects the two. Without DataAnnotationValidateOptionsAsync<T> and ValidateDataAnnotationsAsync(), users who decorate configuration types with AsyncValidationAttribute attributes have no ergonomic path to wire them into Options startup validation. They would need to manually implement IAsyncValidateOptions<T> and call Validator.TryValidateObjectAsync directly — exactly the boilerplate the existing ValidateDataAnnotations() convenience eliminates on the sync side.

Notable consumer: .NET Aspire is a significant consumer of ValidateDataAnnotations() + ValidateOnStart(). The async counterparts directly benefit Aspire-hosted services that need I/O-bound configuration validation (e.g., connection string reachability checks) at startup.

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

API Proposal

Microsoft.Extensions.Options.DataAnnotations

namespace Microsoft.Extensions.Options;

// New class: async counterpart to DataAnnotationValidateOptions<T>
public class DataAnnotationValidateOptionsAsync<TOptions>
    : IAsyncValidateOptions<TOptions> where TOptions : class
{
    [RequiresUnreferencedCode("Uses DataAnnotationValidateOptionsAsync which is unsafe given that " +
        "the options type passed in when calling ValidateAsync cannot be statically analyzed so its " +
        "members may be trimmed.")]
    public DataAnnotationValidateOptionsAsync(string? name);

    public string? Name { get; }

    public Task<ValidateOptionsResult> ValidateAsync(
        string? name,
        TOptions options,
        CancellationToken cancellationToken = default);
}

namespace Microsoft.Extensions.DependencyInjection;

// Existing class — new method added
public static class OptionsBuilderDataAnnotationsExtensions
{
    // Existing — unchanged
    [RequiresUnreferencedCode("...")]
    public static OptionsBuilder<TOptions> ValidateDataAnnotations<TOptions>(
        this OptionsBuilder<TOptions> optionsBuilder) where TOptions : class;

    // New: async counterpart to ValidateDataAnnotations()
    [RequiresUnreferencedCode("Uses DataAnnotationValidateOptionsAsync which is unsafe given that " +
        "the options type passed in when calling ValidateAsync cannot be statically analyzed so its " +
        "members may be trimmed.")]
    public static OptionsBuilder<TOptions> ValidateDataAnnotationsAsync<[DynamicallyAccessedMembers(
        DynamicallyAccessedMemberTypes.PublicProperties |
        DynamicallyAccessedMemberTypes.NonPublicProperties)] TOptions>(
        this OptionsBuilder<TOptions> optionsBuilder) where TOptions : class;
}

API Usage

Scenario 1: Async DataAnnotations at startup

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
builder.Services.AddOptions<TenantDatabaseSettings>()
    .Bind(builder.Configuration.GetSection("Database"))
    .ValidateDataAnnotationsAsync()   // registers DataAnnotationValidateOptionsAsync<T>
    .ValidateOnStart();               // runs async validators at Host.StartAsync()

// What happens at startup:
// Host.StartAsync()
//   → IAsyncStartupValidator.ValidateAsync(ct)
//     → DataAnnotationValidateOptionsAsync<TenantDatabaseSettings>.ValidateAsync()
//       → Validator.TryValidateObjectAsync(settings, ctx, results, true, ct)
//         → [Required], [Range] run synchronously (Phase 1)
//         → [AsyncConnectionStringValid] runs asynchronously (Phase 2)
//       → OptionsValidationException if validation fails → app won't start

Scenario 2: Mixed sync + async DataAnnotations

Sync and async pipelines coexist. Sync validators run inside OptionsFactory.Create() on every IOptions<T>.Value access; async validators run once during Host.StartAsync().

builder.Services.AddOptions<SmtpSettings>()
    .Bind(builder.Configuration.GetSection("Smtp"))
    .ValidateDataAnnotations()        // sync [Required], [Range] — runs in Create()
    .ValidateDataAnnotationsAsync()   // async [AsyncSmtpReachable] — runs at startup
    .ValidateOnStart();

Alternative Designs

Fold into ValidateDataAnnotations()

Merging async registration into the existing sync method was considered and rejected: every existing call to ValidateDataAnnotations() would silently register async startup infrastructure even on options types with zero AsyncValidationAttribute instances — adding a reflection walk at startup for all existing users. The explicit opt-in model (ValidateDataAnnotationsAsync() as a separate call) is consistent with how the rest of #128100 is scoped.

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

No response

[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.