Support ASP.NET Core pour le Native AOT

La publication et le déploiement d’applications natives à l’avance (AOT) dans ASP.NET Core offrent plusieurs avantages :

• Encombrement réduit du disque. Lorsque vous publiez une application à l’aide d’AOT natif, le processus produit un seul fichier exécutable. L’exécutable contient uniquement le code des dépendances externes requises pour prendre en charge l’application. La taille exécutable réduite peut entraîner :

  • Des images de conteneur plus petites, par exemple dans les scénarios de déploiement conteneurisé.
  • Un temps de déploiement réduit à partir d’images plus petites.

• Durée de démarrage réduite. Les applications AOT natives peuvent nécessiter moins de temps de démarrage, ce qui permet :

  • Une application pour traiter les demandes plus rapidement.
  • Déploiement amélioré, où les orchestrateurs de conteneurs gèrent la transition d’une version d’application à une autre.

• Réduction de la demande de mémoire. Les applications AOT natives peuvent nécessiter moins de mémoire, en fonction du travail effectué par l’application. Une consommation réduite de mémoire peut entraîner une plus grande densité de déploiement et une meilleure scalabilité.

Le graphique suivant montre les résultats d’un test d’évaluation sur les différentes applications de modèle. Le benchmark compare les performances d’une application publiée par AOT (barre orange), d’une application runtime réduite (barre verte) et d’une application runtime nontrimmée (barre jaune). Le test a révélé que l’application AOT native illustre une taille d’application inférieure, l’utilisation de la mémoire et le temps de démarrage.

Cet article décrit la prise en charge des applications AOT natives dans ASP.NET Core, notamment une vue d’ensemble de la publication et du déploiement.

Pour les recommandations Native AOT d’ASP.NET Core Blazor WebAssembly Blazor WebAssembly, qui complètent ou remplacent celles de cet article, consultez Outils de génération ASP.NET Core Blazor WebAssemblyBlazor WebAssembly et compilation anticipée (AOT).

Revoir la compatibilité de l'ASP.NET Core et du Native AOT

Toutes les fonctionnalités d’ASP.NET Core ne sont pas actuellement compatibles avec l’AOA natif.

Le tableau suivant récapitule la compatibilité des fonctionnalités ASP.NET Core avec l’AOA natif :

Pour plus d’informations sur les limitations, consultez :

• Limitations du déploiement AOT natif
• Avertissements AOT
• Incompatibilités connues du découpage
• Corriger les avertissements de découpage

Vérifier l’application sur le modèle de déploiement AOT natif

Il est important de tester une application minutieusement lorsque vous passez à un modèle de déploiement AOT natif. Testez l’application AOT déployée et assurez-vous que la fonctionnalité reste inchangée par rapport à l’application non allégée et compilée juste-à-temps (JIT).

Lorsque vous générez l’application, passez en revue et corrigez les avertissements AOT. Une application qui émet des avertissements AOT pendant la publication peut ne pas fonctionner correctement. Si aucun avertissement AOT n’est émis au moment de la publication, vous pouvez vous attendre à ce que l’application AOT publiée fonctionne de la même façon que l’application compilée par JIT et nontriée.

Publier une application AOT native (PublishAot)

Activez l’AOT natif pour votre application à l’aide de la PublishAot propriété MSBuild. L’exemple suivant montre comment activer l’AOA natif dans un fichier projet :

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

La PublishAot propriété active la compilation AOT native pendant le processus de publication et active l’analyse dynamique de l’utilisation du code lors de la génération et de la modification. Un projet qui utilise la publication AOT native implémente la compilation JIT lorsqu’il s’exécute localement.

Une application AOT présente les différences suivantes par rapport à une application compilée juste-à-temps (JIT) :

• Certaines fonctionnalités non compatibles avec l’AOA natif sont désactivées et lèvent des exceptions au moment de l’exécution.
• Un analyseur de source est activé pour mettre en surbrillance le code qui n’est pas compatible avec Native AOT. Au moment de la publication, la compatibilité de l’application entière, y compris les packages NuGet, est à nouveau analysée.

L’analyse AOT native inclut tout le code de l’application et les bibliothèques dont dépend l’application. Passez en revue les avertissements liés à la compilation anticipée native (AOT) et prenez des mesures correctives appropriées. Il est judicieux de publier fréquemment les applications pour détecter les problèmes au début du cycle de vie du développement.

