Hôte web ASP.NET CoreASP.NET Core Web Host

Par Luke LathamBy Luke Latham

Les applications ASP.NET Core configurent et lancent un hôte.ASP.NET Core apps configure and launch a host. L’hôte est responsable de la gestion du démarrage et de la durée de vie des applications.The host is responsible for app startup and lifetime management. Au minimum, l’hôte configure un serveur ainsi qu’un pipeline de traitement des requêtes.At a minimum, the host configures a server and a request processing pipeline. L’hôte peut aussi configurer la journalisation, l’injection de dépendances et la configuration.The host can also set up logging, dependency injection, and configuration.

Cet article traite de l’hôte Web, qui reste disponible uniquement pour la compatibilité descendante.This article covers the Web Host, which remains available only for backward compatibility. L’Hôte générique est recommandé pour tous les types d’applications.The Generic Host is recommended for all app types.

Cet article traite de l’hôte web qui est responsable de l’hébergement des applications web.This article covers the Web Host, which is for hosting web apps. Pour d’autres types d’applications, utilisez l’Hôte générique.For other kinds of apps, use the Generic Host.

Configurer un hôteSet up a host

Créez un hôte en utilisant une instance de IWebHostBuilder.Create a host using an instance of IWebHostBuilder. Cette opération est généralement effectuée au point d’entrée de l’application, à savoir la méthode Main.This is typically performed in the app's entry point, the Main method.

Dans les modèles de projet, Main se trouve dans Program.cs.In the project templates, Main is located in Program.cs. Une application standard appelle CreateDefaultBuilder pour lancer la configuration d’un hôte :A typical app calls CreateDefaultBuilder to start setting up a host:

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.The code that calls CreateDefaultBuilder is in a method named CreateWebHostBuilder, which separates it from the code in Main that calls Run on the builder object. Cette séparation est requise si vous utilisez les outils Entity Framework Core.This separation is required if you use Entity Framework Core tools. 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.The tools expect to find a CreateWebHostBuilder method that they can call at design time to configure the host without running the app. Une alternative consiste à implémenter IDesignTimeDbContextFactory.An alternative is to implement IDesignTimeDbContextFactory. Pour plus d’informations, consultez Création de DbContext au moment du design.For more information, see Design-time DbContext Creation.

CreateDefaultBuilder effectue les tâches suivantes :CreateDefaultBuilder performs the following tasks:

