skip to content

In ASP.NET Core 10 Minimal APIs, what does the Request Delegate Generator do, when is it switched on, and why might it skip an endpoint?

level: seniorimportance: nice to knowfreq 18%

answer

  1. RequestDelegateFactory works by reflection at start-up
  2. EnableRequestDelegateGenerator MSBuild property
  3. C# interceptors on Map* call sites
  4. RDG002 and RDG004 diagnostics
  5. suppresses IL2026 and IL3050 when it succeeds

basics

~20 s

The Request Delegate Generator is a source generator that writes each Minimal API endpoint's request delegate at compile time instead of building it by reflection at start-up. PublishAot or PublishTrimmed turns it on; it skips endpoints it cannot analyse statically and reports RDG diagnostics.

solid answer

~50 s

Without it, `MapGet` and friends hand the delegate to `RequestDelegateFactory`, which inspects parameters by reflection and compiles binding code at start-up; that is why those overloads carry `[RequiresUnreferencedCode]` and `[RequiresDynamicCode]`. The **Request Delegate Generator (RDG)** does the same work at compile time: it reads each `Map*` call, generates the binding and response code, and uses **C# interceptors** to redirect the call site to the generated method. The SDK sets `EnableRequestDelegateGenerator` to `true` when `PublishAot` or `PublishTrimmed` is `true`, and you can set it yourself in a JIT app. For every endpoint it generates, a suppressor removes the IL2026 and IL3050 warnings on that `Map*` call. It skips an endpoint it cannot resolve statically, for example a handler held in a plain `Delegate` variable (`RDG002`) or an anonymous return type (`RDG004`); that endpoint falls back to run-time generation and keeps its AOT warnings.

code

csharp · 8 lines
csharp
// RDG004: anonymous return type - left to run-time generation
app.MapGet("/images/{id}/size", (string id) => new { Id = id, Width = 640, Height = 480 });

// generated at compile time: lambda handler, named record
app.MapGet("/images/{id}/dimensions", (string id) =>
    TypedResults.Ok(new ImageSize(id, 640, 480)));

public record ImageSize(string Id, int Width, int Height);

go deeper

for a junior

Recall that Minimal API endpoints can be generated at compile time and that this is what makes them usable under Native AOT.

for a middle

Explain RequestDelegateFactory versus the generator, the EnableRequestDelegateGenerator property and when the SDK turns it on.

for a senior

Read RDG warnings as AOT defects, explain the interceptor and suppressor mechanics, and reshape handlers so every endpoint is generated.

for a principal

Decide whether compile-time endpoint generation should be standard even for JIT services, based on measured start-up gains and build cost.

