Obecný hostitel .NET v ASP.NET Core

šablony ASP.NET Core vytvoří obecného hostitele .net Core ( HostBuilder ).

Toto téma poskytuje informace o použití obecného hostitele .NET v ASP.NET Core. Informace o použití obecného hostitele .NET v konzolových aplikacích najdete v tématu obecný hostitel .NET.

Definice hostitele

Hostitel je objekt, který zapouzdřuje prostředky aplikace, jako například:

  • Vkládání závislostí (DI)
  • protokolování
  • Konfigurace
  • IHostedService implementaci

Při spuštění hostitele zavolá IHostedService.StartAsync každou implementaci IHostedService zaregistrovanou v kolekci hostovaných služeb kontejneru služby. V rámci webové aplikace je jednou z IHostedService implementací webová služba, která spouští implementaci HTTP serveru.

Hlavním důvodem pro zahrnutí všech vzájemně závislých prostředků aplikace do jednoho objektu je Správa životního cyklu: Kontrola spuštění aplikace a bezproblémové vypnutí.

Nastavení hostitele

Hostitel je obvykle nakonfigurovaný, sestavený a spouštěný pomocí kódu ve Program třídě. MainMetoda:

  • Volá CreateHostBuilder metodu pro vytvoření a konfiguraci objektu Tvůrce.
  • Volání Build a Run metody objektu Builder.

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 jiného typu než HTTP s IHostedService implementací přidanou 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 úlohy HTTP Main je metoda stejná, ale CreateHostBuilder volání 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 ani signaturu CreateHostBuilder metody. Nástroje Entity Framework Core očekávají, že budou nalezeny CreateHostBuilder metody, které nakonfigurují hostitele bez spuštění aplikace. Další informace najdete v tématu vytváření DbContext při návrhu.

Výchozí nastavení tvůrce

CreateDefaultBuilderMetoda:

  • 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é klíče uživatele , když aplikace běží 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
    • Protokol událostí (pouze při spuštění v Windows)
  • Povolí ověřování oboru a ověřování závislostí při vývoji prostředí.

ConfigureWebHostDefaultsMetoda:

část Nastavení pro všechny typy aplikací a Nastavení pro webové aplikace dále v tomto článku ukazuje, jak přepsat výchozí nastavení tvůrce.

Služby poskytované rozhraním

Následující služby jsou registrovány automaticky:

Další informace o službách poskytovaných rozhraním najdete v tématu Injektáž závislostí v ASP.NET Core .

IHostApplicationLifetime

Vložení IHostApplicationLifetime služby (dříve IApplicationLifetime ) do libovolné třídy pro zpracování úloh po spuštění a řádné vypnutí. Tři vlastnosti rozhraní jsou tokeny zrušení použité k registraci metod spuštění aplikace a obslužné rutiny události zastavení aplikace. Rozhraní obsahuje také StopApplication metodu.

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

IHostLifetimeImplementace určuje, kdy se hostitel spustí a kdy se zastaví. Použije se Poslední registrovaná implementace.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime je výchozí IHostLifetime implementací. ConsoleLifetime:

IHostEnvironment

Vložením IHostEnvironment služby do třídy získáte informace o následujících nastaveních:

Webové aplikace implementují IWebHostEnvironment rozhraní, které dědí IHostEnvironment a přidává rozhraní WebRootPath.

Konfigurace hostitele

Konfigurace hostitele se používá pro vlastnosti IHostEnvironment implementace.

Konfigurace hostitele je k dispozici z HostBuilderContext.Configuration uvnitř ConfigureAppConfiguration . Po ConfigureAppConfiguration nahrazení se v HostBuilderContext.Configuration konfiguraci aplikace nahradí.

Chcete-li přidat konfiguraci hostitele, zavolejte ConfigureHostConfiguration na IHostBuilder . ConfigureHostConfiguration dá se volat víckrát s výsledky doplňkových výsledků. Hostitel používá bez ohledu na to, jaká možnost nastaví hodnotu jako poslední na daném klíči.

Zprostředkovatel proměnné prostředí s argumenty předpony DOTNET_ a příkazového řádku jsou obsaženy v CreateDefaultBuilder . U webových aplikací se přidá zprostředkovatel proměnné prostředí s předponou ASPNETCORE_ . Předpona je odebrána při čtení proměnných prostředí. Například hodnota proměnné prostředí pro se nastaví jako ASPNETCORE_ENVIRONMENT hodnota 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 aplikací

Konfigurace aplikace je vytvořena voláním ConfigureAppConfiguration metody IHostBuilder . ConfigureAppConfiguration dá se volat víckrát s výsledky doplňkových výsledků. Aplikace používá možnost, která pro daný klíč nastaví hodnotu Last.

Konfigurace vytvořená nástrojem ConfigureAppConfiguration je k dispozici na adrese HostBuilderContext.Configuration pro následné operace a jako službu z di. Konfigurace hostitele je také přidána do konfigurace aplikace.

Další informace najdete v tématu konfigurace v ASP.NET Core.

Nastavení pro všechny typy aplikací

