Obecný hostitel .NET v ASP.NET Core

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 WebApplicationv 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
• 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 equals true.
• 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:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

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:

• NázevAplikace
• EnvironmentName
• ContentRootPath

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 ConfigureAppConfigurationnahrazení 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:

• Základy: Kořen obsahu
• WebRoot

EnvironmentName

Vlastnost IHostEnvironment.EnvironmentName lze nastavit na libovolnou hodnotu. Hodnoty definované architekturou zahrnují Development, Staginga 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.jsonse 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 falsedojde k chybám při spuštění, dojde k ukončení hostitele. Když truehostitel 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 Developmentprostř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_portTyp: 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:

• Základy: Kořenový adresář webu
• ContentRoot

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.

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).