## What happens without the generator A Minimal API endpoint is a delegate, for example `(string id, int width, IImageStore store) => ...`. ASP.NET Core has to turn that into a `RequestDelegate`, a function of `HttpContext`, that binds `id` from the route, `width` from the query string, `store` from DI, calls your handler and writes the result. By default **`RequestDelegateFactory`** does this **at start-up**: it reflects over the parameters, builds expression trees and compiles them. That costs start-up time, and it cannot work in a Native AOT app, which has no reflection over trimmed code and no run-time compilation. That is why `MapGet(string pattern, Delegate handler)` and its siblings are annotated with both `[RequiresUnreferencedCode]` and `[RequiresDynamicCode]`. ## What the Request Delegate Generator does The **Request Delegate Generator (RDG)** is a Roslyn source generator shipped with the ASP.NET Core shared framework as `Microsoft.AspNetCore.Http.RequestDelegateGenerator.dll`. 1. At compile time it finds the `MapGet`, `MapPost`, `MapPut`, `MapDelete`, `MapPatch`, `MapMethods`, `Map` and `MapFallback` calls that take a delegate handler. 2. It analyses the handler's parameters and return type and emits the binding and response-writing code as C#. 3. It emits a **C# interceptor** that redirects that exact call site to the generated method. The SDK adds the `Microsoft.AspNetCore.Http.Generated` namespace to `InterceptorsPreviewNamespaces` for this. 4. A companion `DiagnosticSuppressor` removes **IL2026** and **IL3050** from each `Map*` call it intercepted without problems, with the justification that the call was replaced by a statically generated variant. You can read the output by setting `<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>` and looking under the `generated` folder in `obj`. ## When it is on The generator is an **off-by-default analyzer**. The SDK's targets contain: | Condition | Effect | |---|---| | `PublishAot` is `true` | `EnableRequestDelegateGenerator` defaults to `true` | | `PublishTrimmed` is `true` | `EnableRequestDelegateGenerator` defaults to `true` | | Neither, but you set `<EnableRequestDelegateGenerator>true</EnableRequestDelegateGenerator>` | on, in an ordinary JIT app | | Otherwise | off; `RequestDelegateFactory` builds every endpoint at start-up | Because these are project properties, the generator runs on every **build**, not only on publish, so `dotnet run` already exercises the generated code. The same block of the SDK targets also enables the configuration-binding source generator. ## When it skips an endpoint The generator only handles what it can prove at compile time. When it cannot, it reports an `RDG` warning and **leaves that endpoint to `RequestDelegateFactory` at run time**, so the endpoint's IL2026 and IL3050 warnings are not suppressed. Common cases: - **`RDG002`**: the handler is not a lambda, a method group, or a read-only field or variable, for example a `Delegate` passed in from elsewhere. - **`RDG003`**: a parameter cannot be resolved statically. - **`RDG004`**: the handler returns an **anonymous type**. In the image-resize API, `return new { width, height };` triggers it; a named `ResizeResult` record fixes it and can also be listed in the JSON context. - **`RDG011`**: the endpoint has generic type parameters. - **`RDG012`**: the endpoint uses an inaccessible type, such as a private nested record. - **`RDG005`** to **`RDG010`**: invalid `[AsParameters]` shapes. In a JIT app a skipped endpoint still works, just with run-time generation. In a Native AOT app the run-time path is exactly what is unsupported, so treat every `RDG` warning there as a defect. ## Checking what was generated When a handler behaves differently after `PublishAot` is switched on, compare the generated binding code with what you expected: - Turn on `EmitCompilerGeneratedFiles` and open the generator's output; each intercepted call site appears there as an interceptor location. - Search the build output for `RDG` warnings; each one points at the endpoint it skipped. - Expect the same binding rules either way: the generator is built to follow the inference rules `RequestDelegateFactory` uses, so a surprise usually means the endpoint was skipped, not bound differently. ## Why it matters in interviews - It explains why Minimal APIs are **partially** supported under AOT and MVC is not: endpoint delegates can be generated at compile time, controller discovery cannot. - It explains why some handler styles are fine on the JIT and wrong under AOT. - It is a start-up optimisation you can turn on even without AOT, after measuring that start-up matters.

  • Why do you still see IL3050 on one MapGet call in an AOT project when the others are clean?
    The generator's suppressor removes IL2026 and IL3050 only from `Map*` calls it intercepted without diagnostics. If that endpoint triggered an RDG warning, for example RDG002 for a handler stored in a `Delegate` variable or RDG004 for an anonymous return type, it was left to `RequestDelegateFactory`, so the warnings remain. Fix the RDG warning and the IL warnings go away.
  • Is it worth enabling the generator in a normal JIT-compiled Minimal API?
    It can be: endpoint construction moves from start-up to compile time, which shortens start-up for apps with many endpoints. Set `EnableRequestDelegateGenerator` to `true` and measure. It changes nothing for controllers, and endpoints it cannot handle still fall back to `RequestDelegateFactory`.

  • The Request Delegate Generator also generates code for MVC controller actions.
  • The generator runs only during dotnet publish, never on an ordinary build.
  • An endpoint the generator skips fails to compile.
  • You must add a separate NuGet package to get the Request Delegate Generator.
  • Returning an anonymous object is fine because the generator infers its shape.