Démarrage d’une application dans ASP.NET Core

Le fichier Program

ASP.NET Core applications initialisent et configurent le démarrage dans le fichier de Program l'application (Program.cs).

La première partie du Program fichier se concentre sur la création de l’application. Cette phase utilise WebApplication.CreateBuilder pour initialiser une nouvelle instance de la WebApplicationBuilder classe avec des valeurs par défaut préconfigurées avant le démarrage de l’application. Les modèles de projet ASP.NET Core attribuent au générateur d’applications web une variable nommée builder:

var builder = WebApplication.CreateBuilder(args);

Les propriétés du générateur d’applications web sont les suivantes :

• builder.Configuration est un IConfigurationBuilder et IConfigurationRoot permettant de gérer les sources de configuration et les fournisseurs. Pour plus d’informations, consultez Configuration dans ASP.NET Core.
• builder.Environment est un IWebHostEnvironment élément qui fournit des informations sur l’environnement d’hébergement web de l’application. Pour plus d’informations, consultez ASP.NET environnements d’exécution Core.
• builder.Host est une IHostBuilder option permettant de configurer des propriétés spécifiques à l’hôte. Pour plus d’informations, consultez Hôte générique .NET dans ASP.NET Core.
• builder.Logging est un ILoggingBuilder avec des méthodes d’extension qui ajoutent et gèrent des fournisseurs de journalisation. Pour plus d’informations, consultez Journalisation dans .NET et ASP.NET Core.
• builder.Metrics(.NET 8 ou version ultérieure) permet d’activer les métriques et de diriger leur sortie. Pour plus d’informations, consultez Métriques ASP.NET Core.
• builder.Services est une collection de services d’injection de dépendances (DI) (IServiceCollection) permettant à l’application de composer via l’inversion de contrôle (IoC). Pour plus d’informations, consultez Injection de dépendances dans ASP.NET Core.
• builder.WebHost est une IWebHostBuilder option permettant de configurer des propriétés spécifiques au serveur.

L’application est générée en appelant WebApplicationBuilder.Build, qui retourne le fichier généré WebApplication. Les modèles de projet ASP.NET Core attribuent l’application web générée à une variable nommée app:

var app = builder.Build();

La partie suivante du Program fichier se concentre sur l’établissement du pipeline de gestion des requêtes HTTP en tant que série de composants middleware. Chaque middleware effectue des opérations sur un HttpContext et invoque le middleware suivant dans le pipeline de traitement, ou met fin à la requête. Par convention, les composants middleware sont ajoutés au pipeline en appelant une méthode d’extension qui commence par «Use ». Pour plus d’informations, consultez ASP.NET Core intergiciel.

La méthode Run démarre l’application et bloque le thread appelant jusqu’à ce que l’hôte soit arrêté :

app.Run();

Lorsque Run s’exécute, l’application passe à l’état de processus actif :

1. Les services hébergés démarrent.

   L’hôte effectue une boucle via tous les services hébergés inscrits (IHostedService instances) et appelle leurs StartAsync méthodes. À moins que l’application n’opte pour le démarrage simultané du service hébergé (.NET 8 ou version ultérieure), les services hébergés démarrent de façon séquentielle dans l’ordre de leurs inscriptions de conteneurs d’di. Pour plus d’informations, consultez Tâches en arrière-plan avec des services hébergés dans ASP.NET Core.

2. Le pipeline de middleware est construit.

   Lorsque builder.Build est appelé, les dépendances sont résolues, mais le pipeline de traitement proprement dit n’est pas encore entièrement défini. Lorsque app.Run s’exécute, le framework finalise le pipeline de middleware HTTP. Les méthodes d’intergiciel déclarées et les mappages de points de terminaison sont compilés en une séquence de délégués d’exécution haute performance unique. Pour plus d’informations, consultez ASP.NET Core intergiciel.

3. Le serveur web (Kestrel par défaut) est démarré.

   L’hôte consulte son conteneur d’injection de dépendances, y localise l’implémentation de serveur enregistrée (généralement Kestrel) et lance sa séquence de démarrage. Kestrel puis :

   • Recherche les URL et ports d’hébergement définis à partir de la configuration, des variables d’environnement ou des arguments de ligne de commande.
   • Ouvre et alloue des sockets réseau physiques.
   • Lie les ports et commence à écouter le trafic entrant.

   Pour plus d’informations, consultez .NET Hôte générique dans ASP.NET Core, implémentations de serveur web dans ASP.NET Core et Kestrel serveur web dans ASP.NET Core.

