Hôte web ASP.NET Core

Article
08/29/2024

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 8 de cet article.

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la Stratégie de prise en charge de .NET et .NET Core. Pour la version actuelle, consultez la version .NET 8 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 8 de cet article.

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 une WebApplication, ce qui est recommandé pour les applications web. Pour plus d’informations sur WebApplicationBuilder et WebApplication, consultez Migrer d’ASP.NET Core 5.0 à 6.0

Configurer un hôte

Créez un hôte en utilisant une instance de IWebHostBuilder. Cette opération est généralement effectuée au point d’entrée de l’application, à savoir la méthode Main dans Program.cs. Une application standard appelle CreateDefaultBuilder pour lancer la configuration d’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 comme serveur web 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.
Définit le chemin retourné par Directory.GetCurrentDirectory comme racine de contenu.
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 des éléments ci-après :
- appsettings.json.
- appsettings.{Environment}.json.
- Les secrets utilisateur quand 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 de journal qui sont spécifiées dans une section de configuration de la journalisation dans 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 connaître les options IIS par défaut, consultez la 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 enrichie par ConfigureAppConfiguration, ConfigureLogging et les autres méthodes et les méthodes d’extension de IWebHostBuilder. En voici quelques exemples :

ConfigureAppConfiguration permet de spécifier une configuration IConfiguration supplémentaire 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 minimal (SetMinimumLevel) sur LogLevel.Warning. Ce paramètre remplace les paramètres de appsettings.Development.json (LogLevel.Debug) et de 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 de Limits.MaxRequestBodySize (30 000 000 octets) établie 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.

