Hôte générique .NET dans ASP.NET Core

Cet article fournit des informations sur l’utilisation de l’hôte générique .NET dans ASP.NET Core.

Les modèles ASP.NET Core créent un WebApplicationBuilder et une WebApplication, qui offrent un moyen simplifié de configurer et d’exécuter des applications web sans classe Startup. Pour plus d’informations sur WebApplicationBuilder et WebApplication, consultez Migrer d’ASP.NET Core 5.0 à 6.0.

Pour plus d’informations sur l’utilisation de l’hôte générique .NET dans les applications console, consultez Hôte générique .NET.

Définition de l’hôte

Un hôte est un objet qui encapsule les ressources de l’application, telles que :

• Injection de dépendances (DI)
• Journalisation
• Configuration
• Implémentations de IHostedService

Lorsqu’un hôte démarre, il appelle IHostedService.StartAsync sur chaque implémentation de IHostedService inscrite dans la collection de services hébergés du conteneur de services. Dans une application web, l’une des implémentations de IHostedService est un service web qui démarre une implémentation de serveur HTTP.

L’inclusion de toutes les ressources interdépendantes de l’application dans un seul objet permet de contrôler le démarrage et l’arrêt approprié de l’application.

Configurer un hôte

L’hôte est généralement configuré, généré et exécuté par du code dans le Program.cs. Le code suivant crée un hôte avec une implémentation IHostedService ajoutée au conteneur de DI :

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

Pour une charge de travail HTTP, appelez ConfigureWebHostDefaults après CreateDefaultBuilder :

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

Paramètres du générateur par défaut

La méthode CreateDefaultBuilder :

• Définit le chemin retourné par GetCurrentDirectory comme racine de contenu.
• Charge la configuration de l’hôte à partir de :
  • Variables d’environnement comportant le préfixe DOTNET_.
  • Arguments de ligne de commande
• Charge la configuration de l’application à partir de :
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Les secrets utilisateur quand l’application s’exécute dans l’environnement Development
  • Variables d'environnement.
  • Arguments de ligne de commande
• Ajoute les fournisseurs de journalisation suivants :
  • Console
  • Déboguer
  • EventSource
  • EventLog (uniquement en cas d’exécution sur Windows)
• Active la validation de l’étendue et la validation de dépendances dans un environnement de développement.

La méthode ConfigureWebHostDefaults :

• Charge la configuration hôte à partir des variables d’environnement comportant le préfixe ASPNETCORE_.
• Définit le serveur Kestrel comme serveur web et le configure en utilisant les fournisseurs de configuration d’hébergement de l’application. Pour connaître les options par défaut du serveur Kestrel, consultez Configurer les options pour le serveur web ASP.NET Core Kestrel.
• Ajoute l’intergiciel (middleware) Filtrage d’hôtes.
• Ajoute l’intergiciel d’en-têtes transférés si ASPNETCORE_FORWARDEDHEADERS_ENABLED est égal à true.
• Permet l’intégration d’IIS. Pour connaître les options IIS par défaut, consultez la Héberger ASP.NET Core sur Windows avec IIS.

Les sections Paramètres pour tous les types d’applications et Paramètres pour les applications web figurant plus loin dans cet article montrent comment remplacer les paramètres du générateur par défaut.

Services fournis par le framework

Les services suivants sont inscrits automatiquement :

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

Pour plus d’informations sur les services fournis par le framework, consultez Injection de dépendances dans ASP.NET Core.

IHostApplicationLifetime

Injectez le service IHostApplicationLifetime (anciennement IApplicationLifetime) dans n’importe quelle classe pour gérer les tâches post-démarrage et d’arrêt approprié. Trois propriétés de l’interface sont des jetons d’annulation utilisés pour inscrire les méthodes du gestionnaire d’événements de démarrage et d’arrêt d’application. L’interface inclut également une méthode StopApplication, qui permet aux applications de demander un arrêt normal.

Lors de l’exécution d’un arrêt correct, l’hôte :

