Restructure and trim the Blazor validation articles - #37488
Draft
oroztocil wants to merge 3 commits into
Draft
Conversation
This comment was marked as resolved.
This comment was marked as resolved.
Member
Author
|
@guardrex Please note that this is just a rough draft and work in progress. So please don't spend time reviewing it before I undraft the PR. 🙂 I will be OOF until August 24 so I will get to finish only then, unfortunately. |
Follow-up to the validation docs restructure. Reduces article length, orders sections from the simplest and most common cases to the most advanced, and moves sample code out of the articles. Blazor forms validation * Merges the three sections that described the DataAnnotationsValidator component into one, with validation order and short-circuiting as a subsection instead of the last section in the article. * Folds the IValidatableObject stub and "Determine if a form field is valid" into the sections they belong to. * Moves the table that routes readers to nested objects, localization, client-side validation, and the advanced article near the top, so a reader looking for one of those finds it early. * Documents the default validation CSS classes, which were previously described only for static SSR. * Moves the FieldCssClassProvider guidance to the advanced article, since it customizes validation rather than explaining it. Advanced form validation * The remote validation walkthrough now references sample projects instead of carrying its code inline, and gains subsections for each step. * The per-field asynchronous validation example shows only what differs from the form-level example rather than repeating it. * The FieldCssClassProvider section arrives here, references its sample files, and gains subsections. Client-side validation in static SSR * The custom rule example references its sample files. Validation in ASP.NET Core * Condenses multi-assembly registration to one pattern with short notes for Minimal APIs and Blazor, instead of two near-identical walkthroughs. Rendered length, .NET 11: 607 to 438, 904 to 714, 283 to 232, and 521 to 483 lines respectively. Verified across all supported versions that no in-page anchor is broken, moniker blocks are balanced, and every active sample reference resolves. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 608096b5-db3e-4006-adaa-b4da0309ff87
oroztocil
force-pushed
the
oroztocil/validation-docs-rework
branch
from
August 25, 2026 11:26
3771431 to
1d6acd7
Compare
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
2 participants
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.
Reworks the Blazor forms validation documentation and adds coverage for the validation features introduced in .NET 11.
A companion pull request in the Blazor samples repository adds the sample projects that the new code references point to. This pull request should not be merged before that one, or the new
:::codereferences won't resolve.Why
The Blazor forms validation article had grown into a single 1,534-line page covering everything from "make this field required" to a multi-project remote validation tutorial. Its ordering worked against readers:
EditContext, construct aValidationMessageStore, subscribe toOnValidationRequested, write a handler. A reader whose actual question was "how do I validate this form" had to scroll past all of that to reach<DataAnnotationsValidator />.DataAnnotationsValidatorcomponent's validation order and short-circuiting was the final section on the page, roughly 1,500 lines below the component it describes.AddValidationchanges which fields are validated, whether messages are localized, and which client-side rules are emitted. It appeared only in a section near the end, presented as a nested-objects feature.Microsoft.Extensions.Validationand apply equally to Minimal APIs, but they were documented only in the Blazor article. The shared validation article had none of them.What changed
Blazor validation is now three articles
EditForm,DataAnnotationsValidator, displaying errors, and a table routing to everything elseEditContext, validator components, asynchronous validation, and the remote validation walkthroughThe entry-point article now opens with a working form as its first code sample, and the routing table appears near the top so readers self-select early.
Shared behavior moved to the shared article
Guidance that belongs to
Microsoft.Extensions.Validationrather than to Blazor now lives in the validation article that both Blazor and Minimal API readers share, which also gives Minimal API readers examples they didn't have:ValidationAttributeandIValidatableObject.AddValidationisn't called, which differs between the two frameworks and previously wasn't stated anywhere.The Blazor articles name each of these in Blazor terms and link down, so a reader who starts in the Blazor node still finds them.
New coverage for .NET 11
EditContextAPI, and displaying pending and faulted state.Corrections
Several sections documented APIs that were removed or renamed. Their samples didn't compile. These are rewritten against the shipping API, and the stale localization guidance elsewhere in the docs, which pointed at a package that no longer exists, is replaced with a pointer to the current guidance.
Trimming
The remote validation walkthrough and the custom CSS class provider guidance now reference sample projects instead of carrying their code inline, and both gained subsections. The per-field asynchronous validation example shows only what differs from the form-level example. Multi-assembly registration is one pattern with short per-framework notes rather than two near-identical walkthroughs.
Result
Rendered length for .NET 11:
The total grows, because three features gained coverage they didn't have, while the article most readers land on is about a third of its previous length.
Two topics that weren't validation topics moved out: the
InputTextinput-event guidance moved to the forms binding article, and the custom CSS class provider guidance moved to the advanced article.Verification
Checked across every supported version, from 3.1 through 11.0:
[CompareProperty], the data annotations validation package, and the pre-.NET 10 nested objects approach continue to appear for the versions that need them.The sample code was built and exercised at runtime, which surfaced four defects now fixed in the companion pull request: an unused
usingthat broke a WebAssembly build, a missing package reference, two unused exception variables, and a missing_Imports.razor.Notes
:::codereference in the pre-.NET 8 content remains commented out. Those samples use a different file naming scheme, and mapping them needs a separate change.Internal previews
Toggle expand/collapse