ASP.NET Core-Unterstützung für Native AOT

Von Mitch Denny

Das Veröffentlichen und Bereitstellen von nativen AOT-Anwendungen (Ahead-of-Time) in ASP.NET Core bietet mehrere Vorteile:

• Minimierter Datenträgerbedarf. Wenn Sie eine App mithilfe von Native AOT veröffentlichen, erzeugt der Prozess eine einzelne ausführbare Datei. Die ausführbare Datei enthält nur den Code aus den externen Abhängigkeiten, die zur Unterstützung der App erforderlich sind. Die reduzierte ausführbare Größe kann zu folgendem Ergebnis führen:

  • Kleinere Container-Images, z. B. in containerisierten Bereitstellungsszenarien.
  • Kürzere Bereitstellungsdauer durch kleinere Images

• Reduzierte Startzeit. Systemeigene AOT-Apps können weniger Startzeit erfordern, was Folgendes ermöglicht:

  • Die App für die schnellere Bearbeitung von Anfragen.
  • Verbesserte Bereitstellung, bei der die Container-Orchestratoren den Übergang von einer App-Version zu einer anderen verwalten.

• Verringerter Arbeitsspeicherbedarf. Systemeigene AOT-Apps können je nach der von der App durchgeführten Arbeit weniger Arbeitsspeicher benötigen. Eine reduzierte Arbeitsspeichernutzung kann zu einer höheren Bereitstellungsdichte und besserer Skalierbarkeit führen.

Das folgende Diagramm zeigt die Ergebnisse eines Benchmarkingtests für die verschiedenen Vorlagen-Apps. Der Benchmark vergleicht die Leistung für eine veröffentlichte AOT-App (orange), eine gekürzte Laufzeit-App (grüne Leiste) und eine ungetrimmte Laufzeit-App (gelber Balken). Der Test ergab, dass die native AOT-App eine geringere App-Größe, Speicherauslastung und Startzeit veranschaulicht.

In diesem Artikel wird die Unterstützung für native AOT-Apps in ASP.NET Core beschrieben, einschließlich einer Übersicht über die Veröffentlichung und Bereitstellung.

Informationen zu ASP.NET Core Blazor WebAssembly Native AOT-Anleitung, die die Anleitungen in diesem Artikel ergänzen oder ersetzen, finden Sie unter ASP.NET Core Blazor WebAssembly Buildtools und Ahead-of-Time-Kompilierung.

Überprüfen Sie die ASP.NET Core- und Native AOT-Kompatibilität.

Zurzeit sind nicht alle Features in ASP.NET Core mit Native AOT kompatibel.

In der folgenden Tabelle ist die Kompatibilität von ASP.NET Core-Features mit nativer AOT-Kompilierung zusammengefasst:

Merkmal	Unterstützt	Partielle Unterstützung	Nicht unterstützt
Blazor Server			❌
CORS (Cross-Origin Resource Sharing)	✔️
gRPC	✔️
HealthChecks	✔️
HttpLogging (Protokollierung von HTTP)	✔️
JWT-Authentifizierung	✔️
Lokalisierung	✔️
Minimale APIs		✔️
MVC			❌
Andere Authentifizierung			❌
Ausgabezwischenspeicherung	✔️
Ratenbegrenzung	✔️
AnfrageDekompression	✔️
Antwortzwischenspeicherung	✔️
Antwortkomprimierung	✔️
Überschreiben	✔️
Sitzung			❌
SignalR		✔️
Kurort			❌
StaticFiles	✔️
WebSockets	✔️

Weitere Informationen zu Beschränkungen finden Sie unter:

• Einschränkungen einer nativen AOT-Bereitstellung
• AOT-Warnungen
• Bekannte Kürzungsinkompatibilitäten
• Beheben von Kürzungswarnungen

Überprüfung der App im nativen AOT-Bereitstellungsmodell

Es ist wichtig, eine App gründlich zu testen, wenn Sie zu einem nativen AOT-Bereitstellungsmodell wechseln. Testen Sie die bereitgestellte AOT-App und vergewissern Sie sich, dass die Funktionalität der nicht getrimmten und Just-in-Time-kompilierten App unverändert ist.

Überprüfen und korrigieren Sie beim Erstellen der App alle AOT-Warnungen. Eine App, die AOT-Warnungen während der Veröffentlichung ausgibt, funktioniert möglicherweise nicht ordnungsgemäß. Wenn zum Zeitpunkt der Veröffentlichung keine AOT-Warnungen ausgegeben werden, können Sie erwarten, dass die veröffentlichte AOT-App genauso funktioniert wie die ungetrimmte und JIT-kompilierte App.

Veröffentlichen einer nativen AOT-App (PublishAot)

