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 WebApplication, které poskytují zjednodušený způsob konfigurace a spouštění webových aplikací bez Startup třídy. Další informace o migraci z ASP.NET Core 5.0 na verzi 6.0 a další informace WebApplicationBuilder najdete v tématu Migrace z ASP.NET Core 5.0.WebApplication

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

Při spuštění hostitele 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 do jednoho objektu umožňuje kontrolu nad spuštěním a bezproblémovým vypnutím aplikace.

Nastavení hostitele

Hostitel je obvykle nakonfigurovaný, sestavený a spuš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.
    • Uživatelské tajné kódy při spuštění aplikace v Development prostředí.
    • 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 :

V části Nastavení pro všechny typy aplikací a Nastavení webových aplikací dále v tomto článku se dozvíte, jak přepsat výchozí nastavení tvůrce.

Služby poskytované architekturou

Automaticky se zaregistrují následující služby:

Další informace oslužbách ASP.NET Core ch

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 metody obslužné rutiny událostí zastavení aplikace. Rozhraní také obsahuje metodu StopApplication , která umožňuje aplikacím požadovat řádné vypnutí.

Při provádění odkladu 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 existující připojení, dokud časový limit vypnutí povolí. Server odešle hlavičku uzavření připojení pro další požadavky na 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:

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.ConfigurationConfigureAppConfiguration. HostBuilderContext.Configuration Po ConfigureAppConfigurationnahrazení konfigurace aplikace.

Pokud chcete přidat konfiguraci hostitele, zavolejte ConfigureHostConfiguration .IHostBuilder ConfigureHostConfiguration lze volat vícekrát s výsledky sčítání. Hostitel používá jakoukoli možnost, která nastaví hodnotu poslední na daném klíči.

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é 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 klíč se stane hodnotou environment konfigurace hostitele.

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 aplikací

Konfigurace aplikace se vytvoří voláním ConfigureAppConfigurationIHostBuilder. ConfigureAppConfiguration lze volat vícekrát s výsledky sčítání. Aplikace používá jakoukoli možnost, která nastaví hodnotu poslední na daném klíči.

Konfigurace vytvořená uživatelem ConfigureAppConfiguration je k dispozici pro HostBuilderContext.Configuration následné operace a jako služba z DI. Konfigurace hostitele se také přidá do konfigurace aplikace.

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 Nastavení výchozího tvůrce a Konfigurace: Proměnné prostředí.

ApplicationName

Vlastnost je nastavena IHostEnvironment.ApplicationName z konfigurace hostitele během sestavování hostitele.

Klíč: applicationName
Typ: string
Výchozí: Název sestavení, které obsahuje vstupní bod aplikace.
Proměnná prostředí: {PREFIX_}APPLICATIONNAME

Chcete-li nastavit tuto hodnotu, 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í: Složka, ve které se nachází sestavení aplikace.
Proměnná prostředí: {PREFIX_}CONTENTROOT

Chcete-li nastavit tuto hodnotu, 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, Staginga Production. Hodnoty nejsou citlivé na malá a velká písmena.

Klíč: environment
Typ: string
Výchozí nastavení: Production
Proměnná prostředí: {PREFIX_}ENVIRONMENT

Chcete-li nastavit tuto hodnotu, použijte proměnnou prostředí nebo voláníUseEnvironment:IHostBuilder

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    // ...

Vypnutí časového limitu

HostOptions.ShutdownTimeout nastaví časový limit pro StopAsync. Výchozí hodnota je pět sekund. Během časového limitu hostitel:

Pokud vyprší platnost časového limitu 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

Chcete-li nastavit tuto hodnotu, 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. Chcete-li toto chování opětovného načítání zakázat v ASP.NET Core 5.0 nebo novějším, nastavte hostBuilder:reloadConfigOnChange klíč na false.

Klíč: hostBuilder:reloadConfigOnChange
Typ: bool (true nebo false)
Výchozí nastavení: true
Argument příkazového řádku: hostBuilder:reloadConfigOnChange
Proměnná prostředí: {PREFIX_}hostBuilder:reloadConfigOnChange

Upozornění

Oddělovač dvojtečky: () nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Další informace najdete v tématu Proměnné prostředí.

Nastavení webových aplikací

Některá nastavení hostitele platí jenom pro úlohy HTTP. Proměnné prostředí používané ke konfiguraci těchto nastavení můžou mít ve výchozím nastavení předponu nebo ASPNETCORE_ předponuDOTNET_, která se zobrazí v následujícím seznamu nastavení jako {PREFIX_} zástupný symbol.

Pro tato nastavení jsou dostupné 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 během spuštění zaznamená výjimky a pokusí se server spustit.

Klíč: captureStartupErrors
Typ: bool (true/1 nebo false/0)
Výchozí: Výchozí nastavení: Pokud aplikace neběží false se Kestrel službou IIS, kde je truevýchozí .
Proměnná prostředí: {PREFIX_}CAPTURESTARTUPERRORS

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

Podrobné chyby

Pokud je prostředí povolené nebo pokud je Developmentprostředí, aplikace zaznamenává podrobné chyby.

Klíč: detailedErrors
Typ: bool (true/1 nebo false/0)
Výchozí nastavení: false
Proměnná prostředí: {PREFIX_}DETAILEDERRORS

Chcete-li nastavit tuto hodnotu, 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í pro načtení při spuštění. I když je hodnota konfigurace výchozí pro prázdný řetězec, hostování spouštěcích sestavení vždy zahrnuje sestavení aplikace. Při hostování spouštěcích sestavení se přidají do sestavení aplikace pro načtení, když aplikace během spuštění sestaví své běžné služby.

Klíč: hostingStartupAssemblies
Typ: string
Výchozí: Prázdný řetězec
Proměnná prostředí: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Chcete-li nastavit tuto hodnotu, 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

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání UseSetting:

webBuilder.UseSetting(
    WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

Port přesměrování HTTPS. Používá se při vynucování protokolu HTTPS.

Klíč: https_port
Typ: string
Výchozí hodnota: Výchozí hodnota není nastavená.
Proměnná prostředí: {PREFIX_}HTTPS_PORT

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

Určuje, jestli by měl hostitel naslouchat adresám URL nakonfigurovaným na IWebHostBuilder místo těchto adres URL nakonfigurovaných s implementací IServer .

Klíč: preferHostingUrls
Typ: bool (true/1 nebo false/0)
Výchozí: true
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í hostování spouštěcích sestavení, včetně hostování spouštěcích sestavení nakonfigurovaných sestavením aplikace. Další informace naleznete v tématu Použití hostování spouštěcích sestavení v ASP.NET Core.

Klíč: preventHostingStartup
Typ: bool (true/1 nebo false/0)
Výchozí: 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í: false
Proměnná prostředí: {PREFIX_}SUPPRESSSTATUSMESSAGES

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

Adresy URL

Seznam IP adres oddělených středníkem nebo hostitelských adres s porty a protokoly, na kterých má server naslouchat požadavkům. Například, http://localhost:123. Pomocí "*" označte, že server by měl naslouchat požadavkům 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 liší mezi servery.

Klíč: urls
Typ: string
Výchozí: 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 pro konfiguraci koncových bodů. 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 typu no-op.

Klíč: webroot
Typ: string
Výchozí: Výchozí hodnota je wwwroot. Cesta k adresáři {content root}/wwwroot musí existovat.
Proměnná prostředí: {PREFIX_}WEBROOT

Chcete-li nastavit tuto hodnotu, 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 vytvořené IHost implementace pro spuštění a zastavení aplikace Tyto metody ovlivňují všechny IHostedService implementace zaregistrované v kontejneru služby.

Spustit

Run spustí aplikaci a zablokuje volající vlákno, dokud se hostitel nevypne.

RunAsync

RunAsync spustí aplikaci a vrátí Task , která se dokončí při aktivaci tokenu zrušení nebo vypnutí.

RunConsoleAsync

RunConsoleAsync umožňuje podporu konzoly, sestavení a spuštění hostitele a čeká na vypnutí kombinace kláves Ctrl+C/SIGINT (Windows), +C (macOS) nebo SIGTERM.

Spustit

Start spustí synchronně hostitele.

StartAsync

StartAsync spustí hostitele a vrátí Task hodnotu, 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í spuštění, dokud není signalizovat externí událost.

StopAsync

StopAsync se pokusí zastavit hostitele během zadaného časového limitu.

WaitForShutdown

WaitForShutdown blokuje 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 aktivaci 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

Při spuštění hostitele 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 do jednoho objektu je správa životnosti: kontrola nad spuštěním aplikace a bezproblémovým vypnutím.

Nastavení hostitele

Hostitel je obvykle nakonfigurovaný, sestavený a spuštěný kódem ve Program třídě. Metoda Main :

  • Volá metodu CreateHostBuilder pro vytvoření a konfiguraci objektu tvůrce.
  • Volání Build a Run 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>();
            });
}