Dans .NET 8 et versions ultérieures, les types d’applications ASP.NET Core suivants prennent en charge L’AOT natif :

• API minimales : pour plus d’informations, consultez le modèle API web (AOT natif) plus loin dans cet article.
• gRPC - Pour plus d’informations, consultez gRPC et AOT natif.
• Services de travail - Pour plus d’informations, consultez Tâches en arrière-plan avec des services hébergés dans ASP.NET Core > Native AOT.

Passez en revue le modèle d’API web (AOT natif)

Le modèle ASP.NET Core Web API (AOT natif) (short name webapiaot) crée un projet avec AOT activé. Le modèle diffère d’un modèle de projet d’API web standard de la manière suivante :

• Utilise uniquement les API minimales, car MVC n’est pas encore compatible avec L’AOT natif.
• Utilise l’API CreateSlimBuilder() pour garantir que seules les fonctionnalités essentielles sont activées par défaut, ce qui réduit la taille déployée de l’application.
• Est configuré pour écouter uniquement sur HTTP. Le trafic HTTPS est généralement géré par un service d’entrée dans les déploiements natifs cloud.
• N’inclut pas de profil de lancement pour l’exécution sous IIS ou IIS Express.
• Crée un fichier .http configuré avec des exemples de requêtes HTTP qui peuvent être envoyées aux points de terminaison de l’application.
• Inclut un exemple d’API Todo au lieu de l’exemple de prévision météorologique.
• Ajoute la PublishAot propriété au fichier projet, comme décrit précédemment.
• Active les générateurs de source du sérialiseur JSON. Le générateur de code source est utilisé pour générer du code de sérialisation lors de la phase de construction, ce qui est requis pour la compilation AOT native.

Mises à jour du code pour la sérialisation JSON (Program.cs)

Le code du fichier Program.cs est modifié pour prendre en charge la génération de source de sérialisation JSON.

L’extrait de code suivant montre les modifications apportées au 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
+{
+
+}

Si vous ne modifiez pas le code, System.Text.Json utilise la réflexion pour sérialiser et désérialiser JSON. La réflexion n’est pas prise en charge dans l’AOT natif.

Pour en savoir plus, consultez :

• Combiner des générateurs de sources
• TypeInfoResolverChain

Modifications du code pour le profil de lancement (launchSettings.json)

Le modèle API web (AOT natif) crée un fichier launchSettings.json . Contrairement à un fichier de lancement standard, le fichier généré n’inclut pas la iisSettings section ou le IIS Express profil.

L’extrait de code suivant montre les sections exclues (rouge coloré) :

