Hôte web ASP.NET Core

Les applications ASP.NET Core configurent et lancent un hôte. L’hôte est responsable de la gestion du démarrage et de la durée de vie des applications. Au minimum, l’hôte configure un serveur ainsi qu’un pipeline de traitement des requêtes. L’hôte peut aussi configurer la journalisation, l’injection de dépendances et la configuration.

Cet article traite de l’hôte Web, qui reste disponible uniquement pour la compatibilité descendante. Les modèles ASP.NET Core créent un WebApplicationBuilder et un WebApplication, ce qui est recommandé pour les applications Web. Pour plus d’informations sur WebApplicationBuilder et WebApplication, consultez Migrer de ASP.NET Core en .NET 5 vers .NET 6

Configurer un hôte

Créez un hôte à l’aide d’une instance de IWebHostBuilder. Cette opération est généralement effectuée dans le point d’entrée de l’application, la méthode Main dans Program.cs. Une application type appelle CreateDefaultBuilder pour commencer à configurer un hôte :

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Le code qui appelle CreateDefaultBuilder est dans une méthode nommée CreateWebHostBuilder, qui le sépare du code dans Main qui appelle Run sur l’objet du générateur. Cette séparation est requise si vous utilisez les outils Entity Framework Core. Les outils s’attendent à trouver une méthode CreateWebHostBuilder qu’ils peuvent appeler au moment du design pour configurer l’hôte sans exécuter l’application. Une alternative consiste à implémenter IDesignTimeDbContextFactory. Pour plus d’informations, consultez Création de DbContext au moment du design.

CreateDefaultBuilder effectue les tâches suivantes :

• Configure le serveur Kestrel en tant que serveur Web à l’aide des fournisseurs de configuration d’hébergement de l’application. Pour connaître les options par défaut du serveur Kestrel, consultez Configurer les options du serveur Web ASP.NET Core Kestrel.
• Définit la racine du contenu sur le chemin d’accès renvoyé par Directory.GetCurrentDirectory.
• Charge la configuration de l’hôte à partir de :
  • Variables d’environnement comportant le préfixe ASPNETCORE_ (par exemple, ASPNETCORE_ENVIRONMENT).
  • Arguments de ligne de commande
• Charge la configuration de l’application dans l’ordre suivant à partir de :
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Secrets utilisateur lorsque l’application s’exécute dans l’environnement Development à l’aide de l’assembly d’entrée.
  • Variables d'environnement.
  • Arguments de ligne de commande
• Configure la journalisation des sorties de la console et du débogage. La journalisation inclut les règles de filtrage des journaux spécifiées dans une section de configuration de journalisation d’un fichier appsettings.json ou appsettings.{Environment}.json.
• Lors de l’exécution derrière IIS avec le module ASP.NET Core, CreateDefaultBuilder permet l’intégration IIS, qui configure l’adresse de base et le port de l’application. L’intégration IIS configure également l’application pour la capture des erreurs de démarrage. Pour les options par défaut d’IIS, consultez Héberger ASP.NET Core sur Windows avec IIS.
• Définit ServiceProviderOptions.ValidateScopes sur true si l’environnement de l’application est Développement. Pour plus d’informations, consultez Validation de l’étendue.

La configuration définie par CreateDefaultBuilder peut être remplacée et complétée par ConfigureAppConfiguration, ConfigureLogging et d’autres méthodes et méthodes d’extension de IWebHostBuilder. En voici quelques exemples :

• ConfigureAppConfiguration est utilisé pour spécifier des IConfiguration supplémentaires pour l’application. L’appel ConfigureAppConfiguration suivant ajoute un délégué pour inclure la configuration de l’application dans le fichier appsettings.xml. ConfigureAppConfiguration peut être appelé plusieurs fois. Notez que cette configuration ne s’applique pas à l’hôte (par exemple, les URL de serveur ou l’environnement). Voir la section Valeurs de configuration de l’hôte.

  WebHost.CreateDefaultBuilder(args)
      .ConfigureAppConfiguration((hostingContext, config) =>
      {
          config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
      })
      ...
  