V této části jsou uvedená nastavení hostitele, která se vztahují na úlohy HTTP i bez HTTP. Ve výchozím nastavení proměnné prostředí použité pro konfiguraci těchto nastavení mohou mít DOTNET_ ASPNETCORE_ předponu nebo. Další informace najdete v části výchozí nastavení tvůrce .

ApplicationName

Vlastnost IHostEnvironment. ApplicationName je nastavena v konfiguraci hostitele během vytváření hostitele.

Klíč: applicationName
Zadejte: 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 vyhledávat soubory obsahu. Pokud cesta neexistuje, hostitele se nepodaří spustit.

Klíč: contentRoot
Zadejte: 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 zavolejte UseContentRoot na IHostBuilder :

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

Další informace naleznete v tématu:

EnvironmentName

Vlastnost IHostEnvironment. Environment lze nastavit na libovolnou hodnotu. Hodnoty definované rozhraním zahrnují Development , Staging a Production . V hodnotách se nerozlišují malá a velká písmena.

Klíč: environment
Zadejte: string
Výchozí: Production
Proměnná prostředí: <PREFIX_>ENVIRONMENT

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

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

ShutdownTimeout

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

Pokud časový limit vyprší před zastavením všech hostovaných služeb, všechny zbývající aktivní služby se zastaví, jakmile se aplikace vypíná. Služby se zastavují i v případě, že se nedokončily zpracování. Pokud služby vyžadují ukončení déle, zvyšte časový limit.

Klíč: shutdownTimeoutSeconds
Zadejte: 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ázat opětovné načtení konfigurace aplikace při změně

Ve výchozím nastavení appsettings.json a appSettings. { Prostředí}. JSON se při změně souboru znovu načte. chcete-li zakázat toto opakované 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 1 )
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é prostředí na všech platformách. Další informace naleznete v tématu proměnné prostředí.

Nastavení pro web apps

Některá nastavení hostitele se vztahují jenom na úlohy HTTP. Ve výchozím nastavení proměnné prostředí použité pro konfiguraci těchto nastavení mohou mít DOTNET_ ASPNETCORE_ předponu nebo.

IWebHostBuilderK dispozici jsou metody rozšíření pro tato nastavení. Ukázky kódu, které ukazují, jak volat metody rozšíření předpokládají webBuilder , je instancí 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

falseV důsledku dojde k chybám při spuštění hostitele. Když true hostitel zachytí výjimky během spouštění a pokusí se o spuštění serveru.

Klíč: captureStartupErrors
Typ: bool ( true nebo 1 )
Výchozí: ve výchozím nastavení false platí, že pokud je aplikace SPUŠTĚNÁ Kestrel za službou IIS, kde je výchozí hodnota true .
Proměnná prostředí: <PREFIX_>CAPTURESTARTUPERRORS

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Pokud je povoleno nebo když je prostředí Development , aplikace zachycuje podrobné chyby.

Klíč: detailedErrors
Typ: bool ( true nebo 1 )
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íkem oddělený řetězec hostujících spouštěcích sestavení, která se mají načíst při spuštění. I když je hodnota konfigurace výchozím prázdným řetězcem, hostující spouštěcí sestavení vždy zahrnuje sestavení aplikace. Po zadání hostování spouštěcích sestavení jsou přidána do sestavení aplikace pro načtení, když aplikace během spouštění sestaví své běžné služby.

Klíč: hostingStartupAssemblies
Zadejte: 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íkem oddělený řetězec hostujících spouštěcích sestavení, která se mají vyloučit při spuštění.

Klíč: hostingStartupExcludeAssemblies
Zadejte: 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í https.

Klíč: https_port
Zadejte: 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, zda má hostitel naslouchat adresám URL nakonfigurovaným pomocí a IWebHostBuilder místo adres URL nakonfigurovaných IServer implementací.

Klíč: preferHostingUrls
Typ: bool ( true nebo 1 )
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í hostujících 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 nebo 1 )
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í, ve kterém se má hledat Startup Třída

Klíč: startupAssembly
Zadejte: string
Výchozí: 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 UseStartup je voláno více metod, má poslední z nich přednost.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

Adresy URL

Středníkem oddělený seznam IP adres nebo adres hostitelů s porty a protokoly, na kterých má Server naslouchat požadavky. Například, http://localhost:123. Pomocí příkazu " * " určete, že server má naslouchat žádostem na jakékoli 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
Zadejte: 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á své vlastní rozhraní API pro konfiguraci koncového bodu. Další informace naleznete v tématu Konfigurace koncových bodů pro ASP.NET Core Kestrel serveru.

WebRoot

Vlastnost IWebHostEnvironment. WebRootPath Určuje relativní cestu ke statickým assetům aplikace. Pokud cesta neexistuje, použije se zprostředkovatel souborů no-op.

Klíč: webroot
Zadejte: string
Výchozí: výchozí hodnota je wwwroot . Cesta k obsahu {root}/wwwroot musí existovat.
Proměnná prostředí: <PREFIX_>WEBROOT

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

webBuilder.UseWebRoot("public");