Aktivieren Sie native AOT für Ihre Anwendung mithilfe der PublishAot MSBuild-Eigenschaft. Das folgende Beispiel zeigt, wie Native AOT in einer Projektdatei aktiviert wird:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

Die PublishAot Eigenschaft ermöglicht die native AOT-Kompilierung während des Veröffentlichungsprozesses und ermöglicht während der Erstellung und Bearbeitung dynamische Codeverwendungsanalyse. Ein Projekt, das die Native-AOT-Veröffentlichung verwendet, implementiert die JIT-Kompilierung bei der lokalen Ausführung.

Eine AOT-App weist die folgenden Unterschiede zu einer JIT-kompilierten App auf:

• Nicht mit nativer AOT-Kompilierung kompatible Features sind deaktiviert und lösen zur Laufzeit Ausnahmen aus.
• Ein Quellanalysetool ist aktiviert, um Code hervorzuheben, der nicht mit nativer AOT-Kompilierung kompatibel ist. Zum Zeitpunkt der Veröffentlichung wird die gesamte App, einschließlich NuGet-Paketen, erneut auf Kompatibilität analysiert.

Die systemeigene AOT-Analyse umfasst den gesamten Anwendungscode und die Bibliotheken, von der die App abhängig ist. Überprüfen Sie Warnungen der nativen AOT-Kompilierung und führen Sie Korrekturschritte durch. Es ist ratsam, Apps häufig zu veröffentlichen, um Probleme frühzeitig im Entwicklungslebenszyklus zu erkennen.

In .NET 8 und höher unterstützen die folgenden ASP.NET Core App-Typen native AOT:

• Minimale APIs – Weitere Informationen finden Sie weiter unten in diesem Artikel unter Überprüfen der Web-API-Vorlage (Native AOT ).
• gRPC - Weitere Informationen finden Sie unter gRPC und Native AOT.
• Worker-Dienste – Weitere Informationen finden Sie unter Background-Aufgaben mit gehosteten Diensten in ASP.NET Core > Native AOT.

Überprüfen der Web-API-Vorlage (Native AOT)

Die ASP.NET Core Web-API (Native AOT) Vorlage (Kurzname webapiaot) erstellt ein Projekt mit aktiviertem AOT. Die Vorlage unterscheidet sich von einer Standardmäßigen Web-API-Projektvorlage auf folgende Weise:

• Verwendet nur minimale APIs, da MVC noch nicht mit Native AOT kompatibel ist.
• Verwendet die CreateSlimBuilder() API, um sicherzustellen, dass nur die wesentlichen Features standardmäßig aktiviert sind, wodurch die bereitgestellte Größe der App minimiert wird.
• Ist so konfiguriert, dass nur HTTP überwacht wird. HTTPS-Datenverkehr wird häufig von einem Ingress-Service in Cloud-nativen Bereitstellungen behandelt.
• Enthält kein Startprofil für die Ausführung unter IIS oder IIS Express.
• Erstellt eine HTTP-Datei , die mit Beispiel-HTTP-Anforderungen konfiguriert ist, die an die Endpunkte der App gesendet werden können.
• Enthält eine Beispiel-Todo-API anstelle des Beispiels für die Wettervorhersage.
• Fügt die PublishAot Eigenschaft der Projektdatei hinzu, wie weiter oben beschrieben.
• Aktiviert die JSON-Serialisierer-Quellgeneratoren. Der Quellgenerator wird verwendet, um Serialisierungscode zur Buildzeit zu generieren. Dies ist für native AOT-Kompilierung erforderlich.

Codeupdates für die JSON-Serialisierung (Program.cs)

Der Code in der Program.cs-Datei wird geändert, um Unterstützung für die JSON-Serialisierungsquellgenerierung bereitzustellen.

Der folgende Codeausschnitt zeigt die Änderungen am Code:

using MyFirstAotWebApi;
+using System.Text.Json.Serialization;

-var builder = WebApplication.CreateBuilder();
+var builder = WebApplication.CreateSlimBuilder(args);

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

var app = builder.Build();

var sampleTodos = TodoGenerator.GenerateTodos().ToArray();

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();

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

Wenn Sie den Code nicht ändern, verwendet System.Text.Json Reflection zum Serialisieren und Deserialisieren von JSON. Reflexion wird in Native AOT nicht unterstützt.

Weitere Informationen finden Sie unter:

• Kombinieren Sie Quellgeneratoren
• TypeInfoResolverChain

Codeänderungen für das Startprofil (launchSettings.json)

Die Web-API-Vorlage (Native AOT) erstellt eine launchSettings.json Datei. Im Gegensatz zu einer Standardstartdatei enthält die generierte Datei nicht den iisSettings Abschnitt oder das IIS Express Profil.