Remarque

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.

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 comme UseContentRoot et UseConfiguration (consultez la section Remplacer 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 définie automatiquement quand 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 la valeur explicitement, utilisez WebHostDefaults.ApplicationKey :

Clé : applicationName
Type : string
Par défaut : nom de l’assembly contenant le point d’entrée de l’application.
Définition avec : UseSetting
La 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 (true ou 1)
Valeur par défaut : false, ou true si l’application s’exécute avec Kestrel derrière IIS.
Définition avec : CaptureStartupErrors
La 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 la recherche des fichiers de contenu.

Clé : contentRoot
Type : string
Valeur par défaut : dossier où réside l’assembly de l’application.
Définition avec : UseContentRoot
La variable d’environnement: ASPNETCORE_CONTENTROOT

La racine de contenu est également utilisée comme chemin de base pour la racine web. Si le chemin de la racine de contenu est introuvable, l’hôte ne peut pas démarrer.

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

Pour en savoir plus, consultez :

Erreurs détaillées

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

Clé : detailedErrors
Type : bool (true ou 1)
Valeur par défaut : false
Définition avec : UseSetting
La 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")

Environment

Définit l’environnement de l’application.

Clé : environment
Type : string
Valeur par défaut : Production
Définition avec : UseEnvironment
La 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. Si vous utilisez Visual Studio, les variables d’environnement peuvent être définies dans le fichier launchSettings.json. Pour plus d’informations, consultez Utiliser plusieurs environnements dans ASP.NET 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 : string
Valeur par défaut : une chaîne vide
Définition avec : UseSetting
La 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 à 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_port
Type : string
Par défaut : Aucune valeur par défaut n’est définie.
Définition avec : UseSetting
La variable d’environnement: ASPNETCORE_HTTPS_PORT

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

Ports HTTPS

Définissez les ports HTTPS sur lesquels écouter les connexions HTTPS.

Clé : https_ports Type : chaîne
Par défaut : Aucune valeur par défaut n’est définie.
Définition avec : UseSetting
La variable d’environnement: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_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 : string
Valeur par défaut : une chaîne vide
Définition avec : UseSetting
La 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 (true ou 1)
Valeur par défaut : false
Définition avec : PreferHostingUrls
La 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 (true ou 1)
Valeur par défaut : false
Définition avec : UseSetting
La 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 : string
Par défaut : http://localhost:5000
Définition avec : UseUrls
La 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 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.

WebHost.CreateDefaultBuilder(args)
    .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.

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éfinition avec : UseShutdownTimeout
La 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 : string
Valeur par défaut : l’assembly de l’application
Définition avec : UseStartup
La 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 : string
Par défaut : la valeur par défaut est wwwroot. Le chemin d’accès à {racine du contenu}/wwwroot doit exister. Si ce chemin n’existe pas, un fournisseur de fichiers no-op est utilisé.
Définition avec : UseWebRoot
La variable d’environnement: ASPNETCORE_WEBROOT

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

Pour en savoir plus, consultez :

Remplacer la configuration

Utilisez Configuration pour configurer l’hôte web. Dans l’exemple suivant, la configuration de l’hôte est facultativement spécifiée dans un fichier hostsettings.json. Une 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 n’a pas d’incidence sur la configuration IWebHostBuilder.

La configuration fournie par UseUrls est d’abord remplacée par la configuration du fichier hostsettings.json et ensuite par la configuration des arguments de ligne de commande :

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

Remarque

UseConfiguration copie seulement les clés de la configuration IConfiguration fournie 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 se substitue à la valeur urls fournie par le fichier hostsettings.json et le serveur écoute 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 de console et, avec WaitForShutdown, elles attendent un arrêt (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 sur http://localhost:5000 pour recevoir la réponse « Hello World! » WaitForShutdown se bloque jusqu’à ce qu’un arrêt (Ctrl-C/SIGINT ou SIGTERM) soit émis. L’application affiche le message Console.WriteLine et attend que l’utilisateur appuie sur une touche pour s’arrêter.

Start(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	Response
`http://localhost:5000/hello/Martin`	Hello, 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`	Hello World!

WaitForShutdown bloque la requête jusqu’à l’émission d’une commande d’arrêt (Ctrl-C/SIGINT ou SIGTERM). 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();
}

StartWith(string url, Action<IApplicationBuilder> app)

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

Remarque

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 Utiliser plusieurs environnements dans ASP.NET 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;
}

IWebHostEnvironment peut être injecté dans la méthode Invoke lors de la création d’un intergiciel (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

IHostApplicationLifetime s’utilise pour les opérations post-démarrage et 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é quand...
`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
    }
}

StopApplication demande l’arrêt 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 Développement.

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, notamment dans l’environnement de production, configurez ServiceProviderOptions avec UseDefaultServiceProvider sur le créateur d’hôte :

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

Ressources supplémentaires

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 hôte générique .NET, qui est recommandé pour tous les types d’application.

Configurer un hôte

Créez un hôte en utilisant une instance de IWebHostBuilder. Cette opération est généralement effectuée au point d’entrée de l’application, à savoir la méthode Main.

Dans les modèles de projet, Main se trouve dans Program.cs. Une application standard appelle CreateDefaultBuilder pour lancer la configuration d’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>();
}

CreateDefaultBuilder effectue les tâches suivantes :

Configure le serveur Kestrel comme serveur web 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.
Définit le chemin retourné par Directory.GetCurrentDirectory comme racine de contenu.
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 des éléments ci-après :
- appsettings.json.
- appsettings.{Environment}.json.
- Les secrets utilisateur quand 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 de journal qui sont spécifiées dans une section de configuration de la journalisation dans 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 connaître les options IIS par défaut, consultez la 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.

ConfigureAppConfiguration permet de spécifier une configuration IConfiguration supplémentaire 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 minimal (SetMinimumLevel) sur LogLevel.Warning. Ce paramètre remplace les paramètres de appsettings.Development.json (LogLevel.Debug) et de 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 de Limits.MaxRequestBodySize (30 000 000 octets) établie lors de la configuration de Kestrel par CreateDefaultBuilder :
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureKestrel((context, options) =>
    {
        options.Limits.MaxRequestBodySize = 20000000;
    });