• L’appel ConfigureLogging suivant ajoute un délégué pour configurer le niveau de journalisation minimum (SetMinimumLevel) sur LogLevel.Warning. Ce paramètre remplace les paramètres dans appsettings.Development.json (LogLevel.Debug) et appsettings.Production.json (LogLevel.Error) configurés par CreateDefaultBuilder. ConfigureLogging peut être appelé plusieurs fois.

  WebHost.CreateDefaultBuilder(args)
      .ConfigureLogging(logging => 
      {
          logging.SetMinimumLevel(LogLevel.Warning);
      })
      ...
  

• L’appel suivant à ConfigureKestrel remplace la valeur par défaut Limits.MaxRequestBodySize de 30 000 000 octets définie lors de la configuration de Kestrel par CreateDefaultBuilder :

  WebHost.CreateDefaultBuilder(args)
      .ConfigureKestrel((context, options) =>
      {
          options.Limits.MaxRequestBodySize = 20000000;
      });
  

La racine de contenu détermine l’emplacement où l’hôte recherche les fichiers de contenu, tels que les fichiers de vue MVC. Quand l’application est démarrée à partir du dossier racine du projet, ce dossier est utilisé comme racine de contenu. Il s’agit du dossier par défaut utilisé dans Visual Studio et les modèles dotnet new.

Pour plus d’informations sur la configuration d’une application, consultez Configuration dans ASP.NET Core.

Note

Au lieu d’utiliser la méthode statique CreateDefaultBuilder, vous pouvez créer un hôte à partir de WebHostBuilder. Cette approche est prise en charge avec ASP.NET Core 2.x.

Lors de la configuration d’un hôte, les méthodes Configure et ConfigureServices peuvent être fournies. Si une classe Startup est spécifiée, elle doit définir une méthode Configure. Pour plus d’informations, consultez Start-up de l’application dans ASP.NET Core. Les appels multiples à ConfigureServices s’ajoutent les uns aux autres. Les appels multiples à Configure ou UseStartup sur WebHostBuilder remplacent les paramètres précédents.

Valeurs de configuration de l’hôte

WebHostBuilder s’appuie sur les approches suivantes pour définir les valeurs de configuration de l’hôte :

• Configuration du générateur de l’hôte, qui inclut des variables d’environnement au format ASPNETCORE_{configurationKey}. Par exemple : ASPNETCORE_ENVIRONMENT.
• Extensions telles que UseContentRoot et UseConfiguration (voir la section Remplacement de la configuration).
• UseSetting et la clé associée. Quand une valeur est définie avec UseSetting, elle est définie au format chaîne indépendamment du type.

L’hôte utilise l’option qui définit une valeur en dernier. Pour plus d’informations, consultez Remplacer une configuration dans la section suivante.

Clé d’application (Nom)

La propriété IWebHostEnvironment.ApplicationName est automatiquement définie lorsque UseStartup ou Configure est appelé pendant la construction de l’hôte. La valeur affectée correspond au nom de l’assembly contenant le point d’entrée de l’application. Pour définir explicitement la valeur, utilisez WebHostDefaults.ApplicationKey :

Clé : applicationName
Type : chaîne
Par défaut : nom de l’assembly contenant le point d’entrée de l’application.
Définir à l’aide de : UseSetting
Variable d’environnement : ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capture des erreurs de démarrage

Ce paramètre contrôle la capture des erreurs de démarrage.

Clé : captureStartupErrors
Type : bool (trueou 1)
Par défaut : la valeur par défaut est false, sauf si l’application s’exécute avec Kestrel derrière IIS, où la valeur par défaut est true.
Définir à l’aide de : CaptureStartupErrors
Variable d’environnement : ASPNETCORE_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.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Racine de contenu

Ce paramètre détermine l’emplacement où ASP.NET Core commence à rechercher les fichiers de contenu.

Clé : contentRoot
Type : chaîne
Par défaut : le dossier dans lequel se trouve l’assembly de l’application.
Définir à l’aide de : UseContentRoot
Variable d’environnement : ASPNETCORE_CONTENTROOT

La racine du contenu est également utilisée comme chemin d’accès de base pour la racine Web. Si le chemin d’accès à la racine du contenu n’existe pas, l’hôte ne démarre pas.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Pour plus d'informations, voir :

• Principes fondamentaux : racine du contenu
• Racine Web

Erreurs détaillées

Détermine si les erreurs détaillées doivent être capturées.

