Unify sync/async Options validation contract

[oroztocil]

Summary

Unifies synchronous and asynchronous options validation under one validator collection while keeping synchronous and asynchronous startup validation as independent compatibility routes.

Fixes#130719
Fixes#131906

Approved contract shape

The two approved rules are intentionally different:

Contract	Consumer behavior	Correct registration
IAsyncValidateOptions<TOptions> : IValidateOptions<TOptions>	Enumerate IValidateOptions<TOptions> and cast for asynchronous capability	Register as IValidateOptions<TOptions> or through OptionsBuilder<TOptions>.Validate<TValidator>()
Independent IStartupValidator and IAsyncStartupValidator interfaces	Resolve each startup contract independently and select the applicable route	Register only as the startup route the implementation is intended to provide

IStartupValidator is now obsolete (SYSLIB0066) in favor of IAsyncStartupValidator. IAsyncStartupValidator remains independent rather than inheriting IStartupValidator, matching the API shape approved in #131906.

Changes

Unified options-validation contract

• IAsyncValidateOptions<TOptions> now derives from IValidateOptions<TOptions>, dropping its previous contravariance.
• All validators are registered and enumerated through IValidateOptions<TOptions>. Async paths detect IAsyncValidateOptions<TOptions> as a capability and call ValidateAsync; sync-only validators continue through Validate.
• Built-in async-delegate validators implement synchronous Validate by returning Skip for nonmatching names or a failed result explaining that the validator requires asynchronous validation. They never perform sync-over-async.
• OptionsBuilder<TOptions>.Validate<TValidator>() preserves the async capability while applying the builder's options name.
• DataAnnotations registration preserves synchronous behavior and named-options filtering while participating in the unified collection.

Startup-validation routing

• ValidateOnStart exposes the built-in startup validator through both compatibility contracts as the same singleton instance.
• A custom synchronous IStartupValidator retains precedence for compatibility and runs the synchronous startup route.
• Otherwise, the host runs every registered IAsyncStartupValidator and aggregates validation failures.
• Startup validation now runs before hosted services are resolved so hosted-service constructors observe a successfully startup-validated value.
• Failure during early startup no longer causes StopAsync to dereference an unresolved hosted-service collection.

Serving the startup-validated value

• For the built-in OptionsFactory<TOptions>, ValidateOnStart uses an internal async creation path that invokes each validator exactly once in registration order.
• A successfully validated value is published into the shared monitor cache when that cache is empty and seeds the built-in IOptions<TOptions> singleton slot for the default name.
• An options value already materialized through a successful synchronous path remains the cache winner; startup validation does not replace it.
• Sync-only options retain the existing synchronous creation and caching behavior.

Scope and limitations

This PR provides asynchronous validation during host startup; it does not add asynchronous equivalents for every synchronous options API.

• IOptions<TOptions>.Value can serve the startup-seeded value after successful ValidateOnStart. Before startup, an async-only validator causes synchronous access to fail explicitly instead of returning an unvalidated value.
• IOptionsSnapshot<TOptions> remains synchronous. Async-only validators therefore make snapshot creation fail explicitly.
• Configuration reload through IOptionsMonitor<TOptions> remains synchronous. This PR does not implement asynchronous reload validation, last-known-good retention, or recovery from a faulted reload cache entry.
• A pre-startup synchronous monitor access that faults is not replaced by later startup validation.
• Async startup creation is supported only by the built-in OptionsFactory<TOptions>. Custom or derived factories use their existing synchronous creation path.
• Seeding the default unnamed value requires the built-in IOptions<TOptions> implementation. Replacing it with a custom implementation is not supported for async startup seeding.
• Registering a validator only as IAsyncValidateOptions<TOptions> is invalid because the options pipeline enumerates IValidateOptions<TOptions>. Use IValidateOptions<TOptions> or OptionsBuilder<TOptions>.Validate<TValidator>(); this PR does not add runtime detection for that static registration error.
• A custom legacy IStartupValidator intentionally replaces the built-in async startup route. New startup validators should register only as IAsyncStartupValidator.
• No public asynchronous options factory, snapshot, monitor-get, or reload API is added.

Testing

• Unified sync/async validator dispatch, ordering, name filtering, and failure aggregation.
• Startup-validator selection, compatibility aliasing, multiple async validators, cancellation, and exception aggregation.
• Startup cache seeding, existing cache winners, named options, concurrent access, custom caches, custom options implementations, and derived factories.
• Explicit behavior for pre-startup access, snapshots, and configuration reload.
• DataAnnotations registration deduplication and named-options behavior.
• Failed startup followed by StopAsync.