```

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

Remarque

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.

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 comme UseContentRoot et UseConfiguration (consultez la section Remplacer 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)

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.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Racine de contenu

Ce paramètre détermine l’emplacement où ASP.NET Core commence la recherche des fichiers de contenu.

La racine de contenu est également utilisée comme chemin de base pour la racine web. Si le chemin de la racine de contenu est introuvable, l’hôte ne peut pas démarrer.

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

Pour en savoir plus, consultez :

Erreurs détaillées

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

Clé : detailedErrors
Type : bool (true ou 1)
Valeur par défaut : false
Définition avec : UseSetting
La 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")

Environment

Définit l’environnement de l’application.

Clé : environment
Type : string
Valeur par défaut : Production
Définition avec : UseEnvironment
La variable d’environnement: ASPNETCORE_ENVIRONMENT

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.

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

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

Port HTTPS

Définissez le port de redirection HTTPS. Utilisé dans l’application de HTTPS.

Clé : https_port
Type : string
Par défaut : Aucune valeur par défaut n’est définie.
Définition avec : UseSetting
La variable d’environnement: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "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.

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.

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

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

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 : string
Par défaut : http://localhost:5000
Définition avec : UseUrls
La variable d’environnement: ASPNETCORE_URLS

WebHost.CreateDefaultBuilder(args)
    .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.

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éfinition avec : UseShutdownTimeout
La 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.

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

Assembly de démarrage

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

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.

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

Pour en savoir plus, consultez :

Remplacer la configuration

La configuration fournie par UseUrls est d’abord remplacée par la configuration du fichier hostsettings.json et ensuite par la configuration des arguments de ligne de commande :

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

Remarque

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();
}

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();
}

Start(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	Response
`http://localhost:5000/hello/Martin`	Hello, 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`	Hello World!

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();
}

StartWith(string url, Action<IApplicationBuilder> app)

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

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

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

Remarque

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

IWebHostEnvironment peut être injecté dans la méthode Invoke lors de la création d’un intergiciel (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

Jeton d’annulation	Déclenché quand...
`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
    }
}

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 Développement.

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.

Pour toujours valider les étendues, notamment dans l’environnement de production, configurez ServiceProviderOptions avec UseDefaultServiceProvider sur le créateur d’hôte :

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

Ressources supplémentaires

Configurer un hôte

Créez un hôte en utilisant une instance de IWebHostBuilder. Cette opération est généralement effectuée au point d’entrée de l’application, à savoir la méthode Main.

Dans les modèles de projet, Main se trouve dans Program.cs. Une application standard appelle CreateDefaultBuilder pour lancer la configuration d’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>();
}

CreateDefaultBuilder effectue les tâches suivantes :

Configure le serveur Kestrel comme serveur web en utilisant les fournisseurs de configuration d’hébergement de l’application. Pour connaître les options par défaut du serveur Kestrel, consultez Kestrel serveur web dans ASP.NET Core.
Définit le chemin retourné par Directory.GetCurrentDirectory comme racine de contenu.
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 des éléments ci-après :
- appsettings.json.
- appsettings.{Environment}.json.
- Les secrets utilisateur quand 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 de journal qui sont spécifiées dans une section de configuration de la journalisation dans 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 connaître les options IIS par défaut, consultez la 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.

ConfigureAppConfiguration permet de spécifier une configuration IConfiguration supplémentaire 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 minimal (SetMinimumLevel) sur LogLevel.Warning. Ce paramètre remplace les paramètres de appsettings.Development.json (LogLevel.Debug) et de 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 de Limits.MaxRequestBodySize (30 000 000 octets) établie lors de la configuration de Kestrel par CreateDefaultBuilder :
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureKestrel((context, options) =>
    {
        options.Limits.MaxRequestBodySize = 20000000;
    });
```

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

Remarque

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.

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 comme UseContentRoot et UseConfiguration (consultez la section Remplacer 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)

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.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Racine de contenu

Ce paramètre détermine l’emplacement où ASP.NET Core commence la recherche des fichiers de contenu.

La racine de contenu est également utilisée comme chemin de base pour la racine web. Si le chemin de la racine de contenu est introuvable, l’hôte ne peut pas démarrer.

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

Pour en savoir plus, consultez :

Erreurs détaillées

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

Clé : detailedErrors
Type : bool (true ou 1)
Valeur par défaut : false
Définition avec : UseSetting
La 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")

Environment

Définit l’environnement de l’application.

Clé : environment
Type : string
Valeur par défaut : Production
Définition avec : UseEnvironment
La variable d’environnement: ASPNETCORE_ENVIRONMENT

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.

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

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

Port HTTPS

Définissez le port de redirection HTTPS. Utilisé dans l’application de HTTPS.

Clé : https_port
Type : string
Par défaut : Aucune valeur par défaut n’est définie.
Définition avec : UseSetting
La variable d’environnement: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "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.

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.

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

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

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 : string
Par défaut : http://localhost:5000
Définition avec : UseUrls
La variable d’environnement: ASPNETCORE_URLS

WebHost.CreateDefaultBuilder(args)
    .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 serveur Kestrelweb dans ASP.NET Core.

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éfinition avec : UseShutdownTimeout
La 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.

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

Assembly de démarrage

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

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.

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

Pour en savoir plus, consultez :

Remplacer la configuration

La configuration fournie par UseUrls est d’abord remplacée par la configuration du fichier hostsettings.json et ensuite par la configuration des arguments de ligne de commande :

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

Remarque

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();
}

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();
}