• Déclenche les gestionnaires d’événements ApplicationStopping, ce qui permet à l’application d’exécuter la logique avant le début du processus d’arrêt.
• Arrête le serveur, ce qui désactive les nouvelles connexions. Le serveur attend que les requêtes 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.
• Déclenche les gestionnaires d’événements ApplicationStopped, ce qui permet à l’application d’exécuter la logique après l’arrêt de l’application.

L’exemple suivant est une implémentation de IHostedService qui inscrit les gestionnaires d’événements IHostApplicationLifetime :

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _hostApplicationLifetime.ApplicationStarted.Register(OnStarted);
        _hostApplicationLifetime.ApplicationStopping.Register(OnStopping);
        _hostApplicationLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

L’implémentation de IHostLifetime contrôle quand l’hôte démarre et quand il s’arrête. La dernière implémentation inscrite est utilisée.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime est l’implémentation de IHostLifetime par défaut. ConsoleLifetime :

• écoute Ctrl+C/SIGINT (Windows), ⌘+C (macOS) et appelle StopApplication pour démarrer le processus d’arrêt.
• Déverrouille les extensions telles que RunAsync et WaitForShutdownAsync.

IHostEnvironment

Injectez le service IHostEnvironment dans une classe pour obtenir des informations sur les paramètres suivants :

• ApplicationName
• EnvironmentName
• ContentRootPath

Les applications web implémentent l’interface IWebHostEnvironment, qui hérite de IHostEnvironment et ajoute le WebRootPath.

Configuration de l’hôte

La configuration de l’hôte est utilisée pour les propriétés de l’implémentation de IHostEnvironment.

La configuration de l’hôte est disponible à partir de HostBuilderContext.Configuration dans ConfigureAppConfiguration. Après ConfigureAppConfiguration, HostBuilderContext.Configuration est remplacé par la configuration de l’application.

Pour ajouter la configuration d’hôte, appelez ConfigureHostConfiguration sur IHostBuilder. ConfigureHostConfiguration peut être appelé plusieurs fois avec des résultats additifs. L’hôte utilise l’option qui définit une valeur en dernier sur une clé donnée.

Le fournisseur de variables d’environnement avec le préfixe DOTNET_ et les arguments de ligne de commande sont inclus par CreateDefaultBuilder. Pour les applications web, le fournisseur de variables d’environnement avec le préfixe ASPNETCORE_ est ajouté. Ce préfixe est supprimé à la lecture des variables d’environnement. Par exemple, la valeur de variable d’environnement de ASPNETCORE_ENVIRONMENT devient la valeur de configuration d’hôte de la clé environment.

L’exemple suivant crée la configuration d’hôte :

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(hostConfig =>
    {
        hostConfig.SetBasePath(Directory.GetCurrentDirectory());
        hostConfig.AddJsonFile("hostsettings.json", optional: true);
        hostConfig.AddEnvironmentVariables(prefix: "PREFIX_");
        hostConfig.AddCommandLine(args);
    });

la configuration d’une application ;

La configuration d’application est créée en appelant ConfigureAppConfiguration sur IHostBuilder. ConfigureAppConfiguration peut être appelé plusieurs fois avec des résultats additifs. L’application utilise l’option qui définit une valeur en dernier sur une clé donnée.

La configuration créée par ConfigureAppConfiguration est disponible dans HostBuilderContext.Configuration pour les opérations suivantes et en tant que service à partir de l’injection de dépendances. La configuration d’hôte est également ajoutée à la configuration d’application.

Pour plus d’informations, consultez Configuration dans ASP.NET Core.

Paramètres pour tous les types d’applications

Cette section liste les paramètres d’hôte qui s’appliquent aux charges de travail HTTP et non-HTTP. Par défaut, les variables d’environnement utilisées pour configurer ces paramètres peuvent avoir un préfixe DOTNET_ ou ASPNETCORE_, qui apparaissent dans la liste suivante des paramètres comme espace réservé {PREFIX_}. Pour plus d’informations, consultez la section Paramètres du générateur par défaut et Configuration : Variables d’environnement.

ApplicationName

La propriété IHostEnvironment.ApplicationName est définie à partir de la configuration d’hôte pendant la construction de l’hôte.