Note

This PR description was drafted with GitHub Copilot assistance.

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).
13 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

This PR updates Microsoft.Extensions.Options and Microsoft.Extensions.Hosting to unify synchronous/asynchronous options validation by making IAsyncValidateOptions<TOptions> derive from IValidateOptions<TOptions>, and adjusts startup validation orchestration to prefer a single async path.

Changes:

• Unifies async validators into the IValidateOptions<TOptions> collection and adds an async-capable creation path in OptionsFactory<TOptions>.
• Updates ValidateOnStart registration/orchestration to drive startup validation through IStartupValidator plus an enumerable IAsyncStartupValidator.
• Updates tests to reflect the single-path startup validation model and new override/precedence behavior.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/libraries/Microsoft.Extensions.Options/tests/Microsoft.Extensions.Options.Tests/AsyncOptionsValidationTests.cs	Updates/options startup validation tests for single-path orchestration and validator precedence; adds new coverage for enumerable async startup validators.
src/libraries/Microsoft.Extensions.Options/src/ValidateOnStart.cs	Removes outdated comment implying a two-stage host startup validation model.
src/libraries/Microsoft.Extensions.Options/src/StartupValidatorOptions.cs	Updates documentation comment for async startup validation entries (now intended to represent complete validation).
src/libraries/Microsoft.Extensions.Options/src/Resources/Strings.resx	Adds a new resource string for sync validation failing when only async validation is supported.
src/libraries/Microsoft.Extensions.Options/src/OptionsFactory.cs	Refactors sync creation to share helper logic and adds CreateAsync to dispatch per-validator capability.
src/libraries/Microsoft.Extensions.Options/src/OptionsBuilderExtensions.cs	Reworks ValidateOnStart registrations and async validation delegate construction.
src/libraries/Microsoft.Extensions.Options/src/OptionsBuilder.cs	Switches async validation registrations to register under IValidateOptions<TOptions>.
src/libraries/Microsoft.Extensions.Options/src/IAsyncValidateOptions.cs	Changes IAsyncValidateOptions<TOptions> to inherit IValidateOptions<TOptions> (and removes contravariance).
src/libraries/Microsoft.Extensions.Options/src/AsyncValidateOptions.cs	Implements the inherited synchronous Validate method with a fail-fast message for async-only validators.
src/libraries/Microsoft.Extensions.Options/ref/Microsoft.Extensions.Options.cs	Updates public ref surface for IAsyncValidateOptions<TOptions> inheritance and adds Validate to async validator types.
src/libraries/Microsoft.Extensions.Hosting/tests/UnitTests/OptionsBuilderExtensionsTests.cs	Adds hosting-level tests for sync startup validator precedence and multiple async startup validators.
src/libraries/Microsoft.Extensions.Hosting/src/Internal/Host.cs	Changes startup validation ordering and orchestration (custom sync validator takes precedence; otherwise runs async startup validators).

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).
13 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/libraries/Microsoft.Extensions.Hosting/src/Internal/Host.cs:108

• In Host.StartAsync, the async path only runs Services.GetServices(). If the resolved IStartupValidator also implements IAsyncStartupValidator but is only registered under IStartupValidator, this code enters the async path and then runs zero validators, effectively skipping startup validation. Consider ensuring an async-capable startupValidator still runs when no IAsyncStartupValidator services are registered.

 IStartupValidator? startupValidator = Services.GetService<IStartupValidator>();
