Move section and add guidance on plain class libs (#36398)

guardrex · web-flow · commit e97cb6aba9b1 · 2025-11-26T08:45:14.000-05:00
diff --git a/aspnetcore/blazor/forms/validation.md b/aspnetcore/blazor/forms/validation.md
@@ -5,7 +5,7 @@ description: Learn how to use validation in Blazor forms.
 monikerRange: '>= aspnetcore-3.1'
 ms.author: wpickett
 ms.custom: mvc
-ms.date: 11/11/2025
+ms.date: 11/25/2025
 uid: blazor/forms/validation
 ---
 # ASP.NET Core Blazor forms validation
@@ -1572,48 +1572,6 @@ The <xref:System.ComponentModel.DataAnnotations.CompareAttribute> doesn't work w
 
 :::moniker range=">= aspnetcore-10.0"
 
-## Use validation models from a different assembly
-
-For model validation defined in a different assembly, such as a library or the `.Client` project of a Blazor Web App:
-
-* If the library is a plain class library (it isn't based on the `Microsoft.NET.Sdk.Web` or `Microsoft.NET.Sdk.Razor` SDKs), add a package reference to the library for the [`Microsoft.Extensions.Validation` NuGet package](https://www.nuget.org/packages/Microsoft.Extensions.Validation).
-* Create a method in the library or `.Client` project that receives an <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection> instance as an argument and calls <xref:Microsoft.Extensions.DependencyInjection.ValidationServiceCollectionExtensions.AddValidation%2A> on it.
-* In the app, call both the method and <xref:Microsoft.Extensions.DependencyInjection.ValidationServiceCollectionExtensions.AddValidation%2A>.
-
-The preceding approach results in validation of the types from both assemblies.
-
-In the following example, the `AddValidationForTypesInClient` method is created for the `.Client` project of a Blazor Web App for validation using types defined in the `.Client` project.
-
-`ServiceCollectionExtensions.cs` (in the `.Client` project):
-
-```csharp
-namespace BlazorSample.Client.Extensions;
-
-public static class ServiceCollectionExtensions
-{
-    public static IServiceCollection AddValidationForTypesInClient(
-        this IServiceCollection collection)
-    {
-        return collection.AddValidation();
-    }
-}
-```
-
-In the server project's `Program` file, add the namespace and call the `.Client` project's service collection extension method (`AddValidationForTypesInClient`) and <xref:Microsoft.Extensions.DependencyInjection.ValidationServiceCollectionExtensions.AddValidation%2A>:
-
-```csharp
-using BlazorSample.Client.Extensions;
-
-...
-
-builder.Services.AddValidationForTypesInClient();
-builder.Services.AddValidation();
-```
-
-:::moniker-end
-
-:::moniker range=">= aspnetcore-10.0"
-
 ## Nested objects and collection types
 
 Blazor form validation includes support for validating properties of nested objects and collection items with the built-in <xref:Microsoft.AspNetCore.Components.Forms.DataAnnotationsValidator>.
@@ -1643,6 +1601,8 @@ In the following `Order` class, the `[ValidatableType]` attribute is required on
 `Order.cs`:
 
 ```csharp
+using System.ComponentModel.DataAnnotations;
+
 [ValidatableType]
 public class Order
 {
@@ -1691,6 +1651,8 @@ In the following `OrderPage` component, the <xref:Microsoft.AspNetCore.Component
 
 The requirement to declare the model types outside of Razor components (`.razor` files) is due to the fact that both the new validation feature and the Razor compiler itself are using a source generator. Currently, output of one source generator can't be used as an input for another source generator.
 
+For guidance on using validation models from a different assembly, see the [Use validation models from a different assembly](#use-validation-models-from-a-different-assembly) section.
+
 :::moniker-end
 
 :::moniker range="< aspnetcore-10.0"
@@ -1750,6 +1712,106 @@ public class ShipDescription
 
 :::moniker-end
 
+:::moniker range=">= aspnetcore-10.0"
+
+## Use validation models from a different assembly
+
+<!-- UPDATE 11.0 - The first list item changes when the content
+                   is updated for plain class libs upon 
+                   experimental status dropping at 11.0 -->
+
+For model validation defined in a different assembly, such as a library or the `.Client` project of a Blazor Web App:
+
+* If the library is a plain class library (it isn't based on the `Microsoft.NET.Sdk.Web` or `Microsoft.NET.Sdk.Razor` SDKs), add a package reference to the library for the [`Microsoft.Extensions.Validation` NuGet package](https://www.nuget.org/packages/Microsoft.Extensions.Validation). Additional steps are required for plain class libraries, which are described later in this section.
+* Create a method in the library or `.Client` project that receives an <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection> instance as an argument and calls <xref:Microsoft.Extensions.DependencyInjection.ValidationServiceCollectionExtensions.AddValidation%2A> on it.
+* In the app, call both the method and <xref:Microsoft.Extensions.DependencyInjection.ValidationServiceCollectionExtensions.AddValidation%2A>.
+
+The preceding approach results in validation of the types from both assemblies.
+
+In the following example, the `AddValidationForTypesInClient` method is created for the `.Client` project of a Blazor Web App for validation using types defined in the `.Client` project.
+
+`ServiceCollectionExtensions.cs` (in the `.Client` project):
+
+```csharp
+namespace BlazorSample.Client.Extensions;
+
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddValidationForTypesInClient(
+        this IServiceCollection collection)
+    {
+        return collection.AddValidation();
+    }
+}
+```
+
+In the server project's `Program` file, add the namespace and call the `.Client` project's service collection extension method (`AddValidationForTypesInClient`) and <xref:Microsoft.Extensions.DependencyInjection.ValidationServiceCollectionExtensions.AddValidation%2A>:
+
+```csharp
+using BlazorSample.Client.Extensions;
+
+...
+
+builder.Services.AddValidationForTypesInClient();
+builder.Services.AddValidation();
+```
+
+<!-- UPDATE 11.0 - The following changes when the content
+                   is updated for plain class libs upon 
+                   experimental status dropping at 11.0 -->
+
+The new attributes from the `Microsoft.Extensions.Validation` package (<xref:Microsoft.Extensions.Validation.ValidatableTypeAttribute> and <xref:Microsoft.Extensions.Validation.SkipValidationAttribute>) are published as *experimental* in .NET 10. The package is intended to provide a new shared infrastructure for validation features across frameworks, and publishing experimental types provides greater flexibility for the final design of the public API for better support in consuming frameworks.
+
+In Blazor apps, types are made available via a generated embedded attribute. If a web app project that uses the `Microsoft.NET.Sdk.Web` SDK (`<Project Sdk="Microsoft.NET.Sdk.Web">`) or an RCL that uses the `Microsoft.NET.Sdk.Razor` SDK (`<Project Sdk="Microsoft.NET.Sdk.Razor">`) contains Razor components (`.razor`), the framework automatically generates an internal attribute inside the project (`Microsoft.Extensions.Validation.Embedded.ValidatableType`, `Microsoft.Extensions.Validation.Embedded.SkipValidation`). These types are interchangeable with the actual attributes and not marked experimental. In the majority of cases, developers use the `[ValidatableType]`/`[SkipValidation]` attributes on their classes without concern over their source.
+
+However, the preceding approach isn't viable in plain class libraries that use the `Microsoft.NET.Sdk` SDK (`<Project Sdk="Microsoft.NET.Sdk">`). Using the types in a plain class library results in an code analysis warning:
+
+> :::no-loc text="ASP0029: 'Microsoft.Extensions.Validation.ValidatableTypeAttribute' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.":::
+
+The warning can be suppressed using any of the following approaches:
+
+* A `<NoWarn>` property in the project file:
+
+  ```xml
+  <PropertyGroup>
+    <NoWarn>$(NoWarn);ASP0029</NoWarn>
+  </PropertyGroup>
+  ```
+
+* A [`pragma` directive](/cpp/preprocessor/pragma-directives-and-the-pragma-keyword) where the attribute is used:
+
+  ```csharp
+  #pragma warning disable ASP0029
+  [Microsoft.Extensions.Validation.ValidatableType]
+  #pragma warning restore ASP0029
+  ```
+
+* An [EditorConfig file (`.editorconfig`)](/visualstudio/ide/create-portable-custom-editor-options) rule:
+
+  ```
+  dotnet_diagnostic.ASP0029.severity = none
+  ```
+
+If suppressing the warning isn't acceptable, manually create the embedded attribute in the library that the Web and Razor SDKs generate automatically.
+
+`ValidatableTypeAttribute.cs`:
+
+```csharp
+namespace Microsoft.Extensions.Validation.Embedded
+{
+    [AttributeUsage(AttributeTargets.Class)]
+    internal sealed class ValidatableTypeAttribute : Attribute
+    {
+    }
+}
+```
+
+Use the exact namespace (`Microsoft.Extensions.Validation.Embedded`) and class name (`ValidatableTypeAttribute`) in order for the validation source generator to detect and use the type. You can declare a global `using` statement for the namespace, either with a `global using Microsoft.Extensions.Validation.Embedded;` statement or with a `<Using Include="Microsoft.Extensions.Validation.Embedded" />` item in the library's project file.
+
+Whichever approach is adopted, denote the presence of the workaround for a future update to your code. Framework updates to ease the adoption of validation types in plain class libraries are planned for .NET 11 (November, 2026).
+
+:::moniker-end
+
 ## Enable the submit button based on form validation
 
 To enable and disable the submit button based on form validation, the following example:
