Rework Blazor validation docs and add .NET 11 features - #37488
Conversation
This comment was marked as resolved.
This comment was marked as resolved.
|
@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. |
3771431 to
1d6acd7
Compare
1d6acd7 to
f63dc43
Compare
f63dc43 to
5f961c1
Compare
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
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b1616697-b97e-43c8-bba6-eadce0a68d2c
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b1616697-b97e-43c8-bba6-eadce0a68d2c
5f961c1 to
8a59e0e
Compare
oroztocil
changed the title
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b1616697-b97e-43c8-bba6-eadce0a68d2c
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b1616697-b97e-43c8-bba6-eadce0a68d2c
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b1616697-b97e-43c8-bba6-eadce0a68d2c
|
Hi @guardrex! I wanted to have this ready sooner, but here is my proposed rework of the Blazor form validation docs, including some parts of the new shared ASP/MEV validation article. I know this is a lot - and probably cannot be read in the diff mode. The details are probably not perfect, and I defer to your expertise there. However, I truly think that the overall direction is a significant improvement in clarity and usability of the validation section. I am also not 100% sure that I (or my copilot) did everything correctly on the technical side (the special markup, references, etc.). Feel free to push fixes and stylistic improvements to the branch. If you would want me to rewrite or extend something content-wise, let me know. Thanks! |
|
Thanks for doing all of this work, @oroztocil! I'm sure that it will be a vast improvement. I'm already gone for the weekend 🏖️😄. I'll review first thing on Monday morning. Have a great weekend! 🍻 |
|
Closing and reopening to fix workflows. |
|
I'm going to close and re-open to rebuild this with the sample updates in place (dotnet/blazor-samples#662). |
|
@guardrex Regarding the broken samples from the blazor-samples repo: Would it work for you if I ask my copilot (which has the full context of the overall change) to make all the new/modified code examples in this PR inline, so that we can fully revert the blazor-samples PR, get this PR merged, and then look at updating the samples correctly later. |
|
Yes ... but since I'm reviewing now, wouldn't it be best to let me get my review done first? That way, you could react to my feedback first. It should result in a cleaner update. I should have my review in to you within a couple of hours. |
|
@guardrex Yes, that sounds good. Thanks! 🙂 |
There was a problem hiding this comment.
Wowzers, @oroztocil! 🤩 Quite an amazing set of updates! I ❤️ everything that you've done here, and I'm sure @danroth27 is excited as well to see these improvements and new content going in.
I just have NITs here and there and some grammatical suggestions on the diff. For things like the header cross-linking and underscore naming of fields, let's go ahead with what you're doing. If I need to make updates, I'll do them separately with Wade and Tom later.
A few more things to do here, too ...........
Please update the ms.dates for the following articles to today:
- aspnetcore/blazor/forms/binding.md
- aspnetcore/blazor/forms/index.md
- aspnetcore/fundamentals/localization/make-content-localizable.md
- aspnetcore/fundamentals/minimal-apis.md
In order to get the release notes sucked into the main release notes article via these INCLUDES, update the date of the release notes article to today ...
https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/release-notes/aspnetcore-11.md
- ms.date: 09/14/2026
+ ms.date: 09/22/2026
There was a problem hiding this comment.
Wowzers, @oroztocil! 🤩 Quite an amazing set of updates! I ❤️ everything that you've done here, and I'm sure @danroth27 is excited as well to see these improvements and new content going in.
I just have NITs here and there and some grammatical+style suggestions on the diff. For things like the header cross-linking and underscore naming of fields, let's go ahead with what you're doing. If I need to make updates, I'll do them separately with Wade and Tom later.
WRT the new 11.0 "BlazorSample_BlazorWebApp" sample, I'll try to roll in the rest of the 10.0 sample's code examples later. I tend to do that immediately before or after GA.
I'm sure you see the sample cross-link errors on the build, as we chatted about. Yes, I hope Copilot can fix those for you now that my review is done.
A few more things to do here, too ...........
Please update the ms.dates for the following articles to today:
- aspnetcore/blazor/forms/binding.md
- aspnetcore/blazor/forms/index.md
- aspnetcore/fundamentals/localization/make-content-localizable.md
- aspnetcore/fundamentals/minimal-apis.md
Please update the date of the release notes article to today ...
https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/release-notes/aspnetcore-11.md
- ms.date: 09/14/2026
+ ms.date: 09/22/2026That rebuilds the article and draws those INCLUDES files into it. Otherwise, only the INCLUDES files are updated, and the live Learn site doesn't show the new content.
guardrex
left a comment
guardrex
left a comment
There was a problem hiding this comment.
Ready to go, unless you have more work to do. Merge when ready, or re-ping me for another review if you need to make more changes.
|
@guardrex Thanks for the feedback and the added polish. I took basically all of your proposed changes and closely adapted the rest. Let me know how you want to proceed with the code samples. Inlining them is fine by me. Do you think we could get this deployed soon? I would love to be able to point testers at the updated docs while they are testing the new features. |
|
The only code updates would be if you want to replace underscores in the 11.0 samples (Blazor samples repo) that you put up. Other than that, this is ready to |
. Merge it when you're ready. I'll then take it live after the
3 participants
Reworks the validation documentation and adds coverage for the validation features introduced in .NET 11.
Motivation
The main Blazor validation article had grown to more than 1,500 lines as new scenarios were added over several releases. It mixed the common form workflow with lower level APIs and specialized tutorials, making basic guidance difficult to find and related concepts difficult to distinguish.
Before this rework:
EditContextusage, validator components, asynchronous validation, client side validation, and remote validation instead of progressing from common to advanced tasks.AddValidationchanges and howDataAnnotationsValidatorselects its validation path, was buried far from the first examples.ValidationMessageStorepatterns were spread across several sections, which obscured the distinction between the two approaches.Microsoft.Extensions.Validationbehavior also applies to Minimal APIs.A companion pull request, dotnet/blazor-samples#662, contains the referenced samples. This pull request shouldn't merge first because the new
:::codereferences depend on those sample files.New documentation layout
EditContextvalidation, messages, field appearance, validation state, and form submissionMicrosoft.Extensions.Validationand DataAnnotations guidance for Blazor and Minimal APIsThe forms index and related articles route readers to the appropriate level instead of placing every scenario in one long Blazor article. Version-specific content remains available from ASP.NET Core 3.1 through 11.0.
Moved
InputTextinput-event guidance moved to the forms binding article because it describes binding behavior rather than validation.Dropped or reduced
Added for .NET 11
AsyncValidationAttribute,IAsyncValidatableObject, andEditContext, includingValidateAsync, field and form pending and faulted state, and the default field state CSS classes.Documentation usability experiment
I tested the updated articles by assigning a set of questions and programming tasks involving Blazor form validation to a group of isolated AI agents that intentionally ran with cheap models (Haiku, Flash, Luna, etc.) and had no access to internet search. The goal was to ensure that the docs are complete and easy to understand. I did three rounds of this experiment and updated the docs with additional details, code examples, or simply clarification. I stopped when all the agents were able to produce good results.
Verification
The articles were rendered and checked for every supported version from ASP.NET Core 3.1 through 11.0. Moniker ranges, code fences, links, anchors, sample references, and version-specific API availability were verified, and the new samples were built and exercised.
Internal previews
Toggle expand/collapse
Build report