Clarify assembly-sensitive behavior of `AddValidation()` in .NET 10 Minimal APIs

[gumbarros]

Summary

The current .NET 10 Minimal API validation documentation does not make it clear that AddValidation() may need to be invoked from the same assembly that defines the Minimal API endpoints.

This leads to a scenario where validation appears correctly configured but does not execute at runtime when endpoints are defined in a different assembly than where AddValidation() is registered.

Problem details

This is confusing because:

• services.AddValidation() is already registered in the host application
• Request DTOs use validation attributes such as [Required]
• Invalid payloads are accepted and return 200 OK
• There is no indication that validation metadata/resolvers are generated or registered in an assembly-sensitive way

After moving validation registration into an extension method defined in the same assembly as the Minimal API endpoints, validation starts working as expected.

Documentation gap

The documentation does not clarify:

• Whether AddValidation() can be called from any referenced assembly
• Whether it must be called from the assembly that contains Minimal API endpoint mappings
• Whether it participates in source generation, interceptor generation, or resolver registration in an assembly-sensitive way

Suggested documentation improvement

Add a section under:

APIs → Minimal APIs → Parameter binding

Proposed subsection: Validation registration and assembly considerations

This section should:

• Explicitly state any assembly requirements for AddValidation()
• Explain how validation metadata is discovered
• Provide a multi-assembly example demonstrating correct and incorrect setups
• Include troubleshooting guidance for cases where validation silently does not execute

Repro

Project layout

• AppHost (net10.0) - host application
• ApiAssembly (net10.0) - contains Minimal API endpoint mappings
• Contracts (netstandard2.0) - contains request DTOs

Contracts/CreateItemRequest.cs

using System.ComponentModel.DataAnnotations;

namespace Contracts;

public record CreateItemRequest
{
    [Required]
    public string Name { get; init; } = null!;
}

ApiAssembly/EndpointMappings.cs

using Contracts;

namespace ApiAssembly;

public static class EndpointMappings
{
    public static void MapApi(this IEndpointRouteBuilder app)
    {
        app.MapPost("/items", (CreateItemRequest request) =>
        {
            return Results.Ok();
        });
    }
}

Failing setup: AppHost/Program.cs

using ApiAssembly;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddValidation();

var app = builder.Build();

app.MapApi();

app.Run();

Request

POST /items
Content-Type: application/json

{
  "name": ""
}

Expected result

HTTP 400 Bad Request with validation errors for Name.

Actual result

HTTP 200 OK.

Working setup

ApiAssembly/ServiceCollectionExtensions.cs

namespace ApiAssembly;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddApiValidation(this IServiceCollection services)
    {
        services.AddValidation();
        return services;
    }
}

AppHost/Program.cs

using ApiAssembly;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApiValidation();

var app = builder.Build();

app.MapApi();

app.Run();

With this setup, the same invalid request correctly returns validation errors.

Why this is hard to diagnose

• The application compiles successfully
• AddValidation() is already present
• DTO attributes like [Required] appear correct
• Runtime behavior differs depending on where validation is registered

Request

Please either:

1. Document this requirement clearly in the Minimal API validation docs, or
2. Confirm this is unintended behavior and track it as a product bug

Software versions

• .NET Core
• .NET 5.0 or later
• .NET Framework
• .NET Standard

dotnet --info output

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-output does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

Host:
  Version:      10.0.4
  Architecture: x64
  Commit:       80d3e14f5e
  RID:          ubuntu.25.10-x64

.NET SDKs installed:
  10.0.104 [/usr/lib/dotnet/sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 10.0.4 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 10.0.4 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]

Other architectures found:
  None

Environment variables:
  DOTNET_BUNDLE_EXTRACT_BASE_DIR           [/home/gumbarros/.cache/dotnet_bundle_extract]

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

[wadepickett]

@gumbarros, thanks very much for providing the details on this issue for the Minimal API docs. Greatly appreicated!! It does need to be addressed.

[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 or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-03-20
Issue: 36899
Model: GitHub Copilot

---

Issue Analysis: Clarify assembly-sensitive behavior of AddValidation() in .NET 10 Minimal APIs

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The issue reports that the .NET 10 Minimal API validation documentation does not clarify that AddValidation() must be invoked from (or within) the same assembly that defines the Minimal API endpoint mappings. When AddValidation() is called in the host application assembly but endpoints are defined in a referenced assembly, validation silently does not execute—invalid payloads return 200 OK instead of 400 Bad Request.

Why this is a genuine documentation gap:

The ASP.NET Core validation system for Minimal APIs uses a source generator (ValidationsGenerator) that employs C# interceptors to intercept the AddValidation() call at compile time. The source generator scans the calling assembly for validatable types and endpoint handlers, then generates a ValidatableInfoResolver with resolver code specific to that assembly. If AddValidation() is called from an assembly that does not contain the endpoint definitions, the source generator in that assembly has no visibility into the endpoint handler types in a different assembly, and no validation resolvers are generated for those types.

This behavior is confirmed by the product source code in dotnet/aspnetcore:

• src/Validation/gen/Emitters/ValidationsGenerator.Emitter.cs — The generator only emits code when an AddValidation call is found in the same compilation unit and only discovers types visible in that compilation.

The existing Blazor documentation already addresses this exact pattern in a "Use validation models from a different assembly" section, demonstrating the workaround of calling AddValidation() from each assembly. However, no equivalent guidance exists for the Minimal API validation docs.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/fundamentals/minimal-apis.md	81-133	"Validation support in Minimal APIs"
Release notes include	aspnetcore/release-notes/aspnetcore-10/includes/ValidationSupportMinAPI.md	1-37	"Validation support in Minimal APIs"
Validation package include	aspnetcore/includes/validation-package-net10.md	1-27	"Validation in .NET 10"
Blazor validation (precedent to refer to as a way to fix this issue)	aspnetcore/blazor/forms/validation.md	1748-1794	"Use validation models from a different assembly"

📝 Preliminary Change Assessment

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

Potential Documentation Update 1: Main Minimal APIs article

File: aspnetcore/fundamentals/minimal-apis.md
Location: Lines 105-114 (after the "Enable built-in validation support for Minimal APIs" heading and AddValidation() code sample)
Type: New [!NOTE] block + subsection

Current content (lines 107-113):

Enable the built-in validation support for Minimal APIs by calling the `AddValidation` extension method to register the required services in the service container for your application:

```csharp
builder.Services.AddValidation();

The implementation automatically discovers types that are defined in Minimal API handlers or as base types of types defined in Minimal API handlers. An endpoint filter performs validation on these types and is added for each endpoint.

**Suggested direction:**

After line 113, add a `[!NOTE]` block and a new subsection:

```markdown
> [!NOTE]
> `AddValidation()` uses a source generator to discover validatable types at compile time. The source generator only discovers types within the assembly where `AddValidation()` is called. If your Minimal API endpoints are defined in a different assembly than where `AddValidation()` is registered, the source generator will not discover those endpoint handler types, and validation will silently not execute.

### Validation registration in multi-assembly applications

When