Add async startup validation for Microsoft.Extensions.Options by ViveliDuCh · Pull Request #128788 · dotnet/runtime

ViveliDuCh · 2026-05-29T23:53:32Z

Implements async startup validation for Microsoft.Extensions.Options as approved in API review.

Follow-up to #128656

Source generator support ([OptionsValidator] emitting ValidateAsync()) is tracked separately in #128882.

OptionsFactory.Create() and IOptions<T>.Value remain fully synchronous. Async validators run in a separate step during Host.StartAsync() only. Lazy validation via .Value and runtime reload via IOptionsMonitor<T> are not affected. See design rationale.

What's included

IAsyncValidateOptions<TOptions> — async counterpart to IValidateOptions<T> returning Task<ValidateOptionsResult>
IAsyncStartupValidator — async counterpart to IStartupValidator for host-level startup validation
AsyncValidateOptions<TOptions> through AsyncValidateOptions<TOptions, TDep1..TDep5> — lambda-based async validators (0–5 dependencies), mirroring the sync ValidateOptions<T, TDep> family
Async Validate overloads on OptionsBuilder<TOptions> (0–5 dependencies) — registers IAsyncValidateOptions<T> via lambda
DataAnnotationValidateOptionsAsync<TOptions> — async counterpart to DataAnnotationValidateOptions<T>, calls Validator.TryValidateObjectAsync and walks [ValidateObjectMembers]/[ValidateEnumeratedItems] recursively
ValidateDataAnnotationsAsync() extension method on OptionsBuilderDataAnnotationsExtensions
StartupValidator extended to implement IAsyncStartupValidator — runs sync validators first, then async validators, collecting all OptionsValidationExceptions
Host.StartAsync() updated to prefer IAsyncStartupValidator when available, falling back to sync IStartupValidator
ValidateOnStart() extended to register async validator entries alongside sync entries when IAsyncValidateOptions<T> services are present
Ref assembly updates for the full async Options API surface

Not in scope

No IAsyncOptions<T>, IAsyncOptionsSnapshot<T>, or IAsyncOptionsMonitor<T> — lazy async resolution is blocked by IOptions<T>.Value being a C# property and OptionsCache using Lazy<T> / ConcurrentDictionary (no async counterparts in the BCL)
No runtime async re-validation on IOptionsMonitor<T> config changes — OnChange callbacks remain sync-only
No Options validation source generator changes — the [OptionsValidator] source generator emitting ValidateAsync() for IAsyncValidateOptions<T> is tracked separately

Implementation notes

StartupValidator.ValidateAsync() calls sync Validate() first (which triggers IOptions<T>.Value → OptionsFactory.Create() → sync validators), then iterates registered async validators sequentially
ValidateOnStart() registers both sync and async entries in StartupValidatorOptions. Async entries are only added when IAsyncValidateOptions<T> services are detected at configure-time
Host.StartAsync() resolves IAsyncStartupValidator first; if not available, falls back to IStartupValidator (backward compatible)
Multiple OptionsValidationExceptions from different async validators are aggregated into an AggregateException when more than one fails

API review decisions reflected

Task<ValidateOptionsResult> return type on IAsyncValidateOptions<T> (not ValueTask)
IAsyncStartupValidator as a separate interface (not extending IStartupValidator)
Async lambda Validate overloads on OptionsBuilder<T> accept Func<TOptions, ..., CancellationToken, Task<bool>>
StartupValidator implements both IStartupValidator and IAsyncStartupValidator, registered as a single service

Implement the async validation API surface approved in dotnet#128100 (DataAnnotations layer): New types: - AsyncValidationAttribute: abstract base class for async validation scenarios. IsValid(object?, ValidationContext) is abstract override; IsValidAsync is the primary async entry point. Sealed override of IsValid(object?) delegates to the context overload. - IAsyncValidatableObject: extends IValidatableObject with ValidateAsync returning IAsyncEnumerable<ValidationResult>. No default interface method. New Validator async methods (8 total): - TryValidateObjectAsync (2 overloads) - TryValidatePropertyAsync - TryValidateValueAsync - ValidateObjectAsync (2 overloads) - ValidatePropertyAsync - ValidateValueAsync All return Task/Task<bool> per API review decision. Implementation details: - 3-step async pipeline matching sync structure: property validation, type attributes, IAsyncValidatableObject/IValidatableObject. - Property validation runs in parallel via Task.WhenAny with linked CancellationTokenSource for cooperative breakOnFirstError. - Per-value validation is two-phase: sync attributes first (abort early), then async attributes in parallel. - try/finally blocks observe in-flight tasks on all exit paths to prevent UnobservedTaskException from the finalizer thread. Refactoring: - Extracted EnsureValidationResultErrorMessage as private protected helper in ValidationAttribute, shared by sync GetValidationResult and async GetValidationResultAsync. - Added RequiresValidationContext XML remark clarifying async behavior. - Added ValidationContext.Items thread-safety remark for parallel async validation. Tests: ~112 test cases covering all async Validator methods, mixed sync/async attributes, breakOnFirstError with parallel async, cancellation propagation, IAsyncValidatableObject, class-level async attributes, error message formatting, sync fallback, and gate-based concurrency probing for deterministic parallelism verification. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add IAsyncValidateOptions<T> and IAsyncStartupValidator interfaces - Add AsyncValidateOptions<T, TDep1..TDep5> lambda-based validators - Add async Validate overloads on OptionsBuilder<T> (0-5 dependencies) - Extend ValidateOnStart to prefer IAsyncStartupValidator when available - Add DataAnnotationValidateOptionsAsync<T> and ValidateDataAnnotationsAsync extension - Wire IAsyncStartupValidator into Host.StartAsync

dotnet-policy-service · 2026-05-29T23:55:06Z

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

Copilot

Pull request overview

This PR adds asynchronous startup validation to Microsoft.Extensions.Options, building on async DataAnnotations support from PR #128656. It introduces a parallel async validation pipeline that runs during Host.StartAsync() while leaving the synchronous IOptions<T>.Value / OptionsFactory.Create() path untouched, so existing behavior is preserved.

Changes:

New public APIs: IAsyncValidateOptions<T>, IAsyncStartupValidator, AsyncValidateOptions<TOptions> (0–5 deps), DataAnnotationValidateOptionsAsync<T>, async Validate overloads on OptionsBuilder<T>, and ValidateDataAnnotationsAsync().
StartupValidator now also implements IAsyncStartupValidator (running sync validators first, then async); ValidateOnStart() registers async entries when IAsyncValidateOptions<T> services are present.
Host.StartAsync() prefers IAsyncStartupValidator over IStartupValidator when both are registered, with corresponding ref-assembly updates and System.ComponentModel.Annotations async validation primitives (AsyncValidationAttribute, IAsyncValidatableObject, async Validator methods).

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`src/libraries/System.ComponentModel.Annotations/src/System/ComponentModel/DataAnnotations/AsyncValidationAttribute.cs`	New abstract base for async validation attributes.
`src/libraries/System.ComponentModel.Annotations/src/System/ComponentModel/DataAnnotations/IAsyncValidatableObject.cs`	New interface extending `IValidatableObject` with `IAsyncEnumerable` results.
`src/libraries/System.ComponentModel.Annotations/src/System/ComponentModel/DataAnnotations/Validator.cs`	Adds 8 async `Validator` methods with two-phase parallel async validation.
`src/libraries/System.ComponentModel.Annotations/src/System/ComponentModel/DataAnnotations/ValidationAttribute.cs`	Adds `EnsureValidationResultErrorMessage` helper used by both sync and async paths.
`src/libraries/System.ComponentModel.Annotations/src/System/ComponentModel/DataAnnotations/ValidationContext.cs`	Doc-only thread-safety remarks for `Items`.
`src/libraries/System.ComponentModel.Annotations/src/System.ComponentModel.Annotations.csproj`	Includes new files in compilation.
`src/libraries/System.ComponentModel.Annotations/ref/System.ComponentModel.Annotations.cs`	Ref assembly for new async APIs.
`src/libraries/System.ComponentModel.Annotations/tests/System/ComponentModel/DataAnnotations/ValidatorTests.cs`	Extensive tests for `Validator.*Async` methods, parallelism, cancellation, and `IAsyncValidatableObject`.
`src/libraries/System.ComponentModel.Annotations/tests/System/ComponentModel/DataAnnotations/ValidationAttributeTests.cs`	Tests for `AsyncValidationAttribute`.
`src/libraries/Microsoft.Extensions.Options/src/IAsyncValidateOptions.cs`	New interface for async options validation.
`src/libraries/Microsoft.Extensions.Options/src/IAsyncStartupValidator.cs`	New interface for async startup validation.
`src/libraries/Microsoft.Extensions.Options/src/AsyncValidateOptions.cs`	Async validator classes (0–5 dependencies).
`src/libraries/Microsoft.Extensions.Options/src/OptionsBuilder.cs`	Async `Validate(...)` overloads.
`src/libraries/Microsoft.Extensions.Options/src/OptionsBuilderExtensions.cs`	`ValidateOnStart` now registers `IAsyncStartupValidator` and async validator entries.
`src/libraries/Microsoft.Extensions.Options/src/StartupValidatorOptions.cs`	Adds `_asyncValidators` dictionary.
`src/libraries/Microsoft.Extensions.Options/src/ValidateOnStart.cs`	`StartupValidator` implements `IAsyncStartupValidator`.
`src/libraries/Microsoft.Extensions.Options/ref/Microsoft.Extensions.Options.cs`	Ref assembly updates for async API surface.
`src/libraries/Microsoft.Extensions.Options.DataAnnotations/src/DataAnnotationValidateOptionsAsync.cs`	Async DataAnnotations validator for options (recursive `[ValidateObjectMembers]`/`[ValidateEnumeratedItems]`).
`src/libraries/Microsoft.Extensions.Options.DataAnnotations/src/OptionsBuilderDataAnnotationsExtensions.cs`	Marks the class `partial`.
`src/libraries/Microsoft.Extensions.Options.DataAnnotations/src/OptionsBuilderDataAnnotationsExtensions.Async.cs`	Adds `ValidateDataAnnotationsAsync<T>` extension.
`src/libraries/Microsoft.Extensions.Options.DataAnnotations/src/Microsoft.Extensions.Options.DataAnnotations.csproj`	Excludes async sources for non-`NetCoreAppCurrent`.
`src/libraries/Microsoft.Extensions.Options.DataAnnotations/ref/Microsoft.Extensions.Options.DataAnnotations.csproj` / `.Async.cs`	Ref assembly entries for async API.
`src/libraries/Microsoft.Extensions.Hosting/src/Internal/Host.cs`	Prefers `IAsyncStartupValidator` over `IStartupValidator` during `StartAsync`.

tarekgh

review

tarekgh · 2026-06-01T18:31:32Z

The PR currently has no test coverage for the Options layer. All test files in the diff (ValidationAttributeTests.cs, ValidatorTests.cs) belong to System.ComponentModel.Annotations (from PR #128656).

The following Options-specific scenarios have no tests:

AsyncValidateOptions<T>.ValidateAsync name matching and skipping
OptionsBuilder.Validate async registration and execution
StartupValidator.ValidateAsync with mixed sync and async validators
Host.StartAsync with async validators present
DataAnnotationValidateOptionsAsync with nested objects, enumerables, and cycle detection
Custom IStartupValidator that does not implement IAsyncStartupValidator (related to the cast in OptionsBuilderExtensions)
ValidateOnStart with only async validators registered (no sync)
Cancellation token propagation through the Options pipeline

tarekgh · 2026-06-01T18:52:54Z

The PR description mentions that the [OptionsValidator] source generator emitting ValidateAsync() for IAsyncValidateOptions<T> is ""tracked separately"", but I could not find a dedicated tracking issue for it. Could you link the tracking issue, or file one so it does not get lost?

tarekgh

Modulo the open comments, LGTM. Thanks!

ViveliDuCh · 2026-06-02T06:43:38Z

The PR description mentions that the [OptionsValidator] source generator emitting ValidateAsync() for IAsyncValidateOptions is ""tracked separately"", but I could not find a dedicated tracking issue for it. Could you link the tracking issue, or file one so it does not get lost?

Filed #128882 to track the source generator work and linked it from the PR description. Thanks @tarekgh

…operators, use IsTargetFrameworkCompatible, add async validation tests

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 7 comments.

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

… async extensions

…ionsAsync, DataAnnotationValidateOptionsAsync)

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

    <Compile Include="System\ComponentModel\DataAnnotations\AsyncValidationAttribute.cs" />