Další informace naleznete v tématu:

Správa životnosti hostitele

Voláním metod v sestavené IHost implementaci spustíte a zastavíte aplikaci. Tyto metody ovlivňují všechny IHostedService implementace, které jsou zaregistrovány v kontejneru služby.

Spustit

Run spustí aplikaci a zablokuje volající vlákno, dokud nebude hostitel vypnutý.

RunAsync

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

RunConsoleAsync

RunConsoleAsyncPovolí podporu konzoly, sestaví a spustí hostitele a počká, + až se vypne CTRLC/SIGINT nebo SIGTERM.

Spustit

Start spustí synchronního hostitele.

StartAsync

StartAsync spustí hostitele a vrátí Task , který se dokončí, když se aktivuje token zrušení nebo vypnutí.

WaitForStartAsync je volána na začátku StartAsync , což čeká na dokončení před pokračováním. Dá se použít ke zpoždění spuštění, dokud se nesignalizuje externí událostí.

StopAsync

StopAsync pokusy o zastavení hostitele v zadaném časovém limitu.

WaitForShutdown

WaitForShutdownblokuje volající vlákno, dokud se neaktivuje IHostLifetime, například pomocí CTRL + C/SIGINT nebo SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync Vrátí a Task , který se dokončí, když se aktivuje při vypnutí prostřednictvím daného tokenu a volání StopAsync .

Externí ovládací prvek

Přímou kontrolu životnosti hostitelů lze dosáhnout pomocí metod, které mohou být volány 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 vytvoří obecného hostitele .net Core ( HostBuilder ).

Toto téma poskytuje informace o použití obecného hostitele .NET v ASP.NET Core. Informace o použití obecného hostitele .NET v konzolových aplikacích najdete v tématu obecný hostitel .NET.

Definice hostitele

Hostitel je objekt, který zapouzdřuje prostředky aplikace, jako například:

  • Vkládání závislostí (DI)
  • protokolování
  • Konfigurace
  • IHostedService implementaci

Při spuštění hostitele zavolá IHostedService.StartAsync každou implementaci IHostedService zaregistrovanou v kolekci hostovaných služeb kontejneru služby. V rámci webové aplikace je jednou z IHostedService implementací webová služba, která spouští implementaci HTTP serveru.

Hlavním důvodem pro zahrnutí všech vzájemně závislých prostředků aplikace do jednoho objektu je Správa životního cyklu: Kontrola spuštění aplikace a bezproblémové vypnutí.

Nastavení hostitele

Hostitel je obvykle nakonfigurovaný, sestavený a spouštěný pomocí kódu ve Program třídě. MainMetoda:

  • Volá CreateHostBuilder metodu pro vytvoření a konfiguraci objektu Tvůrce.
  • Volání Build a Run metody objektu Builder.

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. IHostedServiceImplementace je přidána 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 úlohy HTTP Main je metoda stejná, ale CreateHostBuilder volání ConfigureWebHostDefaults :

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

předchozí kód je vygenerován šablonami ASP.NET Core.

Pokud aplikace používá Entity Framework Core, neměňte název ani signaturu CreateHostBuilder metody. Nástroje Entity Framework Core očekávají, že budou nalezeny CreateHostBuilder metody, které nakonfigurují hostitele bez spuštění aplikace. Další informace najdete v tématu vytváření DbContext při návrhu.

Výchozí nastavení tvůrce

CreateDefaultBuilderMetoda:

  • 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é klíče uživatele , když aplikace běží 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
    • Protokol událostí (pouze při spuštění v Windows)
  • Povolí ověřování oboru a ověřování závislostí při vývoji prostředí.

ConfigureWebHostDefaultsMetoda:

část Nastavení pro všechny typy aplikací a Nastavení pro webové aplikace dále v tomto článku ukazuje, jak přepsat výchozí nastavení tvůrce.

Služby poskytované rozhraním

Následující služby jsou registrovány automaticky:

Další informace o službách poskytovaných rozhraním najdete v tématu Injektáž závislostí v ASP.NET Core .

IHostApplicationLifetime

Vložení IHostApplicationLifetime služby (dříve IApplicationLifetime ) do libovolné třídy pro zpracování úloh po spuštění a řádné vypnutí. Tři vlastnosti rozhraní jsou tokeny zrušení použité k registraci metod spuštění aplikace a obslužné rutiny události zastavení aplikace. Rozhraní obsahuje také StopApplication metodu.

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

IHostLifetimeImplementace určuje, kdy se hostitel spustí a kdy se zastaví. Použije se Poslední registrovaná implementace.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime je výchozí IHostLifetime implementací. ConsoleLifetime:

IHostEnvironment

Vložením IHostEnvironment služby do třídy získáte informace o následujících nastaveních:

Webové aplikace implementují IWebHostEnvironment rozhraní, které dědí IHostEnvironment a přidává rozhraní WebRootPath.

Konfigurace hostitele

Konfigurace hostitele se používá pro vlastnosti IHostEnvironment implementace.