Clé : detailedErrors
Type : bool (trueou 1)
Valeur par défaut : false
Définir à l’aide de : UseSetting
Variable d’environnement : ASPNETCORE_DETAILEDERRORS

Quand cette fonctionnalité est activée (ou que l’environnement est défini sur Development), l’application capture les exceptions détaillées.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Environnement

Définit l’environnement de l’application.

Clé : environment
Type : chaîne
Valeur par défaut : Production
Définir à l’aide de : UseEnvironment
Variable d’environnement : ASPNETCORE_ENVIRONMENT

L’environnement peut être défini à n’importe quelle valeur. Les valeurs définies par le framework sont Development, Staging et Production. Les valeurs ne respectent pas la casse. Par défaut, l’environnement est fourni par la variable d’environnement ASPNETCORE_ENVIRONMENT. Lorsque vous utilisez Visual Studio, les variables d’environnement peuvent être définies dans le fichier launchSettings.json. Pour plus d’informations, consultez ASP.NET environnements d’exécution Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Assemblys d’hébergement au démarrage

Définit les assemblys d’hébergement au démarrage de l’application.

Clé : hostingStartupAssemblies
Type : chaîne
Valeur par défaut : chaîne vide
Définir à l’aide de : UseSetting
Variable d’environnement : ASPNETCORE_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.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Port HTTPS

Définissez le port HTTPS vers lequel 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é. Il est donc possible de rediriger accidentellement des requêtes vers un port inutilisé.

Clé : https_port
Type : chaîne
Valeur par défaut : aucune valeur n’est définie.
Définir à l’aide de : UseSetting
Variable d’environnement : ASPNETCORE_HTTPS_PORT

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Ports HTTPS

Définissez les ports à écouter pour les connexions HTTPS.

Clé : https_ports Type : chaîne
Valeur par défaut : aucune valeur n’est définie.
Définir à l’aide de : UseSetting
Variable d’environnement : ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_ports", "8080")

HTTP Ports

Définissez les ports à écouter pour les connexions HTTP.

Clé : http_ports Type : chaîne
Valeur par défaut : aucune valeur n’est définie.
Définir à l’aide de : UseSetting
Variable d’environnement : ASPNETCORE_HTTP_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("http_ports", "8080")

Assemblys d’hébergement à exclure au démarrage

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

Clé: hostingStartupExcludeAssemblies
Type : chaîne
Valeur par défaut : chaîne vide
Définir à l’aide de : UseSetting
Variable d’environnement : ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

URL d’hébergement préférées

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

Clé : preferHostingUrls
Type : bool (trueou 1)
Valeur par défaut : false
Définir à l’aide de : PreferHostingUrls
Variable d’environnement : ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Bloquer les assemblys d’hébergement au démarrage

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 (trueou 1)
Valeur par défaut : false
Définir à l’aide de : UseSetting
Variable d’environnement : ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

URL du serveur

Indique les adresses IP ou les adresses d’hôte avec les ports et protocoles sur lesquels le serveur doit écouter les requêtes.

Clé : urls
Type : chaîne
Valeur par défaut : http://localhost:5000
Définir à l’aide de : UseUrls
Variable d’environnement : ASPNETCORE_URLS

Liste de préfixes d’URL séparés par des points-virgules (;) correspondant aux URL auxquelles le serveur doit répondre. 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 utilisant 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.

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

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

Délai d’arrêt

Spécifie le délai d’attente avant l’arrêt de l’hôte web.

Clé : shutdownTimeoutSeconds
Type : int
Valeur par défaut : 5
Définir à l’aide de : UseShutdownTimeout
Variable d’environnement : ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

La clé accepte une valeur int avec UseSetting (par exemple, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), mais la méthode d’extension UseShutdownTimeout prend une valeur TimeSpan.

Pendant la période du délai d’attente, l’hébergement :

• Déclenche IApplicationLifetime.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.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Assembly de démarrage

Détermine l’assembly à rechercher pour la classe Startup.

Clé : startupAssembly
Type : chaîne
Valeur par défaut : l’assembly de l’application
Définir à l’aide de : UseStartup
Variable d’environnement : ASPNETCORE_STARTUPASSEMBLY