if (startupValidator is not null and not IAsyncStartupValidator)
{
// For back-compatibility, a custom IStartupValidator takes precedence and fully controls
// startup validation, overriding any registered IAsyncStartupValidator instances,
// including the one registered by ValidateOnStart.
startupValidator.Validate();
}
else
{

[oroztocil]

I am setting NO-MERGE label until we get approval for the API proposal update sent out by @halter73

[tarekgh]

Reviewed the unified sync/async validation contract. The core refactor looks correct: registration-order dispatch in OptionsFactory.CreateAsync, running startup validation before hosted services, and failure aggregation in Host.StartAsync. A few reliability and compatibility issues are worth resolving or documenting before merge. The most important are the config-reload behavior and the startup-validator selection in Host.cs.

[tarekgh]

Follow-up on items beyond the inline findings above. These are mostly scope and decision items rather than line-level bugs.

API shape for IAsyncStartupValidator is unresolved. The ref surface ships two independent interfaces (IAsyncStartupValidator does not derive from IStartupValidator) and IStartupValidator is not marked [Obsolete]. This matches neither the approved proposal (derive from IStartupValidator) nor the revised proposal on the issue (obsolete IStartupValidator, no inheritance). This needs an API-review decision and the ref should match the outcome.

Startup-validator idempotency. A manual IAsyncStartupValidator.ValidateAsync() followed by the host call re-runs CreateAsync and validates a second time. Consider making the built-in validator idempotent so a user pre-validating does not double-validate at startup.

Breaking-change documentation. The issue carries needs-breaking-change-doc. The silent-skip -> throw behavior change (synchronous access of an async-validated type now fails instead of returning an unvalidated value) needs a preview migration note.

Test coverage. Please add regression tests for: config reload of an async-validated type, IOptionsSnapshot<T> throwing for async-validated types, a custom IOptionsMonitorCache<T>, a custom validator implementing both startup interfaces registered only as IStartupValidator, named async-validated options, and the seed vs GetOrAdd race.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/libraries/Microsoft.Extensions.Options/ref/Microsoft.Extensions.Options.cs:147

• API approval check: issue #130719 is labeled api-approved, and the approved API shape (bartonjs comment on 2026-07-21) has IAsyncStartupValidator : IStartupValidator. This change obsoletes IStartupValidator and (in this PR) keeps IAsyncStartupValidator as an independent interface, which does not match the currently approved proposal. Please either align the public API to the approved shape, or obtain updated API approval for the revised design and then update the ref contract accordingly before merge.

 {
void PostConfigure(string? name, TOptions options);
}
[System.ObsoleteAttribute("Implement IAsyncStartupValidator instead.", DiagnosticId = "SYSLIB0066", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
public partial interface IStartupValidator
{
void Validate();

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/libraries/Microsoft.Extensions.Options/src/IAsyncStartupValidator.cs:18

• The current api-approved issue (#130719) includes an approved API shape comment that has IAsyncStartupValidator : IStartupValidator, but this PR keeps IAsyncStartupValidator independent and instead obsoletes IStartupValidator. Please ensure the approved API shape is updated (or adjust the implementation) before merge so the shipped ref contract matches the approved proposal.

 public interface IAsyncStartupValidator
{

src/libraries/Microsoft.Extensions.Diagnostics/tests/MetricsSubscriptionManagerTests.cs:26

• This synchronous test blocks on an async startup validation (ValidateAsync().GetAwaiter().GetResult()), which can deadlock under a SynchronizationContext and makes failures harder to diagnose. Prefer making the test async and awaiting startup validation.

// Make sure the subscription manager is started.
serviceProvider.GetRequiredService<IAsyncStartupValidator>().ValidateAsync().GetAwaiter().GetResult();

[tarekgh]

LGTM, thanks @ViveliDuCh!

Will be good to get @halter73 take one last look.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/libraries/Microsoft.Extensions.Diagnostics/tests/DebugConsoleMetricListenerTests.cs:29

• This test blocks on ValidateAsync() via GetResult(). If ValidateAsync later performs real async work, sync-over-async here can lead to deadlocks and less readable exceptions. Consider converting the RemoteExecutor.Invoke callback and this test to async so ValidateAsync can be awaited.

 sp.GetRequiredService<IAsyncStartupValidator>().ValidateAsync().GetAwaiter().GetResult();

src/libraries/Microsoft.Extensions.Hosting/src/Internal/Host.cs:167

• Mixed AggregateException values (e.g., the built-in StartupValidator can aggregate OptionsValidationException plus an unexpected exception) currently get treated as a single unexpected exception and may end up nested inside the host-level AggregateException, which makes failures harder to inspect. Consider flattening AggregateException.InnerExceptions here (continuing only if they’re all OptionsValidationException; otherwise stop after adding them) so the host reports a single, flat set of failures.

 catch (Exception ex)
{
// An unexpected (non-validation) failure stops further validation, but any
// validation failures already collected are retained and reported alongside it.
(validationFailures ??= new()).Add(ex);

src/libraries/Microsoft.Extensions.Diagnostics/tests/MetricsSubscriptionManagerTests.cs:26

• This test blocks on an async startup validation call using GetResult(). Since xUnit supports async tests, converting this to an async test and awaiting ValidateAsync avoids sync-over-async and produces cleaner failure behavior if ValidateAsync ever does real async work.

 serviceProvider.GetRequiredService<IAsyncStartupValidator>().ValidateAsync().GetAwaiter().GetResult();

[halter73]