Clé : applicationName
Type : string
Par défaut : nom de l’assembly contenant le point d’entrée de l’application.
La variable d’environnement: {PREFIX_}APPLICATIONNAME

Pour définir cette valeur, utilisez la variable d’environnement.

ContentRoot

La propriété IHostEnvironment.ContentRootPath détermine où l’hôte commence la recherche des fichiers de contenu. Si le chemin est introuvable, l’hôte ne peut pas démarrer.

Clé : contentRoot
Type : string
Par défaut : dossier où réside l’assembly de l’application.
La variable d’environnement: {PREFIX_}CONTENTROOT

Pour définir cette valeur, utilisez la variable d’environnement ou appelez UseContentRoot sur IHostBuilder :

Host.CreateDefaultBuilder(args)
    .UseContentRoot("/path/to/content/root")
    // ...

Pour plus d'informations, consultez les pages suivantes :

• Notions de base : Racine du contenu
• WebRoot

EnvironmentName

La valeur de la propriété IHostEnvironment.EnvironmentName peut être n’importe quelle valeur. Les valeurs définies par le framework sont Development, Staging et Production. Les valeurs ne respectent pas la casse.

Clé : environment
Type : string
Par défaut : Production
La variable d’environnement: {PREFIX_}ENVIRONMENT

Pour définir cette valeur, utilisez la variable d’environnement ou appelez UseEnvironment sur IHostBuilder :

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    // ...

ShutdownTimeout

HostOptions.ShutdownTimeout définit le délai d’expiration pour StopAsync. La valeur par défaut est de 30 secondes. Pendant la période du délai d’expiration, l’hôte :

• Déclenche IHostApplicationLifetime.ApplicationStopping.
• Tente d’arrêter les services hébergés, en journalisant les erreurs pour les services qui échouent à s’arrêter.

Si la période du délai d’attente expire avant l’arrêt de tous les services hébergés, les services actifs restants sont arrêtés quand l’application s’arrête. Les services s’arrêtent même s’ils n’ont pas terminé les traitements. Si des services nécessitent plus de temps pour s’arrêter, augmentez le délai d’attente.

Clé : shutdownTimeoutSeconds
Type : int
Valeur par défaut : 30 secondes
La variable d’environnement: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Pour définir cette valeur, utilisez la variable d’environnement ou configurez HostOptions. L’exemple suivant définit un délai d’expiration de 20 secondes :

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(options =>
        {
            options.ShutdownTimeout = TimeSpan.FromSeconds(20);
        });
    });

Désactiver le rechargement de la configuration de l’application lors de la modification

Par défaut, appsettings.json et appsettings.{Environment}.json sont rechargés lorsque le fichier change. Pour désactiver ce comportement de rechargement dans ASP.NET Core 5.0 ou version ultérieure, définissez la clé hostBuilder:reloadConfigOnChange sur false.

Clé : hostBuilder:reloadConfigOnChange
Type : bool (true ou false)
Par défaut : true
Argument de ligne de commande : hostBuilder:reloadConfigOnChange
La variable d’environnement: {PREFIX_}hostBuilder:reloadConfigOnChange

Avertissement

Le séparateur deux-points (:) ne fonctionne pas avec les clés hiérarchiques des variables d’environnement sur toutes les plateformes. Pour en savoir plus, voir Variables d’environnement.

Paramètres pour les applications web

Certains paramètres d’hôte s’appliquent uniquement aux charges de travail HTTP. Par défaut, les variables d’environnement utilisées pour configurer ces paramètres peuvent avoir un préfixe DOTNET_ ou ASPNETCORE_, qui apparaissent dans la liste suivante des paramètres comme espace réservé {PREFIX_}.

Des méthodes d’extension sur IWebHostBuilder sont disponibles pour ces paramètres. Les exemples de code qui montrent comment appeler les méthodes d’extension supposent que webBuilder est une instance de IWebHostBuilder, comme dans l’exemple suivant :

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // ...
    });

CaptureStartupErrors

Avec la valeur false, la survenue d’erreurs au démarrage entraîne la fermeture de l’hôte. Avec la valeur true, l’hôte capture les exceptions levées au démarrage et tente de démarrer le serveur.