L’assembly peut être référencé par nom (string) ou type (TStartup). Si plusieurs méthodes UseStartup sont appelées, la dernière prévaut.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Racine web

Définit le chemin relatif des ressources statiques de l’application.

Clé : webroot
Type : chaîne
Valeur par défaut : La valeur par défaut est wwwroot. Le chemin d’accès à {content root}/wwwroot doit exister. Si ce chemin n’existe pas, un fournisseur de fichiers no-op est utilisé.
Définir à l’aide de : UseWebRoot
Variable d’environnement : ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Pour plus d'informations, voir :

• Principes fondamentaux : Racine Web
• Racine du contenu

Remplacer la configuration

Utilisez Configuration pour configurer l’hôte web. Dans l’exemple suivant, la configuration de l’hôte est spécifiée de manière facultative dans un fichier hostsettings.json. Toute configuration chargée à partir du fichier hostsettings.json peut être remplacée par des arguments de ligne de commande. La configuration intégrée (dans config) est utilisée pour configurer l’hôte avec UseConfiguration. La configuration IWebHostBuilder est ajoutée à la configuration de l’application, mais l’inverse n’est pas vrai :ConfigureAppConfiguration elle n’affecte pas la configuration IWebHostBuilder.

Remplacement de la configuration fournie par UseUrls par hostsettings.json config d’abord, puis par l’argument de ligne de commande config :

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json :

{
    urls: "http://*:5005"
}

Note

UseConfigurationcopie uniquement les clés du fichier IConfiguration fourni vers la configuration du générateur d’hôte. Par conséquent, le fait de définir reloadOnChange: true pour les fichiers de paramètres XML, JSON et INI n’a aucun effet.

Pour spécifier l’exécution de l’hôte sur une URL particulière, vous pouvez passer la valeur souhaitée à partir d’une invite de commandes lors de l’exécution de dotnet run. L’argument de ligne de commande remplace la valeur urls du fichier hostsettings.json et le serveur écoute sur le port 8080 :

dotnet run --urls "http://*:8080"

Gérer l’hôte

Exécuter

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

host.Run();

Démarrer

Appelez la méthode Start pour exécuter l’hôte en mode non bloquant :

using (host)
{
    host.Start();
    Console.ReadLine();
}

Si une liste d’URL est passée à la méthode Start, l’hôte écoute les URL spécifiées :

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

L’application peut initialiser et démarrer un nouvel hôte ayant les valeurs par défaut préconfigurées de CreateDefaultBuilder en utilisant une méthode d’usage statique. Ces méthodes démarrent le serveur sans sortie console et avec WaitForShutdown attend une interruption (Ctrl-C/SIGINT ou SIGTERM) :

Start(RequestDelegate app)

Commencez par un RequestDelegate :

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Effectuez une requête dans le navigateur vers http://localhost:5000 pour recevoir la réponse « Hello World ! » WaitForShutdown bloque jusqu’à ce qu’une interruption (Ctrl-C/SIGINT ou SIGTERM) soit émise. L’application affiche le message Console.WriteLine et attend que l’utilisateur appuie sur une touche pour s’arrêter.

Démarrer(string url, RequestDelegate app)

Commencez par une URL et RequestDelegate :

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Produit le même résultat que Start(RequestDelegate app), sauf que l’application répond sur http://localhost:8080.

Start(Action<IRouteBuilder routeBuilder> )

Utilisez une instance de IRouteBuilder (Microsoft.AspNetCore.Routing) pour utiliser le middleware de routage :

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Utilisez les requêtes de navigateur suivantes avec l’exemple :

Requête	Réponse
http://localhost:5000/hello/Martin	Bonjour, Martin !
http://localhost:5000/buenosdias/Catrina	Buenos dias, Catrina !
http://localhost:5000/throw/ooops!	Lève une exception avec la chaîne « ooops! »
http://localhost:5000/throw	Lève une exception avec la chaîne « Uh oh! »
http://localhost:5000/Sante/Kevin	Sante, Kevin !
http://localhost:5000	Salut tout le monde!

WaitForShutdown bloque jusqu’à ce qu’une interruption (Ctrl-C/SIGINT ou SIGTERM) soit émise. L’application affiche le message Console.WriteLine et attend que l’utilisateur appuie sur une touche pour s’arrêter.