4. Les événements du cycle de vie sont déclenchés au démarrage de l’application.

   Le service IHostApplicationLifetime déclenche son jeton ApplicationStarted, qui appelle les rappels inscrits sur le jeton. Toutes les fonctions de rappel, les scripts d’initialisation de la base de données ou les autres écouteurs d’événements personnalisés configurés pour attendre le déclenchement du jeton sont activés pour lancer le traitement.

5. Le thread d’exécution principal est bloqué pendant l’exécution de l’application.

   Run (app.Run()) attend de façon synchrone jusqu’à l’arrêt.

6. L’application est prête à traiter les demandes.

   À ce stade, l’interpréteur de commandes consigne les diagnostics d’hébergement :

   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: https://localhost:7123
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: http://localhost:5123
   info: Microsoft.Hosting.Lifetime[0]
         Application started. Press Ctrl+C to shut down.
   

L’application reste dans cet état indéfiniment, transmettant le trafic web entrant au pipeline de middleware et renvoyant des réponses.

Lorsque l’arrêt est signalé, par exemple lorsque Ctrl+c est détecté dans l’interpréteur de commandes exécutant l’application ou un outil d’orchestration de conteneur envoie un événement SIGTERM, Run débloque et les actions suivantes se produisent :

1. ApplicationStopping les jetons sont déclenchés, ce qui permet à l’application d’exécuter la logique avant le début du processus d’arrêt.

2. Le Kestrel serveur est arrêté, ce qui désactive les nouvelles connexions. Le serveur attend que les demandes sur les connexions existantes se terminent tant que le délai d’arrêt le permet. Le serveur envoie l’en-tête de fermeture de connexion pour les requêtes supplémentaires sur les connexions existantes.

3. L’hôte arrête les services hébergés enregistrés. Sauf si l’application choisit d’arrêter les services hébergés simultanément (.NET 8 ou version ultérieure), les services hébergés s’arrêtent de façon séquentielle dans l’ordre inverse de leurs inscriptions de conteneurs d’di. Pour plus d’informations, consultez Tâches en arrière-plan avec des services hébergés dans ASP.NET Core.

4. ApplicationStopped les gestionnaires d’événements sont déclenchés, ce qui permet à l’application d’exécuter la logique après l’arrêt de l’application.

5. L’exécution de la console se termine avec un code de sortie de 0.

La classe Startup configure les services et le pipeline de demande de l’application.

La classe Startup

ASP.NET Core applications utilisent une classe de démarrage, nommée Startup par convention. La classe Startup :

• Inclut éventuellement une méthode ConfigureServices pour configurer les services de l’application. Un service est un composant réutilisable qui fournit une fonctionnalité d’application. Les services sont inscrits dans ConfigureServices et consommés dans l’application par injection de dépendance ou ApplicationServices.
• Inclut une méthode Configure pour créer le pipeline de traitement des requêtes de l’application.

ConfigureServices et Configure sont appelés par le runtime ASP.NET Core au lancement de l’application :

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
    }
}

La classe Startup est spécifiée quand l’hôte de l’application est créé. La Startup classe est généralement spécifiée en appelant WebHostBuilderExtensions.UseStartup le générateur d’hôtes :

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

L’hôte fournit des services accessibles au constructeur de classe Startup. L’application ajoute des services supplémentaires à l’aide de ConfigureServices. Les services de l’hôte ainsi que ceux de l’application sont disponibles dans Configure et dans l’ensemble de l’application.

Seuls les types de service suivants peuvent être injectés dans le constructeur Startup lorsque vous utilisez l’hôte générique (IHostBuilder) :

• IWebHostEnvironment
• IHostEnvironment
• IConfiguration

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
        }
        else
        {
        }
    }
}

La plupart des services ne sont pas disponibles tant que la Configure méthode n’est pas appelée.

Plusieurs Startup classes

Quand l’application définit différentes classes Startup pour différents environnements (par exemple, StartupDevelopment), la classe Startup appropriée est sélectionnée au moment de l’exécution. La classe dont le suffixe du nom correspond à l'environnement actuel est prioritaire. Si l’application est exécutée dans l’environnement Development et inclut une classe Startup et une classe StartupDevelopment, la classe StartupDevelopment est utilisée. Pour plus d’informations, consultez Utiliser plusieurs environnements.