La configuration définie par CreateDefaultBuilder peut être remplacée et enrichie par ConfigureAppConfiguration, ConfigureLogging et les autres méthodes et les méthodes d’extension de IWebHostBuilder.The configuration defined by CreateDefaultBuilder can be overridden and augmented by ConfigureAppConfiguration, ConfigureLogging, and other methods and extension methods of IWebHostBuilder. En voici quelques exemples :A few examples follow:

  • ConfigureAppConfiguration permet de spécifier une configuration IConfiguration supplémentaire pour l’application.ConfigureAppConfiguration is used to specify additional IConfiguration for the app. L’appel ConfigureAppConfiguration suivant ajoute un délégué pour inclure la configuration de l’application dans le fichier appsettings.xml.The following ConfigureAppConfiguration call adds a delegate to include app configuration in the appsettings.xml file. ConfigureAppConfiguration peut être appelé plusieurs fois.ConfigureAppConfiguration may be called multiple times. Notez que cette configuration ne s’applique pas à l’hôte (par exemple, les URL de serveur ou l’environnement).Note that this configuration doesn't apply to the host (for example, server URLs or environment). Voir la section Valeurs de configuration de l’hôte.See the Host configuration values section.

    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 minimal (SetMinimumLevel) sur LogLevel.Warning.The following ConfigureLogging call adds a delegate to configure the minimum logging level (SetMinimumLevel) to LogLevel.Warning. Ce paramètre remplace les paramètres de appsettings.Development.json (LogLevel.Debug) et appsettings.Production.json (LogLevel.Error) configurés par CreateDefaultBuilder.This setting overrides the settings in appsettings.Development.json (LogLevel.Debug) and appsettings.Production.json (LogLevel.Error) configured by CreateDefaultBuilder. ConfigureLogging peut être appelé plusieurs fois.ConfigureLogging may be called multiple times.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • L’appel suivant à ConfigureKestrel remplace la valeur par défaut de Limits.MaxRequestBodySize (30 000 000 octets) établie lors de la configuration de Kestrel par CreateDefaultBuilder :The following call to ConfigureKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured by CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    
  • L’appel suivant à UseKestrel remplace la valeur par défaut de Limits.MaxRequestBodySize (30 000 000 octets) établie lors de la configuration de Kestrel par CreateDefaultBuilder :The following call to UseKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured by CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .UseKestrel(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.The content root determines where the host searches for content files, such as MVC view files. Quand l’application est démarrée à partir du dossier racine du projet, ce dossier est utilisé comme racine de contenu.When the app is started from the project's root folder, the project's root folder is used as the content root. Il s’agit du dossier par défaut utilisé dans Visual Studio et les modèles dotnet new.This is the default used in Visual Studio and the dotnet new templates.

Pour plus d’informations sur la configuration d’application, consultez Configuration dans ASP.NET Core.For more information on app configuration, see Configuration dans ASP.NET Core.

Notes

Au lieu d’utiliser la méthode statique CreateDefaultBuilder, vous pouvez aussi créer un hôte à partir de WebHostBuilder. Cette approche est prise en charge dans ASP.NET Core 2.x.As an alternative to using the static CreateDefaultBuilder method, creating a host from WebHostBuilder is a supported approach with ASP.NET Core 2.x.

Lors de la configuration d’un hôte, les méthodes Configure et ConfigureServices peuvent être fournies.When setting up a host, Configure and ConfigureServices methods can be provided. Si une classe Startup est spécifiée, elle doit définir une méthode Configure.If a Startup class is specified, it must define a Configure method. Pour plus d’informations, consultez Démarrage d’une application dans ASP.NET Core.For more information, see Démarrage d’une application dans ASP.NET Core. Les appels multiples à ConfigureServices s’ajoutent les uns aux autres.Multiple calls to ConfigureServices append to one another. Les appels multiples à Configure ou UseStartup sur WebHostBuilder remplacent les paramètres précédents.Multiple calls to Configure or UseStartup on the WebHostBuilder replace previous settings.

Valeurs de configuration de l’hôteHost configuration values

WebHostBuilder s’appuie sur les approches suivantes pour définir les valeurs de configuration de l’hôte :WebHostBuilder relies on the following approaches to set the host configuration values:

  • Configuration du générateur de l’hôte, qui inclut des variables d’environnement au format ASPNETCORE_{configurationKey}.Host builder configuration, which includes environment variables with the format ASPNETCORE_{configurationKey}. Par exemple, ASPNETCORE_ENVIRONMENT.For example, ASPNETCORE_ENVIRONMENT.
  • Des extensions comme UseContentRoot et UseConfiguration (voir la section Remplacer la configuration).Extensions such as UseContentRoot and UseConfiguration (see the Override configuration section).
  • UseSetting et la clé associée.UseSetting and the associated key. Quand une valeur est définie avec UseSetting, elle est définie au format chaîne indépendamment du type.When setting a value with UseSetting, the value is set as a string regardless of the type.

L’hôte utilise l’option qui définit une valeur en dernier.The host uses whichever option sets a value last. Pour plus d’informations, consultez Remplacer une configuration dans la section suivante.For more information, see Override configuration in the next section.

Clé d’application (Nom)Application Key (Name)

La propriété IHostingEnvironment.ApplicationName est définie automatiquement quand UseStartup ou Configure est appelé pendant la construction de l’hôte.The IHostingEnvironment.ApplicationName property is automatically set when UseStartup or Configure is called during host construction. La valeur affectée correspond au nom de l’assembly contenant le point d’entrée de l’application.The value is set to the name of the assembly containing the app's entry point. Pour définir la valeur explicitement, utilisez WebHostDefaults.ApplicationKey :To set the value explicitly, use the WebHostDefaults.ApplicationKey:

Clé : applicationNameKey: applicationName
Type : stringType: string
Par défaut : nom de l’assembly contenant le point d’entrée de l’application.Default: The name of the assembly containing the app's entry point.
Définition avec : UseSettingSet using: UseSetting
Variable d’environnement : ASPNETCORE_APPLICATIONNAMEEnvironment variable: ASPNETCORE_APPLICATIONNAME

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

Capture des erreurs de démarrageCapture Startup Errors

Ce paramètre contrôle la capture des erreurs de démarrage.This setting controls the capture of startup errors.

Clé : captureStartupErrorsKey: captureStartupErrors
Type : bool (true ou 1)Type: bool (true or 1)
Par défaut : false, ou true si l’application s’exécute avec Kestrel derrière IIS.Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true.
Définition avec : CaptureStartupErrorsSet using: CaptureStartupErrors
Variable d’environnement : ASPNETCORE_CAPTURESTARTUPERRORSEnvironment variable: ASPNETCORE_CAPTURESTARTUPERRORS

Avec la valeur false, la survenue d’erreurs au démarrage entraîne la fermeture de l’hôte.When false, errors during startup result in the host exiting. Avec la valeur true, l’hôte capture les exceptions levées au démarrage et tente de démarrer le serveur.When true, the host captures exceptions during startup and attempts to start the server.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Racine de contenuContent Root

Ce paramètre détermine l’emplacement où ASP.NET Core commence la recherche des fichiers de contenu, tels que les vues MVC.This setting determines where ASP.NET Core begins searching for content files, such as MVC views.

Clé : contentRootKey: contentRoot
Type : stringType: string
Par défaut : dossier où réside l’assembly de l’application.Default: Defaults to the folder where the app assembly resides.
Définition avec : UseContentRootSet using: UseContentRoot
Variable d’environnement : ASPNETCORE_CONTENTROOTEnvironment variable: ASPNETCORE_CONTENTROOT

La racine de contenu est également utilisée comme chemin de base pour le paramètre de la racine Web.The content root is also used as the base path for the Web Root setting. Si le chemin est introuvable, l’hôte ne peut pas démarrer.If the path doesn't exist, the host fails to start.

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

Erreurs détailléesDetailed Errors

Détermine si les erreurs détaillées doivent être capturées.Determines if detailed errors should be captured.

Clé : detailedErrorsKey: detailedErrors
Type : bool (true ou 1)Type: bool (true or 1)
Valeur par défaut : falseDefault: false
Définition avec : UseSettingSet using: UseSetting
Variable d’environnement : ASPNETCORE_DETAILEDERRORSEnvironment variable: 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.When enabled (or when the Environment is set to Development), the app captures detailed exceptions.

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

EnvironnementEnvironment

Définit l’environnement de l’application.Sets the app's environment.

Clé : environmentKey: environment
Type : stringType: string
Par défaut : ProductionDefault: Production
Définition avec : UseEnvironmentSet using: UseEnvironment
Variable d’environnement : ASPNETCORE_ENVIRONMENTEnvironment variable: ASPNETCORE_ENVIRONMENT

L’environnement peut être défini à n’importe quelle valeur.The environment can be set to any value. Les valeurs définies par le framework sont Development, Staging et Production.Framework-defined values include Development, Staging, and Production. Les valeurs ne respectent pas la casse.Values aren't case sensitive. Par défaut, l’environnement est fourni par la variable d’environnement ASPNETCORE_ENVIRONMENT.By default, the Environment is read from the ASPNETCORE_ENVIRONMENT environment variable. Si vous utilisez Visual Studio, les variables d’environnement peuvent être définies dans le fichier launchSettings.json.When using Visual Studio, environment variables may be set in the launchSettings.json file. Pour plus d’informations, consultez Utiliser plusieurs environnements dans ASP.NET Core.For more information, see Utiliser plusieurs environnements dans ASP.NET Core.

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

Assemblys d’hébergement au démarrageHosting Startup Assemblies

Définit les assemblys d’hébergement au démarrage de l’application.Sets the app's hosting startup assemblies.

Clé : hostingStartupAssembliesKey: hostingStartupAssemblies
Type : stringType: string
Par défaut : Chaîne videDefault: Empty string
Définition avec : UseSettingSet using: UseSetting
Variable d’environnement : ASPNETCORE_HOSTINGSTARTUPASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Chaîne délimitée par des points-virgules qui spécifie les assemblys d’hébergement à charger au démarrage.A semicolon-delimited string of hosting startup assemblies to load on startup.

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.Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. 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.When hosting startup assemblies are provided, they're added to the app's assembly for loading when the app builds its common services during startup.

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

Port HTTPSHTTPS Port

Définissez le port de redirection HTTPS.Set the HTTPS redirect port. Utilisé dans l’application de HTTPS.Used in enforcing HTTPS.

Clé : https_port Type : string Par défaut : Aucune valeur par défaut n’est définie.Key: https_port Type: string Default: A default value isn't set. Définir avec : UseSetting La variable d’environnement: ASPNETCORE_HTTPS_PORTSet using: UseSetting Environment variable: ASPNETCORE_HTTPS_PORT

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

Assemblys d’hébergement à exclure au démarrageHosting Startup Exclude Assemblies

Chaîne délimitée par des points-virgules qui spécifie les assemblys d’hébergement à exclure au démarrage.A semicolon-delimited string of hosting startup assemblies to exclude on startup.

Clé : hostingStartupExcludeAssembliesKey: hostingStartupExcludeAssemblies
Type : stringType: string
Par défaut : Chaîne videDefault: Empty string
Définition avec : UseSettingSet using: UseSetting
Variable d’environnement : ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

URL d’hébergement préféréesPrefer Hosting URLs

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.Indicates whether the host should listen on the URLs configured with the WebHostBuilder instead of those configured with the IServer implementation.

Clé : preferHostingUrlsKey: preferHostingUrls
Type : bool (true ou 1)Type: bool (true or 1)
Valeur par défaut : trueDefault: true
Définition avec : PreferHostingUrlsSet using: PreferHostingUrls
Variable d’environnement : ASPNETCORE_PREFERHOSTINGURLSEnvironment variable: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

Bloquer les assemblys d’hébergement au démarragePrevent Hosting Startup

Empêche le chargement automatique des assemblys d’hébergement au démarrage, y compris ceux configurés par l’assembly de l’application.Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. Pour plus d’informations, consultez Utiliser des assemblys de démarrage d’hébergement dans ASP.NET Core.For more information, see Utiliser des assemblys de démarrage d’hébergement dans ASP.NET Core.

Clé : preventHostingStartupKey: preventHostingStartup
Type : bool (true ou 1)Type: bool (true or 1)
Valeur par défaut : falseDefault: false
Définition avec : UseSettingSet using: UseSetting
Variable d’environnement : ASPNETCORE_PREVENTHOSTINGSTARTUPEnvironment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

URL du serveurServer URLs

Indique les adresses IP ou les adresses d’hôte avec les ports et protocoles sur lesquels le serveur doit écouter les requêtes.Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for requests.

Clé : urlsKey: urls
Type : stringType: string
Par défaut : http://localhost:5000Default: http://localhost:5000
Définition avec : UseUrlsSet using: UseUrls
Variable d’environnement : ASPNETCORE_URLSEnvironment variable: ASPNETCORE_URLS

Liste de préfixes d’URL séparés par des points-virgules (;) correspondant aux URL auxquelles le serveur doit répondre.Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. Par exemple, http://localhost:123.For example, 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).Use "*" to indicate that the server should listen for requests on any IP address or hostname using the specified port and protocol (for example, http://*:5000). Le protocole (http:// ou https://) doit être inclus avec chaque URL.The protocol (http:// or https://) must be included with each URL. Les formats pris en charge varient selon les serveurs.Supported formats vary among servers.

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

Kestrel a sa propre API de configuration de points de terminaison.Kestrel has its own endpoint configuration API. Pour plus d’informations, consultez Implémentation du serveur web Kestrel dans ASP.NET Core.For more information, see Implémentation du serveur web Kestrel dans ASP.NET Core.

Délai d’arrêtShutdown Timeout

Spécifie le délai d’attente avant l’arrêt de l’hôte web.Specifies the amount of time to wait for Web Host to shut down.

Clé : shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
Type : intType: int
Par défaut : 5Default: 5
Définition avec : UseShutdownTimeoutSet using: UseShutdownTimeout
Variable d’environnement : ASPNETCORE_SHUTDOWNTIMEOUTSECONDSEnvironment variable: 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.Although the key accepts an int with UseSetting (for example, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), the UseShutdownTimeout extension method takes a TimeSpan.

Pendant la période du délai d’attente, l’hébergement :During the timeout period, hosting:

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.If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. Les services s’arrêtent même s’ils n’ont pas terminé les traitements.The services stop even if they haven't finished processing. Si des services nécessitent plus de temps pour s’arrêter, augmentez le délai d’attente.If services require additional time to stop, increase the timeout.

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

Assembly de démarrageStartup Assembly

Détermine l’assembly à rechercher pour la classe Startup.Determines the assembly to search for the Startup class.

Clé : startupAssemblyKey: startupAssembly
Type : stringType: string
Par défaut : l’assembly de l’applicationDefault: The app's assembly
Définition avec : UseStartupSet using: UseStartup
Variable d’environnement : ASPNETCORE_STARTUPASSEMBLYEnvironment variable: ASPNETCORE_STARTUPASSEMBLY

L’assembly peut être référencé par nom (string) ou type (TStartup).The assembly by name (string) or type (TStartup) can be referenced. Si plusieurs méthodes UseStartup sont appelées, la dernière prévaut.If multiple UseStartup methods are called, the last one takes precedence.

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

Racine WebWeb Root

Définit le chemin relatif des ressources statiques de l’application.Sets the relative path to the app's static assets.

Clé : webrootKey: webroot
Type : stringType: string
Par défaut : quand aucune valeur n’est spécifiée, la valeur par défaut est « (Racine de contenu)/wwwroot », si ce chemin existe.Default: If not specified, the default is "(Content Root)/wwwroot", if the path exists. Si ce chemin est introuvable, un fournisseur de fichiers no-op est utilisé.If the path doesn't exist, then a no-op file provider is used.
Définition avec : UseWebRootSet using: UseWebRoot
Variable d’environnement : ASPNETCORE_WEBROOTEnvironment variable: ASPNETCORE_WEBROOT

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

Remplacer la configurationOverride configuration

Utilisez Configuration pour configurer l’hôte web.Use Configuration to configure Web Host. Dans l’exemple suivant, la configuration de l’hôte est spécifiée de façon facultative dans un fichier hostsettings.json.In the following example, host configuration is optionally specified in a hostsettings.json file. Toute configuration chargée à partir du fichier hostsettings.json est remplaçable par des arguments de ligne de commande.Any configuration loaded from the hostsettings.json file may be overridden by command-line arguments. La configuration définie (dans config) est utilisée pour configurer l’hôte avec UseConfiguration.The built configuration (in config) is used to configure the host with UseConfiguration. La configuration IWebHostBuilder est ajoutée à la configuration de l’application, mais l’inverse n’est pas vrai — ConfigureAppConfiguration n’a pas d’incidence sur la configuration IWebHostBuilder.IWebHostBuilder configuration is added to the app's configuration, but the converse isn't true—ConfigureAppConfiguration doesn't affect the IWebHostBuilder configuration.

La configuration fournie par UseUrls est d’abord remplacée par la configuration hostsettings.json, puis par la configuration des arguments de ligne de commande :Overriding the configuration provided by UseUrls with hostsettings.json config first, command-line argument config second:

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 :hostsettings.json:

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

Notes

La méthode d’extension UseConfiguration ne peut pas analyser une section de configuration retournée par GetSection (par exemple, .UseConfiguration(Configuration.GetSection("section")).The UseConfiguration extension method isn't currently capable of parsing a configuration section returned by GetSection (for example, .UseConfiguration(Configuration.GetSection("section")). La méthode GetSection filtre les clés de configuration dans la section demandée, mais laisse le nom de la section dans les clés (par exemple, section:urls, section:environment).The GetSection method filters the configuration keys to the section requested but leaves the section name on the keys (for example, section:urls, section:environment). La méthode UseConfiguration suppose que les clés correspondent aux clés WebHostBuilder (par exemple, urls, environment).The UseConfiguration method expects the keys to match the WebHostBuilder keys (for example, urls, environment). La présence du nom de la section dans les clés empêche l’utilisation des valeurs de la section pour configurer l’hôte.The presence of the section name on the keys prevents the section's values from configuring the host. Ce problème sera résolu dans une prochaine mise en production.This issue will be addressed in an upcoming release. Pour obtenir plus d’informations et connaître les solutions de contournement possibles, consultez Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.For more information and workarounds, see Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.

UseConfiguration copie seulement les clés de la configuration IConfiguration fournie vers la configuration du générateur d’hôte.UseConfiguration only copies keys from the provided IConfiguration to the host builder configuration. Par conséquent, le fait de définir reloadOnChange: true pour les fichiers de paramètres XML, JSON et INI n’a aucun effet.Therefore, setting reloadOnChange: true for JSON, INI, and XML settings files has no effect.

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.To specify the host run on a particular URL, the desired value can be passed in from a command prompt when executing dotnet run. L’argument de ligne de commande remplace la valeur urls du fichier hostsettings.json, et le serveur écoute le port 8080 :The command-line argument overrides the urls value from the hostsettings.json file, and the server listens on port 8080:

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

Gérer l’hôteManage the host

ExécuterRun

La méthode Run démarre l’application web et bloque le thread appelant jusqu’à l’arrêt de l’hôte :The Run method starts the web app and blocks the calling thread until the host is shut down:

host.Run();

DémarrerStart

Appelez la méthode Start pour exécuter l’hôte en mode non bloquant :Run the host in a non-blocking manner by calling its Start method:

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 :If a list of URLs is passed to the Start method, it listens on the URLs specified:

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.The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder using a static convenience method. Ces méthodes démarrent le serveur sans sortie de console et, avec WaitForShutdown, elles attendent un arrêt (Ctrl-C/SIGINT ou SIGTERM) :These methods start the server without console output and with WaitForShutdown wait for a break (Ctrl-C/SIGINT or SIGTERM):

Start(RequestDelegate app)Start(RequestDelegate app)

Commencez par un RequestDelegate :Start with a RequestDelegate:

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

Envoyez une requête à http://localhost:5000 dans le navigateur pour recevoir la réponse « Hello World! »Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown bloque la requête jusqu’à l’émission d’une commande d’arrêt (Ctrl-C/SIGINT ou SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. L’application affiche le message Console.WriteLine et attend que l’utilisateur appuie sur une touche pour s’arrêter.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, RequestDelegate app)Start(string url, RequestDelegate app)

Commencez par une URL et RequestDelegate :Start with a URL and 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.Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)Start(Action<IRouteBuilder> routeBuilder)

Utilisez une instance de IRouteBuilder (Microsoft.AspNetCore.Routing) pour utiliser le middleware de routage :Use an instance of IRouteBuilder (Microsoft.AspNetCore.Routing) to use routing middleware:

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 :Use the following browser requests with the example:

RequêteRequest RéponseResponse
http://localhost:5000/hello/Martin Hello, Martin!Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Lève une exception avec la chaîne « ooops! »Throws an exception with string "ooops!"
http://localhost:5000/throw Lève une exception avec la chaîne « Uh oh! »Throws an exception with string "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!Sante, Kevin!
http://localhost:5000 Hello World!Hello World!

WaitForShutdown bloque la requête jusqu’à l’émission d’une commande d’arrêt (Ctrl-C/SIGINT ou SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. L’application affiche le message Console.WriteLine et attend que l’utilisateur appuie sur une touche pour s’arrêter.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, Action<IRouteBuilder> routeBuilder)Start(string url, Action<IRouteBuilder> routeBuilder)

Utilisez une URL et une instance de IRouteBuilder :Use a URL and an instance of 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.Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)StartWith(Action<IApplicationBuilder> app)