Der folgende Codeausschnitt zeigt die ausgeschlossenen Abschnitte (rot farbig):

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
-  "iisSettings": {
-     "windowsAuthentication": false,
-     "anonymousAuthentication": true,
-     "iisExpress": {
-       "applicationUrl": "http://localhost:11152",
-       "sslPort": 0
-     }
-   },
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "todos",
      "applicationUrl": "http://localhost:5102",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      },
-     "IIS Express": {
-       "commandName": "IISExpress",
-       "launchBrowser": true,
-       "launchUrl": "todos",
-      "environmentVariables": {
-       "ASPNETCORE_ENVIRONMENT": "Development"
-      }
-    }
  }
}

CreateSlimBuilder() für minimale App-Standardwerte aufgerufen

Die Web-API-Vorlage (Native AOT) verwendet die CreateSlimBuilder() Methode anstelle der CreateBuilder() Methode.

using System.Text.Json.Serialization;
using MyFirstAotWebApi;

var builder = WebApplication.CreateSlimBuilder(args);
builder.Logging.AddConsole();

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

var app = builder.Build();

var sampleTodos = TodoGenerator.GenerateTodos().ToArray();

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();

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

Die CreateSlimBuilder-Methode initialisiert WebApplicationBuilder mit den ASP.NET Core-Mindestfunktionen, die zum Ausführen einer App erforderlich sind.

Wie weiter oben beschrieben, enthält die CreateSlimBuilder Methode keine Unterstützung für HTTPS oder HTTP/3. Für Apps, die hinter einem TLS-Beendigungsproxy ausgeführt werden, sind diese Protokolle in der Regel nicht erforderlich. Beispiele finden Sie unter TLS-Abschluss und End-to-End-TSL mit Application Gateway. Sie können HTTPS aktivieren, indem Sie die Methode builder.WebHost.UseKestrelHttpsConfiguration aufrufen, oder HTTP/3 aktivieren, indem Sie builder.WebHost.UseQuic aufrufen.

Vergleichen von CreateSlimBuilder() und CreateBuilder()

Die CreateSlimBuilder Methode bietet Zugriff auf einen Teil der Anwendungsfeatures, die mit der CreateBuilder Methode verfügbar sind. Wie bereits beschrieben, ruft die Web-API (Native AOT) Vorlage CreateSlimBuilder auf, um WebApplicationBuilder zu initialisieren, sodass der Generator die mindesten ASP.NET Core Features verwendet, die zum Ausführen der App erforderlich sind.

Beide Methoden bieten die erforderlichen Features für eine effiziente Entwicklungserfahrung:

• Konfiguration für die appsettings.json und appsettings.{ EnvironmentName}.json Dateien
• Konfiguration geheimer Benutzerschlüssel
• Konsolenprotokollierung
• Protokollierungskonfiguration

Die Einbeziehung von minimalen Features besitzt Vorteile für das Kürzen sowie für AOT. Weitere Informationen finden Sie unter Kürzen eigenständiger Bereitstellungen und ausführbarer Dateien.

Wenn Sie lieber einen Generator verwenden möchten, der alle Features weglässt, lesen Sie die WebApplication.CreateEmptyBuilder-Methode.

Nicht verfügbare Features in CreateSlimBuilder

Die CreateSlimBuilder-Methode bietet nicht die folgenden Funktionen, die in CreateBuilder verfügbar sind:

• Hostingstartassemblys
• UseStartup-Methode
• Protokollierungsanbieter:
  • Windows EventLog
  • Debuggen
  • EventSource
• Webhosting-Funktionen
  • UseStaticWebAssets-Methode
  • IIS-Integration
• Kestrel Konfiguration:
  • HTTPS-Endpunkte
  • QUIC (HTTP/3)