Pro úlohu Main HTTP je metoda stejná, 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, neměňte název nebo podpis CreateHostBuilder metody. Nástroje Entity Framework Core očekávají, že najde metoduCreateHostBuilder, která nakonfiguruje hostitele bez spuštění aplikace. Další informace naleznete v tématu Návrh-time DbContext Vytvoření.

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.
    • Uživatelské tajné kódy při spuštění aplikace v Development prostředí.
    • 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 :

V části Nastavení pro všechny typy aplikací a Nastavení webových aplikací dále v tomto článku se dozvíte, jak přepsat výchozí nastavení tvůrce.

Služby poskytované architekturou

Automaticky se zaregistrují následující služby:

Další informace oslužbách ASP.NET Core ch

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 metody obslužné rutiny událostí zastavení aplikace. 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:

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.ConfigurationConfigureAppConfiguration. HostBuilderContext.Configuration Po ConfigureAppConfigurationnahrazení konfigurace aplikace.

Pokud chcete přidat konfiguraci hostitele, zavolejte ConfigureHostConfiguration .IHostBuilder ConfigureHostConfiguration lze volat vícekrát s výsledky sčítání. Hostitel používá jakoukoli možnost, která nastaví hodnotu poslední na daném klíči.

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é 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 klíč se stane hodnotou environment konfigurace hostitele.

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 aplikací

Konfigurace aplikace se vytvoří voláním ConfigureAppConfigurationIHostBuilder. ConfigureAppConfiguration lze volat vícekrát s výsledky sčítání. Aplikace používá jakoukoli možnost, která nastaví hodnotu poslední na daném klíči.

Konfigurace vytvořená uživatelem ConfigureAppConfiguration je k dispozici pro HostBuilderContext.Configuration následné operace a jako služba z DI. Konfigurace hostitele se také přidá do konfigurace aplikace.

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 Nastavení výchozího tvůrce a Konfigurace: Proměnné prostředí.

ApplicationName

Vlastnost IHostEnvironment.ApplicationName je nastavena z konfigurace hostitele během sestavování hostitele.

Klíč: applicationName
Typ: string
Výchozí: 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

Chcete-li nastavit tuto hodnotu, 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, Staginga Production. Hodnoty nerozlišovat malá a velká písmena.

Klíč: environment
Typ: string
Výchozí: Production
Proměnná prostředí: {PREFIX_}ENVIRONMENT

Chcete-li nastavit tuto hodnotu, použijte proměnnou prostředí nebo voláníUseEnvironment:IHostBuilder

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

Vypnutí časového limitu

HostOptions.ShutdownTimeout nastaví časový limit pro StopAsync. Výchozí hodnota je pět sekund. Během časového limitu hostitel:

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 zpracování nedokončily. Pokud služby vyžadují k zastavení více času, zvyšte časový limit.

Klíč: shutdownTimeoutSeconds
Typ: int
Výchozí: 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í se appsettings.{Environment}.json při appsettings.json změně souboru znovu načtou. Chcete-li zakázat toto chování opětovného načítání v ASP.NET Core 5.0 nebo novějším, nastavte hostBuilder:reloadConfigOnChange klíč na false.