{
  "$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() appelé pour les paramètres par défaut de l'application minimale

Le modèle API Web (AOT natif) utilise la CreateSlimBuilder() méthode au lieu de la CreateBuilder() méthode.

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
{
}

La méthode CreateSlimBuilder initialise le WebApplicationBuilder avec les fonctionnalités ASP.NET Core minimales nécessaires à l’exécution d’une application.

Comme décrit précédemment, la CreateSlimBuilder méthode n’inclut pas la prise en charge du protocole HTTPS ou HTTP/3. Ces protocoles ne sont généralement pas requis pour les applications qui s’exécutent derrière un proxy de terminaison TLS. Par exemple, consultez Terminaison TLS et TLS de bout en bout avec Application Gateway. Vous pouvez activer HTTPS en appelant la méthode builder.WebHost.UseKestrelHttpsConfiguration ou activer HTTP/3 en appelant builder.WebHost.UseQuic.

Comparer CreateSlimBuilder() et CreateBuilder()

La CreateSlimBuilder méthode permet d’accéder à une partie des fonctionnalités de l’application disponibles avec la CreateBuilder méthode. Comme décrit précédemment, le modèle Web (Native AOT) appelle CreateSlimBuilder pour initialiser WebApplicationBuilder, de sorte que le générateur utilise les fonctionnalités minimales ASP.NET Core nécessaires pour exécuter l’application.

Les deux méthodes fournissent les fonctionnalités nécessaires pour une expérience de développement efficace :

• Configuration pour les fichiers appsettings.json et appsettings.{EnvironmentName}.json
• Configuration des secrets utilisateur
• Écriture dans le journal de la console
• Configuration de la journalisation

L’inclusion de fonctionnalités minimales présente des avantages pour le découpage ainsi que pour l’AOT. Pour plus d’informations, consultez Découper les déploiements autonomes et les exécutables.

Si vous préférez utiliser un générateur qui omet toutes les fonctionnalités, consultez la méthode WebApplication.CreateEmptyBuilder .

Fonctionnalités indisponibles dans CreateSlimBuilder

La CreateSlimBuilder méthode ne fournit pas les fonctionnalités suivantes, qui sont disponibles dans CreateBuilder:

• Accueil des assemblées de démarrage
• UseStartup , méthode
• Fournisseurs d'enregistrement :
  • Windows EventLog
  • Déboguer
  • EventSource
• Fonctionnalités d’hébergement web :
  • UseStaticWebAssets , méthode
  • Intégration d’IIS
• Kestrel d'origine :
  • Points de terminaison HTTPS
  • QUIC (HTTP/3)
• Regex et contraintes alpha utilisées dans le routage (GitHub /dotnet/aspnetcore/issues #46142)

Pour plus d’informations, consultez Comparaison de WebApplication.CreateBuilder à CreateSlimBuilder

Utiliser des générateurs de code source et éviter la réflexion dynamique

Pendant le processus de publication d’AOT natif, tout code inutilisé est supprimé. Par conséquent, une application ne peut pas utiliser la réflexion sans limite au moment de l’exécution. Vous pouvez utiliser des générateurs sources qui produisent du code qui évite le besoin de réflexion. Dans certains cas, le code de sortie des générateurs sources est optimisé pour AOT même lorsqu’un générateur n’est pas nécessaire.

• Pour afficher le code source généré, ajoutez la propriété EmitCompilerGeneratedFiles au fichier de projet d’application (.csproj) :

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

• Pour afficher le code généré, exécutez la dotnet build commande. La commande compile les fichiers sources et génère les fichiers intermédiaires nécessaires pour exécuter l’application dans un environnement de développement. La sortie inclut un répertoire obj/Debug/<.NET>/generated/ qui contient tous les fichiers générés pour le projet.

• Pour préparer l’application pour le déploiement, exécutez la dotnet publish commande. La commande compile les fichiers sources et génère tous les fichiers requis pour déployer l’application. Il transmet les assemblys générés à un compilateur IL natif, qui produit l’exécutable natif. L’exécutable natif contient le code de l’ordinateur natif.

Utiliser des bibliothèques avec AOT natif

De nombreuses bibliothèques populaires utilisées dans ASP.NET Core projets présentent actuellement des problèmes de compatibilité lorsqu'elles sont incorporées dans des projets qui ciblent L'AOT natif, par exemple :

• Utilisation de la réflexion pour inspecter et découvrir des types
• Chargement conditionnel de bibliothèques au moment de l’exécution
• Génération de code à la volée pour implémenter des fonctionnalités

Les bibliothèques qui utilisent ces fonctionnalités dynamiques nécessitent des mises à jour pour fonctionner avec AOT natif. Différents outils sont disponibles pour appliquer les mises à jour nécessaires, telles que les générateurs de sources Roslyn.

Les auteurs de bibliothèque qui espèrent prendre en charge Native AOT sont encouragés à consulter les articles suivants :

• Déploiement de Native AOT
• Préparer des bibliothèques .NET pour le découpage

Utiliser des API minimales et des charges utiles JSON

L’infrastructure d’API minimale est optimisée pour recevoir et retourner des charges utiles JSON à l’aide du System.Text.Json.

• L’espace de noms impose des exigences de compatibilité pour JSON et Native AOT.
• Il nécessite l’utilisation du générateur source System.Text.Json.

Tous les types transmis dans le corps HTTP ou retournés par les délégués de requête dans les applications API minimales doivent être configurés sur une JsonSerializerContext instance. L’instance doit être inscrite avec l'injection de dépendances d'ASP.NET Core.

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
{
}

• Le contexte de sérialiseur JSON est inscrit auprès du conteneur DI. Pour plus d’informations, consultez Combiner des générateurs de sources et le TypeInfoResolverChain.

• Le code personnalisé JsonSerializerContext est annoté avec l’attribut JsonSerializable , qui active le code de sérialiseur JSON généré par la source pour le ToDo type.

Un paramètre sur le délégué qui n’est pas lié au corps n’a pas besoin d’être sérialisable. Par exemple, un paramètre de chaîne de requête peut être un type d’objet enrichi qui implémente IParsable<T>.

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.

Passer en revue les problèmes connus

Pour signaler ou passer en revue les problèmes liés à la prise en charge DOT native dans ASP.NET Core, consultez GitHub /dotnet/core/issues #8288).

Contenu connexe

• Publier une application ASP.NET Core avec native AOT
• Déploiement de Native AOT
• Optimiser les déploiements AOT

.NET 8 introduit la prise en charge pour l’avance de temps (AOT, ahead-of-time) native .NET.

Pourquoi utiliser l’AOA natif avec ASP.NET Core

La publication et le déploiement d’une application AOT natif offrent les avantages suivants :

• Empreinte disque réduite : lors de la publication à l’aide de l’AOA natif, un fichier exécutable unique est produit qui contient uniquement le code des dépendances externes utilisé pour prendre en charge le programme. Une taille d’exécutable réduite peut entraîner :
  • Des images de conteneur plus petites, par exemple dans les scénarios de déploiement conteneurisé.
  • Un temps de déploiement réduit à partir d’images plus petites.
• Temps de démarrage réduit : les applications AOT natives peuvent présenter des temps de démarrage réduits, ce qui signifie
  • L'application est prête à traiter les requêtes plus rapidement.
  • Un déploiement amélioré où les orchestrateurs de conteneurs doivent gérer la transition d’une version de l’application à une autre.
• Demande en mémoire réduite : les applications AOT natives peuvent avoir des demandes en mémoire réduites en fonction du travail effectué par l’application. Une consommation réduite de mémoire peut entraîner une plus grande densité de déploiement et une meilleure scalabilité.

L’application modèle a été exécutée dans notre laboratoire d’évaluation pour comparer les performances d’une application publiée AOT, d’une application runtime découpée et d’une application runtime non découpée. Le graphique suivant montre les résultats de l’évaluation :

Le graphique précédent montre que l’AOA natif présente des valeurs plus faibles de taille d’application, d’utilisation de mémoire et de temps de démarrage.

Compatibilité ASP.NET Core et AOT natif

Toutes les fonctionnalités d’ASP.NET Core ne sont pas actuellement compatibles avec l’AOA natif. Le tableau suivant récapitule la compatibilité des fonctionnalités ASP.NET Core avec l’AOA natif :

Pour plus d’informations sur les limitations, consultez :

• Limitations du déploiement AOT natif
• Présentation des avertissements AOT
• Incompatibilités connues du découpage
• Introduction aux avertissements de découpage
• Problème GitHub dotnet/core #8288

Il est important de tester soigneusement une application lors du passage à un modèle de déploiement d’AOA natif. L’application déployée AOT doit être testée pour vérifier que la fonctionnalité n’a pas changé à partir de l’application compilée juste-à-temps (JIT) et non découpée. Lors de la génération de l’application, passez en revue et corrigez les avertissements AOT. Une application qui génère des avertissements AOT pendant la publication peut ne pas fonctionner correctement. Si aucun avertissement AOT n’est émis au moment de la publication, l’application AOT publiée doit fonctionner de la même façon que l’application non tronquée compilée par JIT.

Publication AOT native

L’AOT native est activée avec la propriété MSBuild PublishAot. L’exemple suivant montre comment activer l’AOA natif dans un fichier projet :

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

Ce paramètre permet la compilation d’AOT natif pendant la publication et active l’analyse dynamique de l’utilisation du code pendant la construction et l'édition. Un projet qui utilise la publication AOT native utilise la compilation JIT lors de l’exécution locale. Une application AOT présente les différences suivantes par rapport à une application compilée juste-à-temps (JIT) :

• Certaines fonctionnalités non compatibles avec l’AOA natif sont désactivées et lèvent des exceptions au moment de l’exécution.
• Un analyseur de source est activé pour mettre en surbrillance le code qui n’est pas compatible avec Native AOT. Au moment de la publication, la compatibilité de l’application entière, y compris les packages NuGet, est à nouveau analysée.

L’analyse d’AOT native inclut tout le code de l’application et les bibliothèques dont dépend l’application. Passez en revue les avertissements d’AOT natif et adoptez des mesures correctives. Il est judicieux de publier fréquemment les applications pour détecter les problèmes au début du cycle de vie du développement.

Dans .NET 8, l’AOA natif est pris en charge par les types d’applications ASP.NET Core suivants :

• API minimales : pour plus d’informations, consultez la section de modèle API web (AOT native) plus loin dans cet article.
• gRPC : pour plus d’informations, consultez gRPC et AOT natif.
• Services Worker : pour plus d’informations, consultez AOT dans les modèles de service Worker.

Modèle d’API web (AOA natif)

Le modèle API web ASP.NET Core (AOA natif) (nom court webapiaot) crée un projet avec l’AOA activé. Le modèle diffère du modèle de projet d’API web de la manière suivante :

• Utilise uniquement les API minimales, car MVC n’est pas encore compatible avec L’AOT natif.
• Utilise l’API CreateSlimBuilder() pour garantir que seules les fonctionnalités essentielles sont activées par défaut, ce qui réduit la taille déployée de l’application.
• Est configuré pour écouter uniquement sur HTTP, car le trafic HTTPS est généralement géré par un service d’entrée dans les déploiements natifs cloud.
• N’inclut pas de profil de lancement pour l’exécution sous IIS ou IIS Express.
• Crée un fichier .http configuré avec des exemples de requêtes HTTP qui peuvent être envoyées aux points de terminaison de l’application.
• Inclut un exemple d’API Todo au lieu de l’exemple de prévision météorologique.
• Ajoute PublishAot au fichier projet, comme indiqué précédemment dans cet article.
• Active les générateurs de source du sérialiseur JSON. Le générateur de code source est utilisé pour générer du code de sérialisation au moment de la compilation, nécessaire pour la compilation Native AOT.

Modifications pour prendre en charge la génération de code source

L’exemple suivant montre le code ajouté au fichier Program.cs pour prendre en charge la génération de source de sérialisation JSON :

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
+{
+
+}

Sans ce code ajouté, System.Text.Json utilise la réflexion pour sérialiser et désérialiser JSON. La réflexion n’est pas prise en charge dans Native AOT.

Pour en savoir plus, consultez :

• Combiner des générateurs de sources
• TypeInfoResolverChain

Modifications apportées à launchSettings.json

Le fichier launchSettings.json créé par le modèle API web (AOA natif) ne contient pas la section iisSettings et le profil IIS Express :

{
  "$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"
-      }
-    }
  }
}