Start(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	Response
`http://localhost:5000/hello/Martin`	Hello, 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`	Hello World!

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();
}

StartWith(string url, Action<IApplicationBuilder> app)

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

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

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

Remarque

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

IWebHostEnvironment peut être injecté dans la méthode Invoke lors de la création d’un intergiciel (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

Jeton d’annulation	Déclenché quand...
`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
    }
}

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 Développement.

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.

Pour toujours valider les étendues, notamment dans l’environnement de production, configurez ServiceProviderOptions avec UseDefaultServiceProvider sur le créateur d’hôte :

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

Partager via

Hôte web ASP.NET Core

Configurer un hôte

Valeurs de configuration de l’hôte

Clé d’application (Nom)

Capture des erreurs de démarrage

Racine de contenu

Erreurs détaillées

Environment

Assemblys d’hébergement au démarrage

Port HTTPS

Ports HTTPS

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

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

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

URL du serveur

Délai d’arrêt

Assembly de démarrage

Racine web

Remplacer la configuration

Gérer l’hôte

Interface IWebHostEnvironment

Interface IHostApplicationLifetime

Validation de l’étendue

Ressources supplémentaires

Configurer un hôte

Valeurs de configuration de l’hôte

Clé d’application (Nom)

Capture des erreurs de démarrage

Racine de contenu

Erreurs détaillées

Environment

Assemblys d’hébergement au démarrage

Port HTTPS

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

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

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

URL du serveur

Délai d’arrêt

Assembly de démarrage

Racine web

Remplacer la configuration

Gérer l’hôte

Interface IWebHostEnvironment

Interface IHostApplicationLifetime

Validation de l’étendue

Ressources supplémentaires

Configurer un hôte

Valeurs de configuration de l’hôte

Clé d’application (Nom)

Capture des erreurs de démarrage

Racine de contenu

Erreurs détaillées

Environment

Assemblys d’hébergement au démarrage

Port HTTPS

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

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

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

URL du serveur

Délai d’arrêt

Assembly de démarrage

Racine web

Remplacer la configuration

Gérer l’hôte

Interface IWebHostEnvironment

Interface IHostApplicationLifetime

Validation de l’étendue

Ressources supplémentaires

Ressources supplémentaires