Konfigurace hostitele je k dispozici z HostBuilderContext.Configuration uvnitř ConfigureAppConfiguration . Po ConfigureAppConfiguration nahrazení se v HostBuilderContext.Configuration konfiguraci aplikace nahradí.

Chcete-li přidat konfiguraci hostitele, zavolejte ConfigureHostConfiguration na IHostBuilder . ConfigureHostConfiguration dá se volat víckrát s výsledky doplňkových výsledků. Hostitel používá bez ohledu na to, jaká možnost nastaví hodnotu jako poslední na daném klíči.

Zprostředkovatel proměnné prostředí s argumenty předpony DOTNET_ a příkazového řádku jsou obsaženy v CreateDefaultBuilder . U webových aplikací se přidá zprostředkovatel proměnné prostředí s předponou ASPNETCORE_ . Předpona je odebrána při čtení proměnných prostředí. Například hodnota proměnné prostředí pro se nastaví jako ASPNETCORE_ENVIRONMENT hodnota 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 aplikací

Konfigurace aplikace je vytvořena voláním ConfigureAppConfiguration metody IHostBuilder . ConfigureAppConfiguration dá se volat víckrát s výsledky doplňkových výsledků. Aplikace používá možnost, která pro daný klíč nastaví hodnotu Last.

Konfigurace vytvořená nástrojem ConfigureAppConfiguration je k dispozici na adrese HostBuilderContext.Configuration pro následné operace a jako službu z di. Konfigurace hostitele je také přidána do konfigurace aplikace.

Další informace najdete v tématu konfigurace v ASP.NET Core.

Nastavení pro všechny typy aplikací

V této části jsou uvedená nastavení hostitele, která se vztahují na úlohy HTTP i bez HTTP. Ve výchozím nastavení proměnné prostředí použité pro konfiguraci těchto nastavení mohou mít DOTNET_ ASPNETCORE_ předponu nebo.

ApplicationName

Vlastnost IHostEnvironment. ApplicationName je nastavena v konfiguraci hostitele během vytváření hostitele.

Klíč: applicationName
Zadejte: 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 vyhledávat soubory obsahu. Pokud cesta neexistuje, hostitele se nepodaří spustit.

Klíč: contentRoot
Zadejte: 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 zavolejte UseContentRoot na IHostBuilder :

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

Další informace naleznete v tématu:

EnvironmentName

Vlastnost IHostEnvironment. Environment lze nastavit na libovolnou hodnotu. Hodnoty definované rozhraním zahrnují Development , Staging a Production . V hodnotách se nerozlišují malá a velká písmena.

Klíč: environment
Zadejte: string
Výchozí: Production
Proměnná prostředí: <PREFIX_>ENVIRONMENT

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

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

ShutdownTimeout

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

Pokud časový limit vyprší před zastavením všech hostovaných služeb, všechny zbývající aktivní služby se zastaví, jakmile se aplikace vypíná. Služby se zastavují i v případě, že se nedokončily zpracování. Pokud služby vyžadují ukončení déle, zvyšte časový limit.

Klíč: shutdownTimeoutSeconds
Zadejte: 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 web apps

Některá nastavení hostitele se vztahují jenom na úlohy HTTP. Ve výchozím nastavení proměnné prostředí použité pro konfiguraci těchto nastavení mohou mít DOTNET_ ASPNETCORE_ předponu nebo.

IWebHostBuilderK dispozici jsou metody rozšíření pro tato nastavení. Ukázky kódu, které ukazují, jak volat metody rozšíření předpokládají webBuilder , je instancí 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

falseV důsledku dojde k chybám při spuštění hostitele. Když true hostitel zachytí výjimky během spouštění a pokusí se o spuštění serveru.

Klíč: captureStartupErrors
Typ: bool ( true nebo 1 )
Výchozí: ve výchozím nastavení false platí, že pokud je aplikace SPUŠTĚNÁ Kestrel za službou IIS, kde je výchozí hodnota true .
Proměnná prostředí: <PREFIX_>CAPTURESTARTUPERRORS

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Pokud je povoleno nebo když je prostředí Development , aplikace zachycuje podrobné chyby.

Klíč: detailedErrors
Typ: bool ( true nebo 1 )
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íkem oddělený řetězec hostujících spouštěcích sestavení, která se mají načíst při spuštění. I když je hodnota konfigurace výchozím prázdným řetězcem, hostující spouštěcí sestavení vždy zahrnuje sestavení aplikace. Po zadání hostování spouštěcích sestavení jsou přidána do sestavení aplikace pro načtení, když aplikace během spouštění sestaví své běžné služby.

Klíč: hostingStartupAssemblies
Zadejte: 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íkem oddělený řetězec hostujících spouštěcích sestavení, která se mají vyloučit při spuštění.

Klíč: hostingStartupExcludeAssemblies
Zadejte: 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í https.

Klíč: https_port
Zadejte: 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, zda má hostitel naslouchat adresám URL nakonfigurovaným pomocí a IWebHostBuilder místo adres URL nakonfigurovaných IServer implementací.

Klíč: preferHostingUrls
Typ: bool ( true nebo 1 )
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í hostujících 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 nebo 1 )
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í, ve kterém se má hledat Startup Třída

