Obecný hostitel .NET v ASP.NET Core
Poznámka:
Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Upozorňující
Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Důležité
Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.
Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Tento článek obsahuje informace o používání obecného hostitele .NET v ASP.NET Core.
Šablony ASP.NET Core vytvářejí WebApplicationBuilder a WebApplicationposkytují zjednodušený způsob konfigurace a spouštění webových aplikací bez Startup
třídy. Další informace o WebApplicationBuilder
migraci z ASP.NET Core 5.0 na verzi 6.0 najdete WebApplication
v tématu Migrace z ASP.NET Core 5.0 na verzi 6.0.
Informace o použití obecného hostitele .NET v konzolových aplikacích naleznete v tématu .NET Generic Host.
Definice hostitele
Hostitel je objekt, který zapouzdřuje prostředky aplikace, například:
- Injektáž závislostí (DI)
- Protokolování
- Konfigurace
IHostedService
implementace
Když se hostitel spustí, volá IHostedService.StartAsync každou implementaci zaregistrované IHostedService v kolekci hostovaných služeb kontejneru služby. Jednou z IHostedService
implementací webové aplikace je webová služba, která spouští implementaci serveru HTTP.
Zahrnutí všech vzájemně závislých prostředků aplikace v jednom objektu umožňuje kontrolu nad spuštěním a řádném vypnutím aplikace.
Nastavení hostitele
Hostitel je obvykle nakonfigurovaný, sestavený a spouštěný kódem v souboru Program.cs
. Následující kód vytvoří hostitele s implementací přidanou IHostedService
do kontejneru DI:
await Host.CreateDefaultBuilder(args)
.ConfigureServices(services =>
{
services.AddHostedService<SampleHostedService>();
})
.Build()
.RunAsync();
Pro úlohu HTTP volejte ConfigureWebHostDefaults za CreateDefaultBuilder:
await Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
})
.Build()
.RunAsync();
Výchozí nastavení tvůrce
Metoda CreateDefaultBuilder:
- Nastaví kořen obsahu na cestu vrácenou .GetCurrentDirectory
- Načte konfiguraci hostitele z:
- Proměnné prostředí s předponou
DOTNET_
. - Argumenty příkazového řádku
- Proměnné prostředí s předponou
- Načte konfiguraci aplikace z:
appsettings.json
.appsettings.{Environment}.json
.- Tajné kódy uživatelů, když aplikace běží v prostředí
Development
. - Proměnné prostředí.
- Argumenty příkazového řádku
- Přidá následující zprostředkovatele protokolování :
- Konzola
- Ladění
- EventSource
- EventLog (pouze při spuštění ve Windows)
- Povolí ověřování oboru a ověřování závislostí při vývoji prostředí.
Metoda ConfigureWebHostDefaults:
- Načte konfiguraci hostitele z proměnných prostředí s předponou
ASPNETCORE_
. - Nastaví Kestrel server jako webový server a nakonfiguruje ho pomocí poskytovatelů konfigurace hostingu aplikace. Kestrel Výchozí možnosti serveru najdete v tématu Konfigurace možností webového serveru ASP.NET CoreKestrel.
- Přidá middleware filtrování hostitelů.
- Přidá middleware forwarded Headers if
ASPNETCORE_FORWARDEDHEADERS_ENABLED
equalstrue
. - Povolí integraci služby IIS. Výchozí možnosti služby IIS najdete v tématu Hostitel ASP.NET Core ve Windows se službou IIS.
Části Nastavení pro všechny typy aplikací a Nastavení webových aplikací dále v tomto článku ukazují, jak přepsat výchozí nastavení tvůrce.
Služby poskytované architekturou
Následující služby se registrují automaticky:
Další informace o službách poskytovaných architekturou najdete v tématu Injektáž závislostí v ASP.NET Core.
IHostApplicationLifetime
IHostApplicationLifetime Vložte službu (dříveIApplicationLifetime
) do jakékoli třídy pro zpracování úloh po spuštění a řádném vypnutí. Tři vlastnosti rozhraní jsou tokeny zrušení používané k registraci metod spuštění aplikace a zastavení aplikace obslužné rutiny událostí. Rozhraní také obsahuje metodu StopApplication
, která umožňuje aplikacím požadovat řádné vypnutí.
Při provádění řádného vypnutí hostitel:
- Aktivuje obslužné rutiny ApplicationStopping událostí, které aplikaci umožní spustit logiku před zahájením procesu vypnutí.
- Zastaví server, který zakáže nová připojení. Server čeká na dokončení požadavků na stávající připojení, dokud časový limit vypnutí umožňuje. Server odešle hlavičku uzavření připojení pro další žádosti o stávající připojení.
- Aktivuje obslužné rutiny ApplicationStopped událostí, které aplikaci umožní spustit logiku po vypnutí aplikace.
Následující příklad je IHostedService
implementace, která registruje obslužné rutiny IHostApplicationLifetime
událostí:
public class HostApplicationLifetimeEventsHostedService : IHostedService
{
private readonly IHostApplicationLifetime _hostApplicationLifetime;
public HostApplicationLifetimeEventsHostedService(
IHostApplicationLifetime hostApplicationLifetime)
=> _hostApplicationLifetime = hostApplicationLifetime;
public Task StartAsync(CancellationToken cancellationToken)
{
_hostApplicationLifetime.ApplicationStarted.Register(OnStarted);
_hostApplicationLifetime.ApplicationStopping.Register(OnStopping);
_hostApplicationLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
=> Task.CompletedTask;
private void OnStarted()
{
// ...
}
private void OnStopping()
{
// ...
}
private void OnStopped()
{
// ...
}
}
IHostLifetime
Implementace IHostLifetime řídí, kdy se hostitel spustí a kdy se zastaví. Použije se poslední zaregistrovaná implementace.
Microsoft.Extensions.Hosting.Internal.ConsoleLifetime
je výchozí IHostLifetime
implementace. ConsoleLifetime
:
- Naslouchá ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM a volání StopApplication pro spuštění procesu vypnutí.
- Odblokuje rozšíření, jako je RunAsync a WaitForShutdownAsync.
IHostEnvironment
IHostEnvironment Vložte službu do třídy, abyste získali informace o následujících nastaveních:
Webové aplikace implementují IWebHostEnvironment
rozhraní, které dědí IHostEnvironment
a přidává WebRootPath.
Konfigurace hostitele
Konfigurace hostitele se používá pro vlastnosti IHostEnvironment implementace.
Konfigurace hostitele je k dispozici uvnitř HostBuilderContext.Configuration ConfigureAppConfiguration. HostBuilderContext.Configuration
Po ConfigureAppConfiguration
nahrazení konfigurace aplikace.
Chcete-li přidat konfiguraci hostitele, zavolejte ConfigureHostConfiguration IHostBuilder
. ConfigureHostConfiguration
lze volat vícekrát s doplňkovými výsledky. Hostitel používá jakoukoli možnost, která nastaví hodnotu poslední pro daný klíč.
Zprostředkovatel proměnné prostředí s předponou DOTNET_
a argumenty příkazového řádku jsou součástí CreateDefaultBuilder
. U webových aplikací se přidá zprostředkovatel proměnných prostředí s předponou ASPNETCORE_
. Předpona se odebere při čtení proměnných prostředí. Například hodnota proměnné prostředí pro ASPNETCORE_ENVIRONMENT
se stane hodnotou konfigurace hostitele pro environment
klíč.
Následující příklad vytvoří konfiguraci hostitele:
Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(hostConfig =>
{
hostConfig.SetBasePath(Directory.GetCurrentDirectory());
hostConfig.AddJsonFile("hostsettings.json", optional: true);
hostConfig.AddEnvironmentVariables(prefix: "PREFIX_");
hostConfig.AddCommandLine(args);
});
Konfigurace aplikace
Konfigurace aplikace se vytvoří voláním ConfigureAppConfiguration IHostBuilder
. ConfigureAppConfiguration
lze volat vícekrát s doplňkovými výsledky. Aplikace používá jakoukoli možnost, která nastaví hodnotu poslední pro daný klíč.
Konfigurace vytvořená službou ConfigureAppConfiguration
je k dispozici HostBuilderContext.Configuration pro následné operace a jako služba z DI. Do konfigurace aplikace se přidá také konfigurace hostitele.
Další informace najdete v tématu Konfigurace v ASP.NET Core.
Nastavení pro všechny typy aplikací
Tato část obsahuje seznam nastavení hostitele, která platí pro úlohy HTTP i jiné úlohy než HTTP. Ve výchozím nastavení můžou mít proměnné prostředí použité ke konfiguraci těchto nastavení předponu DOTNET_
nebo ASPNETCORE_
předponu, která se zobrazí v následujícím seznamu nastavení jako {PREFIX_}
zástupný symbol. Další informace najdete v části Výchozí nastavení tvůrce a Konfigurace: Proměnné prostředí.
NázevAplikace
Vlastnost je nastavena IHostEnvironment.ApplicationName z konfigurace hostitele během vytváření hostitelů.
Klíč: applicationName
Typ: string
Výchozí hodnota: Název sestavení, které obsahuje vstupní bod aplikace.
Proměnná prostředí: {PREFIX_}APPLICATIONNAME
K nastavení této hodnoty použijte proměnnou prostředí.
ContentRoot
Vlastnost IHostEnvironment.ContentRootPath určuje, kde hostitel začne hledat soubory obsahu. Pokud cesta neexistuje, hostitel se nespustí.
Klíč: contentRoot
Typ: string
Výchozí hodnota: Složka, ve které se nachází sestavení aplikace.
Proměnná prostředí: {PREFIX_}CONTENTROOT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseContentRoot
IHostBuilder
:
Host.CreateDefaultBuilder(args)
.UseContentRoot("/path/to/content/root")
// ...
Další informace naleznete v tématu:
EnvironmentName
Vlastnost IHostEnvironment.EnvironmentName lze nastavit na libovolnou hodnotu. Hodnoty definované architekturou zahrnují Development
, Staging
a Production
. U hodnot se nerozlišuje malá a velká písmena.
Klíč: environment
Typ: string
Výchozí hodnota: Production
Proměnná prostředí: {PREFIX_}ENVIRONMENT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseEnvironment
IHostBuilder
:
Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
// ...
Čas vypnutí
HostOptions.ShutdownTimeout nastaví časový limit pro StopAsync. Výchozí hodnota je 30 sekund. Během časového limitu hostitel:
- Aktivační události IHostApplicationLifetime.ApplicationStopping.
- Pokusí se zastavit hostované služby a protokolovat chyby služeb, které se nepodaří zastavit.
Pokud vyprší časový limit před zastavením všech hostovaných služeb, všechny zbývající aktivní služby se zastaví, když se aplikace vypne. Služby se zastaví i v případě, že nedokončily zpracování. Pokud služby vyžadují k zastavení více času, zvyšte časový limit.
Klíč: shutdownTimeoutSeconds
Typ: int
Výchozí hodnota: 30 sekund
Proměnná prostředí: {PREFIX_}SHUTDOWNTIMEOUTSECONDS
K nastavení této hodnoty použijte proměnnou prostředí nebo nakonfigurujte HostOptions
. Následující příklad nastaví časový limit na 20 sekund:
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(options =>
{
options.ShutdownTimeout = TimeSpan.FromSeconds(20);
});
});
Zakázání opětovného načtení konfigurace aplikace při změně
Ve výchozím nastavení appsettings.json
se appsettings.{Environment}.json
při změně souboru znovu načte. Pokud chcete toto chování opětovného hostBuilder:reloadConfigOnChange
načítání zakázat v ASP.NET Core 5.0 nebo novějším, nastavte klíč na false
.
Klíč: hostBuilder:reloadConfigOnChange
Typ: bool
(true
nebo false
)
Výchozí hodnota: true
Argument příkazového řádku: hostBuilder:reloadConfigOnChange
Proměnná prostředí: {PREFIX_}hostBuilder:reloadConfigOnChange
Upozorňující
Oddělovač dvojtečky (:
) nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Další informace naleznete v tématu Proměnné prostředí.
Nastavení pro webové aplikace
Některá nastavení hostitele platí jenom pro úlohy HTTP. Ve výchozím nastavení můžou mít proměnné prostředí použité ke konfiguraci těchto nastavení předponu DOTNET_
nebo ASPNETCORE_
předponu, která se zobrazí v následujícím seznamu nastavení jako {PREFIX_}
zástupný symbol.
Pro tato nastavení jsou k dispozici metody IWebHostBuilder
rozšíření. Ukázky kódu, které ukazují, jak volat metody rozšíření předpokládá webBuilder
je instance IWebHostBuilder
, jako v následujícím příkladu:
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
// ...
});
CaptureStartupErrors
Pokud false
dojde k chybám při spuštění, dojde k ukončení hostitele. Když true
hostitel zaznamená výjimky při spuštění a pokusí se spustit server.
Klíč: captureStartupErrors
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: Výchozí hodnota platí, false
pokud aplikace neběží se Kestrel službou IIS, kde výchozí hodnota je true
.
Proměnná prostředí: {PREFIX_}CAPTURESTARTUPERRORS
K nastavení této hodnoty použijte konfiguraci nebo volání CaptureStartupErrors
:
webBuilder.CaptureStartupErrors(true);
Podrobné chyby
Když je prostředí povolené nebo když je Development
prostředí, aplikace zaznamenává podrobné chyby.
Klíč: detailedErrors
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}DETAILEDERRORS
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");
HostingStartupAssemblies
Středník oddělený řetězec hostování spouštěcích sestavení, která se mají načíst při spuštění. I když se hodnota konfigurace ve výchozím nastavení nastaví na prázdný řetězec, hostitelské spouštěcí sestavení vždy obsahují sestavení aplikace. Při hostování spouštěcích sestavení se přidají do sestavení aplikace pro načtení, když aplikace během spouštění sestaví své běžné služby.
Klíč: hostingStartupAssemblies
Typ: string
Výchozí: Prázdný řetězec
Proměnná prostředí: {PREFIX_}HOSTINGSTARTUPASSEMBLIES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(
WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");
HostingStartupExcludeAssemblies
Středník oddělený řetězec hostování spouštěcích sestavení, která se mají vyloučit při spuštění.
Klíč: hostingStartupExcludeAssemblies
Typ: string
Výchozí: Prázdný řetězec
Proměnná prostředí: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(
WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");
HTTPS_Port
Nastavte port HTTPS tak, aby se přesměrovává, pokud se zobrazí připojení jiného typu než HTTPS. Používá se při vynucování HTTPS. Toto nastavení nezpůsobí, že server naslouchá na zadaném portu. To znamená, že je možné omylem přesměrovat požadavky na nepoužívaný port.
Klíč: https_port
Typ: string
Výchozí hodnota: Výchozí hodnota není nastavená.
Proměnná prostředí: {PREFIX_}HTTPS_PORT
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting("https_port", "8080");
HTTPS_Ports
Porty, na které se mají naslouchat připojení HTTPS.
Klíč: https_ports
Typ: string
Výchozí hodnota: Výchozí hodnota není nastavená.
Proměnná prostředí: {PREFIX_}HTTPS_PORTS
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting("https_ports", "8080");
PreferHostingUrls
Určuje, jestli má hostitel naslouchat adresám URL nakonfigurovaným IWebHostBuilder
namísto těchto adres URL nakonfigurovaných s implementací IServer
.
Klíč: preferHostingUrls
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}PREFERHOSTINGURLS
K nastavení této hodnoty použijte proměnnou prostředí nebo volání PreferHostingUrls
:
webBuilder.PreferHostingUrls(true);
PreventHostingStartup
Zabraňuje automatickému načítání hostitelských spouštěcích sestavení, včetně hostování spouštěcích sestavení nakonfigurovaných sestavením aplikace. Další informace viz Použití hostujících spouštěcích sestavení v ASP.NET Core.
Klíč: preventHostingStartup
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}PREVENTHOSTINGSTARTUP
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");
StartupAssembly
Sestavení, které má vyhledat Startup
třídu.
Klíč: startupAssembly
Typ: string
Výchozí: Sestavení aplikace
Proměnná prostředí: {PREFIX_}STARTUPASSEMBLY
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseStartup
. UseStartup
může převzít název sestavení (string
) nebo typ (TStartup
). Pokud se volá více UseStartup
metod, má přednost poslední metoda.
webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();
SuppressStatusMessages
Pokud je tato možnost povolená, potlačí hostování stavových zpráv při spuštění.
Klíč: suppressStatusMessages
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}SUPPRESSSTATUSMESSAGES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");
Adresy URL
Seznam IP adres nebo hostitelských adres oddělených středníkem s porty a protokoly, na kterých má server naslouchat žádostem. Například http://localhost:123
. Pomocí *označte, že server by měl naslouchat žádostem na libovolné IP adrese nebo názvu hostitele pomocí zadaného portu a protokolu (například http://*:5000
). Protokol (http://
nebo https://
) musí být součástí každé adresy URL. Podporované formáty se mezi servery liší.
Klíč: urls
Typ: string
Výchozí hodnota: http://localhost:5000
a https://localhost:5001
Proměnná prostředí: {PREFIX_}URLS
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseUrls
:
webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");
Kestrel má vlastní rozhraní API konfigurace koncového bodu. Další informace najdete v tématu Konfigurace koncových bodů pro webový server ASP.NET CoreKestrel.
WebRoot
Vlastnost IWebHostEnvironment.WebRootPath určuje relativní cestu ke statickým prostředkům aplikace. Pokud cesta neexistuje, použije se zprostředkovatel souboru no-op.
Klíč: webroot
Typ: string
Výchozí hodnota: Výchozí hodnota je wwwroot
. Cesta k adresáři {content root}/wwwroot musí existovat.
Proměnná prostředí: {PREFIX_}WEBROOT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseWebRoot
IWebHostBuilder
:
webBuilder.UseWebRoot("public");
Další informace naleznete v tématu:
Správa doby života hostitele
Volání metod v vytvořené IHost implementaci pro spuštění a zastavení aplikace Tyto metody ovlivňují všechny IHostedService implementace zaregistrované v kontejneru služby.
Rozdíl mezi Run*
metodami Start*
spočívá v tom, že Run*
metody čekají na dokončení hostitele před vrácením, zatímco Start*
metody se vrátí okamžitě. Metody Run*
se obvykle používají v konzolových aplikacích, zatímco Start*
metody se obvykle používají v dlouhotrvajících službách.
Spustit
Run spustí aplikaci a zablokuje volající vlákno, dokud se hostitel nevypíná.
RunAsync
RunAsync spustí aplikaci a vrátí Task , která se dokončí při aktivaci tokenu zrušení nebo vypnutí.
RunConsoleAsync
RunConsoleAsyncumožňuje podporu konzoly, sestavení a spuštění hostitele a čeká na vypnutí ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM.
Spustit
Start spustí hostitele synchronně.
StartAsync
StartAsync spustí hostitele a vrátí Task , který se dokončí při aktivaci tokenu zrušení nebo vypnutí.
WaitForStartAsync je volána na začátku StartAsync
, který čeká na dokončení před pokračováním. Tuto metodu lze použít ke zpoždění spouštění, dokud není signalizovat externí událostí.
StopAsync
StopAsync pokusí zastavit hostitele v zadaném časovém limitu.
WaitForShutdown
WaitForShutdownblokuje volající vlákno, dokud se neaktivuje IHostLifetime, například pomocí Ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM.
WaitForShutdownAsync
WaitForShutdownAsyncTask vrátí hodnotu, která se dokončí při vypnutí prostřednictvím daného tokenu a volání StopAsync.
Šablony ASP.NET Core vytvářejí obecného hostitele .NET Core (HostBuilder).
Tento článek obsahuje informace o používání obecného hostitele .NET v ASP.NET Core. Informace o používání obecného hostitele .NET v konzolových aplikacích naleznete v tématu .NET Generic Host.
Definice hostitele
Hostitel je objekt, který zapouzdřuje prostředky aplikace, například:
- Injektáž závislostí (DI)
- Protokolování
- Konfigurace
IHostedService
implementace
Když se hostitel spustí, volá IHostedService.StartAsync každou implementaci zaregistrované IHostedService v kolekci hostovaných služeb kontejneru služby. Jednou z IHostedService
implementací webové aplikace je webová služba, která spouští implementaci serveru HTTP.
Hlavním důvodem zahrnutí všech vzájemně závislých prostředků aplikace v jednom objektu je správa životnosti: kontrola nad spuštěním aplikace a řádné vypnutí.
Nastavení hostitele
Hostitel je obvykle nakonfigurovaný, sestavený a spouštěný kódem ve Program
třídě. Metoda Main
:
- Volá metodu
CreateHostBuilder
pro vytvoření a konfiguraci objektu tvůrce. - Volání
Build
aRun
metody objektu tvůrce
Webové šablony ASP.NET Core generují následující kód pro vytvoření hostitele:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
Následující kód vytvoří úlohu bez HTTP s implementací přidanou IHostedService
do kontejneru DI.
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.AddHostedService<Worker>();
});
}
U úlohy HTTP je metoda stejná, Main
ale CreateHostBuilder
volá ConfigureWebHostDefaults
:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
Pokud aplikace používá Entity Framework Core, nezměníte název ani podpis CreateHostBuilder
metody. Nástroje Entity Framework Core očekávají, že najdou metoduCreateHostBuilder
, která nakonfiguruje hostitele bez spuštění aplikace. Další informace naleznete v tématu Vytvoření DbContext v době návrhu.
Výchozí nastavení tvůrce
Metoda CreateDefaultBuilder:
- Nastaví kořen obsahu na cestu vrácenou .GetCurrentDirectory
- Načte konfiguraci hostitele z:
- Proměnné prostředí s předponou
DOTNET_
. - Argumenty příkazového řádku
- Proměnné prostředí s předponou
- Načte konfiguraci aplikace z:
appsettings.json
.appsettings.{Environment}.json
.- Tajné kódy uživatelů, když aplikace běží v prostředí
Development
. - Proměnné prostředí.
- Argumenty příkazového řádku
- Přidá následující zprostředkovatele protokolování :
- Konzola
- Ladění
- EventSource
- EventLog (pouze při spuštění ve Windows)
- Povolí ověřování oboru a ověřování závislostí při vývoji prostředí.
Metoda ConfigureWebHostDefaults:
- Načte konfiguraci hostitele z proměnných prostředí s předponou
ASPNETCORE_
. - Nastaví Kestrel server jako webový server a nakonfiguruje ho pomocí poskytovatelů konfigurace hostingu aplikace. Kestrel Výchozí možnosti serveru najdete v tématu Konfigurace možností webového serveru ASP.NET CoreKestrel.
- Přidá middleware filtrování hostitelů.
- Přidá middleware forwarded Headers if
ASPNETCORE_FORWARDEDHEADERS_ENABLED
equalstrue
. - Povolí integraci služby IIS. Výchozí možnosti služby IIS najdete v tématu Hostitel ASP.NET Core ve Windows se službou IIS.
Části Nastavení pro všechny typy aplikací a Nastavení webových aplikací dále v tomto článku ukazují, jak přepsat výchozí nastavení tvůrce.
Služby poskytované architekturou
Následující služby se registrují automaticky:
Další informace o službách poskytovaných architekturou najdete v tématu Injektáž závislostí v ASP.NET Core.
IHostApplicationLifetime
IHostApplicationLifetime Vložte službu (dříveIApplicationLifetime
) do jakékoli třídy pro zpracování úloh po spuštění a řádném vypnutí. Tři vlastnosti rozhraní jsou tokeny zrušení používané k registraci metod spuštění aplikace a zastavení aplikace obslužné rutiny událostí. Rozhraní také obsahuje metodu StopApplication
.
Následující příklad je IHostedService
implementace, která registruje IHostApplicationLifetime
události:
internal class LifetimeEventsHostedService : IHostedService
{
private readonly ILogger _logger;
private readonly IHostApplicationLifetime _appLifetime;
public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger,
IHostApplicationLifetime appLifetime)
{
_logger = logger;
_appLifetime = appLifetime;
}
public Task StartAsync(CancellationToken cancellationToken)
{
_appLifetime.ApplicationStarted.Register(OnStarted);
_appLifetime.ApplicationStopping.Register(OnStopping);
_appLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
{
return Task.CompletedTask;
}
private void OnStarted()
{
_logger.LogInformation("OnStarted has been called.");
// Perform post-startup activities here
}
private void OnStopping()
{
_logger.LogInformation("OnStopping has been called.");
// Perform on-stopping activities here
}
private void OnStopped()
{
_logger.LogInformation("OnStopped has been called.");
// Perform post-stopped activities here
}
}
IHostLifetime
Implementace IHostLifetime řídí, kdy se hostitel spustí a kdy se zastaví. Použije se poslední zaregistrovaná implementace.
Microsoft.Extensions.Hosting.Internal.ConsoleLifetime
je výchozí IHostLifetime
implementace. ConsoleLifetime
:
- Naslouchá ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM a volání StopApplication pro spuštění procesu vypnutí.
- Odblokuje rozšíření, jako je RunAsync a WaitForShutdownAsync.
IHostEnvironment
IHostEnvironment Vložte službu do třídy, abyste získali informace o následujících nastaveních:
Webové aplikace implementují IWebHostEnvironment
rozhraní, které dědí IHostEnvironment
a přidává WebRootPath.
Konfigurace hostitele
Konfigurace hostitele se používá pro vlastnosti IHostEnvironment implementace.
Konfigurace hostitele je k dispozici uvnitř HostBuilderContext.Configuration ConfigureAppConfiguration. HostBuilderContext.Configuration
Po ConfigureAppConfiguration
nahrazení konfigurace aplikace.
Chcete-li přidat konfiguraci hostitele, zavolejte ConfigureHostConfiguration IHostBuilder
. ConfigureHostConfiguration
lze volat vícekrát s doplňkovými výsledky. Hostitel používá jakoukoli možnost, která nastaví hodnotu poslední pro daný klíč.
Zprostředkovatel proměnné prostředí s předponou DOTNET_
a argumenty příkazového řádku jsou součástí CreateDefaultBuilder
. U webových aplikací se přidá zprostředkovatel proměnných prostředí s předponou ASPNETCORE_
. Předpona se odebere při čtení proměnných prostředí. Například hodnota proměnné prostředí pro ASPNETCORE_ENVIRONMENT
se stane hodnotou konfigurace hostitele pro environment
klíč.
Následující příklad vytvoří konfiguraci hostitele:
// using Microsoft.Extensions.Configuration;
Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
});
Konfigurace aplikace
Konfigurace aplikace se vytvoří voláním ConfigureAppConfiguration IHostBuilder
. ConfigureAppConfiguration
lze volat vícekrát s doplňkovými výsledky. Aplikace používá jakoukoli možnost, která nastaví hodnotu poslední pro daný klíč.
Konfigurace vytvořená službou ConfigureAppConfiguration
je k dispozici HostBuilderContext.Configuration pro následné operace a jako služba z DI. Do konfigurace aplikace se přidá také konfigurace hostitele.
Další informace najdete v tématu Konfigurace v ASP.NET Core.
Nastavení pro všechny typy aplikací
Tato část obsahuje seznam nastavení hostitele, která platí pro úlohy HTTP i jiné úlohy než HTTP. Ve výchozím nastavení můžou mít proměnné prostředí použité ke konfiguraci těchto nastavení předponu DOTNET_
nebo ASPNETCORE_
předponu, která se zobrazí v následujícím seznamu nastavení jako {PREFIX_}
zástupný symbol. Další informace najdete v části Výchozí nastavení tvůrce a Konfigurace: Proměnné prostředí.
NázevAplikace
Vlastnost je nastavena IHostEnvironment.ApplicationName z konfigurace hostitele během vytváření hostitelů.
Klíč: applicationName
Typ: string
Výchozí hodnota: Název sestavení, které obsahuje vstupní bod aplikace.
Proměnná prostředí: {PREFIX_}APPLICATIONNAME
K nastavení této hodnoty použijte proměnnou prostředí.
ContentRoot
Vlastnost IHostEnvironment.ContentRootPath určuje, kde hostitel začne hledat soubory obsahu. Pokud cesta neexistuje, hostitel se nespustí.
Klíč: contentRoot
Typ: string
Výchozí hodnota: Složka, ve které se nachází sestavení aplikace.
Proměnná prostředí: {PREFIX_}CONTENTROOT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseContentRoot
IHostBuilder
:
Host.CreateDefaultBuilder(args)
.UseContentRoot("c:\\content-root")
//...
Další informace naleznete v tématu:
EnvironmentName
Vlastnost IHostEnvironment.EnvironmentName lze nastavit na libovolnou hodnotu. Hodnoty definované architekturou zahrnují Development
, Staging
a Production
. U hodnot se nerozlišuje malá a velká písmena.
Klíč: environment
Typ: string
Výchozí hodnota: Production
Proměnná prostředí: {PREFIX_}ENVIRONMENT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseEnvironment
IHostBuilder
:
Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
//...
Čas vypnutí
HostOptions.ShutdownTimeout nastaví časový limit pro StopAsync. Výchozí hodnota je pět sekund. Během časového limitu hostitel:
- Aktivační události IHostApplicationLifetime.ApplicationStopping.
- Pokusí se zastavit hostované služby a protokolovat chyby služeb, které se nepodaří zastavit.
Pokud vyprší časový limit před zastavením všech hostovaných služeb, všechny zbývající aktivní služby se zastaví, když se aplikace vypne. Služby se zastaví i v případě, že nedokončily zpracování. Pokud služby vyžadují k zastavení více času, zvyšte časový limit.
Klíč: shutdownTimeoutSeconds
Typ: int
Výchozí hodnota: 5 sekund
Proměnná prostředí: {PREFIX_}SHUTDOWNTIMEOUTSECONDS
K nastavení této hodnoty použijte proměnnou prostředí nebo nakonfigurujte HostOptions
. Následující příklad nastaví časový limit na 20 sekund:
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(option =>
{
option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
});
});
Zakázání opětovného načtení konfigurace aplikace při změně
Ve výchozím nastavení appsettings.json
se appsettings.{Environment}.json
při změně souboru znovu načte. Pokud chcete toto chování opětovného hostBuilder:reloadConfigOnChange
načítání zakázat v ASP.NET Core 5.0 nebo novějším, nastavte klíč na false
.
Klíč: hostBuilder:reloadConfigOnChange
Typ: bool
(true
nebo false
)
Výchozí hodnota: true
Argument příkazového řádku: hostBuilder:reloadConfigOnChange
Proměnná prostředí: {PREFIX_}hostBuilder:reloadConfigOnChange
Upozorňující
Oddělovač dvojtečky (:
) nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Další informace naleznete v tématu Proměnné prostředí.
Nastavení pro webové aplikace
Některá nastavení hostitele platí jenom pro úlohy HTTP. Ve výchozím nastavení můžou mít proměnné prostředí použité ke konfiguraci těchto nastavení předponu DOTNET_
nebo ASPNETCORE_
předponu, která se zobrazí v následujícím seznamu nastavení jako {PREFIX_}
zástupný symbol.
Pro tato nastavení jsou k dispozici metody IWebHostBuilder
rozšíření. Ukázky kódu, které ukazují, jak volat metody rozšíření předpokládá webBuilder
je instance IWebHostBuilder
, jako v následujícím příkladu:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.CaptureStartupErrors(true);
webBuilder.UseStartup<Startup>();
});
CaptureStartupErrors
Pokud false
dojde k chybám při spuštění, dojde k ukončení hostitele. Když true
hostitel zaznamená výjimky při spuštění a pokusí se spustit server.
Klíč: captureStartupErrors
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: Výchozí hodnota platí, false
pokud aplikace neběží se Kestrel službou IIS, kde výchozí hodnota je true
.
Proměnná prostředí: {PREFIX_}CAPTURESTARTUPERRORS
K nastavení této hodnoty použijte konfiguraci nebo volání CaptureStartupErrors
:
webBuilder.CaptureStartupErrors(true);
Podrobné chyby
Když je prostředí povolené nebo když je Development
prostředí, aplikace zaznamenává podrobné chyby.
Klíč: detailedErrors
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}DETAILEDERRORS
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");
HostingStartupAssemblies
Středník oddělený řetězec hostování spouštěcích sestavení, která se mají načíst při spuštění. I když se hodnota konfigurace ve výchozím nastavení nastaví na prázdný řetězec, hostitelské spouštěcí sestavení vždy obsahují sestavení aplikace. Při hostování spouštěcích sestavení se přidají do sestavení aplikace pro načtení, když aplikace během spouštění sestaví své běžné služby.
Klíč: hostingStartupAssemblies
Typ: string
Výchozí: Prázdný řetězec
Proměnná prostředí: {PREFIX_}HOSTINGSTARTUPASSEMBLIES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");
HostingStartupExcludeAssemblies
Středník oddělený řetězec hostování spouštěcích sestavení, která se mají vyloučit při spuštění.
Klíč: hostingStartupExcludeAssemblies
Typ: string
Výchozí: Prázdný řetězec
Proměnná prostředí: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");
HTTPS_Port
Port pro přesměrování HTTPS. Používá se při vynucování HTTPS.
Klíč: https_port
Typ: string
Výchozí hodnota: Výchozí hodnota není nastavená.
Proměnná prostředí: {PREFIX_}HTTPS_PORT
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting("https_port", "8080");
PreferHostingUrls
Určuje, jestli má hostitel naslouchat adresám URL nakonfigurovaným IWebHostBuilder
namísto těchto adres URL nakonfigurovaných s implementací IServer
.
Klíč: preferHostingUrls
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}PREFERHOSTINGURLS
K nastavení této hodnoty použijte proměnnou prostředí nebo volání PreferHostingUrls
:
webBuilder.PreferHostingUrls(true);
PreventHostingStartup
Zabraňuje automatickému načítání hostitelských spouštěcích sestavení, včetně hostování spouštěcích sestavení nakonfigurovaných sestavením aplikace. Další informace viz Použití hostujících spouštěcích sestavení v ASP.NET Core.
Klíč: preventHostingStartup
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}PREVENTHOSTINGSTARTUP
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");
StartupAssembly
Sestavení, které má vyhledat Startup
třídu.
Klíč: startupAssembly
Typ: string
Výchozí: Sestavení aplikace
Proměnná prostředí: {PREFIX_}STARTUPASSEMBLY
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseStartup
. UseStartup
může převzít název sestavení (string
) nebo typ (TStartup
). Pokud se volá více UseStartup
metod, má přednost poslední metoda.
webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();
SuppressStatusMessages
Pokud je tato možnost povolená, potlačí hostování stavových zpráv při spuštění.
Klíč: suppressStatusMessages
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}SUPPRESSSTATUSMESSAGES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");
Adresy URL
Seznam IP adres nebo hostitelských adres oddělených středníkem s porty a protokoly, na kterých má server naslouchat žádostem. Například http://localhost:123
. Pomocí *označte, že server by měl naslouchat žádostem na libovolné IP adrese nebo názvu hostitele pomocí zadaného portu a protokolu (například http://*:5000
). Protokol (http://
nebo https://
) musí být součástí každé adresy URL. Podporované formáty se mezi servery liší.
Klíč: urls
Typ: string
Výchozí hodnota: http://localhost:5000
a https://localhost:5001
Proměnná prostředí: {PREFIX_}URLS
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseUrls
:
webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");
Kestrel má vlastní rozhraní API konfigurace koncového bodu. Další informace najdete v tématu Konfigurace koncových bodů pro webový server ASP.NET CoreKestrel.
WebRoot
Vlastnost IWebHostEnvironment.WebRootPath určuje relativní cestu ke statickým prostředkům aplikace. Pokud cesta neexistuje, použije se zprostředkovatel souboru no-op.
Klíč: webroot
Typ: string
Výchozí hodnota: Výchozí hodnota je wwwroot
. Cesta k adresáři {content root}/wwwroot musí existovat.
Proměnná prostředí: {PREFIX_}WEBROOT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseWebRoot
IWebHostBuilder
:
webBuilder.UseWebRoot("public");
Další informace naleznete v tématu:
Správa doby života hostitele
Volání metod v vytvořené IHost implementaci pro spuštění a zastavení aplikace Tyto metody ovlivňují všechny IHostedService implementace zaregistrované v kontejneru služby.
Rozdíl mezi Run*
metodami Start*
spočívá v tom, že Run*
metody čekají na dokončení hostitele před vrácením, zatímco Start*
metody se vrátí okamžitě. Metody Run*
se obvykle používají v konzolových aplikacích, zatímco Start*
metody se obvykle používají v dlouhotrvajících službách.
Spustit
Run spustí aplikaci a zablokuje volající vlákno, dokud se hostitel nevypíná.
RunAsync
RunAsync spustí aplikaci a vrátí Task , která se dokončí při aktivaci tokenu zrušení nebo vypnutí.
RunConsoleAsync
RunConsoleAsyncumožňuje podporu konzoly, sestavení a spuštění hostitele a čeká na vypnutí ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM.
Spustit
Start spustí hostitele synchronně.
StartAsync
StartAsync spustí hostitele a vrátí Task , který se dokončí při aktivaci tokenu zrušení nebo vypnutí.
WaitForStartAsync je volána na začátku StartAsync
, který čeká na dokončení před pokračováním. Tuto metodu lze použít ke zpoždění spouštění, dokud není signalizovat externí událostí.
StopAsync
StopAsync pokusí zastavit hostitele v zadaném časovém limitu.
WaitForShutdown
WaitForShutdownblokuje volající vlákno, dokud se neaktivuje IHostLifetime, například pomocí Ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM.
WaitForShutdownAsync
WaitForShutdownAsyncTask vrátí hodnotu, která se dokončí při vypnutí prostřednictvím daného tokenu a volání StopAsync.
Externí ovládací prvek
Přímé řízení životnosti hostitele lze dosáhnout pomocí metod, které lze volat externě:
public class Program
{
private IHost _host;
public Program()
{
_host = new HostBuilder()
.Build();
}
public async Task StartAsync()
{
_host.StartAsync();
}
public async Task StopAsync()
{
using (_host)
{
await _host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
Šablony ASP.NET Core vytvářejí obecného hostitele .NET Core (HostBuilder).
Tento článek obsahuje informace o používání obecného hostitele .NET v ASP.NET Core. Informace o používání obecného hostitele .NET v konzolových aplikacích naleznete v tématu .NET Generic Host.
Definice hostitele
Hostitel je objekt, který zapouzdřuje prostředky aplikace, například:
- Injektáž závislostí (DI)
- Protokolování
- Konfigurace
IHostedService
implementace
Když se hostitel spustí, volá IHostedService.StartAsync každou implementaci zaregistrované IHostedService v kolekci hostovaných služeb kontejneru služby. Jednou z IHostedService
implementací webové aplikace je webová služba, která spouští implementaci serveru HTTP.
Hlavním důvodem zahrnutí všech vzájemně závislých prostředků aplikace v jednom objektu je správa životnosti: kontrola nad spuštěním aplikace a řádné vypnutí.
Nastavení hostitele
Hostitel je obvykle nakonfigurovaný, sestavený a spouštěný kódem ve Program
třídě. Metoda Main
:
- Volá metodu
CreateHostBuilder
pro vytvoření a konfiguraci objektu tvůrce. - Volání
Build
aRun
metody objektu tvůrce
Webové šablony ASP.NET Core generují následující kód pro vytvoření obecného hostitele:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
Následující kód vytvoří obecného hostitele pomocí úlohy jiného typu než HTTP. Implementace IHostedService
se přidá do kontejneru DI:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.AddHostedService<Worker>();
});
}
U úlohy HTTP je metoda stejná, Main
ale CreateHostBuilder
volá ConfigureWebHostDefaults
:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
Předchozí kód je generován šablonami ASP.NET Core.
Pokud aplikace používá Entity Framework Core, nezměníte název ani podpis CreateHostBuilder
metody. Nástroje Entity Framework Core očekávají, že najdou metoduCreateHostBuilder
, která nakonfiguruje hostitele bez spuštění aplikace. Další informace naleznete v tématu Vytvoření DbContext v době návrhu.
Výchozí nastavení tvůrce
Metoda CreateDefaultBuilder:
- Nastaví kořen obsahu na cestu vrácenou .GetCurrentDirectory
- Načte konfiguraci hostitele z:
- Proměnné prostředí s předponou
DOTNET_
. - Argumenty příkazového řádku
- Proměnné prostředí s předponou
- Načte konfiguraci aplikace z:
appsettings.json
.appsettings.{Environment}.json
.- Tajné kódy uživatelů, když aplikace běží v prostředí
Development
. - Proměnné prostředí.
- Argumenty příkazového řádku
- Přidá následující zprostředkovatele protokolování :
- Konzola
- Ladění
- EventSource
- EventLog (pouze při spuštění ve Windows)
- Povolí ověřování oboru a ověřování závislostí při vývoji prostředí.
Metoda ConfigureWebHostDefaults
:
- Načte konfiguraci hostitele z proměnných prostředí s předponou
ASPNETCORE_
. - Nastaví Kestrel server jako webový server a nakonfiguruje ho pomocí poskytovatelů konfigurace hostingu aplikace. Kestrel Výchozí možnosti serveru najdete Kestrel na webovém serveru v ASP.NET Core.
- Přidá middleware filtrování hostitelů.
- Přidá middleware forwarded Headers if
ASPNETCORE_FORWARDEDHEADERS_ENABLED
equalstrue
. - Povolí integraci služby IIS. Výchozí možnosti služby IIS najdete v tématu Hostitel ASP.NET Core ve Windows se službou IIS.
Části Nastavení pro všechny typy aplikací a Nastavení webových aplikací dále v tomto článku ukazují, jak přepsat výchozí nastavení tvůrce.
Služby poskytované architekturou
Následující služby se registrují automaticky:
Další informace o službách poskytovaných architekturou najdete v tématu Injektáž závislostí v ASP.NET Core.
IHostApplicationLifetime
IHostApplicationLifetime Vložte službu (dříveIApplicationLifetime
) do jakékoli třídy pro zpracování úloh po spuštění a řádném vypnutí. Tři vlastnosti rozhraní jsou tokeny zrušení používané k registraci metod spuštění aplikace a zastavení aplikace obslužné rutiny událostí. Rozhraní také obsahuje metodu StopApplication
.
Následující příklad je IHostedService
implementace, která registruje IHostApplicationLifetime
události:
internal class LifetimeEventsHostedService : IHostedService
{
private readonly ILogger _logger;
private readonly IHostApplicationLifetime _appLifetime;
public LifetimeEventsHostedService(
ILogger<LifetimeEventsHostedService> logger,
IHostApplicationLifetime appLifetime)
{
_logger = logger;
_appLifetime = appLifetime;
}
public Task StartAsync(CancellationToken cancellationToken)
{
_appLifetime.ApplicationStarted.Register(OnStarted);
_appLifetime.ApplicationStopping.Register(OnStopping);
_appLifetime.ApplicationStopped.Register(OnStopped);
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken)
{
return Task.CompletedTask;
}
private void OnStarted()
{
_logger.LogInformation("OnStarted has been called.");
// Perform post-startup activities here
}
private void OnStopping()
{
_logger.LogInformation("OnStopping has been called.");
// Perform on-stopping activities here
}
private void OnStopped()
{
_logger.LogInformation("OnStopped has been called.");
// Perform post-stopped activities here
}
}
IHostLifetime
Implementace IHostLifetime řídí, kdy se hostitel spustí a kdy se zastaví. Použije se poslední zaregistrovaná implementace.
Microsoft.Extensions.Hosting.Internal.ConsoleLifetime
je výchozí IHostLifetime
implementace. ConsoleLifetime
:
- Naslouchá ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM a volání StopApplication pro spuštění procesu vypnutí.
- Odblokuje rozšíření, jako je RunAsync a WaitForShutdownAsync.
IHostEnvironment
IHostEnvironment Vložte službu do třídy, abyste získali informace o následujících nastaveních:
Webové aplikace implementují IWebHostEnvironment
rozhraní, které dědí IHostEnvironment
a přidává WebRootPath.
Konfigurace hostitele
Konfigurace hostitele se používá pro vlastnosti IHostEnvironment implementace.
Konfigurace hostitele je k dispozici uvnitř HostBuilderContext.Configuration ConfigureAppConfiguration. HostBuilderContext.Configuration
Po ConfigureAppConfiguration
nahrazení konfigurace aplikace.
Chcete-li přidat konfiguraci hostitele, zavolejte ConfigureHostConfiguration IHostBuilder
. ConfigureHostConfiguration
lze volat vícekrát s doplňkovými výsledky. Hostitel používá jakoukoli možnost, která nastaví hodnotu poslední pro daný klíč.
Zprostředkovatel proměnné prostředí s předponou DOTNET_
a argumenty příkazového řádku jsou součástí CreateDefaultBuilder
. U webových aplikací se přidá zprostředkovatel proměnných prostředí s předponou ASPNETCORE_
. Předpona se odebere při čtení proměnných prostředí. Například hodnota proměnné prostředí pro ASPNETCORE_ENVIRONMENT
se stane hodnotou konfigurace hostitele pro environment
klíč.
Následující příklad vytvoří konfiguraci hostitele:
// using Microsoft.Extensions.Configuration;
Host.CreateDefaultBuilder(args)
.ConfigureHostConfiguration(configHost =>
{
configHost.SetBasePath(Directory.GetCurrentDirectory());
configHost.AddJsonFile("hostsettings.json", optional: true);
configHost.AddEnvironmentVariables(prefix: "PREFIX_");
configHost.AddCommandLine(args);
});
Konfigurace aplikace
Konfigurace aplikace se vytvoří voláním ConfigureAppConfiguration IHostBuilder
. ConfigureAppConfiguration
lze volat vícekrát s doplňkovými výsledky. Aplikace používá jakoukoli možnost, která nastaví hodnotu poslední pro daný klíč.
Konfigurace vytvořená službou ConfigureAppConfiguration
je k dispozici HostBuilderContext.Configuration pro následné operace a jako služba z DI. Do konfigurace aplikace se přidá také konfigurace hostitele.
Další informace najdete v tématu Konfigurace v ASP.NET Core.
Nastavení pro všechny typy aplikací
Tato část obsahuje seznam nastavení hostitele, která platí pro úlohy HTTP i jiné úlohy než HTTP. Ve výchozím nastavení můžou mít proměnné prostředí použité ke konfiguraci těchto nastavení předponu DOTNET_
nebo ASPNETCORE_
předponu, které se zobrazí v následující konfiguraci zástupného symbolu {PREFIX_}
.
NázevAplikace
Vlastnost je nastavena IHostEnvironment.ApplicationName z konfigurace hostitele během vytváření hostitelů.
Klíč: applicationName
Typ: string
Výchozí hodnota: Název sestavení, které obsahuje vstupní bod aplikace.
Proměnná prostředí: {PREFIX_}APPLICATIONNAME
K nastavení této hodnoty použijte proměnnou prostředí.
ContentRoot
Vlastnost IHostEnvironment.ContentRootPath určuje, kde hostitel začne hledat soubory obsahu. Pokud cesta neexistuje, hostitel se nespustí.
Klíč: contentRoot
Typ: string
Výchozí hodnota: Složka, ve které se nachází sestavení aplikace.
Proměnná prostředí: {PREFIX_}CONTENTROOT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseContentRoot
IHostBuilder
:
Host.CreateDefaultBuilder(args)
.UseContentRoot("c:\\content-root")
//...
Další informace naleznete v tématu:
EnvironmentName
Vlastnost IHostEnvironment.EnvironmentName lze nastavit na libovolnou hodnotu. Hodnoty definované architekturou zahrnují Development
, Staging
a Production
. U hodnot se nerozlišuje malá a velká písmena.
Klíč: environment
Typ: string
Výchozí hodnota: Production
Proměnná prostředí: {PREFIX_}ENVIRONMENT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseEnvironment
IHostBuilder
:
Host.CreateDefaultBuilder(args)
.UseEnvironment("Development")
//...
Čas vypnutí
HostOptions.ShutdownTimeout nastaví časový limit pro StopAsync. Výchozí hodnota je pět sekund. Během časového limitu hostitel:
- Aktivační události IHostApplicationLifetime.ApplicationStopping.
- Pokusí se zastavit hostované služby a protokolovat chyby služeb, které se nepodaří zastavit.
Pokud vyprší časový limit před zastavením všech hostovaných služeb, všechny zbývající aktivní služby se zastaví, když se aplikace vypne. Služby se zastaví i v případě, že nedokončily zpracování. Pokud služby vyžadují k zastavení více času, zvyšte časový limit.
Klíč: shutdownTimeoutSeconds
Typ: int
Výchozí hodnota: 5 sekund
Proměnná prostředí: {PREFIX_}SHUTDOWNTIMEOUTSECONDS
K nastavení této hodnoty použijte proměnnou prostředí nebo nakonfigurujte HostOptions
. Následující příklad nastaví časový limit na 20 sekund:
Host.CreateDefaultBuilder(args)
.ConfigureServices((hostContext, services) =>
{
services.Configure<HostOptions>(option =>
{
option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
});
});
Nastavení pro webové aplikace
Některá nastavení hostitele platí jenom pro úlohy HTTP. Ve výchozím nastavení můžou mít proměnné prostředí používané ke konfiguraci těchto nastavení předponu nebo ASPNETCORE_
předponuDOTNET_
.
Pro tato nastavení jsou k dispozici metody IWebHostBuilder
rozšíření. Ukázky kódu, které ukazují, jak volat metody rozšíření předpokládá webBuilder
je instance IWebHostBuilder
, jako v následujícím příkladu:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.CaptureStartupErrors(true);
webBuilder.UseStartup<Startup>();
});
CaptureStartupErrors
Pokud false
dojde k chybám při spuštění, dojde k ukončení hostitele. Když true
hostitel zaznamená výjimky při spuštění a pokusí se spustit server.
Klíč: captureStartupErrors
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: Výchozí hodnota platí, false
pokud aplikace neběží se Kestrel službou IIS, kde výchozí hodnota je true
.
Proměnná prostředí: {PREFIX_}CAPTURESTARTUPERRORS
K nastavení této hodnoty použijte konfiguraci nebo volání CaptureStartupErrors
:
webBuilder.CaptureStartupErrors(true);
Podrobné chyby
Když je prostředí povolené nebo když je Development
prostředí, aplikace zaznamenává podrobné chyby.
Klíč: detailedErrors
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}DETAILEDERRORS
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");
HostingStartupAssemblies
Středník oddělený řetězec hostování spouštěcích sestavení, která se mají načíst při spuštění. I když se hodnota konfigurace ve výchozím nastavení nastaví na prázdný řetězec, hostitelské spouštěcí sestavení vždy obsahují sestavení aplikace. Při hostování spouštěcích sestavení se přidají do sestavení aplikace pro načtení, když aplikace během spouštění sestaví své běžné služby.
Klíč: hostingStartupAssemblies
Typ: string
Výchozí: Prázdný řetězec
Proměnná prostředí: {PREFIX_}HOSTINGSTARTUPASSEMBLIES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");
HostingStartupExcludeAssemblies
Středník oddělený řetězec hostování spouštěcích sestavení, která se mají vyloučit při spuštění.
Klíč: hostingStartupExcludeAssemblies
Typ: string
Výchozí: Prázdný řetězec
Proměnná prostředí: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");
HTTPS_Port
Port pro přesměrování HTTPS. Používá se při vynucování HTTPS.
Klíč: https_port
Typ: string
Výchozí hodnota: Výchozí hodnota není nastavená.
Proměnná prostředí: {PREFIX_}HTTPS_PORT
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting("https_port", "8080");
PreferHostingUrls
Určuje, jestli má hostitel naslouchat adresám URL nakonfigurovaným IWebHostBuilder
namísto těchto adres URL nakonfigurovaných s implementací IServer
.
Klíč: preferHostingUrls
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}PREFERHOSTINGURLS
K nastavení této hodnoty použijte proměnnou prostředí nebo volání PreferHostingUrls
:
webBuilder.PreferHostingUrls(true);
PreventHostingStartup
Zabraňuje automatickému načítání hostitelských spouštěcích sestavení, včetně hostování spouštěcích sestavení nakonfigurovaných sestavením aplikace. Další informace viz Použití hostujících spouštěcích sestavení v ASP.NET Core.
Klíč: preventHostingStartup
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}PREVENTHOSTINGSTARTUP
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");
StartupAssembly
Sestavení, které má vyhledat Startup
třídu.
Klíč: startupAssembly
Typ: string
Výchozí: Sestavení aplikace
Proměnná prostředí: {PREFIX_}STARTUPASSEMBLY
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseStartup
. UseStartup
může převzít název sestavení (string
) nebo typ (TStartup
). Pokud se volá více UseStartup
metod, má přednost poslední metoda.
webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();
SuppressStatusMessages
Pokud je tato možnost povolená, potlačí hostování stavových zpráv při spuštění.
Klíč: suppressStatusMessages
Typ: bool
(true
/1
nebo false
/0
)
Výchozí hodnota: false
Proměnná prostředí: {PREFIX_}SUPPRESSSTATUSMESSAGES
K nastavení této hodnoty použijte konfiguraci nebo volání UseSetting
:
webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");
Adresy URL
Seznam IP adres nebo hostitelských adres oddělených středníkem s porty a protokoly, na kterých má server naslouchat žádostem. Například http://localhost:123
. Pomocí *označte, že server by měl naslouchat žádostem na libovolné IP adrese nebo názvu hostitele pomocí zadaného portu a protokolu (například http://*:5000
). Protokol (http://
nebo https://
) musí být součástí každé adresy URL. Podporované formáty se mezi servery liší.
Klíč: urls
Typ: string
Výchozí hodnota: http://localhost:5000
a https://localhost:5001
Proměnná prostředí: {PREFIX_}URLS
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseUrls
:
webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");
Kestrel má vlastní rozhraní API konfigurace koncového bodu. Další informace najdete Kestrel na webovém serveru v ASP.NET Core.
WebRoot
Vlastnost IWebHostEnvironment.WebRootPath určuje relativní cestu ke statickým prostředkům aplikace. Pokud cesta neexistuje, použije se zprostředkovatel souboru no-op.
Klíč: webroot
Typ: string
Výchozí hodnota: Výchozí hodnota je wwwroot
. Cesta k adresáři {content root}/wwwroot musí existovat.
Proměnná prostředí: {PREFIX_}WEBROOT
K nastavení této hodnoty použijte proměnnou prostředí nebo volání UseWebRoot
IWebHostBuilder
:
webBuilder.UseWebRoot("public");
Další informace naleznete v tématu:
Správa doby života hostitele
Volání metod v vytvořené IHost implementaci pro spuštění a zastavení aplikace Tyto metody ovlivňují všechny IHostedService implementace zaregistrované v kontejneru služby.
Rozdíl mezi Run*
metodami Start*
spočívá v tom, že Run*
metody čekají na dokončení hostitele před vrácením, zatímco Start*
metody se vrátí okamžitě. Metody Run*
se obvykle používají v konzolových aplikacích, zatímco Start*
metody se obvykle používají v dlouhotrvajících službách.
Spustit
Run spustí aplikaci a zablokuje volající vlákno, dokud se hostitel nevypíná.
RunAsync
RunAsync spustí aplikaci a vrátí Task , která se dokončí při aktivaci tokenu zrušení nebo vypnutí.
RunConsoleAsync
RunConsoleAsyncumožňuje podporu konzoly, sestavení a spuštění hostitele a čeká na vypnutí ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM.
Spustit
Start spustí hostitele synchronně.
StartAsync
StartAsync spustí hostitele a vrátí Task , který se dokončí při aktivaci tokenu zrušení nebo vypnutí.
WaitForStartAsync je volána na začátku StartAsync
, který čeká na dokončení před pokračováním. Tuto metodu lze použít ke zpoždění spouštění, dokud není signalizovat externí událostí.
StopAsync
StopAsync pokusí zastavit hostitele v zadaném časovém limitu.
WaitForShutdown
WaitForShutdownblokuje volající vlákno, dokud se neaktivuje IHostLifetime, například pomocí Ctrl+C/SIGINT (Windows), ⌘+C (macOS) nebo SIGTERM.
WaitForShutdownAsync
WaitForShutdownAsyncTask vrátí hodnotu, která se dokončí při vypnutí prostřednictvím daného tokenu a volání StopAsync.
Externí ovládací prvek
Přímé řízení životnosti hostitele lze dosáhnout pomocí metod, které lze volat externě:
public class Program
{
private IHost _host;
public Program()
{
_host = new HostBuilder()
.Build();
}
public async Task StartAsync()
{
_host.StartAsync();
}
public async Task StopAsync()
{
using (_host)
{
await _host.StopAsync(TimeSpan.FromSeconds(5));
}
}
}
Další materiály
- Úlohy na pozadí s hostovanými službami v ASP.NET Core
- Odkaz GitHubu na obecný zdroj hostitele
Poznámka:
Odkazy na dokumentaci k referenčnímu zdroji .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).