• Regex- und Alphaeinschränkungen im Routing (GitHub /dotnet/aspnetcore/issues #46142)

Ausführlichere Informationen finden Sie unter "Vergleich von WebApplication.CreateBuilder" mit "CreateSlimBuilder"

Verwenden von Quellgeneratoren und Vermeiden von Spiegelungen

Während des Veröffentlichungsprozesses für Native AOT wird nicht verwendeter Code entfernt. Daher kann eine App zur Laufzeit keine ungebundene Spiegelung verwenden. Sie können Quellgeneratoren verwenden, die Code erzeugen, der die Notwendigkeit der Reflexion vermeidet. In einigen Fällen können Quellgeneratoren Ausgabecode erzeugen, der für AOT optimiert wird, auch wenn kein Generator erforderlich ist.

• Um den generierten Quellcode anzuzeigen, fügen Sie die EmitCompilerGeneratedFiles-Eigenschaft der Anwendungsprojektdatei (CSPROJ) hinzu:

  <Project Sdk="Microsoft.NET.Sdk.Web">
  
     <PropertyGroup>
       <!-- Other properties omitted for brevity -->
       <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
     </PropertyGroup>
  
  </Project>
  

• Führen Sie den dotnet build Befehl aus, um den generierten Code anzuzeigen. Der Befehl kompiliert die Quelldateien und generiert die Zwischendateien, die zum Ausführen der App in einer Entwicklungsumgebung erforderlich sind. Die Ausgabe enthält ein verzeichnis obj/Debug/<.NET version>/generated/, das alle generierten Dateien für das Projekt enthält.

• Führen Sie den dotnet publish Befehl aus, um die App für die Bereitstellung vorzubereiten. Der Befehl kompiliert die Quelldateien und generiert alle Zum Bereitstellen der App erforderlichen Dateien. Sie übergibt die generierten Assemblys an einen nativen IL-Compiler, der die systemeigene ausführbare Datei erzeugt. Die native ausführbare Datei enthält den nativen Computercode.

Bibliotheken mit nativem AOT verwenden

Viele beliebte Bibliotheken, die in ASP.NET Core Projekten verwendet werden, weisen derzeit einige Kompatibilitätsprobleme auf, wenn sie in Projekte integriert werden, die auf native AOT abzielen, z. B.:

• Verwenden von Spiegelung zum Untersuchen und Ermitteln von Typen
• Bedingtes Laden von Bibliotheken zur Laufzeit
• Generieren von Code im Handumdrehen zur Implementierung von Funktionalität

Bibliotheken, die diese dynamischen Features verwenden, erfordern Updates für die Arbeit mit nativem AOT. Es stehen verschiedene Tools zum Anwenden der erforderlichen Updates zur Verfügung, z. B. Roslyn-Quellgeneratoren.

Bibliotheksautoren, die hoffen, native AOT zu unterstützen, werden ermutigt, die folgenden Artikel zu lesen:

• Native AOT-Bereitstellung
• Vorbereiten von .NET-Bibliotheken für das Trimmen

Arbeiten mit minimalen APIs und JSON-Nutzlasten

Das minimal API-Framework ist für das Empfangen und Zurückgeben von JSON-Daten mithilfe der System.Text.Json optimiert.

• Der Namespace erzwingt Kompatibilitätsanforderungen für JSON und native AOT.
• Es erfordert die Verwendung des System.Text.Json-Quellgenerators.

Alle Typen, die als Teil des HTTP-Nachrichtentexts übertragen oder von Delegierten in Minimal-API-Apps zurückgegeben werden, müssen in einer JsonSerializerContext Instanz konfiguriert werden. Die Instanz muss bei ASP.NET Core Dependency Injection registriert werden.

using System.Text.Json.Serialization;
using MyFirstAotWebApi;

var builder = WebApplication.CreateSlimBuilder(args);
builder.Logging.AddConsole();

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

var app = builder.Build();

var sampleTodos = TodoGenerator.GenerateTodos().ToArray();

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();

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

• Der JSON-Serialisierungskontext ist im DI-Container registriert. Weitere Informationen finden Sie unter Kombinieren von Quellgeneratoren und dem TypeInfoResolverChain.

• Der benutzerdefinierte JsonSerializerContext wird mit dem JsonSerializable-Attribut annotiert, wodurch für den ToDo-Typ generierter JSON-Serialisierungscode ermöglicht wird.

Ein Parameter für den Delegaten, der nicht an den Textkörper gebunden ist, muss nicht serialisierbar sein. Ein Abfragezeichenfolgenparameter kann z. B. ein erweiterter Objekttyp sein, der IParsable<T> implementiert.

public class Todo
{
    public int Id { get; set; }
    public string? Title { get; set; }
    public DateOnly? DueBy { get; set; }
    public bool IsComplete { get; set; }
}

static class TodoGenerator
{
    private static readonly (string[] Prefixes, string[] Suffixes)[] _parts = new[]
        {
            (new[] { "Walk the", "Feed the" }, new[] { "dog", "cat", "goat" }),
            (new[] { "Do the", "Put away the" }, new[] { "groceries", "dishes", "laundry" }),
            (new[] { "Clean the" }, new[] { "bathroom", "pool", "blinds", "car" })
        };
    // Remaining code omitted for brevity.

Überprüfen bekannter Probleme

Informationen zum Melden oder Überprüfen von Problemen mit der nativen AOT-Unterstützung in ASP.NET Core finden Sie unter GitHub /dotnet/core/issues #8288).

Verwandte Inhalte

• Publishen Sie eine ASP.NET Core App mit nativem AOT
• Native AOT-Bereitstellung
• Optimieren von AOT-Bereitstellungen