Méthode CreateSlimBuilder

Le modèle utilise la méthode CreateSlimBuilder() au lieu de la méthode CreateBuilder().

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
{
}

La méthode CreateSlimBuilder initialise le WebApplicationBuilder avec les fonctionnalités ASP.NET Core minimales nécessaires à l’exécution d’une application.

Comme indiqué précédemment, la méthode CreateSlimBuilder n’inclut pas la prise en charge du protocole HTTPS ou HTTP/3. Ces protocoles ne sont généralement pas requis pour les applications qui s’exécutent derrière un proxy de terminaison TLS. Par exemple, consultez Terminaison TLS et TLS de bout en bout avec Application Gateway. HTTPS peut être activé en appelant générateur. WebHost.UseKestrelHttpsConfiguration HTTP/3 peut être activé en appelant générateur. WebHost.UseQuic.

Comparaison de CreateSlimBuilder et de CreateBuilder

La méthode CreateSlimBuilder ne prend pas en charge les fonctionnalités suivantes prises en charge par la méthode CreateBuilder :

• Accueil des assemblées de démarrage
• UseStartup
• Les fournisseurs de journalisation suivants :
  • Windows EventLog
  • Déboguer
  • Source de l'événement
• Fonctionnalités d’hébergement web :
  • UseStaticWebAssets
  • Intégration IIS