Méthode ConfigureServices

La méthode facultative ConfigureServices est :

• Appelée par l’hôte avant la méthode Configure pour configurer les services de l’application
• L’emplacement où les options de configuration sont définies par convention.

L’hôte peut configurer certains services avant l’appel des méthodes Startup. Pour plus d’informations, consultez ASP.NET vue d’ensemble des principes fondamentaux de base.

Pour les fonctionnalités nécessitant une configuration importante, il existe des méthodes d’extension Add{Service} sur IServiceCollection, telles que :

• AddDbContext
• AddDefaultIdentity
• AddEntityFrameworkStores
• AddRazorPages

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {

        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                Configuration.GetConnectionString("DefaultConnection")));
        services.AddDefaultIdentity<IdentityUser>(
            options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<ApplicationDbContext>();

        services.AddRazorPages();
    }
}

L’ajout de services au conteneur de service les rend disponibles dans l’application et dans la méthode Configure. Les services sont résolus via l’injection de dépendances ou à partir de ApplicationServices.

Méthode Configure

La méthode Configure permet de spécifier le mode de réponse de l’application aux requêtes HTTP. Vous configurez le pipeline de requête en ajoutant des composants d’intergiciel (middleware) à une instance de IApplicationBuilder. IApplicationBuilder est disponible pour la méthode Configure, mais elle n’est pas inscrite dans le conteneur de service. L’hébergement crée un IApplicationBuilder et le passe directement à Configure.

Les modèles ASP.NET Core configurent le pipeline pour permettre la prise en charge des éléments suivants :

• Page d’exceptions du développeur
• Gestionnaire d’exceptions
• HSTS (HTTP Strict Transport Security)
• Redirection HTTPS
• Fichiers statiques
• ASP.NET Core MVC et Razor Pages

L’exemple suivant illustre l’intergiciel pour une application Pages standard Razor :

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

L’échantillon précédent concerne les Pages Razor, toutefois, la version MVC est similaire.

Chaque méthode d’extension Use ajoute un ou plusieurs composants de middleware au pipeline de requête. Par exemple, UseStaticFiles configure le middleware pour qu’il traite des fichiers statiques.

Chaque composant de middleware du pipeline des requêtes est chargé d’appeler le composant suivant du pipeline ou de court-circuiter la chaîne, si c’est approprié.

Vous pouvez spécifier des services supplémentaires (comme IWebHostEnvironment, ILoggerFactory et tout service défini dans ConfigureServices) dans la signature de la méthode Configure. Ces services sont injectés s’ils sont disponibles.

Pour plus d’informations sur l’utilisation IApplicationBuilder et l’ordre du traitement des intergiciels, consultez ASP.NET Core middleware.

Configurer des services sans Startup classe

Pour configurer les services et le pipeline de traitement de requête sans utiliser de classe Startup, appelez les méthodes pratiques ConfigureServices et Configure sur le générateur de l’hôte. Les appels multiples à ConfigureServices s’ajoutent les uns aux autres. S’il existe plusieurs appels de méthode Configure, le dernier appel de Configure est utilisé.

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.ConfigureServices(services =>
                {
                    ...
                })
                .Configure(app =>
                {
                    ...
                });
        });
}

L’implémentation du filtre de démarrage est inscrite dans le Program fichier :

builder.Services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

L’implémentation du filtre de démarrage est inscrite dans Startup.ConfigureServices:

services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

La classe Startup (méthodes ConfigureServices et Configure)

Bien que pris en charge dans les applications ASP.NET Core ciblant .NET 6 ou une version ultérieure, l’utilisation d’une classe Startup n’est pas recommandée. Pour plus d’informations, consultez Migrer de ASP.NET Core dans .NET 5 vers .NET 6.

Pour plus d’informations sur l’utilisation des ConfigureServicesConfigure méthodes avec le modèle d’hébergement minimal, consultez les rubriques suivantes :

• Utiliser une Startup classe avec le modèle d’hébergement minimal
• Classe Startup (.NET 5 version de cet article)

Mesurer les performances de démarrage

L’hébergement EventSource ASP.NET Core émet l’événementServerReady, qui représente le point où le serveur est prêt à répondre aux demandes et peut être utilisé pour mesurer le temps de démarrage. Pour plus d’informations, consultez Journalisation dans .NET et ASP.NET Core.