Fournissez un délégué pour configurer un IApplicationBuilder :Provide a delegate to configure an 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();
}

Envoyez une requête à http://localhost:5000 dans le navigateur pour recevoir la réponse « Hello World! »Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown bloque la requête jusqu’à l’émission d’une commande d’arrêt (Ctrl-C/SIGINT ou SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. L’application affiche le message Console.WriteLine et attend que l’utilisateur appuie sur une touche pour s’arrêter.The app displays the Console.WriteLine message and waits for a keypress to exit.

StartWith(string url, Action<IApplicationBuilder> app)StartWith(string url, Action<IApplicationBuilder> app)

Fournissez une URL et un délégué pour configurer un IApplicationBuilder :Provide a URL and a delegate to configure an 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.Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on http://localhost:8080.

Interface IHostingEnvironmentIHostingEnvironment interface

L’interface IHostingEnvironment fournit des informations sur l’environnement d’hébergement web de l’application.The IHostingEnvironment interface provides information about the app's web hosting environment. Utilisez l’injection de constructeur pour obtenir l’interface IHostingEnvironment afin d’utiliser ses propriétés et méthodes d’extension :Use constructor injection to obtain the IHostingEnvironment in order to use its properties and extension methods:

public class CustomFileReader
{
    private readonly IHostingEnvironment _env;