Clé : captureStartupErrors
Type : bool (true/1 ou false/0)
Valeur par défaut : false, ou true si l’application s’exécute avec Kestrel derrière IIS.
La variable d’environnement: {PREFIX_}CAPTURESTARTUPERRORS

Pour définir cette valeur, utilisez la configuration ou appelez CaptureStartupErrors :

webBuilder.CaptureStartupErrors(true);

DetailedErrors

En cas d’activation ou quand l’environnement est Development, l’application capture des erreurs détaillées.

Clé : detailedErrors
Type : bool (true/1 ou false/0)
Par défaut : false
La variable d’environnement: {PREFIX_}DETAILEDERRORS

Pour définir cette valeur, utilisez la configuration ou appelez UseSetting :

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

Chaîne délimitée par des points-virgules qui spécifie les assemblys d’hébergement à charger au démarrage. La valeur de configuration par défaut est une chaîne vide, mais les assemblys d’hébergement au démarrage incluent toujours l’assembly de l’application. Quand des assemblys d’hébergement au démarrage sont fournis, ils sont ajoutés à l’assembly de l’application et sont chargés lorsque l’application génère ses services communs au démarrage.

Clé : hostingStartupAssemblies
Type : string
Valeur par défaut : une chaîne vide
La variable d’environnement: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Pour définir cette valeur, utilisez la configuration ou appelez UseSetting :

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

Chaîne délimitée par des points-virgules qui spécifie les assemblys d’hébergement à exclure au démarrage.

Clé : hostingStartupExcludeAssemblies
Type : string
Valeur par défaut : une chaîne vide
La variable d’environnement: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Pour définir cette valeur, utilisez la configuration ou appelez UseSetting :

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

Définissez le port HTTPS à rediriger si vous obtenez une connexion non HTTPS. Utilisé dans l’application de HTTPS. Ce paramètre n’entraîne pas l’écoute du serveur sur le port spécifié. Autrement dit, il est possible de rediriger accidentellement les demandes vers un port inutilisé.

Clé : https_portType : string
Par défaut : Aucune valeur par défaut n’est définie.
La variable d’environnement: {PREFIX_}HTTPS_PORT

Pour définir cette valeur, utilisez la configuration ou appelez UseSetting :

webBuilder.UseSetting("https_port", "8080");

HTTPS_Ports

Ports sur lesquels écouter les connexions HTTPS.

Clé : https_ports
Type : string
Par défaut : Aucune valeur par défaut n’est définie.
La variable d’environnement: {PREFIX_}HTTPS_PORTS

Pour définir cette valeur, utilisez la configuration ou appelez UseSetting :

webBuilder.UseSetting("https_ports", "8080");

PreferHostingUrls

Indique si l’hôte doit écouter les URL configurées avec IWebHostBuilder au lieu d’écouter celles configurées avec l’implémentation IServer.

Clé : preferHostingUrls
Type : bool (true/1 ou false/0)
Par défaut : false
La variable d’environnement: {PREFIX_}PREFERHOSTINGURLS

Pour définir cette valeur, utilisez la variable d’environnement ou appelez PreferHostingUrls :

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Empêche le chargement automatique des assemblys d’hébergement au démarrage, y compris ceux configurés par l’assembly de l’application. Pour plus d’informations, consultez Utiliser des assemblys d’hébergement au démarrage dans ASP.NET Core.

Clé : preventHostingStartup
Type : bool (true/1 ou false/0)
Par défaut : false
La variable d’environnement: {PREFIX_}PREVENTHOSTINGSTARTUP

Pour définir cette valeur, utilisez la variable d’environnement ou appelez UseSetting :

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

Assembly où rechercher la classe Startup.

Clé : startupAssembly
Type : string
Valeur par défaut : l’assembly de l’application
La variable d’environnement: {PREFIX_}STARTUPASSEMBLY

Pour définir cette valeur, utilisez la variable d’environnement ou appelez UseStartup. UseStartup peut prendre un nom d’assembly (string) ou un type (TStartup). Si plusieurs méthodes UseStartup sont appelées, la dernière prévaut.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Lorsque cette option est activée, supprime les messages d’état de démarrage d’hébergement.