Klíč: hostBuilder:reloadConfigOnChange
Typ: bool (true nebo false)
Výchozí: true
Argument příkazového řádku: hostBuilder:reloadConfigOnChange
Proměnná prostředí: {PREFIX_}hostBuilder:reloadConfigOnChange

Upozornění

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í webových aplikací

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 falsepři spuštění dojde k chybám při spuštění, dojde k ukončení hostitele. Když truehostitel zaznamená výjimky během spouštění a pokusí se spustit server.

Klíč: captureStartupErrors
Typ: bool (true/1 nebo false/0)
Výchozí hodnota: Výchozí hodnota je, false pokud se aplikace nespustí se Kestrel službou IIS, kde je truevýchozí hodnota .
Proměnná prostředí: {PREFIX_}CAPTURESTARTUPERRORS

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

Podrobné chyby

Když je prostředí povolené nebo pokud je Developmentprostředí, aplikace zaznamená podrobné chyby.

Klíč: detailedErrors
Typ: bool (true/1 nebo false/0)
Výchozí: false
Proměnná prostředí: {PREFIX_}DETAILEDERRORS

Chcete-li nastavit tuto hodnotu, 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 výchozí hodnota konfigurace 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, aby se načítaly, 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

Chcete-li nastavit tuto hodnotu, 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

Chcete-li nastavit tuto hodnotu, 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

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

Určuje, jestli má hostitel naslouchat adresám URL nakonfigurovaným místo IWebHostBuilder těchto adres URL nakonfigurovaným s implementací IServer .

Klíč: preferHostingUrls
Typ: bool (true/1 nebo false/0)
Výchozí: true
Proměnná prostředí: {PREFIX_}PREFERHOSTINGURLS

K nastavení této hodnoty použijte proměnnou prostředí nebo volání PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Zabraňuje automatickému načítání hostování spouštěcích sestavení, včetně hostování spouštěcích sestavení nakonfigurovaných sestavením aplikace. Další informace naleznete v tématu Použití hostování spouštěcích sestavení v ASP.NET Core.

Klíč: preventHostingStartup
Typ: bool (true/1 nebo false/0)
Výchozí: 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í: false
Proměnná prostředí: {PREFIX_}SUPPRESSSTATUSMESSAGES

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

Adresy URL

Seznam IP adres oddělených středníkem nebo hostitelských adres s porty a protokoly, na kterých má server naslouchat požadavkům. Například, http://localhost:123. Pomocí "*" označte, že server by měl naslouchat požadavkům 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 liší mezi servery.

Klíč: urls
Typ: string
Výchozí: 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 pro konfiguraci koncových bodů. 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 typu no-op.

Klíč: webroot
Typ: string
Výchozí: Výchozí hodnota je wwwroot. Cesta k adresáři {content root}/wwwroot musí existovat.
Proměnná prostředí: {PREFIX_}WEBROOT

Chcete-li nastavit tuto hodnotu, 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 vytvořené IHost implementace pro spuštění a zastavení aplikace Tyto metody ovlivňují všechny IHostedService implementace zaregistrované v kontejneru služby.

Spustit

Run spustí aplikaci a zablokuje volající vlákno, dokud se hostitel nevypne.

RunAsync

RunAsync spustí aplikaci a vrátí Task , která se dokončí při aktivaci tokenu zrušení nebo vypnutí.

RunConsoleAsync

RunConsoleAsync umožňuje podporu konzoly, sestavení a spuštění hostitele a čeká na vypnutí kombinace kláves Ctrl+C/SIGINT (Windows), +C (macOS) nebo SIGTERM.

Spustit

Start spustí synchronně hostitele.

StartAsync

StartAsync spustí hostitele a vrátí Task hodnotu, 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í spuštění, dokud není signalizovat externí událost.

StopAsync

StopAsync se pokusí zastavit hostitele během zadaného časového limitu.

WaitForShutdown

WaitForShutdown blokuje 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 aktivaci vypnutí prostřednictvím daného tokenu a volání StopAsync.

Externí ovládací prvek

Přímé řízení doby života 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

Při spuštění hostitele 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 do jednoho objektu je správa životnosti: kontrola nad spuštěním aplikace a bezproblémovým vypnutím.

Nastavení hostitele