• Configuration Kestrel
  • Points de terminaison HTTPS dans Kestrel
  • Quic (HTTP/3)
• Contraintes regex et alpha utilisées dans le routage

La méthode CreateSlimBuilder comprend les fonctionnalités suivantes nécessaires à une expérience de développement efficace :

• Configuration du fichier JSON pour appsettings.json et appsettings.{EnvironmentName}.json.
• Configuration des secrets utilisateur.
• Journalisation de la console.
• Configuration de la journalisation.

Pour un générateur qui omet les fonctionnalités précédentes, consultez la méthode CreateEmptyBuilder.

L’inclusion de fonctionnalités minimales présente des avantages pour le découpage ainsi que pour l’AOT. Pour plus d’informations, consultez Découper les déploiements autonomes et les exécutables.

Pour plus d’informations, consultez Comparaison de WebApplication.CreateBuilder à CreateSlimBuilder

Générateurs de source

Étant donné que le code inutilisé est supprimé lors de la publication pour l'AOT natif, l’application ne peut pas utiliser la réflexion illimitée à l'exécution. Les générateurs de sources sont utilisés pour produire du code afin d’éviter la réflexion. Dans certains cas, les générateurs de sources produisent du code optimisé pour l’AOT, même lorsqu’un générateur n’est pas requis.