Klíč: startupAssembly
Zadejte: string
Výchozí: 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 UseStartup je voláno více metod, má poslední z nich přednost.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

Adresy URL

Středníkem oddělený seznam IP adres nebo adres hostitelů s porty a protokoly, na kterých má Server naslouchat požadavky. Například, http://localhost:123. Pomocí příkazu " * " určete, že server má naslouchat žádostem na jakékoli 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
Zadejte: 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á své vlastní rozhraní API pro konfiguraci koncového bodu. Další informace naleznete v tématu Kestrelimplementace webového serveru v ASP.NET Core.

WebRoot

Vlastnost IWebHostEnvironment. WebRootPath Určuje relativní cestu ke statickým assetům aplikace. Pokud cesta neexistuje, použije se zprostředkovatel souborů no-op.

Klíč: webroot
Zadejte: string
Výchozí: výchozí hodnota je wwwroot . Cesta k obsahu {root}/wwwroot musí existovat.
Proměnná prostředí: <PREFIX_>WEBROOT

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

webBuilder.UseWebRoot("public");

Další informace naleznete v tématu:

Správa životnosti hostitele

Voláním metod v sestavené IHost implementaci spustíte a zastavíte aplikaci. Tyto metody ovlivňují všechny IHostedService implementace, které jsou zaregistrované v kontejneru služby.

Spustit

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

RunAsync (Asynchronní spouštění)

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

RunConsoleAsync

RunConsoleAsyncumožňuje podporu konzoly, sestaví a spustí hostitele a čeká na vypnutí ctrl + C/SIGINT nebo SIGTERM.

Spustit

Start spustí hostitele synchronně.

StartAsync (Asynchronní spuštění)

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

WaitForStartAsync se volá na začátku , která před pokračováním čeká na StartAsync dokončení. To lze použít ke zpoždění spuštění, dokud nebude signalizováno externí událostí.

Metoda StopAsync

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

WaitForShutdown

WaitForShutdownblokuje volající vlákno, dokud se nespouštěje prostřednictvím IHostLifetime, například prostřednictvím Ctrl + C/SIGINT nebo SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync vrátí , Task který se dokončí, když se prostřednictvím daného tokenu aktivuje vypnutí, a zavolá StopAsync .

Externí řízení

Přímé kontroly nad životností 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));
        }
    }
}

ASP.NET Core aplikace nakonfigurují a spustí hostitele. Hostitel zodpovídá za správu spuštění a životnosti aplikace.

Tento článek popisuje ASP.NET Core Obecný hostitel ( ), který se používá pro aplikace, které HostBuilder nezpracují požadavky HTTP.

Účelem obecného hostitele je oddělení kanálu HTTP od rozhraní API webového hostitele, aby bylo možné rozšířit řadu scénářů hostitele. Zasílání zpráv, úlohy na pozadí a další úlohy jiné než HTTP založené na obecném hostiteli těží z možností, jako je konfigurace, injektáž závislostí (DI) a protokolování.

Obecný hostitel je ve ASP.NET Core 2.1 nový a není vhodný pro scénáře hostování webu. Pro scénáře hostování webu použijte webhosting. Obecný hostitel nahradí v budoucí verzi webového hostitele a bude fungovat jako rozhraní API primárního hostitele ve scénářích HTTP i mimo HTTP.

Zobrazení nebo stažení ukázkového kódu (stažení)

Při spuštění ukázkové aplikace v Visual Studio Codepoužijte externí nebo integrovaný terminál. Nespouštět ukázku v internalConsole .

Nastavení konzoly v Visual Studio Code:

  1. Otevřete soubor .vscode/launch.json.
  2. V konfiguraci spuštění .NET Core (konzola) vyhledejte položku konzoly. Nastavte hodnotu na externalTerminal nebo integratedTerminal .

Úvod

Knihovna obecných hostitelů je dostupná v oboru Microsoft.Extensions.Hosting názvů a poskytuje ho balíček Microsoft.Extensions.Hosting. Balíček Microsoft.Extensions.Hosting je součástí balíčku Microsoft.AspNetCore.App (ASP.NET Core 2.1 nebo novější).

IHostedService je vstupním bodem provádění kódu. Každá IHostedService implementace se provádí v pořadí registrace služby v configureservices. StartAsync se volá u každého při spuštění hostitele a volá se v obráceném pořadí registrace, když se hostitel řádně IHostedService StopAsync vypne.

Nastavení hostitele

IHostBuilder je hlavní komponenta, kterou knihovny a aplikace používají k inicializaci, sestavení a spuštění hostitele:

public static async Task Main(string[] args)
{
    var host = new HostBuilder()
        .Build();

    await host.RunAsync();
}

Možnosti

HostOptions nakonfigurujte možnosti pro IHost .

Časový limit vypnutí

ShutdownTimeout nastaví časový limit pro StopAsync . Výchozí hodnota je pět sekund.

Následující konfigurace možností v nástroji zvýší výchozí časový limit vypnutí po pěti Program.Main sekundách na 20 sekund:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    })
    .Build();