Hostitel je obvykle nakonfigurovaný, sestavený a spuštěný kódem ve Program třídě. Metoda Main :

  • Volá metodu CreateHostBuilder pro vytvoření a konfiguraci objektu tvůrce.
  • Volání Build a Run 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>();
            });
}

Pro úlohu Main HTTP je metoda stejná, ale CreateHostBuilder volá ConfigureWebHostDefaults:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Předchozí kód se vygeneruje šablonami ASP.NET Core.

Pokud aplikace používá Entity Framework Core, neměňte název nebo podpis CreateHostBuilder metody. Nástroje Entity Framework Core očekávají, že najde metoduCreateHostBuilder, která nakonfiguruje hostitele bez spuštění aplikace. Další informace naleznete v tématu Návrh-time DbContext Vytvoření.

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.
    • Uživatelské tajné kódy při spuštění aplikace v Development prostředí.
    • 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 :

V části Nastavení pro všechny typy aplikací a Nastavení webových aplikací dále v tomto článku se dozvíte, jak přepsat výchozí nastavení tvůrce.

Služby poskytované architekturou

Automaticky se zaregistrují následující služby:

Další informace oslužbách ASP.NET Core ch

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 metody obslužné rutiny událostí zastavení aplikace. 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:

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.ConfigurationConfigureAppConfiguration. HostBuilderContext.Configuration Po ConfigureAppConfigurationnahrazení konfigurace aplikace.

Pokud chcete přidat konfiguraci hostitele, zavolejte ConfigureHostConfiguration .IHostBuilder ConfigureHostConfiguration lze volat vícekrát s výsledky sčítání. Hostitel používá jakoukoli možnost, která nastaví hodnotu poslední na daném klíči.

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é 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 klíč se stane hodnotou environment konfigurace hostitele.

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 aplikací

Konfigurace aplikace se vytvoří voláním ConfigureAppConfigurationIHostBuilder. ConfigureAppConfiguration lze volat vícekrát s výsledky sčítání. Aplikace používá jakoukoli možnost, která nastaví hodnotu poslední na daném klíči.

Konfigurace vytvořená uživatelem ConfigureAppConfiguration je k dispozici pro HostBuilderContext.Configuration následné operace a jako služba z DI. Konfigurace hostitele se také přidá do konfigurace aplikace.

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

ApplicationName

Vlastnost IHostEnvironment.ApplicationName je nastavena z konfigurace hostitele během sestavování hostitele.

Klíč: applicationName
Typ: string
Výchozí: 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

Chcete-li nastavit tuto hodnotu, 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, Staginga Production. Hodnoty nerozlišovat malá a velká písmena.

Klíč: environment
Typ: string
Výchozí: Production
Proměnná prostředí: {PREFIX_}ENVIRONMENT

Chcete-li nastavit tuto hodnotu, použijte proměnnou prostředí nebo voláníUseEnvironment:IHostBuilder

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

Vypnutí časového limitu

HostOptions.ShutdownTimeout nastaví časový limit pro StopAsync. Výchozí hodnota je pět sekund. Během časového limitu hostitel:

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 zpracování nedokončily. Pokud služby vyžadují k zastavení více času, zvyšte časový limit.

Klíč: shutdownTimeoutSeconds
Typ: int
Výchozí: 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í webových aplikací

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 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 falsepři spuštění dojde k chybám při spuštění, dojde k ukončení hostitele. Když truehostitel zaznamená výjimky během spouštění a pokusí se spustit server.

Klíč: captureStartupErrors
Typ: bool (true/1 nebo false/0)
Výchozí hodnota: Výchozí hodnota je, false pokud se aplikace nespustí se Kestrel službou IIS, kde je truevýchozí hodnota .
Proměnná prostředí: {PREFIX_}CAPTURESTARTUPERRORS

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

Podrobné chyby

Když je prostředí povolené nebo pokud je Developmentprostředí, aplikace zaznamená podrobné chyby.

Klíč: detailedErrors
Typ: bool (true/1 nebo false/0)
Výchozí: false
Proměnná prostředí: {PREFIX_}DETAILEDERRORS