Clé : suppressStatusMessages
Type : bool (true/1 ou false/0)
Par défaut : false
La variable d’environnement: {PREFIX_}SUPPRESSSTATUSMESSAGES

Pour définir cette valeur, utilisez la configuration ou appelez UseSetting :

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

URLs

Liste délimitée par des points-virgules d’adresses IP ou d’adresses d’hôte avec les ports et protocoles sur lesquels le serveur doit écouter les requêtes. Par exemple, http://localhost:123 Utilisez « * » pour indiquer que le serveur doit écouter les requêtes sur toutes les adresses IP ou tous les noms d’hôte qui utilisent le port et le protocole spécifiés (par exemple, http://*:5000). Le protocole (http:// ou https://) doit être inclus avec chaque URL. Les formats pris en charge varient selon les serveurs.

Clé : urls
Type : string
Par défaut : http://localhost:5000 et https://localhost:5001
La variable d’environnement: {PREFIX_}URLS

Pour définir cette valeur, utilisez la variable d’environnement ou appelez UseUrls :

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel a sa propre API de configuration de points de terminaison. Pour plus d’informations, consultez Configurer des points de terminaison pour le serveur web ASP.NET Core Kestrel.

WebRoot

La propriété IWebHostEnvironment.WebRootPath détermine le chemin d’accès relatif aux ressources statiques de l’application. Si ce chemin n’existe pas, un fournisseur de fichiers no-op est utilisé.

Clé : webroot
Type : string
Par défaut : la valeur par défaut est wwwroot. Le chemin d’accès à {racine du contenu}/wwwroot doit exister.
La variable d’environnement: {PREFIX_}WEBROOT

Pour définir cette valeur, utilisez la variable d’environnement ou appelez UseWebRoot sur IWebHostBuilder :

webBuilder.UseWebRoot("public");

Pour plus d'informations, consultez les pages suivantes :

• Principes de base : Racine web
• ContentRoot

Gérer la durée de vie de l’hôte

Appelez des méthodes sur l’implémentation de IHost pour démarrer et arrêter l’application. Ces méthodes affectent toutes les implémentations de IHostedService qui sont inscrites dans le conteneur de service.

La différence entre les méthodes Run* et Start* est que les méthodes Run* attendent que l’hôte se termine avant de retourner, tandis que les méthodes Start* retournent immédiatement. Les méthodes Run* sont généralement utilisées dans les applications console, tandis que les méthodes Start* sont généralement utilisées dans les services de longue durée.

Exécuter

Run exécute l’application et bloque le thread appelant jusqu’à l’arrêt de l’hôte.

RunAsync

RunAsync exécute l’application et retourne un Task qui est effectué quand le jeton d’annulation ou l’arrêt est déclenché.

RunConsoleAsync

RunConsoleAsync permet la prise en charge de la console, génère et démarre l’hôte et attend Ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM pour l’arrêter.

Commencement

Start démarre l’hôte en mode synchrone.

StartAsync

StartAsync démarre l’hôte et retourne un Task qui est effectué quand le jeton d’annulation ou l’arrêt est déclenché.

WaitForStartAsync est appelé au début de StartAsync, lequel attend qu’il soit fini avant de continuer. Cette méthode permet de retarder le démarrage jusqu’à ce que celui-ci soit signalé par un événement externe.

StopAsync

StopAsync tente d’arrêter l’hôte dans le délai d’attente fourni.

WaitForShutdown

WaitForShutdown bloque le thread appelant jusqu’à ce qu’un arrêt soit déclenché par IHostLifetime, par exemple par le biais de Ctrl+C/SIGINT (Windows), ⌘+C ou SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync retourne une Task qui est effectuée quand l’arrêt est déclenché par le biais du jeton fourni et appelle StopAsync.

Ressources supplémentaires

• Tâches d’arrière-plan avec des services hébergés dans ASP.NET Core
• Lien GitHub vers la source d’hôte générique

  Remarque

  Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).