Pour afficher le code source généré, ajoutez la propriété EmitCompilerGeneratedFiles au fichier .csproj d’une application, comme illustré dans l’exemple suivant :

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

  <PropertyGroup>
    <!-- Other properties omitted for brevity -->
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  </PropertyGroup>

</Project>

Exécutez la commande dotnet build pour afficher le code généré. La sortie inclut un répertoire obj/Debug/net8.0/generated/ qui contient tous les fichiers générés pour le projet.

La commande dotnet publish compile également les fichiers sources et génère des fichiers compilés. En outre, dotnet publish transmet les assemblys générés à un compilateur IL natif. Le compilateur IL produit l’exécutable natif. L’exécutable natif contient le code de l’ordinateur natif.

Utiliser des bibliothèques avec AOT natif

De nombreuses bibliothèques populaires utilisées dans ASP.NET Core projets présentent actuellement des problèmes de compatibilité lorsqu'elles sont incorporées dans des projets qui ciblent L'AOT natif, par exemple :

• Utilisation de la réflexion pour inspecter et découvrir des types
• Chargement conditionnel de bibliothèques au moment de l’exécution
• Génération de code à la volée pour implémenter des fonctionnalités

Les bibliothèques qui utilisent ces fonctionnalités dynamiques nécessitent des mises à jour pour fonctionner avec AOT natif. Différents outils sont disponibles pour appliquer les mises à jour nécessaires, telles que les générateurs de sources Roslyn.

Les auteurs de bibliothèque qui espèrent prendre en charge Native AOT sont encouragés à consulter les articles suivants :

• Déploiement de Native AOT
• Préparer des bibliothèques .NET pour le découpage

API minimales et charges utiles JSON

L’infrastructure d’API minimales est optimisée pour recevoir et retourner des charges utiles JSON à l’aide de System.Text.Json. System.Text.Json :

• Impose des exigences de compatibilité pour JSON et l’AOT natif.
• Nécessite l’utilisation du générateur source System.Text.Json.

Tous les types transmis dans le corps HTTP ou retournés par les délégués de requête dans les applications API minimales doivent être configurés sur un JsonSerializerContext inscrit via l’injection de dépendances d’ASP.NET Core :

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
{
}

Dans le code mis en évidence préexistant :

• Le contexte de sérialiseur JSON est inscrit auprès du conteneur DI. Pour plus d’informations, consultez :
  • Combiner des générateurs de sources
  • TypeInfoResolverChain
• Le JsonSerializerContext personnalisé est annoté avec l’attribut [JsonSerializable] pour activer le code de sérialiseur JSON généré par la source pour le type ToDo.

Paramètre sur le délégué qui n’est pas lié au corps et n’a pas besoin d’être sérialisable. Par exemple, un paramètre de chaîne de requête qui est un type d’objet enrichi et implémente IParsable<T>.

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.

Problèmes connus

Consultez ce ticket GitHub pour signaler ou examiner les problèmes liés à la prise en charge de l’AOT natif dans ASP.NET Core.

Voir aussi

• Tutoriel : publier une application ASP.NET Core à l'aide de l’AOA natif
• Déploiement de Native AOT
• Optimiser les déploiements AOT
• Générateur de source de liaison de configuration
• Utilisation du générateur de sources du classeur de configuration
• Modèle de compilation AOT de l'API Minimal
• Comparaison de WebApplication.CreateBuilder à CreateSlimBuilder
• Exploration du nouveau générateur de source d’API minimale
• Remplacement des appels de méthode par des intercepteurs
• Derrière[LogProperties] et le nouveau générateur de journaux d'activité de télémétrie