Výchozí služby

Během inicializace hostitele jsou zaregistrované následující služby:

Konfigurace hostitele

Konfiguraci hostitele vytvoří:

Metody rozšíření

Klíč aplikace (název)

Vlastnost IHostingEnvironment.ApplicationName se při konstrukci hostitele nastavuje z konfigurace hostitele. K explicitnímu nastavení hodnoty použijte HostDefaults.ApplicationKey:

Klíč:applicationName
Zadejte: string
Default: Název sestavení obsahující vstupní bod aplikace.
Nastavení pomocí: HostBuilderContext.HostingEnvironment.ApplicationName
Proměnná prostředí: <PREFIX_>APPLICATIONNAME ( je <PREFIX_> volitelná a definovaná uživatelem)

Kořen obsahu

Toto nastavení určuje, kde hostitel začne hledat soubory obsahu.

Klíč:contentRoot
Zadejte: string
Výchozí: Výchozí hodnota je složka, ve které se nachází sestavení aplikace.
Nastavení pomocí: UseContentRoot
Proměnná prostředí: <PREFIX_>CONTENTROOT ( je <PREFIX_> volitelná a definovaná uživatelem)

Pokud cesta neexistuje, hostitel se nespustí.

var host = new HostBuilder()
    .UseContentRoot("c:\\<content-root>")

Další informace najdete v tématu Fundamentals: Content root.

Prostředí

Nastaví prostředí aplikace.

Klíč:environment
Zadejte: string
Výchozí hodnota:Production
Nastavení pomocí: UseEnvironment
Proměnná prostředí: <PREFIX_>ENVIRONMENT ( je <PREFIX_> volitelná a definovaná uživatelem)

Prostředí je možné nastavit na libovolnou hodnotu. Mezi hodnoty definované architekturou patří Development Staging , a Production . V hodnotách se rozlišují malá a velká písmena.

var host = new HostBuilder()
    .UseEnvironment(EnvironmentName.Development)

Konfigurace hostitele

ConfigureHostConfiguration používá IConfigurationBuilder k vytvoření IConfiguration pro hostitele . Konfigurace hostitele slouží k inicializaci pro použití v procesu IHostingEnvironment sestavení aplikace.

ConfigureHostConfiguration s aditivními výsledky lze volat vícekrát. Hostitel použije možnost, která nastaví poslední hodnotu pro daný klíč.

Ve výchozím nastavení nejsou zahrnuti žádní zprostředkovatelé. V souboru musíte explicitně zadat zprostředkovatele konfigurace, které aplikace ConfigureHostConfiguration vyžaduje:

  • Konfigurace souboru (například zhostsettings.js v souboru).
  • Konfigurace proměnné prostředí.
  • Konfigurace argumentu příkazového řádku.
  • Všechny ostatní požadované zprostředkovatele konfigurace.

Konfigurace souboru hostitele je povolená zadáním základní cesty aplikace a následnou voláním jednoho z SetBasePath zprostředkovatelů konfigurace souborů. Ukázková aplikace používá soubor JSON, hostsettings.jszapnutý, a volá AddJsonFile k využívání nastavení konfigurace hostitele souboru.

Chcete-li přidat konfiguraci proměnné prostředí hostitele, zavolejte AddEnvironmentVariables na tvůrce hostitele. AddEnvironmentVariables přijme volitelnou uživatelem definovanou předponu. Ukázková aplikace používá předponu PREFIX_ . Předpona je odebrána při čtení proměnných prostředí. Když je hostitel ukázkové aplikace nakonfigurovaný, hodnota proměnné prostředí PREFIX_ENVIRONMENT se bude hodnotou konfigurace hostitele pro tento environment klíč.

během vývoje při použití Visual Studio nebo spuštění aplikace s se dotnet run mohou proměnné prostředí nastavit v souboru Properties/launchSettings.js . v Visual Studio Codemohou být proměnné prostředí nastaveny v souboru . vscode/launch.js při vývoji. Další informace naleznete v tématu Používání více prostředí v ASP.NET Core.

Konfigurace příkazového řádku je přidána voláním AddCommandLine . K povolení argumentů příkazového řádku pro přepsání konfigurace poskytované předchozími poskytovateli konfigurace se přidá poslední konfigurace příkazového řádku.

hostsettings.js:

{
  "environment": "Development"
}

Další konfiguraci lze poskytnout pomocí klíčů ApplicationName a contentRoot .

Příklad HostBuilder Konfigurace pomocí ConfigureHostConfiguration :

var host = new HostBuilder()
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    })

ConfigureAppConfiguration

Konfigurace aplikace je vytvořena voláním ConfigureAppConfiguration IHostBuilder implementace. ConfigureAppConfiguration používá IConfigurationBuilder k vytvoření IConfiguration pro aplikaci. ConfigureAppConfiguration dá se volat víckrát s výsledky doplňkových výsledků. Aplikace používá možnost, která pro daný klíč nastaví hodnotu Last. Konfigurace vytvořená nástrojem ConfigureAppConfiguration je k dispozici na adrese HostBuilderContext.Configuration pro následné operace a v Services .