    public CustomFileReader(IHostingEnvironment 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.A convention-based approach can be used to configure the app at startup based on the environment. Vous pouvez également injecter IHostingEnvironment dans le constructeur Startup pour l’utiliser dans ConfigureServices :Alternatively, inject the IHostingEnvironment into the Startup constructor for use in ConfigureServices:

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

    public IHostingEnvironment HostingEnvironment { get; }

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

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Notes

En plus de la méthode d’extension IsDevelopment, IHostingEnvironment fournit les méthodes IsStaging, IsProduction et IsEnvironment(string environmentName).In addition to the IsDevelopment extension method, IHostingEnvironment offers IsStaging, IsProduction, and IsEnvironment(string environmentName) methods. Pour plus d’informations, consultez Utiliser plusieurs environnements dans ASP.NET Core.For more information, see Utiliser plusieurs environnements dans ASP.NET Core.

Le service IHostingEnvironment peut également être injecté directement dans la méthode Configure pour configurer le pipeline de traitement :The IHostingEnvironment service can also be injected directly into the Configure method for setting up the processing pipeline:

public void Configure(IApplicationBuilder app, IHostingEnvironment 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;
}

IHostingEnvironment peut être injecté dans la méthode Invoke lors de la création d’un intergiciel (middleware) personnalisé :IHostingEnvironment can be injected into the Invoke method when creating custom middleware:

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

    var contentRootPath = env.ContentRootPath;
}

Interface IApplicationLifetimeIApplicationLifetime interface

IApplicationLifetime s’utilise pour les opérations post-démarrage et arrêt.IApplicationLifetime allows for post-startup and shutdown activities. 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.Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

Jeton d’annulationCancellation Token Événement déclencheurTriggered when…
ApplicationStartedApplicationStarted L’hôte a complètement démarré.The host has fully started.
ApplicationStoppedApplicationStopped L’hôte effectue un arrêt approprié.The host is completing a graceful shutdown. Toutes les requêtes doivent être traitées.All requests should be processed. L’arrêt est bloqué tant que cet événement n’est pas terminé.Shutdown blocks until this event completes.
ApplicationStoppingApplicationStopping L’hôte effectue un arrêt approprié.The host is performing a graceful shutdown. Des requêtes peuvent encore être en cours de traitement.Requests may still be processing. L’arrêt est bloqué tant que cet événement n’est pas terminé.Shutdown blocks until this event completes.
public class Startup
{
    public void Configure(IApplicationBuilder app, IApplicationLifetime 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
    }
}

StopApplication requête l’arrêt de l’application.StopApplication requests termination of the app. La classe suivante utilise StopApplication pour arrêter normalement une application quand la méthode Shutdown de la classe est appelée :The following class uses StopApplication to gracefully shut down an app when the class's Shutdown method is called:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

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

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

Validation de l’étendueScope validation

CreateDefaultBuilder affecte la valeur true à ServiceProviderOptions.ValidateScopes si l’environnement de l’application est Développement.CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true if the app's environment is Development.

Quand ValidateScopes est défini sur true, le fournisseur de services par défaut vérifie que :When ValidateScopes is set to true, the default service provider performs checks to verify that:

  • Les services délimités ne sont pas résolus directement ou indirectement à partir du fournisseur de services racine.Scoped services aren't directly or indirectly resolved from the root service provider.
  • Les services Scoped ne sont pas directement ou indirectement injectés dans des singletons.Scoped services aren't directly or indirectly injected into singletons.

Le fournisseur de services racine est créé quand BuildServiceProvider est appelé.The root service provider is created when BuildServiceProvider is called. 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.The root service provider's lifetime corresponds to the app/server's lifetime when the provider starts with the app and is disposed when the app shuts down.

Les services Scoped sont supprimés par le conteneur qui les a créés.Scoped services are disposed by the container that created them. 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é.If a scoped service is created in the root container, the service's lifetime is effectively promoted to singleton because it's only disposed by the root container when app/server is shut down. La validation des étendues du service permet de traiter ces situations quand BuildServiceProvider est appelé.Validating service scopes catches these situations when BuildServiceProvider is called.

Pour toujours valider les étendues, notamment dans l’environnement de production, configurez ServiceProviderOptions avec UseDefaultServiceProvider sur le créateur d’hôte :To always validate scopes, including in the Production environment, configure the ServiceProviderOptions with UseDefaultServiceProvider on the host builder:

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

Ressources supplémentairesAdditional resources