Umwandeln von Map-Methoden in Anforderungsdelegaten mit dem Anforderungsdelegat-Generator von ASP.NET Core

Der Anforderungsdelegat-Generator (RDG) von ASP.NET Core ist ein Kompilierzeit-Quellgenerator, der Routenhandler kompiliert, die für eine minimale API bereitgestellt werden, um Delegaten anzufordern, die von der ASP.NET Core-Routinginfrastruktur verarbeitet werden können. RDG ist implizit aktiviert, wenn Anwendungen mit aktiviertem AoT veröffentlicht werden oder Kürzung aktiviert ist. RDG generiert kürzbaren und nativen AoT-kompatiblen Code.

Hinweis

• Der native AOT befindet sich derzeit in der Vorschauphase.
• In .NET 8 sind nicht alle ASP.NET Core-Features mit nativem AOT kompatibel.

Der RDG:

• Ist ein Quellgenerator
• Wandelt jede Map-Methode in einen RequestDelegate um, der der spezifischen Route zugeordnet ist. Map-Methoden umfassen die Methoden in EndpointRouteBuilderExtensions wie MapGet, MapPost, MapPatch, MapPut und MapDelete.

Beim Veröffentlichen, und wenn der native AOT nicht aktiviert ist:

• Map-Methoden, die einer bestimmten Route zugeordnet sind, werden im Arbeitsspeicher in einen Anforderungsdelegaten kompiliert, wenn die App gestartet wird, nicht, wenn die App erstellt wird.
• Die Anforderungsdelegaten werden zur Laufzeit generiert.

Beim Veröffentlichen, und wenn der native AOT aktiviert ist:

• Map-Methoden, die einer bestimmten Route zugeordnet sind, werden kompiliert, wenn die App erstellt wird. Der RDG erstellt den Anforderungsdelegaten für die Route, und der Anforderungsdelegat wird in das native Image der App kompiliert.
• Beseitigt die Notwendigkeit, den Anforderungsdelegaten zur Laufzeit zu generieren.
• Stellt sicher:
  • Dass die in den APIs der App verwendeten Typen im App-Code auf eine Weise verwurzelt sind, die von der Toolkette des nativen AOT statisch analysierbar ist
  • Dass der erforderliche Code nicht entfernt wird.

Der RDG:

• Wird automatisch in einem Projekt aktiviert, wenn beim Veröffentlichen der native AOT oder Kürzung aktiviert ist.
• Kann auch ohne nativen AOT manuell aktiviert werden, indem Sie in der Projektdatei <EnableRequestDelegateGenerator>true</EnableRequestDelegateGenerator> festlegen:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <EnableRequestDelegateGenerator>true</EnableRequestDelegateGenerator>
  </PropertyGroup>
    
</Project>

Das manuelle Aktivieren des RDG kann für Folgendes nützlich sein:

• Auswerten der Kompatibilität eines Projekts mit der nativem AOT
• Verringern der Startzeit der App, indem die Anforderungsdelegaten vorab generiert werden.

Minimale APIs sind für die Verwendung von System.Text.Jsonoptimiert, was die Verwendung des System.Text.Json-Quellgenerators erfordert. Alle Typen, die als Parameter von Anforderungsdelegaten in Minimal-APIs akzeptiert oder von diesen zurückgegeben werden, müssen in einem JsonSerializerContext konfiguriert werden, der über die Dependency Injection von ASP.NET Core registriert ist:

using System.Text.Json.Serialization;

var builder = WebApplication.CreateSlimBuilder(args);

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(
                         0, AppJsonSerializerContext.Default);
});

var app = builder.Build();

var sampleTodos = new Todo[] {
    new(1, "Walk the dog"),
    new(2, "Do the dishes", DateOnly.FromDateTime(DateTime.Now)),
    new(3, "Do the laundry", DateOnly.FromDateTime(DateTime.Now.AddDays(1))),
    new(4, "Clean the bathroom"),
    new(5, "Clean the car", DateOnly.FromDateTime(DateTime.Now.AddDays(2)))
};

var todosApi = app.MapGroup("/todos");
todosApi.MapGet("/", () => sampleTodos);
todosApi.MapGet("/{id}", (int id) =>
    sampleTodos.FirstOrDefault(a => a.Id == id) is { } todo
        ? Results.Ok(todo)
        : Results.NotFound());

app.Run();

public record Todo(int Id, string? Title, DateOnly? DueBy = null, bool IsComplete = false);

[JsonSerializable(typeof(Todo[]))]
internal partial class AppJsonSerializerContext : JsonSerializerContext
{

}

Diagnose für nicht unterstützte RDG-Szenarios

Wenn die App erstellt wird, gibt der RDG Diagnosen für Szenarios aus, die vom nativen AOT nicht unterstützt werden. Die Diagnosen werden als Warnungen ausgegeben und verhindern nicht, dass die App erstellt wird. Eine Liste der Diagnose finden Sie unter ASP.NET-Diagnose für den Request Delegate Generator.