Chcete-li nastavit tuto hodnotu, 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í pro načtení při spuštění. I když je hodnota konfigurace výchozí pro prázdný řetězec, hostování spouštěcích sestavení vždy zahrnuje sestavení aplikace. Při hostování spouštěcích sestavení se přidají do sestavení aplikace pro načtení, když aplikace během spuštění sestaví své běžné služby.

Klíč: hostingStartupAssemblies
Typ: string
Výchozí: Prázdný řetězec
Proměnná prostředí: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Chcete-li nastavit tuto hodnotu, 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

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

Port přesměrování HTTPS. Používá se při vynucování protokolu HTTPS.

Klíč: https_port
Typ: string
Výchozí hodnota: Výchozí hodnota není nastavená.
Proměnná prostředí: {PREFIX_}HTTPS_PORT

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

Určuje, jestli by měl hostitel naslouchat adresám URL nakonfigurovaným na IWebHostBuilder místo těchto adres URL nakonfigurovaných s implementací IServer .

Klíč: preferHostingUrls
Typ: bool (true/1 nebo false/0)
Výchozí nastavení: true
Proměnná prostředí: {PREFIX_}PREFERHOSTINGURLS

Chcete-li nastavit tuto hodnotu, použijte proměnnou prostředí nebo volání PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Zabrání automatickému načítání spouštěcích sestavení hostování, včetně hostování spouštěcích sestavení nakonfigurovaných sestavením aplikace. Další informace najdete v tématu Použití spouštěcích sestavení hostování v ASP.NET Core.

Klíč: preventHostingStartup
Typ: bool (true/1 nebo false/0)
Výchozí nastavení: false
Proměnná prostředí: {PREFIX_}PREVENTHOSTINGSTARTUP

Chcete-li nastavit tuto hodnotu, 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í nastavení: Sestavení aplikace
Proměnná prostředí: {PREFIX_}STARTUPASSEMBLY

Chcete-li nastavit tuto hodnotu, 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í zpráv o stavu spuštění.

Klíč: suppressStatusMessages
Typ: bool (true/1 nebo false/0)
Výchozí nastavení: false
Proměnná prostředí: {PREFIX_}SUPPRESSSTATUSMESSAGES

Chcete-li nastavit tuto hodnotu, použijte konfiguraci nebo volání UseSetting:

webBuilder.UseSetting(WebHostDefaults.SuppressStatusMessagesKey, "true");

Adresy URL

Středník oddělený seznam IP adres nebo hostitelských adres s porty a protokoly, na kterých má server naslouchat žádostem. Například, http://localhost:123. Pomocí znaku *označte, že server by měl naslouchat požadavkům na libovolnou IP adresu nebo název 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 liší mezi servery.

Klíč: urls
Typ: string
Výchozí nastavení: http://localhost:5000 a https://localhost:5001
Proměnná prostředí: {PREFIX_}URLS

Chcete-li nastavit tuto hodnotu, 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 Kestrel implementace webového 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 {content root}/wwwroot musí existovat.
Proměnná prostředí: {PREFIX_}WEBROOT

Chcete-li nastavit tuto hodnotu, použijte proměnnou prostředí nebo voláníUseWebRoot:IWebHostBuilder

webBuilder.UseWebRoot("public");

Další informace naleznete v tématu:

Správa životnosti hostitele

Volání metod pro integrovanou IHost implementaci pro spuštění a zastavení aplikace Tyto metody ovlivňují všechny IHostedService implementace zaregistrované v kontejneru služby.

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

RunConsoleAsync umožňuje podporu konzoly, sestavení a spuštění hostitele a čeká na vypnutí kombinace kláves 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á, dokud nebude dokončena, než budete pokračovat. Tuto metodu lze použít ke zpoždění spuštění, dokud není signalizovat externí událost.

StopAsync

StopAsync pokusí se zastavit hostitele v rámci poskytnutého časového limitu.

WaitForShutdown

WaitForShutdown blokuje 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 aktivaci vypnutí prostřednictvím daného tokenu a volání StopAsync.

Externí ovládací prvek

Přímé řízení doby života 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