Start(string url, Action<IRouteBuilder routeBuilder> )

Utilisez une URL et une instance de IRouteBuilder :

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produit le même résultat que Start(Action<IRouteBuilder> routeBuilder), sauf que l’application répond sur http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)

Fournissez un délégué pour configurer un IApplicationBuilder :

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Effectuez une requête dans le navigateur vers http://localhost:5000 pour recevoir la réponse « Hello World ! » WaitForShutdown bloque jusqu’à ce qu’une interruption (Ctrl-C/SIGINT ou SIGTERM) soit émise. L’application affiche le message Console.WriteLine et attend que l’utilisateur appuie sur une touche pour s’arrêter.

StartWith(string url, Action<IApplicationBuilder> application)

Fournissez une URL et un délégué pour configurer un IApplicationBuilder :

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produit le même résultat que StartWith(Action<IApplicationBuilder> app), sauf que l’application répond sur http://localhost:8080.

Interface IWebHostEnvironment

L’interface IWebHostEnvironment fournit des informations sur l’environnement d’hébergement Web de l’application. Utilisez l’injection de constructeur pour obtenir l’interface IWebHostEnvironment afin d’utiliser ses propriétés et méthodes d’extension :

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Vous pouvez utiliser une approche basée sur une convention pour configurer l’application au démarrage en fonction de l’environnement. Vous pouvez également injecter IWebHostEnvironment dans le constructeur Startup pour l’utiliser dans ConfigureServices :

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Note

En plus de la méthode d’extension IsDevelopment, IWebHostEnvironment fournit les méthodes IsStaging, IsProduction et IsEnvironment(string environmentName). Pour plus d’informations, consultez ASP.NET environnements d’exécution Core.

Le service IWebHostEnvironment peut également être injecté directement dans la méthode Configure pour configurer le pipeline de traitement :

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IWebHostEnvironmentpeut être injecté dans la méthode Invoke lors de la création d’un middleware personnalisé :

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Interface IHostApplicationLifetime

IHostApplicationLifetimepermet les activités post-démarrage et d’arrêt. Trois propriétés de l’interface sont des jetons d’annulation utilisés pour inscrire les méthodes Action qui définissent les événements de démarrage et d’arrêt.

Jeton d’annulation	Déclenché lorsque...
ApplicationStarted	L’hôte a complètement démarré.
ApplicationStopped	L’hôte effectue un arrêt approprié. Toutes les requêtes doivent être traitées. L’arrêt est bloqué tant que cet événement n’est pas terminé.
ApplicationStopping	L’hôte effectue un arrêt approprié. Des requêtes peuvent encore être en cours de traitement. L’arrêt est bloqué tant que cet événement n’est pas terminé.

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplicationdemande la fermeture de l’application. La classe suivante utilise StopApplication pour arrêter normalement une application lors de l’appel de la méthode Shutdown de la classe :

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

    public MyClass(IHostApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Validation de l’étendue

CreateDefaultBuilder définit ServiceProviderOptions.ValidateScopes sur true si l’environnement de l’application est Development.

Quand ValidateScopes est défini sur true, le fournisseur de services par défaut vérifie que :

• Les services délimités ne sont pas résolus directement ou indirectement à partir du fournisseur de services racine.
• Les services Scoped ne sont pas directement ou indirectement injectés dans des singletons.

Le fournisseur de services racine est créé quand BuildServiceProvider est appelé. La durée de vie du fournisseur de services racine correspond à la durée de vie de l’application/du serveur quand le fournisseur démarre avec l’application et qu’il est supprimé quand l’application s’arrête.

Les services Scoped sont supprimés par le conteneur qui les a créés. Si un service Scoped est créé dans le conteneur racine, la durée de vie du service est promue en singleton, car elle est supprimée par le conteneur racine seulement quand l’application/le serveur est arrêté. La validation des étendues du service permet de traiter ces situations quand BuildServiceProvider est appelé.

Pour toujours valider les étendues, y compris dans l’environnement Production, configurez ServiceProviderOptions avec UseDefaultServiceProvider sur le générateur d’hôte :

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Ressources supplémentaires

• Héberger ASP.NET Core sur Windows avec IIS
• Héberger ASP.NET Core sur Linux avec Nginx
• Héberger ASP.NET Core dans un service Windows