Document .NET 11 DataAnnotations async validation - #13101
Open
ViveliDuCh wants to merge 3 commits into
Open
ViveliDuCh wants to merge 3 commits into
ViveliDuCh wants to merge 3 commits into
Conversation
Port source documentation for async validation and fill existing documentation gaps in the System.ComponentModel.DataAnnotations namespace. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Port source remarks explaining async validator dispatch, complete validation checks, and registration ordering. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
@ViveliDuCh - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates in the /// comments in the dotnet/runtime repo (or dotnet/extensions repo) instead. |
Restore structured XML in seven remarks blocks, clarify ValidationContext.Items dictionary-copy and concurrency behavior, and fix inline documentation spacing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ViveliDuCh
force-pushed
the
docs/dataannotations-async-validation
branch
from
September 29, 2026 18:58
56e68d6 to
d86a2ff
Compare
ViveliDuCh
marked this pull request as ready for review
September 29, 2026 18:59
Contributor
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Options coverage is absent, several exception contracts are incomplete, and synchronous fallback guidance remains unresolved.
Review effort: Balanced
Findings: 5
Open (8)
What changed in this PR
Updates .NET 11 DataAnnotations documentation for asynchronous validation. Despite the stated scope, the diff contains no Options documentation changes.
Changes:
- Documents asynchronous validators, dispatch, cancellation, and fallback behavior.
- Clarifies
ValidationContext.Itemsconcurrency guidance. - Completes related validation API remarks.
| File | Description |
|---|---|
AsyncValidationAttribute.xml |
Documents asynchronous validation attributes. |
IAsyncValidatableObject.xml |
Explains asynchronous object validation. |
ValidationAttribute.xml |
Clarifies asynchronous context requirements. |
ValidationContext.xml |
Documents copied items and concurrency constraints. |
ValidationException.xml |
Adds constructor guidance. |
Validator.xml |
Documents eight asynchronous validation overloads. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+227
to
+230
| <exception cref="T:System.ArgumentNullException">When <paramref name="instance" /> is <see langword="null" />.</exception> | ||
| <exception cref="T:System.ArgumentException"> | ||
| <para>When <paramref name="instance" /> doesn't match the <see cref="P:System.ComponentModel.DataAnnotations.ValidationContext.ObjectInstance" /> on <paramref name="validationContext" />.</para> | ||
| </exception> |
Comment on lines
+283
to
+285
| When <paramref name="validateAllProperties" /> is <see langword="true" />, properties are validated | ||
| in parallel. Within each property, synchronous attributes run first; asynchronous | ||
| attributes run only if all synchronous attributes pass. |
| validation attributes have passed. | ||
| </para> | ||
| </remarks> | ||
| <exception cref="T:System.ArgumentException">When the <see cref="P:System.ComponentModel.DataAnnotations.ValidationContext.MemberName" /> of <paramref name="validationContext" /> is not a valid property.</exception> |
| Any <see cref="T:System.ComponentModel.DataAnnotations.AsyncValidationAttribute" /> instances will be evaluated asynchronously after all synchronous | ||
| validation attributes have passed. | ||
| </para> | ||
| </remarks> |
Comment on lines
+861
to
+862
| <exception cref="T:System.ArgumentNullException">When <paramref name="validationContext" /> is <see langword="null" />.</exception> | ||
| <exception cref="T:System.ComponentModel.DataAnnotations.ValidationException">When <paramref name="value" /> is invalid for this property.</exception> |
Comment on lines
+78
to
+79
| <para>This method must perform all applicable checks, including checks that can run synchronously.</para> | ||
| <para>The asynchronous <see cref="T:System.ComponentModel.DataAnnotations.Validator" /> APIs do not automatically invoke <see cref="M:System.ComponentModel.DataAnnotations.IValidatableObject.Validate(System.ComponentModel.DataAnnotations.ValidationContext)" /> first. Share common checks through a helper when needed.</para> |
| <returns>A <see cref="T:System.Threading.Tasks.Task`1" /> that is <see langword="true" /> if the object is valid, <see langword="false" /> if any validation errors are encountered.</returns> | ||
| <remarks> | ||
| <para> | ||
| This method will test each <see cref="T:System.ComponentModel.DataAnnotations.ValidationAttribute" />s specified. If |
| <returns>To be added.</returns> | ||
| <param name="value">The value to test.</param> | ||
| <param name="validationContext">Describes the object being tested.</param> | ||
| <param name="validationAttributes">The list of <see cref="T:System.ComponentModel.DataAnnotations.ValidationAttribute" />s to validate against this instance.</param> |
ViveliDuCh
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the .NET 11 DataAnnotations async-validation APIs.
AsyncValidationAttribute,IAsyncValidatableObject, and the eight asynchronousValidatoroverloads, including synchronous fallback behavior and asynchronous dispatch.ValidationContext.Itemsto describe the copied input dictionary and its read-only-during-validation usage contract, including the risk of concurrent mutation.This PR also fills pre-existing documentation gaps in the same namespace, such as the
ValidationException(string)constructor remarks. It is not limited to documentation for APIs introduced by my changes.Scope and related work
The changes are confined to documentation inside existing
<Docs>elements. They do not add or modify API signatures, assembly metadata, or framework membership.The
ValidationContext.ObjectInstanceclarification from dotnet/dotnet-api-docs#12939 is already present and is not changed.This PR is a draft while synchronous fallback guidance is reconciled with dotnet/runtime#131498. The distinction between invalid input and unsupported synchronous invocation, and the prohibition on sync-over-async, should be reviewed against that discussion. The exceptional advisory/no-op scenario remains in the ported text; the latest proposed simplification would remove that exception and retain success only for genuinely non-applicable rules. This needs agreement before final approval.
ValidationAttribute.FormatMessageand its eight overrides are not added here: their member records still need the reference-assembly import associated with dotnet/runtime#132764 and its .NET 11 backport dotnet/runtime#132853. Their prose and the dependentFormatErrorMessageupdate will follow that import.Conceptual guides, examples, and diagnostic documentation are separate follow-ups. No unrelated
IPEndPointdocumentation changes are included.Internal previews
Build report
Note
This PR description was prepared with GitHub Copilot.