Document support for async validation for Options

[danroth27]

Description

Document support for async validation for options once fully landed:

• Add async startup validation for Microsoft.Extensions.Options runtime#128788
• Add async DataAnnotations bridge for Microsoft.Extensions.Options runtime#129218
• [OptionsValidator] source generator: emit ValidateAsync() for IAsyncValidateOptions<T> runtime#130263

@ViveliDuCh @jeffhandley @halter73

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/options?view=aspnetcore-11.0#options-validation

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/configuration/options.md

Document ID

dc7e3449-650b-d117-5eac-69e5ccb250cb

Platform Id

c815d451-e2c8-0cf1-5862-03b12dd0392a

Article author

@tdykstra

Metadata

• ID: ed39cb0e-aa85-8bba-ffb4-859b56a60723
• PlatformId: c815d451-e2c8-0cf1-5862-03b12dd0392a
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

[wadepickett]

@tdykstra, this is your article. I assigned this to you, but if you can't get to it let me know and I'll see about dropping other stuff so I can get to this, or we can share the work.

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution and does not represent a final decision. A team member will review it before any action is taken.

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-08-12
Issue: 37465
Model: GitHub Copilot

---

Issue Analysis: Document async validation support for Options

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

.NET 11 adds a parallel async validation pipeline for Microsoft.Extensions.Options. The options article (options.md) currently documents only the synchronous validation pipeline (ValidateDataAnnotations() + ValidateOnStart()) in the Options validation section. The new async APIs need to be documented for the >= aspnetcore-11.0 moniker.

API landing status (verified in dotnet/runtime)

The tracking/API proposal issue dotnet/runtime#128100 is closed/completed, api-approved, milestone 11.0.0. Status of the three linked PRs:

PR	Title	Status	Milestone
runtime#128788	Async startup validation for Microsoft.Extensions.Options (runtime pipeline)	✅ Merged (2026-06-07)	11.0-preview6
runtime#129218	Async DataAnnotations bridge for Options	✅ Merged (2026-06-12)	11.0-preview6
runtime#130263	[OptionsValidator] source generator emitting ValidateAsync()	⏳ Open (mergeable_state: blocked)	none set

Implication: The runtime + DataAnnotations pieces (the primary developer-facing surface) have landed. Only the source-generator piece is still open, so source-generator-specific ValidateAsync() documentation should wait for #130263 to merge. The rest can be documented now.

Note

API surface note: The proposal in #128100 used ValueTask<ValidateOptionsResult> and ValidateOnStartAsync(), but the merged PR #128788 description states the shipped IAsyncValidateOptions<T>.ValidateAsync returns Task<ValidateOptionsResult> and that ValidateOnStart() was extended to register async validators. The exact final public signatures/method names (ValidateOnStartAsync vs. extended ValidateOnStart, Task vs. ValueTask, ValidateDataAnnotationsAsync()) must be confirmed against the shipped .NET 11 ref assemblies / API browser before writing samples.

✅ Documentation Work Already Done?

No existing documentation work was found. Verification performed as of 2026-08-12 12:50PM PST:

• Code search across aspnetcore/fundamentals/configuration for IAsyncValidateOptions, ValidateAsync, AsyncValidateOptions, ValidateOnStartAsync → no results.
• The current source file (commit c44f16825f) contains only synchronous validation content in the Options validation and ValidateOnStart sections.
• No open PRs/issues in dotnet/AspNetCore.Docs reference the async options validation APIs.

📁 Potentially Affected Files

File	Path	Lines	Section
Main article	options.md	~1051–1096	"Options validation"
Main article	options.md	~1525–1544	"Run options validation when the app starts with ValidateOnStart"

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential documentation Updates

File: options.md
Location: After the ValidateOnStart subsection (~line 1544)
Type: New subsection, moniker-gated to >= aspnetcore-11.0

Current content (the closest existing anchor, lines 1533-1544):

To run options validation when the app starts, call <xref:Microsoft.Extensions.DependencyInjection.OptionsBuilderExtensions.ValidateOnStart%2A> in the `Program` file where services are registered for dependency injection:

​```csharp
builder.Services.AddOptions<KeyOptions>()
    .Bind(builder.Configuration.GetSection(KeyOptions.Key))
    .ValidateDataAnnotations()
    .ValidateOnStart();
​```

Suggested direction (a new >= aspnetcore-11.0 subsection — signatures to be confirmed):

:::moniker range=">= aspnetcore-11.0"

### Asynchronous options validation

For validation that performs I/O (for example, verifying a connection string or
checking a remote resource), .NET 11 adds an asynchronous validation pipeline that
runs during host startup. Async validators run in a separate step during
`Host.StartAsync()`; `IOptions<T>.Value` and `OptionsFactory.Create()` remain
synchronous.

Register async validation with a lambda:

​```csharp
builder.Services.AddOptions<CloudInfoOptions>()
    .BindConfiguration("CloudInfo")
    .ValidateAsync<IStorageService>(async (options, storageService, ct) =>
        await storageService.ExistsAsync(options.Storage, ct),
        "Storage endpoint does not exist.")
    .ValidateOnStart();
​```

Or implement `IAsyncValidateOptions<TOptions>` directly:

​```csharp
public class CloudInfoValidator : IAsyncValidateOptions<CloudInfoOptions>
{
    private readonly IStorageService _storage;

    public CloudInfoValidator(IStorageService storage) => _storage = storage;

    public async Task<ValidateOptionsResult> ValidateAsync(
        string? name, CloudInfoOptions options, CancellationToken ct)
    {
        if (!await _storage.ExistsAsync(options.Storage, ct))
            return ValidateOptionsResult.Fail(
                $"Storage '{options.Storage}' not found.");
        return ValidateOptionsResult.Success;
    }
}
​```

> [!NOTE]
> Async validators run once at startup. Runtime config changes surfaced through
> `IOptionsMonitor<T>` run only synchronous validators. Async validators may run
> in parallel, so they must be safe for concurrent execution and not depend on
> execution order.

:::moniker-end

🎯 Suggested Action Plan

For documentation team review

1. Confirm shipped API surface first. Reconcile the proposal (#128100) against the merged runtime PRs (#128788, #129218) using the .NET 11 API browser/ref assemblies. Nail down: ValidateOnStart vs ValidateOnStartAsync, Task vs ValueTask return, ValidateDataAnnotationsAsync() name, and IAsyncValidateOptions<T> / IAsyncStartupValidator signatures.
2. Add a >= aspnetcore-11.0 "Asynchronous options validation" subsection to options.md after the ValidateOnStart section. Cover: lambda-based ValidateAsync, IAsyncValidateOptions<T> implementation, DataAnnotations async bridge, the startup-only/parallel-execution caveats, and the IOptionsMonitor runtime limitation.
3. Defer source-generator ([OptionsValidator] → ValidateAsync()) content until runtime#130263 merges. Track it as a follow-up so the docs don't describe an unshipped generator behavior.
4. Add sample code to the options sample project consistent with existing Blazor/Razor Pages samples in the article, gated to net11.0.
5. Cross-link to the .NET Options validation docs (/dotnet/core/extensions/options#options-validation) and, if applicable, the DataAnnotations async validation topic.

⚠️ Review Considerations

• The source-generator PR (#130263) is still open and its milestone is unset — do not document generated ValidateAsync() yet.
• Verify final method names/return types against the shipped 11.0 API before publishing; the proposal and merged PRs diverge (ValueTask vs Task, separate ValidateOnStartAsync vs extended ValidateOnStart).
• Consider whether parallel companion content in /dotnet/core/extensions/options (the .NET console-apps version) should be updated too, since this article links to it.
• Confirm whether IOptionsMonitor runtime re-validation limitation warrants a [!NOTE] in the interfaces section as well.

🔗 References

• Published article: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/options?view=aspnetcore-11.0#options-validation
• Source file: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/configuration/options.md
• Related issue: dotnet/AspNetCore.Docs#37465
• API proposal (approved, completed): dotnet/runtime#128100
• Runtime PR (merged): dotnet/runtime#128788
• DataAnnotations bridge PR (merged): dotnet/runtime#129218
• Source generator PR (open): dotnet/runtime#130263