Konfigurace aplikace automaticky přijímá konfiguraci hostitele, kterou poskytuje ConfigureHostConfiguration.

Příklad konfigurace aplikace pomocí ConfigureAppConfiguration :

var host = new HostBuilder()
    .ConfigureAppConfiguration((hostContext, configApp) =>
    {
        configApp.SetBasePath(Directory.GetCurrentDirectory());
        configApp.AddJsonFile("appsettings.json", optional: true);
        configApp.AddJsonFile(
            $"appsettings.{hostContext.HostingEnvironment.EnvironmentName}.json", 
            optional: true);
        configApp.AddEnvironmentVariables(prefix: "PREFIX_");
        configApp.AddCommandLine(args);
    })

appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

appsettings.Development.js:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

appsettings.Production.js:

{
  "Logging": {
    "LogLevel": {
      "Default": "Error",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

chcete-li přesunout soubory nastavení do výstupního adresáře, zadejte soubory nastavení MSBuild položky projektu v souboru projektu. Ukázková aplikace přesune své soubory nastavení aplikace JSON a hostsettings.js s touto <Content> položkou:

<ItemGroup>
  <Content Include="**\*.json" Exclude="bin\**\*;obj\**\*" 
      CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Poznámka

metody rozšíření konfigurace, například AddJsonFile a AddEnvironmentVariables vyžadují další balíčky NuGet, jako je například Microsoft.Extensions.Configuration.Jsna uration aMicrosoft.Extensions.Config. EnvironmentVariables. Pokud aplikace nepoužívá metapackage Microsoft.AspNetCore.app, musí být tyto balíčky kromě balíčku základní Microsoft.Extensions.Configuration přidány do projektu. Další informace naleznete v tématu Konfigurace v ASP.NET Core.

ConfigureServices

ConfigureServices Přidá služby do kontejneru vkládání závislostí aplikace. ConfigureServices dá se volat víckrát s výsledky doplňkových výsledků.

Hostovaná služba je třída s logikou úlohy na pozadí, která implementuje IHostedService rozhraní. Další informace naleznete v tématu Úlohy na pozadí s hostovanými službami v ASP.NET Core.

Ukázková aplikace používá AddHostedService metodu rozšíření k přidání služby pro události života, LifetimeEventsHostedService a časově omezená úloha na pozadí, TimedHostedService do aplikace:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        if (hostContext.HostingEnvironment.IsDevelopment())
        {
            // Development service configuration
        }
        else
        {
            // Non-development service configuration
        }

        services.AddHostedService<LifetimeEventsHostedService>();
        services.AddHostedService<TimedHostedService>();
    })

ConfigureLogging

ConfigureLogging Přidá delegáta pro konfiguraci poskytnutého ILoggingBuilder . ConfigureLogging může být voláno vícekrát s přísadou výsledků.

var host = new HostBuilder()
    .ConfigureLogging((hostContext, configLogging) =>
    {
        configLogging.AddConsole();
        configLogging.AddDebug();
    })

UseConsoleLifetime

UseConsoleLifetimenaslouchá klávesám CTRL + C/SIGINT nebo SIGTERM a voláním StopApplication ke spuštění procesu vypnutí. UseConsoleLifetime odblokuje rozšíření jako RunAsync a WaitForShutdownAsync. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime je předem registrován jako výchozí implementace životního cyklu. Je použita poslední registrovaná doba života.

var host = new HostBuilder()
    .UseConsoleLifetime()

Konfigurace kontejneru

Pro podporu zapojení do jiných kontejnerů může hostitel přijmout IServiceProviderFactory<TContainerBuilder> . Poskytnutí továrny není součástí registrace DI Container, ale je místo toho hostitel, který se používá k vytvoření konkrétního kontejneru DI. UseServiceProviderFactory (IServiceProviderFactory < TContainerBuilder > ) přepisuje výchozí továrnu, která byla použita k vytvoření poskytovatele služeb aplikace.

Vlastní konfigurace kontejneru je spravovaná ConfigureContainer metodou. ConfigureContainer poskytuje silné typové prostředí pro konfiguraci kontejneru nad podkladovým rozhraním API hostitele. ConfigureContainer dá se volat víckrát s výsledky doplňkových výsledků.

Vytvoření kontejneru služby pro aplikaci:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

Poskytněte objekt pro vytváření kontejnerů služby:

using System;
using Microsoft.Extensions.DependencyInjection;

namespace GenericHostSample
{
    internal class ServiceContainerFactory : 
        IServiceProviderFactory<ServiceContainer>
    {
        public ServiceContainer CreateBuilder(
            IServiceCollection services)
        {
            return new ServiceContainer();
        }

        public IServiceProvider CreateServiceProvider(
            ServiceContainer containerBuilder)
        {
            throw new NotImplementedException();
        }
    }
}

Použijte objekt pro vytváření a nakonfigurujte vlastní kontejner služby pro aplikaci:

var host = new HostBuilder()
    .UseServiceProviderFactory<ServiceContainer>(new ServiceContainerFactory())
    .ConfigureContainer<ServiceContainer>((hostContext, container) =>
    {
    })

Rozšiřitelnost

Rozšiřitelnost hostitelů se provádí s metodami rozšíření na IHostBuilder . Následující příklad ukazuje, jak rozšiřující metoda rozšiřuje IHostBuilder implementaci s příkladem TimedHostedService znázorněným v Úlohy na pozadí s hostovanými službami v ASP.NET Core .

var host = new HostBuilder()
    .UseHostedService<TimedHostedService>()
    .Build();

await host.StartAsync();

Aplikace vytváří UseHostedService metodu rozšíření pro registraci hostované služby, která byla předána T :

using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class Extensions
{
    public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
        where T : class, IHostedService, IDisposable
    {
        return hostBuilder.ConfigureServices(services =>
            services.AddHostedService<T>());
    }
}

Správa hostitele

IHostImplementace zodpovídá za spouštění a zastavování IHostedService implementací, které jsou zaregistrované v kontejneru služby.

Spustit

Run spustí aplikaci a zablokuje volající vlákno, dokud není hostitel vypnutý:

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        host.Run();
    }
}