+    <Compile Include="System\ComponentModel\DataAnnotations\AssociationAttribute.cs" />


+        public virtual Microsoft.Extensions.Options.OptionsBuilder<TOptions> Validate(System.Func<TOptions, System.Threading.CancellationToken, System.Threading.Tasks.Task<bool>> validation) { throw null; }
+        public virtual Microsoft.Extensions.Options.OptionsBuilder<TOptions> Validate(System.Func<TOptions, System.Threading.CancellationToken, System.Threading.Tasks.Task<bool>> validation, string failureMessage) { throw null; }
+        public virtual Microsoft.Extensions.Options.OptionsBuilder<TOptions> Validate<TDep>(System.Func<TOptions, TDep, System.Threading.CancellationToken, System.Threading.Tasks.Task<bool>> validation) where TDep : notnull { throw null; }
+        public virtual Microsoft.Extensions.Options.OptionsBuilder<TOptions> Validate<TDep>(System.Func<TOptions, TDep, System.Threading.CancellationToken, System.Threading.Tasks.Task<bool>> validation, string failureMessage) where TDep : notnull { throw null; }
+        public virtual Microsoft.Extensions.Options.OptionsBuilder<TOptions> Validate<TDep1, TDep2>(System.Func<TOptions, TDep1, TDep2, System.Threading.CancellationToken, System.Threading.Tasks.Task<bool>> validation) where TDep1 : notnull where TDep2 : notnull { throw null; }


+                    var validators = new List<IAsyncValidateOptions<TOptions>>(asyncValidators);
+                    if (validators.Count > 0)
+                    {
+                        vo._asyncValidators[(typeof(TOptions), optionsBuilder.Name)] = async (CancellationToken ct) =>
+                        {
+                            // Retrieve the options value (already created by sync Validate() call)
+                            TOptions optionsValue = options.Get(optionsBuilder.Name);
+
+                            // Run async validators
+                            List<string>? failures = null;
+                            foreach (IAsyncValidateOptions<TOptions> validator in validators)
+                            {
+                                ValidateOptionsResult result = await validator.ValidateAsync(optionsBuilder.Name, optionsValue, ct).ConfigureAwait(false);
+                                if (result is not null && result.Failed)
+                                {
+                                    failures ??= new List<string>();
+                                    failures.AddRange(result.Failures);
+                                }
+                            }
+
+                            if (failures is not null && failures.Count > 0)
+                            {
+                                throw new OptionsValidationException(optionsBuilder.Name, typeof(TOptions), failures);
+                            }
+                        };


+                if (exceptions.Count > 1)
+                {
+                    throw new AggregateException(exceptions);
+                }


+        /// <exception cref="System.AggregateException">
+        /// Multiple validators return failed <see cref="ValidateOptionsResult"/> results when validating.
+        /// </exception>


ViveliDuCh and others added 2 commits May 29, 2026 15:22

Copilot AI review requested due to automatic review settings May 29, 2026 23:53

Copilot started reviewing on behalf of ViveliDuCh May 29, 2026 23:53 View session

github-actions Bot added the area-System.ComponentModel.DataAnnotations label May 29, 2026

dotnet-policy-service Bot assigned ViveliDuCh May 29, 2026

Copilot AI reviewed May 29, 2026

View reviewed changes

build-analysis Bot mentioned this pull request May 30, 2026

XHarness package install failure on iOS due to devicectl NSPOSIXErrorDomain error 49 #123796

Open