Move two-stage validation to Host.cs, fix cancellation rethrow, merge async extensions

Author: ViveliDuCh

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

@@ -66,6 +66,7 @@ public Host(IServiceProvider services,
         /// Order:
         ///  IHostLifetime.WaitForStartAsync
         ///  Services.GetService{IStartupValidator}().Validate()
+        ///  Services.GetService{IAsyncStartupValidator}().ValidateAsync()
         ///  IHostedLifecycleService.StartingAsync
         ///  IHostedService.Start
         ///  IHostedLifecycleService.StartedAsync
@@ -96,23 +97,31 @@ public async Task StartAsync(CancellationToken cancellationToken = default)
                     _hostedServices ??= Services.GetRequiredService<IEnumerable<IHostedService>>();
                     _hostedLifecycleServices = GetHostLifecycles(_hostedServices);
 
-                    // Call startup validators (prefer async if available).
-                    // IAsyncStartupValidator takes precedence; the built-in StartupValidator implements both
-                    // interfaces and its ValidateAsync() calls Validate() internally.
+                    // Two-stage startup validation:
+                    // Stage 1 (sync): Run IStartupValidator.Validate() — iterates _validators dictionary
+                    //   (or user's custom implementation if registered).
+                    //   If sync validation fails, skip async to avoid expensive I/O on invalid config.
+                    // Stage 2 (async): Run IAsyncStartupValidator.ValidateAsync() — iterates _asyncValidators
+                    //   dictionary (or user's custom implementation if registered).
+                    //
+                    // Each interface is resolved independently via DI. TryAddTransient semantics ensure
+                    // user-registered implementations replace the built-in for each interface separately.
+                    IStartupValidator? validator = Services.GetService<IStartupValidator>();
+                    validator?.Validate();
+
                     IAsyncStartupValidator? asyncValidator = Services.GetService<IAsyncStartupValidator>();
                     if (asyncValidator is not null)
                     {
                         await asyncValidator.ValidateAsync(cancellationToken).ConfigureAwait(false);
                     }
-                    else
-                    {
-                        IStartupValidator? validator = Services.GetService<IStartupValidator>();
-                        validator?.Validate();
-                    }
                 }
                 catch (Exception ex)
                 {
-                    cancellationToken.ThrowIfCancellationRequested();
+                    if (ex is OperationCanceledException)
+                    {
+                        cancellationToken.ThrowIfCancellationRequested();
+                    }
+
                     // service factory or validation failed, abort startup.
                     exceptions.Add(ex);
                     LogAndRethrow();

src/libraries/Microsoft.Extensions.Options.DataAnnotations/src/Microsoft.Extensions.Options.DataAnnotations.csproj

@@ -18,7 +18,6 @@
 
   <ItemGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net11.0'))">
     <Compile Remove="DataAnnotationValidateOptionsAsync.cs" />
-    <Compile Remove="OptionsBuilderDataAnnotationsExtensions.Async.cs" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' != '$(NetCoreAppCurrent)'">

src/libraries/Microsoft.Extensions.Options.DataAnnotations/src/OptionsBuilderDataAnnotationsExtensions.Async.cs

@@ -9,7 +9,7 @@ namespace Microsoft.Extensions.DependencyInjection
     /// <summary>
     /// Extension methods for adding configuration related options services to the DI container via <see cref="OptionsBuilder{TOptions}"/>.
     /// </summary>
-    public static partial class OptionsBuilderDataAnnotationsExtensions
+    public static class OptionsBuilderDataAnnotationsExtensions
     {
         /// <summary>
         /// Register this options instance for validation of its DataAnnotations.
@@ -24,5 +24,25 @@ public static partial class OptionsBuilderDataAnnotationsExtensions
             optionsBuilder.Services.AddSingleton<IValidateOptions<TOptions>>(new DataAnnotationValidateOptions<TOptions>(optionsBuilder.Name));
             return optionsBuilder;
         }
+
+#if NET11_0_OR_GREATER
+        /// <summary>
+        /// Register this options instance for asynchronous validation of its DataAnnotations.
+        /// </summary>
+        /// <typeparam name="TOptions">The options type to be configured.</typeparam>
+        /// <param name="optionsBuilder">The options builder to add the services to.</param>
+        /// <returns>The <see cref="OptionsBuilder{TOptions}"/> so that additional calls can be chained.</returns>
+        /// <remarks>
+        /// Async validators run only at startup when used with <c>ValidateOnStart</c>.
+        /// <see cref="IOptionsMonitor{TOptions}"/> reload validation uses only synchronous validators.
+        /// </remarks>
+        [RequiresUnreferencedCode("Uses DataAnnotationValidateOptionsAsync which is unsafe given that the options type passed in when calling Validate 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
+        {
+            optionsBuilder.Services.AddSingleton<IAsyncValidateOptions<TOptions>>(new DataAnnotationValidateOptionsAsync<TOptions>(optionsBuilder.Name));
+            return optionsBuilder;
+        }
+#endif
     }
 }

src/libraries/Microsoft.Extensions.Options.DataAnnotations/src/OptionsBuilderDataAnnotationsExtensions.cs

@@ -55,11 +55,8 @@ public void Validate()
 
         public async Task ValidateAsync(CancellationToken cancellationToken = default)
         {
-            // Run sync validators first. If sync validation fails, skip async validators
-            // to avoid expensive I/O operations on already-invalid configuration (two-stage validation).
-            Validate();
-
-            // Then run async validators
+            // Async validators only — sync validation is handled separately by
+            // IStartupValidator.Validate() in Host.StartAsync() (two-stage orchestration).
             List<Exception>? exceptions = null;
 
             foreach (Func<CancellationToken, Task> asyncValidator in _validatorOptions._asyncValidators.Values)

src/libraries/Microsoft.Extensions.Options/src/ValidateOnStart.cs

@@ -76,7 +76,7 @@ public async Task OptionsBuilder_AsyncValidate_RegistersAndExecutes()
         }
 
         [Fact]
-        public async Task StartupValidator_ValidateAsync_RunsBothSyncAndAsyncValidators()
+        public async Task StartupValidator_TwoStage_RunsBothSyncAndAsyncValidators()
         {
             var services = new ServiceCollection();
             bool syncRan = false;
@@ -93,16 +93,19 @@ public async Task StartupValidator_ValidateAsync_RunsBothSyncAndAsyncValidators(
                 .ValidateOnStart();
 
             ServiceProvider sp = services.BuildServiceProvider();
-            var validator = sp.GetRequiredService<IAsyncStartupValidator>();
-
-            await validator.ValidateAsync(CancellationToken.None);
 
+            // Two-stage orchestration: Host.cs calls Validate() then ValidateAsync() independently
+            var syncValidator = sp.GetRequiredService<IStartupValidator>();
+            syncValidator.Validate();
             Assert.True(syncRan);
+
+            var asyncValidator = sp.GetRequiredService<IAsyncStartupValidator>();
+            await asyncValidator.ValidateAsync(CancellationToken.None);
             Assert.True(asyncRan);
         }
 
         [Fact]
-        public async Task StartupValidator_ValidateAsync_SyncFailureSkipsAsyncValidators()
+        public async Task StartupValidator_TwoStage_SyncFailureSkipsAsyncValidators()
         {
             var services = new ServiceCollection();
             bool asyncRan = false;
@@ -118,9 +121,13 @@ public async Task StartupValidator_ValidateAsync_SyncFailureSkipsAsyncValidators
                 .ValidateOnStart();
 
             ServiceProvider sp = services.BuildServiceProvider();
-            var validator = sp.GetRequiredService<IAsyncStartupValidator>();
 
-            await Assert.ThrowsAsync<OptionsValidationException>(() => validator.ValidateAsync(CancellationToken.None));
+            // Stage 1: Sync throws — in Host.cs, this prevents reaching Stage 2
+            var syncValidator = sp.GetRequiredService<IStartupValidator>();
+            Assert.Throws<OptionsValidationException>(() => syncValidator.Validate());
+
+            // Stage 2 is never reached because the exception propagates.
+            // Verify async didn't run (simulating Host.cs short-circuit behavior).
             Assert.False(asyncRan);
         }