RunAsync

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

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        await host.RunAsync();
    }
}

RunConsoleAsync

RunConsoleAsyncPovolí podporu konzoly, sestaví a spustí hostitele a počká, + až se vypne CTRLC/SIGINT nebo SIGTERM.

public class Program
{
    public static async Task Main(string[] args)
    {
        var hostBuilder = new HostBuilder();

        await hostBuilder.RunConsoleAsync();
    }
}

Spustit a StopAsync

Start spustí synchronního hostitele.

StopAsync pokusy o zastavení hostitele v zadaném časovém limitu.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            await host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

StartAsync a StopAsync

StartAsync spustí aplikaci.

StopAsync ukončí aplikaci.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.StopAsync();
        }
    }
}

WaitForShutdown

WaitForShutdownje aktivována prostřednictvím IHostLifetime , například Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (naslouchá pro CTRL + C/SIGINT nebo SIGTERM). WaitForShutdown volání StopAsync .

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsync

WaitForShutdownAsync Vrátí a Task , který se dokončí, když se aktivuje při vypnutí prostřednictvím daného tokenu a volání StopAsync .

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.WaitForShutdownAsync();
        }

    }
}

Externí ovládací prvek

Externí kontrolu hostitele lze dosáhnout pomocí metod, které mohou být volány 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));
        }
    }
}

WaitForStartAsync je volána na začátku StartAsync , což čeká na dokončení před pokračováním. Dá se použít ke zpoždění spuštění, dokud se nesignalizuje externí událostí.

Rozhraní IHostingEnvironment

IHostingEnvironment poskytuje informace o hostitelském prostředí aplikace. Použijte Injektáže konstruktoru pro získání, aby IHostingEnvironment bylo možné použít jeho vlastnosti a metody rozšíření:

public class MyClass
{
    private readonly IHostingEnvironment _env;

    public MyClass(IHostingEnvironment env)
    {
        _env = env;
    }

    public void DoSomething()
    {
        var environmentName = _env.EnvironmentName;
    }
}

Další informace naleznete v tématu Používání více prostředí v ASP.NET Core.

Rozhraní IApplicationLifetime

IApplicationLifetime umožňuje aktivity po spuštění a vypnutí, včetně řádných požadavků na vypnutí. Tři vlastnosti rozhraní jsou tokeny zrušení používané k registraci Action metod, které definují události spuštění a vypnutí.

Token zrušení Aktivované při…
ApplicationStarted Hostitel byl plně spuštěn.
ApplicationStopped Hostitel dokončuje řádné vypnutí. Všechny požadavky by se měly zpracovat. Bloky vypnutí, dokud se tato událost nedokončí.
ApplicationStopping Hostitel provádí bezproblémové vypnutí. Žádosti se pořád dají zpracovat. Bloky vypnutí, dokud se tato událost nedokončí.

Konstruktor – vloží IApplicationLifetime službu do libovolné třídy. Ukázková aplikace používá vkládání konstruktoru do LifetimeEventsHostedService třídy ( IHostedService implementace) pro registraci událostí.

LifetimeEventsHostedService. cs:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IApplicationLifetime 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
    }
}

StopApplication požaduje ukončení aplikace. Následující třída elegantně vypne aplikaci při volání StopApplication Shutdown metody třídy:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

    public MyClass(IApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Další zdroje informací

  • Úlohy na pozadí s hostovanými službami v ASP.NET Core
  • GitHub odkaz na obecný zdroj hostitele

    Poznámka

    dokumentace odkazuje na zdrojový odkaz na ASP.NET Core načtení main větve úložiště, která představuje aktuální vývoj jednotky produktu pro další verzi ASP.NET Core. Pokud chcete vybrat větev pro jinou verzi, vyberte ji pomocí rozevíracího seznamu větve přepínače nebo značky . vyberte například release/5.0 větev pro verzi ASP.NET Core 5,0.