Hôte web ASP.NET Core
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
- Variables d’environnement comportant le préfixe
- 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
ouappsettings.{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’appelConfigureAppConfiguration
suivant ajoute un délégué pour inclure la configuration de l’application dans le fichierappsettings.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 deappsettings.Development.json
(LogLevel.Debug
) et deappsettings.Production.json
(LogLevel.Error
) configurés parCreateDefaultBuilder
.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 parCreateDefaultBuilder
: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 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.
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();
}
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.
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
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 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>();
}
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
- Variables d’environnement comportant le préfixe
- 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
ouappsettings.{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’appelConfigureAppConfiguration
suivant ajoute un délégué pour inclure la configuration de l’application dans le fichierappsettings.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 deappsettings.Development.json
(LogLevel.Debug
) et deappsettings.Production.json
(LogLevel.Error
) configurés parCreateDefaultBuilder
.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 parCreateDefaultBuilder
: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 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.
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();
}
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.
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
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 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>();
}
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 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
- Variables d’environnement comportant le préfixe
- 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
ouappsettings.{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’appelConfigureAppConfiguration
suivant ajoute un délégué pour inclure la configuration de l’application dans le fichierappsettings.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 deappsettings.Development.json
(LogLevel.Debug
) et deappsettings.Production.json
(LogLevel.Error
) configurés parCreateDefaultBuilder
.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 parCreateDefaultBuilder
: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 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.
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 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.
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();
}
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.
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;
})