Udostępnij za pośrednictwem


Host ogólny platformy .NET w programie ASP.NET Core

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core Support Policy (Zasady obsługi platformy .NET Core). Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ten artykuł zawiera informacje na temat korzystania z hosta ogólnego platformy .NET w programie ASP.NET Core.

Szablony ASP.NET Core tworzą WebApplicationBuilder szablony i WebApplication, które zapewniają usprawniony sposób konfigurowania i uruchamiania aplikacji internetowych bez Startup klasy. Aby uzyskać więcej informacji na temat WebApplicationBuilder i , zobacz Migrowanie z platformy ASP.NET Core 5.0 do 6.0WebApplication.

Aby uzyskać informacje na temat korzystania z hosta ogólnego platformy .NET w aplikacjach konsoli, zobacz Host ogólny platformy .NET.

Definicja hosta

Host to obiekt, który hermetyzuje zasoby aplikacji, takie jak:

  • Wstrzykiwanie zależności (DI)
  • Rejestrowanie
  • Konfigurowanie
  • IHostedService Implementacje

Po uruchomieniu hosta wywołuje IHostedService.StartAsync każdą implementację zarejestrowaną IHostedService w kolekcji hostowanych usług kontenera usługi. W aplikacji internetowej jedną z IHostedService implementacji jest usługa internetowa, która uruchamia implementację serwera HTTP.

Uwzględnienie wszystkich współzależnych zasobów aplikacji w jednym obiekcie umożliwia kontrolę nad uruchamianiem aplikacji i bezproblemowym zamykaniem.

Konfigurowanie hosta

Host jest zwykle skonfigurowany, skompilowany i uruchamiany według kodu w pliku Program.cs. Poniższy kod tworzy hosta z implementacją dodaną IHostedService do kontenera DI:

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

W przypadku obciążenia HTTP wywołaj metodę ConfigureWebHostDefaults po :CreateDefaultBuilder

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

Domyślne ustawienia konstruktora

Metoda CreateDefaultBuilder:

  • Ustawia katalog główny zawartości na ścieżkę zwróconą przez GetCurrentDirectory.
  • Ładuje konfigurację hosta z:
    • Zmienne środowiskowe poprzedzone prefiksem DOTNET_.
    • Argumenty wiersza polecenia.
  • Ładuje konfigurację aplikacji z:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Wpisy tajne użytkownika w przypadku aplikacji działającej w środowisku Development.
    • Zmienne środowiskowe.
    • Argumenty wiersza polecenia.
  • Dodaje następujących dostawców rejestrowania :
    • Konsola
    • Debugowanie
    • EventSource
    • EventLog (tylko w przypadku uruchamiania w systemie Windows)
  • Włącza walidację zakresu i walidację zależności, gdy środowisko jest programowaniem.

Metoda ConfigureWebHostDefaults:

  • Ładuje konfigurację hosta ze zmiennych środowiskowych poprzedzonych prefiksem ASPNETCORE_.
  • Ustawia Kestrel serwer jako serwer internetowy i konfiguruje go przy użyciu dostawców konfiguracji hostingu aplikacji. Kestrel Aby uzyskać opcje domyślne serwera, zobacz Konfigurowanie opcji dla serwera internetowego ASP.NET CoreKestrel.
  • Dodaje oprogramowanie pośredniczące filtrowania hostów.
  • Dodaje oprogramowanie pośredniczące Nagłówki przekazane, jeśli ASPNETCORE_FORWARDEDHEADERS_ENABLED jest równe true.
  • Umożliwia integrację z usługami IIS. Aby uzyskać opcje domyślne usług IIS, zobacz Host ASP.NET Core w systemie Windows z usługami IIS.

Sekcje Ustawienia dla wszystkich typów aplikacji i Ustawienia dla aplikacji internetowych w dalszej części tego artykułu pokazują, jak zastąpić domyślne ustawienia konstruktora.

Usługi dostarczane przez platformę

Następujące usługi są rejestrowane automatycznie:

Aby uzyskać więcej informacji na temat usług udostępnianych przez platformę, zobacz Wstrzykiwanie zależności w programie ASP.NET Core.

IHostApplicationLifetime

Wstrzykuj usługę IHostApplicationLifetime (dawniej IApplicationLifetime) do dowolnej klasy, aby obsługiwać zadania po uruchomieniu i bezproblemowym zamykaniu. Trzy właściwości interfejsu to tokeny anulowania używane do rejestrowania metod obsługi uruchamiania aplikacji i zatrzymywania aplikacji. Interfejs zawiera również metodę StopApplication , która umożliwia aplikacjom żądanie bezproblemowego zamknięcia.

Podczas przeprowadzania bezproblemowego zamykania host:

  • Wyzwala programy obsługi zdarzeń ApplicationStopping , które umożliwiają aplikacji uruchamianie logiki przed rozpoczęciem procesu zamykania.
  • Zatrzymuje serwer, który wyłącza nowe połączenia. Serwer czeka na ukończenie żądań istniejących połączeń, dopóki limit czasu zamknięcia jest dozwolony. Serwer wysyła nagłówek zamknięcia połączenia dla dalszych żądań dotyczących istniejących połączeń.
  • Wyzwala programy obsługi zdarzeń ApplicationStopped , co umożliwia aplikacji uruchamianie logiki po zamknięciu aplikacji.

W poniższym przykładzie przedstawiono implementację IHostedService rejestrującą IHostApplicationLifetime programy obsługi zdarzeń:

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

Implementacja IHostLifetime steruje, gdy host zostanie uruchomiony i zatrzymany. Używana jest ostatnia zarejestrowana implementacja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime to domyślna IHostLifetime implementacja. ConsoleLifetime:

IHostEnvironment

Wstrzyknąć usługę IHostEnvironment do klasy, aby uzyskać informacje o następujących ustawieniach:

Aplikacje internetowe implementują IWebHostEnvironment interfejs, który dziedziczy IHostEnvironment i dodaje element WebRootPath.

Konfiguracja hosta

Konfiguracja hosta jest używana dla właściwości implementacji IHostEnvironment .

Konfiguracja hosta jest dostępna z HostBuilderContext.Configuration wewnątrz ConfigureAppConfigurationprogramu . HostBuilderContext.Configuration Po ConfigureAppConfigurationpliku zostanie zastąpiony konfiguracją aplikacji.

Aby dodać konfigurację hosta, wywołaj metodę ConfigureHostConfiguration .IHostBuilder ConfigureHostConfiguration można wywołać wiele razy z wynikami dodawania. Host używa dowolnej opcji ustawia ostatnią wartość dla danego klucza.

Dostawca zmiennej środowiskowej z prefiksem DOTNET_ i argumentami wiersza polecenia są uwzględniane przez CreateDefaultBuilderelement . W przypadku aplikacji internetowych dodawany jest dostawca zmiennych środowiskowych z prefiksem ASPNETCORE_ . Prefiks jest usuwany po odczytaniu zmiennych środowiskowych. Na przykład wartość ASPNETCORE_ENVIRONMENT zmiennej środowiskowej dla parametru staje się wartością konfiguracji hosta dla environment klucza.

Poniższy przykład tworzy konfigurację hosta:

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(hostConfig =>
    {
        hostConfig.SetBasePath(Directory.GetCurrentDirectory());
        hostConfig.AddJsonFile("hostsettings.json", optional: true);
        hostConfig.AddEnvironmentVariables(prefix: "PREFIX_");
        hostConfig.AddCommandLine(args);
    });

Konfiguracja aplikacji

Konfiguracja aplikacji jest tworzona przez wywołanie ConfigureAppConfiguration metody .IHostBuilder ConfigureAppConfiguration można wywołać wiele razy z wynikami dodawania. Aplikacja używa dowolnej opcji ustawia ostatnią wartość dla danego klucza.

Konfiguracja utworzona przez ConfigureAppConfiguration jest dostępna na HostBuilderContext.Configuration potrzeby kolejnych operacji i jako usługi z di. Konfiguracja hosta jest również dodawana do konfiguracji aplikacji.

Aby uzyskać więcej informacji, zobacz Konfiguracja na platformie ASP.NET Core.

Ustawienia dla wszystkich typów aplikacji

W tej sekcji wymieniono ustawienia hosta, które mają zastosowanie zarówno do obciążeń HTTP, jak i innych niż HTTP. Domyślnie zmienne środowiskowe używane do konfigurowania tych ustawień mogą mieć DOTNET_ prefiks lub ASPNETCORE_ , który jest wyświetlany na poniższej liście ustawień jako {PREFIX_} symbol zastępczy. Aby uzyskać więcej informacji, zobacz sekcję Domyślne ustawienia konstruktora i Konfigurację: Zmienne środowiskowe.

ApplicationName

Właściwość IHostEnvironment.ApplicationName jest ustawiana z konfiguracji hosta podczas budowy hosta.

Klucz: applicationName
Typ: string
Ustawienie domyślne: nazwa zestawu, który zawiera punkt wejścia aplikacji.
Zmienna środowiskowa: {PREFIX_}APPLICATIONNAME

Aby ustawić tę wartość, użyj zmiennej środowiskowej.

ContentRoot

Właściwość IHostEnvironment.ContentRootPath określa, gdzie host rozpoczyna wyszukiwanie plików zawartości. Jeśli ścieżka nie istnieje, uruchomienie hosta nie powiedzie się.

Klucz: contentRoot
Typ: string
Ustawienie domyślne: folder, w którym znajduje się zestaw aplikacji.
Zmienna środowiskowa: {PREFIX_}CONTENTROOT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseContentRoot :IHostBuilder

Host.CreateDefaultBuilder(args)
    .UseContentRoot("/path/to/content/root")
    // ...

Aby uzyskać więcej informacji, zobacz:

NazwaŚrodowiska

Właściwość IHostEnvironment.EnvironmentName można ustawić na dowolną wartość. Zdefiniowane przez platformę wartości obejmują Development, Stagingi Production. Wartości nie są uwzględniane w wielkości liter.

Klucz: environment
Typ: string
Ustawienie domyślne: Production
Zmienna środowiskowa: {PREFIX_}ENVIRONMENT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseEnvironment :IHostBuilder

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

ShutdownTimeout

HostOptions.ShutdownTimeout ustawia limit czasu dla elementu StopAsync. Wartość domyślna to 30 sekund. W okresie przekroczenia limitu czasu host:

Jeśli okres przekroczenia limitu czasu wygaśnie przed zatrzymaniem wszystkich hostowanych usług, pozostałe aktywne usługi zostaną zatrzymane po zamknięciu aplikacji. Usługi są zatrzymywane nawet wtedy, gdy nie zakończyły przetwarzania. Jeśli usługi wymagają więcej czasu na zatrzymanie, zwiększ limit czasu.

Klucz: shutdownTimeoutSeconds
Typ: int
Ustawienie domyślne: 30 sekund
Zmienna środowiskowa: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub skonfiguruj wartość HostOptions. Poniższy przykład ustawia limit czasu na 20 sekund:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(options =>
        {
            options.ShutdownTimeout = TimeSpan.FromSeconds(20);
        });
    });

Wyłączanie ponownego ładowania konfiguracji aplikacji po zmianie

Domyślnie appsettings.json i appsettings.{Environment}.json są ponownie ładowane po zmianie pliku. Aby wyłączyć to zachowanie ponownego ładowania w programie ASP.NET Core 5.0 lub nowszym hostBuilder:reloadConfigOnChange , ustaw klucz na falsewartość .

Klucz: hostBuilder:reloadConfigOnChange
Typ: bool (true lub false)
Ustawienie domyślne: true
Argument wiersza polecenia: hostBuilder:reloadConfigOnChange
Zmienna środowiskowa: {PREFIX_}hostBuilder:reloadConfigOnChange

Ostrzeżenie

Separator dwukropka (:) nie działa z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. Aby uzyskać więcej informacji, zobacz Zmienne środowiskowe.

Ustawienia aplikacji internetowych

Niektóre ustawienia hosta dotyczą tylko obciążeń HTTP. Domyślnie zmienne środowiskowe używane do konfigurowania tych ustawień mogą mieć DOTNET_ prefiks lub ASPNETCORE_ , który jest wyświetlany na poniższej liście ustawień jako {PREFIX_} symbol zastępczy.

Dostępne są metody IWebHostBuilder rozszerzenia dla tych ustawień. Przykłady kodu pokazujące sposób wywoływania metod rozszerzenia zakładają webBuilder , że jest wystąpieniem IWebHostBuilderklasy , jak w poniższym przykładzie:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // ...
    });

CaptureStartupErrors

W przypadku false, błędy podczas uruchamiania powodują zamknięcie hosta. Gdy truehost przechwytuje wyjątki podczas uruchamiania i próbuje uruchomić serwer.

Klucz: captureStartupErrors
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: wartość domyślna to false , chyba że aplikacja jest uruchamiana za usługami Kestrel IIS, gdzie wartość domyślna to true.
Zmienna środowiskowa: {PREFIX_}CAPTURESTARTUPERRORS

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

Szczegółowe błędy

Po włączeniu lub w przypadku środowiska Developmentaplikacja przechwytuje szczegółowe błędy.

Klucz: detailedErrors
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}DETAILEDERRORS

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HostingStartupAssemblies

Rozdzielany średnikami ciąg hostowania zestawów startowych do załadowania podczas uruchamiania. Mimo że wartość konfiguracji jest domyślnie pusta, zestawy uruchamiania hostingu zawsze zawierają zestaw aplikacji. Podczas hostowania zestawów uruchamiania są one dodawane do zestawu aplikacji do ładowania, gdy aplikacja kompiluje swoje typowe usługi podczas uruchamiania.

Klucz: hostingStartupAssemblies
Typ: string
Ustawienie domyślne: Pusty ciąg
Zmienna środowiskowa: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HostingStartupExcludeAssemblies

Rozdzielany średnikami ciąg hostowania zestawów startowych do wykluczenia podczas uruchamiania.

Klucz: hostingStartupExcludeAssemblies
Typ: string
Ustawienie domyślne: Pusty ciąg
Zmienna środowiskowa: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HTTPS_Port

Ustaw port HTTPS, aby przekierować do, jeśli otrzymasz połączenie inne niż HTTPS. Używany w wymuszaniu protokołu HTTPS. To ustawienie nie powoduje, że serwer nasłuchuje na określonym porcie. Oznacza to, że możliwe jest przypadkowe przekierowanie żądań do nieużywanego portu.

Klucz: Typ: https_portstring
Ustawienie domyślne: wartość domyślna nie jest ustawiona.
Zmienna środowiskowa: {PREFIX_}HTTPS_PORT

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HTTPS_Ports

Porty do nasłuchiwania połączeń HTTPS.

Klucz: https_ports
Typ: string
Ustawienie domyślne: wartość domyślna nie jest ustawiona.
Zmienna środowiskowa: {PREFIX_}HTTPS_PORTS

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

PreferujhostowanieUrls

Wskazuje, czy host powinien nasłuchiwać adresów URL skonfigurowanych przy IWebHostBuilder użyciu zamiast tych adresów URL skonfigurowanych przy użyciu implementacji IServer .

Klucz: preferHostingUrls
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}PREFERHOSTINGURLS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Zapobiega automatycznemu ładowaniu zestawów uruchamiania, w tym hostowania zestawów uruchamiania skonfigurowanych przez zestaw aplikacji. Więcej informacji można znaleźć w temacie Korzystanie z hostowania zestawów startowych na platformie ASP.NET Core.

Klucz: preventHostingStartup
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}PREVENTHOSTINGSTARTUP

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseSetting :

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

StartupAssembly

Zestaw do wyszukiwania Startup klasy.

Klucz: startupAssembly
Typ: string
Ustawienie domyślne: zestaw aplikacji
Zmienna środowiskowa: {PREFIX_}STARTUPASSEMBLY

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseStartup. UseStartup może przyjmować nazwę zestawu (string) lub typ (TStartup). Jeśli wywoływano wiele UseStartup metod, ostatni z nich ma pierwszeństwo.

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

SuppressStatusMessages

Po włączeniu pomija hostowanie komunikatów o stanie uruchamiania.

Klucz: suppressStatusMessages
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}SUPPRESSSTATUSMESSAGES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

Adresy URL

Rozdzielana średnikami lista adresów IP lub adresów hostów z portami i protokołami, na których serwer powinien nasłuchiwać żądań. Na przykład http://localhost:123. Użyj "*", aby wskazać, że serwer powinien nasłuchiwać żądań na dowolnym adresie IP lub nazwie hosta przy użyciu określonego portu i protokołu (na przykład http://*:5000). Protokół (http:// lub https://) musi być dołączony do każdego adresu URL. Obsługiwane formaty różnią się między serwerami.

Klucz: urls
Typ: string
Ustawienie domyślne: http://localhost:5000 i https://localhost:5001
Zmienna środowiskowa: {PREFIX_}URLS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseUrls:

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel ma własny interfejs API konfiguracji punktu końcowego. Aby uzyskać więcej informacji, zobacz Konfigurowanie punktów końcowych dla serwera internetowego ASP.NET CoreKestrel.

WebRoot

Właściwość IWebHostEnvironment.WebRootPath określa ścieżkę względną do zasobów statycznych aplikacji. Jeśli ścieżka nie istnieje, zostanie użyty dostawca plików bez operacji.

Klucz: webroot
Typ: string
Ustawienie domyślne: wartość domyślna to wwwroot. Ścieżka do katalogu {content root}/wwwroot musi istnieć.
Zmienna środowiskowa: {PREFIX_}WEBROOT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseWebRoot :IWebHostBuilder

webBuilder.UseWebRoot("public");

Aby uzyskać więcej informacji, zobacz:

Zarządzanie okresem istnienia hosta

Wywołaj metody na wbudowanej IHost implementacji, aby uruchomić i zatrzymać aplikację. Te metody mają wpływ na wszystkie IHostedService implementacje zarejestrowane w kontenerze usługi.

Różnica między metodami Run* i Start* polega na tym, że Run* metody oczekują na ukończenie hosta przed zwróceniem, podczas gdy Start* metody są zwracane natychmiast. Metody Run* są zwykle używane w aplikacjach konsoli, podczas gdy Start* metody są zwykle używane w długotrwałych usługach.

Uruchom

Run uruchamia aplikację i blokuje wątek wywołujący do momentu zamknięcia hosta.

RunAsync

RunAsync uruchamia aplikację i zwraca wartość Task , która zostanie ukończona po wyzwoleniu tokenu anulowania lub zamknięcia.

RunConsoleAsync

RunConsoleAsync włącza obsługę konsoli, kompiluje i uruchamia hosta oraz czeka na zamknięcie Ctrl+C/SIGINT (Windows), +C (macOS) lub SIGTERM.

Rozpocznij

Start uruchamia hosta synchronicznie.

StartAsync

StartAsync uruchamia hosta i zwraca wartość Task , która zostanie ukończona po wyzwoleniu tokenu anulowania lub zamknięcia.

WaitForStartAsync parametr jest wywoływany na początku StartAsyncciągu , który czeka, aż zostanie ukończony przed kontynuowaniem. Ta metoda może służyć do opóźniania uruchamiania do momentu zasygnaliowania zdarzenia zewnętrznego.

StopAsync

StopAsync próbuje zatrzymać hosta w ramach podanego limitu czasu.

WaitForShutdown

WaitForShutdownblokuje wątek wywołujący do momentu wyzwolenia zamknięcia przez interfejs IHostLifetime, na przykład za pomocą Ctrl+C/SIGINT (Windows), ⌘+C (macOS) lub SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync Zwraca wartość Task , która kończy się po wyzwoleniu zamknięcia za pośrednictwem danego tokenu i wywołuje metodę StopAsync.

Szablony ASP.NET Core tworzą hosta ogólnego platformy .NET Core (HostBuilder).

Ten artykuł zawiera informacje na temat korzystania z hosta ogólnego platformy .NET w programie ASP.NET Core. Aby uzyskać informacje na temat korzystania z hosta ogólnego platformy .NET w aplikacjach konsoli, zobacz Host ogólny platformy .NET.

Definicja hosta

Host to obiekt, który hermetyzuje zasoby aplikacji, takie jak:

  • Wstrzykiwanie zależności (DI)
  • Rejestrowanie
  • Konfigurowanie
  • IHostedService Implementacje

Po uruchomieniu hosta wywołuje IHostedService.StartAsync każdą implementację zarejestrowaną IHostedService w kolekcji hostowanych usług kontenera usługi. W aplikacji internetowej jedną z IHostedService implementacji jest usługa internetowa, która uruchamia implementację serwera HTTP.

Główną przyczyną włączenia wszystkich współzależnych zasobów aplikacji w jednym obiekcie jest zarządzanie okresem istnienia: kontrola nad uruchamianiem aplikacji i bezproblemowym zamykaniem.

Konfigurowanie hosta

Host jest zwykle skonfigurowany, skompilowany i uruchamiany według kodu w Program klasie . Metoda Main:

  • Wywołuje metodę do utworzenia CreateHostBuilder i skonfigurowania obiektu konstruktora.
  • Wywołuje Build metody i Run w obiekcie konstruktora.

Szablony internetowe platformy ASP.NET Core generują następujący kod w celu utworzenia hosta:

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>();
            });
}

Poniższy kod tworzy obciążenie inne niż HTTP z implementacją dodaną IHostedService do kontenera 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>();
            });
}

W przypadku obciążenia HTTP metoda jest taka sama, Main ale CreateHostBuilder wywołuje metodę ConfigureWebHostDefaults:

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

Jeśli aplikacja używa platformy Entity Framework Core, nie zmieniaj nazwy ani podpisu CreateHostBuilder metody. Narzędzia Platformy Entity Framework Core oczekują znalezienia CreateHostBuilder metody, która konfiguruje hosta bez uruchamiania aplikacji. Aby uzyskać więcej informacji, zobacz Design-time DbContext Creation (Tworzenie elementu DbContext w czasie projektowania).

Domyślne ustawienia konstruktora

Metoda CreateDefaultBuilder:

  • Ustawia katalog główny zawartości na ścieżkę zwróconą przez GetCurrentDirectory.
  • Ładuje konfigurację hosta z:
    • Zmienne środowiskowe poprzedzone prefiksem DOTNET_.
    • Argumenty wiersza polecenia.
  • Ładuje konfigurację aplikacji z:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Wpisy tajne użytkownika w przypadku aplikacji działającej w środowisku Development.
    • Zmienne środowiskowe.
    • Argumenty wiersza polecenia.
  • Dodaje następujących dostawców rejestrowania :
    • Konsola
    • Debugowanie
    • EventSource
    • EventLog (tylko w przypadku uruchamiania w systemie Windows)
  • Włącza walidację zakresu i walidację zależności, gdy środowisko jest programowaniem.

Metoda ConfigureWebHostDefaults:

  • Ładuje konfigurację hosta ze zmiennych środowiskowych poprzedzonych prefiksem ASPNETCORE_.
  • Ustawia Kestrel serwer jako serwer internetowy i konfiguruje go przy użyciu dostawców konfiguracji hostingu aplikacji. Kestrel Aby uzyskać opcje domyślne serwera, zobacz Konfigurowanie opcji dla serwera internetowego ASP.NET CoreKestrel.
  • Dodaje oprogramowanie pośredniczące filtrowania hostów.
  • Dodaje oprogramowanie pośredniczące Nagłówki przekazane, jeśli ASPNETCORE_FORWARDEDHEADERS_ENABLED jest równe true.
  • Umożliwia integrację z usługami IIS. Aby uzyskać opcje domyślne usług IIS, zobacz Host ASP.NET Core w systemie Windows z usługami IIS.

Sekcje Ustawienia dla wszystkich typów aplikacji i Ustawienia dla aplikacji internetowych w dalszej części tego artykułu pokazują, jak zastąpić domyślne ustawienia konstruktora.

Usługi dostarczane przez platformę

Następujące usługi są rejestrowane automatycznie:

Aby uzyskać więcej informacji na temat usług udostępnianych przez platformę, zobacz Wstrzykiwanie zależności w programie ASP.NET Core.

IHostApplicationLifetime

Wstrzykuj usługę IHostApplicationLifetime (dawniej IApplicationLifetime) do dowolnej klasy, aby obsługiwać zadania po uruchomieniu i bezproblemowym zamykaniu. Trzy właściwości interfejsu to tokeny anulowania używane do rejestrowania metod obsługi uruchamiania aplikacji i zatrzymywania aplikacji. Interfejs zawiera również metodę StopApplication .

W poniższym przykładzie przedstawiono implementację IHostedService rejestrującą IHostApplicationLifetime zdarzenia:

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

Implementacja IHostLifetime steruje, gdy host zostanie uruchomiony i zatrzymany. Używana jest ostatnia zarejestrowana implementacja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime to domyślna IHostLifetime implementacja. ConsoleLifetime:

IHostEnvironment

Wstrzyknąć usługę IHostEnvironment do klasy, aby uzyskać informacje o następujących ustawieniach:

Aplikacje internetowe implementują IWebHostEnvironment interfejs, który dziedziczy IHostEnvironment i dodaje element WebRootPath.

Konfiguracja hosta

Konfiguracja hosta jest używana dla właściwości implementacji IHostEnvironment .

Konfiguracja hosta jest dostępna z HostBuilderContext.Configuration wewnątrz ConfigureAppConfigurationprogramu . HostBuilderContext.Configuration Po ConfigureAppConfigurationpliku zostanie zastąpiony konfiguracją aplikacji.

Aby dodać konfigurację hosta, wywołaj metodę ConfigureHostConfiguration .IHostBuilder ConfigureHostConfiguration można wywołać wiele razy z wynikami dodawania. Host używa dowolnej opcji ustawia ostatnią wartość dla danego klucza.

Dostawca zmiennej środowiskowej z prefiksem DOTNET_ i argumentami wiersza polecenia są uwzględniane przez CreateDefaultBuilderelement . W przypadku aplikacji internetowych dodawany jest dostawca zmiennych środowiskowych z prefiksem ASPNETCORE_ . Prefiks jest usuwany po odczytaniu zmiennych środowiskowych. Na przykład wartość ASPNETCORE_ENVIRONMENT zmiennej środowiskowej dla parametru staje się wartością konfiguracji hosta dla environment klucza.

Poniższy przykład tworzy konfigurację hosta:

// 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);
    });

Konfiguracja aplikacji

Konfiguracja aplikacji jest tworzona przez wywołanie ConfigureAppConfiguration metody .IHostBuilder ConfigureAppConfiguration można wywołać wiele razy z wynikami dodawania. Aplikacja używa dowolnej opcji ustawia ostatnią wartość dla danego klucza.

Konfiguracja utworzona przez ConfigureAppConfiguration jest dostępna na HostBuilderContext.Configuration potrzeby kolejnych operacji i jako usługi z di. Konfiguracja hosta jest również dodawana do konfiguracji aplikacji.

Aby uzyskać więcej informacji, zobacz Konfiguracja na platformie ASP.NET Core.

Ustawienia dla wszystkich typów aplikacji

W tej sekcji wymieniono ustawienia hosta, które mają zastosowanie zarówno do obciążeń HTTP, jak i innych niż HTTP. Domyślnie zmienne środowiskowe używane do konfigurowania tych ustawień mogą mieć DOTNET_ prefiks lub ASPNETCORE_ , który jest wyświetlany na poniższej liście ustawień jako {PREFIX_} symbol zastępczy. Aby uzyskać więcej informacji, zobacz sekcję Domyślne ustawienia konstruktora i Konfigurację: Zmienne środowiskowe.

ApplicationName

Właściwość IHostEnvironment.ApplicationName jest ustawiana z konfiguracji hosta podczas budowy hosta.

Klucz: applicationName
Typ: string
Ustawienie domyślne: nazwa zestawu, który zawiera punkt wejścia aplikacji.
Zmienna środowiskowa: {PREFIX_}APPLICATIONNAME

Aby ustawić tę wartość, użyj zmiennej środowiskowej.

ContentRoot

Właściwość IHostEnvironment.ContentRootPath określa, gdzie host rozpoczyna wyszukiwanie plików zawartości. Jeśli ścieżka nie istnieje, uruchomienie hosta nie powiedzie się.

Klucz: contentRoot
Typ: string
Ustawienie domyślne: folder, w którym znajduje się zestaw aplikacji.
Zmienna środowiskowa: {PREFIX_}CONTENTROOT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseContentRoot :IHostBuilder

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

Aby uzyskać więcej informacji, zobacz:

NazwaŚrodowiska

Właściwość IHostEnvironment.EnvironmentName można ustawić na dowolną wartość. Zdefiniowane przez platformę wartości obejmują Development, Stagingi Production. Wartości nie są uwzględniane w wielkości liter.

Klucz: environment
Typ: string
Ustawienie domyślne: Production
Zmienna środowiskowa: {PREFIX_}ENVIRONMENT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseEnvironment :IHostBuilder

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

ShutdownTimeout

HostOptions.ShutdownTimeout ustawia limit czasu dla elementu StopAsync. Wartość domyślna to pięć sekund. W okresie przekroczenia limitu czasu host:

Jeśli okres przekroczenia limitu czasu wygaśnie przed zatrzymaniem wszystkich hostowanych usług, pozostałe aktywne usługi zostaną zatrzymane po zamknięciu aplikacji. Usługi są zatrzymywane nawet wtedy, gdy nie zakończyły przetwarzania. Jeśli usługi wymagają więcej czasu na zatrzymanie, zwiększ limit czasu.

Klucz: shutdownTimeoutSeconds
Typ: int
Ustawienie domyślne: 5 sekund
Zmienna środowiskowa: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub skonfiguruj wartość HostOptions. Poniższy przykład ustawia limit czasu na 20 sekund:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

Wyłączanie ponownego ładowania konfiguracji aplikacji po zmianie

Domyślnie appsettings.json i appsettings.{Environment}.json są ponownie ładowane po zmianie pliku. Aby wyłączyć to zachowanie ponownego ładowania w programie ASP.NET Core 5.0 lub nowszym hostBuilder:reloadConfigOnChange , ustaw klucz na falsewartość .

Klucz: hostBuilder:reloadConfigOnChange
Typ: bool (true lub false)
Ustawienie domyślne: true
Argument wiersza polecenia: hostBuilder:reloadConfigOnChange
Zmienna środowiskowa: {PREFIX_}hostBuilder:reloadConfigOnChange

Ostrzeżenie

Separator dwukropka (:) nie działa z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. Aby uzyskać więcej informacji, zobacz Zmienne środowiskowe.

Ustawienia aplikacji internetowych

Niektóre ustawienia hosta dotyczą tylko obciążeń HTTP. Domyślnie zmienne środowiskowe używane do konfigurowania tych ustawień mogą mieć DOTNET_ prefiks lub ASPNETCORE_ , który jest wyświetlany na poniższej liście ustawień jako {PREFIX_} symbol zastępczy.

Dostępne są metody IWebHostBuilder rozszerzenia dla tych ustawień. Przykłady kodu pokazujące sposób wywoływania metod rozszerzenia zakładają webBuilder , że jest wystąpieniem IWebHostBuilderklasy , jak w poniższym przykładzie:

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

CaptureStartupErrors

W przypadku false, błędy podczas uruchamiania powodują zamknięcie hosta. Gdy truehost przechwytuje wyjątki podczas uruchamiania i próbuje uruchomić serwer.

Klucz: captureStartupErrors
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: wartość domyślna to false , chyba że aplikacja jest uruchamiana za usługami Kestrel IIS, gdzie wartość domyślna to true.
Zmienna środowiskowa: {PREFIX_}CAPTURESTARTUPERRORS

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

Szczegółowe błędy

Po włączeniu lub w przypadku środowiska Developmentaplikacja przechwytuje szczegółowe błędy.

Klucz: detailedErrors
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}DETAILEDERRORS

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HostingStartupAssemblies

Rozdzielany średnikami ciąg hostowania zestawów startowych do załadowania podczas uruchamiania. Mimo że wartość konfiguracji jest domyślnie pusta, zestawy uruchamiania hostingu zawsze zawierają zestaw aplikacji. Podczas hostowania zestawów uruchamiania są one dodawane do zestawu aplikacji do ładowania, gdy aplikacja kompiluje swoje typowe usługi podczas uruchamiania.

Klucz: hostingStartupAssemblies
Typ: string
Ustawienie domyślne: Pusty ciąg
Zmienna środowiskowa: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HostingStartupExcludeAssemblies

Rozdzielany średnikami ciąg hostowania zestawów startowych do wykluczenia podczas uruchamiania.

Klucz: hostingStartupExcludeAssemblies
Typ: string
Ustawienie domyślne: Pusty ciąg
Zmienna środowiskowa: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HTTPS_Port

Port przekierowania HTTPS. Używany w wymuszaniu protokołu HTTPS.

Klucz: https_port
Typ: string
Ustawienie domyślne: wartość domyślna nie jest ustawiona.
Zmienna środowiskowa: {PREFIX_}HTTPS_PORT

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

PreferujhostowanieUrls

Wskazuje, czy host powinien nasłuchiwać adresów URL skonfigurowanych przy IWebHostBuilder użyciu zamiast tych adresów URL skonfigurowanych przy użyciu implementacji IServer .

Klucz: preferHostingUrls
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}PREFERHOSTINGURLS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Zapobiega automatycznemu ładowaniu zestawów uruchamiania, w tym hostowania zestawów uruchamiania skonfigurowanych przez zestaw aplikacji. Więcej informacji można znaleźć w temacie Korzystanie z hostowania zestawów startowych na platformie ASP.NET Core.

Klucz: preventHostingStartup
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}PREVENTHOSTINGSTARTUP

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseSetting :

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

StartupAssembly

Zestaw do wyszukiwania Startup klasy.

Klucz: startupAssembly
Typ: string
Ustawienie domyślne: zestaw aplikacji
Zmienna środowiskowa: {PREFIX_}STARTUPASSEMBLY

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseStartup. UseStartup może przyjmować nazwę zestawu (string) lub typ (TStartup). Jeśli wywoływano wiele UseStartup metod, ostatni z nich ma pierwszeństwo.

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

SuppressStatusMessages

Po włączeniu pomija hostowanie komunikatów o stanie uruchamiania.

Klucz: suppressStatusMessages
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}SUPPRESSSTATUSMESSAGES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

Adresy URL

Rozdzielana średnikami lista adresów IP lub adresów hostów z portami i protokołami, na których serwer powinien nasłuchiwać żądań. Na przykład http://localhost:123. Użyj "*", aby wskazać, że serwer powinien nasłuchiwać żądań na dowolnym adresie IP lub nazwie hosta przy użyciu określonego portu i protokołu (na przykład http://*:5000). Protokół (http:// lub https://) musi być dołączony do każdego adresu URL. Obsługiwane formaty różnią się między serwerami.

Klucz: urls
Typ: string
Ustawienie domyślne: http://localhost:5000 i https://localhost:5001
Zmienna środowiskowa: {PREFIX_}URLS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseUrls:

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel ma własny interfejs API konfiguracji punktu końcowego. Aby uzyskać więcej informacji, zobacz Konfigurowanie punktów końcowych dla serwera internetowego ASP.NET CoreKestrel.

WebRoot

Właściwość IWebHostEnvironment.WebRootPath określa ścieżkę względną do zasobów statycznych aplikacji. Jeśli ścieżka nie istnieje, zostanie użyty dostawca plików bez operacji.

Klucz: webroot
Typ: string
Ustawienie domyślne: wartość domyślna to wwwroot. Ścieżka do katalogu {content root}/wwwroot musi istnieć.
Zmienna środowiskowa: {PREFIX_}WEBROOT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseWebRoot :IWebHostBuilder

webBuilder.UseWebRoot("public");

Aby uzyskać więcej informacji, zobacz:

Zarządzanie okresem istnienia hosta

Wywołaj metody na wbudowanej IHost implementacji, aby uruchomić i zatrzymać aplikację. Te metody mają wpływ na wszystkie IHostedService implementacje zarejestrowane w kontenerze usługi.

Różnica między metodami Run* i Start* polega na tym, że Run* metody oczekują na ukończenie hosta przed zwróceniem, podczas gdy Start* metody są zwracane natychmiast. Metody Run* są zwykle używane w aplikacjach konsoli, podczas gdy Start* metody są zwykle używane w długotrwałych usługach.

Uruchom

Run uruchamia aplikację i blokuje wątek wywołujący do momentu zamknięcia hosta.

RunAsync

RunAsync uruchamia aplikację i zwraca wartość Task , która zostanie ukończona po wyzwoleniu tokenu anulowania lub zamknięcia.

RunConsoleAsync

RunConsoleAsync włącza obsługę konsoli, kompiluje i uruchamia hosta oraz czeka na zamknięcie Ctrl+C/SIGINT (Windows), +C (macOS) lub SIGTERM.

Rozpocznij

Start uruchamia hosta synchronicznie.

StartAsync

StartAsync uruchamia hosta i zwraca wartość Task , która zostanie ukończona po wyzwoleniu tokenu anulowania lub zamknięcia.

WaitForStartAsync parametr jest wywoływany na początku StartAsyncciągu , który czeka, aż zostanie ukończony przed kontynuowaniem. Ta metoda może służyć do opóźniania uruchamiania do momentu zasygnaliowania zdarzenia zewnętrznego.

StopAsync

StopAsync próbuje zatrzymać hosta w ramach podanego limitu czasu.

WaitForShutdown

WaitForShutdownblokuje wątek wywołujący do momentu wyzwolenia zamknięcia przez interfejs IHostLifetime, na przykład za pomocą Ctrl+C/SIGINT (Windows), ⌘+C (macOS) lub SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync Zwraca wartość Task , która kończy się po wyzwoleniu zamknięcia za pośrednictwem danego tokenu i wywołuje metodę StopAsync.

Kontrola zewnętrzna

Bezpośrednią kontrolę nad okresem istnienia hosta można osiągnąć przy użyciu metod, które mogą być wywoływane zewnętrznie:

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));
        }
    }
}

Szablony ASP.NET Core tworzą hosta ogólnego platformy .NET Core (HostBuilder).

Ten artykuł zawiera informacje na temat korzystania z hosta ogólnego platformy .NET w programie ASP.NET Core. Aby uzyskać informacje na temat korzystania z hosta ogólnego platformy .NET w aplikacjach konsoli, zobacz Host ogólny platformy .NET.

Definicja hosta

Host to obiekt, który hermetyzuje zasoby aplikacji, takie jak:

  • Wstrzykiwanie zależności (DI)
  • Rejestrowanie
  • Konfigurowanie
  • IHostedService Implementacje

Po uruchomieniu hosta wywołuje IHostedService.StartAsync każdą implementację zarejestrowaną IHostedService w kolekcji hostowanych usług kontenera usługi. W aplikacji internetowej jedną z IHostedService implementacji jest usługa internetowa, która uruchamia implementację serwera HTTP.

Główną przyczyną włączenia wszystkich współzależnych zasobów aplikacji w jednym obiekcie jest zarządzanie okresem istnienia: kontrola nad uruchamianiem aplikacji i bezproblemowym zamykaniem.

Konfigurowanie hosta

Host jest zwykle skonfigurowany, skompilowany i uruchamiany według kodu w Program klasie . Metoda Main:

  • Wywołuje metodę do utworzenia CreateHostBuilder i skonfigurowania obiektu konstruktora.
  • Wywołuje Build metody i Run w obiekcie konstruktora.

Szablony internetowe platformy ASP.NET Core generują następujący kod w celu utworzenia hosta ogólnego:

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>();
            });
}

Poniższy kod tworzy hosta ogólnego przy użyciu obciążenia innego niż HTTP. Implementacja IHostedService jest dodawana do kontenera 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>();
            });
}

W przypadku obciążenia HTTP metoda jest taka sama, Main ale CreateHostBuilder wywołuje metodę ConfigureWebHostDefaults:

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

Powyższy kod jest generowany przez szablony ASP.NET Core.

Jeśli aplikacja używa platformy Entity Framework Core, nie zmieniaj nazwy ani podpisu CreateHostBuilder metody. Narzędzia Platformy Entity Framework Core oczekują znalezienia CreateHostBuilder metody, która konfiguruje hosta bez uruchamiania aplikacji. Aby uzyskać więcej informacji, zobacz Design-time DbContext Creation (Tworzenie elementu DbContext w czasie projektowania).

Domyślne ustawienia konstruktora

Metoda CreateDefaultBuilder:

  • Ustawia katalog główny zawartości na ścieżkę zwróconą przez GetCurrentDirectory.
  • Ładuje konfigurację hosta z:
    • Zmienne środowiskowe poprzedzone prefiksem DOTNET_.
    • Argumenty wiersza polecenia.
  • Ładuje konfigurację aplikacji z:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Wpisy tajne użytkownika w przypadku aplikacji działającej w środowisku Development.
    • Zmienne środowiskowe.
    • Argumenty wiersza polecenia.
  • Dodaje następujących dostawców rejestrowania :
    • Konsola
    • Debugowanie
    • EventSource
    • EventLog (tylko w przypadku uruchamiania w systemie Windows)
  • Włącza walidację zakresu i walidację zależności, gdy środowisko jest programowaniem.

Metoda ConfigureWebHostDefaults:

Sekcje Ustawienia dla wszystkich typów aplikacji i Ustawienia dla aplikacji internetowych w dalszej części tego artykułu pokazują, jak zastąpić domyślne ustawienia konstruktora.

Usługi dostarczane przez platformę

Następujące usługi są rejestrowane automatycznie:

Aby uzyskać więcej informacji na temat usług udostępnianych przez platformę, zobacz Wstrzykiwanie zależności w programie ASP.NET Core.

IHostApplicationLifetime

Wstrzykuj usługę IHostApplicationLifetime (dawniej IApplicationLifetime) do dowolnej klasy, aby obsługiwać zadania po uruchomieniu i bezproblemowym zamykaniu. Trzy właściwości interfejsu to tokeny anulowania używane do rejestrowania metod obsługi uruchamiania aplikacji i zatrzymywania aplikacji. Interfejs zawiera również metodę StopApplication .

W poniższym przykładzie przedstawiono implementację IHostedService rejestrującą IHostApplicationLifetime zdarzenia:

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

Implementacja IHostLifetime steruje, gdy host zostanie uruchomiony i zatrzymany. Używana jest ostatnia zarejestrowana implementacja.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime to domyślna IHostLifetime implementacja. ConsoleLifetime:

IHostEnvironment

Wstrzyknąć usługę IHostEnvironment do klasy, aby uzyskać informacje o następujących ustawieniach:

Aplikacje internetowe implementują IWebHostEnvironment interfejs, który dziedziczy IHostEnvironment i dodaje element WebRootPath.

Konfiguracja hosta

Konfiguracja hosta jest używana dla właściwości implementacji IHostEnvironment .

Konfiguracja hosta jest dostępna z HostBuilderContext.Configuration wewnątrz ConfigureAppConfigurationprogramu . HostBuilderContext.Configuration Po ConfigureAppConfigurationpliku zostanie zastąpiony konfiguracją aplikacji.

Aby dodać konfigurację hosta, wywołaj metodę ConfigureHostConfiguration .IHostBuilder ConfigureHostConfiguration można wywołać wiele razy z wynikami dodawania. Host używa dowolnej opcji ustawia ostatnią wartość dla danego klucza.

Dostawca zmiennej środowiskowej z prefiksem DOTNET_ i argumentami wiersza polecenia są uwzględniane przez CreateDefaultBuilderelement . W przypadku aplikacji internetowych dodawany jest dostawca zmiennych środowiskowych z prefiksem ASPNETCORE_ . Prefiks jest usuwany po odczytaniu zmiennych środowiskowych. Na przykład wartość ASPNETCORE_ENVIRONMENT zmiennej środowiskowej dla parametru staje się wartością konfiguracji hosta dla environment klucza.

Poniższy przykład tworzy konfigurację hosta:

// 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);
    });

Konfiguracja aplikacji

Konfiguracja aplikacji jest tworzona przez wywołanie ConfigureAppConfiguration metody .IHostBuilder ConfigureAppConfiguration można wywołać wiele razy z wynikami dodawania. Aplikacja używa dowolnej opcji ustawia ostatnią wartość dla danego klucza.

Konfiguracja utworzona przez ConfigureAppConfiguration jest dostępna na HostBuilderContext.Configuration potrzeby kolejnych operacji i jako usługi z di. Konfiguracja hosta jest również dodawana do konfiguracji aplikacji.

Aby uzyskać więcej informacji, zobacz Konfiguracja na platformie ASP.NET Core.

Ustawienia dla wszystkich typów aplikacji

W tej sekcji wymieniono ustawienia hosta, które mają zastosowanie zarówno do obciążeń HTTP, jak i innych niż HTTP. Domyślnie zmienne środowiskowe używane do konfigurowania tych ustawień mogą mieć DOTNET_ prefiks lub ASPNETCORE_ , który jest wyświetlany w poniższej konfiguracji dla symbolu zastępczego {PREFIX_} .

ApplicationName

Właściwość IHostEnvironment.ApplicationName jest ustawiana z konfiguracji hosta podczas budowy hosta.

Klucz: applicationName
Typ: string
Ustawienie domyślne: nazwa zestawu, który zawiera punkt wejścia aplikacji.
Zmienna środowiskowa: {PREFIX_}APPLICATIONNAME

Aby ustawić tę wartość, użyj zmiennej środowiskowej.

ContentRoot

Właściwość IHostEnvironment.ContentRootPath określa, gdzie host rozpoczyna wyszukiwanie plików zawartości. Jeśli ścieżka nie istnieje, uruchomienie hosta nie powiedzie się.

Klucz: contentRoot
Typ: string
Ustawienie domyślne: folder, w którym znajduje się zestaw aplikacji.
Zmienna środowiskowa: {PREFIX_}CONTENTROOT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseContentRoot :IHostBuilder

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

Aby uzyskać więcej informacji, zobacz:

NazwaŚrodowiska

Właściwość IHostEnvironment.EnvironmentName można ustawić na dowolną wartość. Zdefiniowane przez platformę wartości obejmują Development, Stagingi Production. Wartości nie są uwzględniane w wielkości liter.

Klucz: environment
Typ: string
Ustawienie domyślne: Production
Zmienna środowiskowa: {PREFIX_}ENVIRONMENT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseEnvironment :IHostBuilder

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

ShutdownTimeout

HostOptions.ShutdownTimeout ustawia limit czasu dla elementu StopAsync. Wartość domyślna to pięć sekund. W okresie przekroczenia limitu czasu host:

Jeśli okres przekroczenia limitu czasu wygaśnie przed zatrzymaniem wszystkich hostowanych usług, pozostałe aktywne usługi zostaną zatrzymane po zamknięciu aplikacji. Usługi są zatrzymywane nawet wtedy, gdy nie zakończyły przetwarzania. Jeśli usługi wymagają więcej czasu na zatrzymanie, zwiększ limit czasu.

Klucz: shutdownTimeoutSeconds
Typ: int
Ustawienie domyślne: 5 sekund
Zmienna środowiskowa: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub skonfiguruj wartość HostOptions. Poniższy przykład ustawia limit czasu na 20 sekund:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

Ustawienia aplikacji internetowych

Niektóre ustawienia hosta dotyczą tylko obciążeń HTTP. Domyślnie zmienne środowiskowe używane do konfigurowania tych ustawień mogą mieć DOTNET_ prefiks lub ASPNETCORE_ .

Dostępne są metody IWebHostBuilder rozszerzenia dla tych ustawień. Przykłady kodu pokazujące sposób wywoływania metod rozszerzenia zakładają webBuilder , że jest wystąpieniem IWebHostBuilderklasy , jak w poniższym przykładzie:

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

CaptureStartupErrors

W przypadku false, błędy podczas uruchamiania powodują zamknięcie hosta. Gdy truehost przechwytuje wyjątki podczas uruchamiania i próbuje uruchomić serwer.

Klucz: captureStartupErrors
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: wartość domyślna to false , chyba że aplikacja jest uruchamiana za usługami Kestrel IIS, gdzie wartość domyślna to true.
Zmienna środowiskowa: {PREFIX_}CAPTURESTARTUPERRORS

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

Szczegółowe błędy

Po włączeniu lub w przypadku środowiska Developmentaplikacja przechwytuje szczegółowe błędy.

Klucz: detailedErrors
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}DETAILEDERRORS

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HostingStartupAssemblies

Rozdzielany średnikami ciąg hostowania zestawów startowych do załadowania podczas uruchamiania. Mimo że wartość konfiguracji jest domyślnie pusta, zestawy uruchamiania hostingu zawsze zawierają zestaw aplikacji. Podczas hostowania zestawów uruchamiania są one dodawane do zestawu aplikacji do ładowania, gdy aplikacja kompiluje swoje typowe usługi podczas uruchamiania.

Klucz: hostingStartupAssemblies
Typ: string
Ustawienie domyślne: Pusty ciąg
Zmienna środowiskowa: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HostingStartupExcludeAssemblies

Rozdzielany średnikami ciąg hostowania zestawów startowych do wykluczenia podczas uruchamiania.

Klucz: hostingStartupExcludeAssemblies
Typ: string
Ustawienie domyślne: Pusty ciąg
Zmienna środowiskowa: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

HTTPS_Port

Port przekierowania HTTPS. Używany w wymuszaniu protokołu HTTPS.

Klucz: https_port
Typ: string
Ustawienie domyślne: wartość domyślna nie jest ustawiona.
Zmienna środowiskowa: {PREFIX_}HTTPS_PORT

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

PreferujhostowanieUrls

Wskazuje, czy host powinien nasłuchiwać adresów URL skonfigurowanych przy IWebHostBuilder użyciu zamiast tych adresów URL skonfigurowanych przy użyciu implementacji IServer .

Klucz: preferHostingUrls
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}PREFERHOSTINGURLS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Zapobiega automatycznemu ładowaniu zestawów uruchamiania, w tym hostowania zestawów uruchamiania skonfigurowanych przez zestaw aplikacji. Więcej informacji można znaleźć w temacie Korzystanie z hostowania zestawów startowych na platformie ASP.NET Core.

Klucz: preventHostingStartup
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}PREVENTHOSTINGSTARTUP

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseSetting :

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

StartupAssembly

Zestaw do wyszukiwania Startup klasy.

Klucz: startupAssembly
Typ: string
Ustawienie domyślne: zestaw aplikacji
Zmienna środowiskowa: {PREFIX_}STARTUPASSEMBLY

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseStartup. UseStartup może przyjmować nazwę zestawu (string) lub typ (TStartup). Jeśli wywoływano wiele UseStartup metod, ostatni z nich ma pierwszeństwo.

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

SuppressStatusMessages

Po włączeniu pomija hostowanie komunikatów o stanie uruchamiania.

Klucz: suppressStatusMessages
Typ: bool (true/1 lub false/0)
Ustawienie domyślne: false
Zmienna środowiskowa: {PREFIX_}SUPPRESSSTATUSMESSAGES

Aby ustawić tę wartość, użyj konfiguracji lub wywołaj metodę UseSetting:

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

Adresy URL

Rozdzielana średnikami lista adresów IP lub adresów hostów z portami i protokołami, na których serwer powinien nasłuchiwać żądań. Na przykład http://localhost:123. Użyj "*", aby wskazać, że serwer powinien nasłuchiwać żądań na dowolnym adresie IP lub nazwie hosta przy użyciu określonego portu i protokołu (na przykład http://*:5000). Protokół (http:// lub https://) musi być dołączony do każdego adresu URL. Obsługiwane formaty różnią się między serwerami.

Klucz: urls
Typ: string
Ustawienie domyślne: http://localhost:5000 i https://localhost:5001
Zmienna środowiskowa: {PREFIX_}URLS

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseUrls:

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel ma własny interfejs API konfiguracji punktu końcowego. Aby uzyskać więcej informacji, zobacz Kestrel serwer internetowy w programie ASP.NET Core.

WebRoot

Właściwość IWebHostEnvironment.WebRootPath określa ścieżkę względną do zasobów statycznych aplikacji. Jeśli ścieżka nie istnieje, zostanie użyty dostawca plików bez operacji.

Klucz: webroot
Typ: string
Ustawienie domyślne: wartość domyślna to wwwroot. Ścieżka do katalogu {content root}/wwwroot musi istnieć.
Zmienna środowiskowa: {PREFIX_}WEBROOT

Aby ustawić tę wartość, użyj zmiennej środowiskowej lub wywołaj metodę UseWebRoot :IWebHostBuilder

webBuilder.UseWebRoot("public");

Aby uzyskać więcej informacji, zobacz:

Zarządzanie okresem istnienia hosta

Wywołaj metody na wbudowanej IHost implementacji, aby uruchomić i zatrzymać aplikację. Te metody mają wpływ na wszystkie IHostedService implementacje zarejestrowane w kontenerze usługi.

Różnica między metodami Run* i Start* polega na tym, że Run* metody oczekują na ukończenie hosta przed zwróceniem, podczas gdy Start* metody są zwracane natychmiast. Metody Run* są zwykle używane w aplikacjach konsoli, podczas gdy Start* metody są zwykle używane w długotrwałych usługach.

Uruchom

Run uruchamia aplikację i blokuje wątek wywołujący do momentu zamknięcia hosta.

RunAsync

RunAsync uruchamia aplikację i zwraca wartość Task , która zostanie ukończona po wyzwoleniu tokenu anulowania lub zamknięcia.

RunConsoleAsync

RunConsoleAsync włącza obsługę konsoli, kompiluje i uruchamia hosta oraz czeka na zamknięcie Ctrl+C/SIGINT (Windows), +C (macOS) lub SIGTERM.

Rozpocznij

Start uruchamia hosta synchronicznie.

StartAsync

StartAsync uruchamia hosta i zwraca wartość Task , która zostanie ukończona po wyzwoleniu tokenu anulowania lub zamknięcia.

WaitForStartAsync parametr jest wywoływany na początku StartAsyncciągu , który czeka, aż zostanie ukończony przed kontynuowaniem. Ta metoda może służyć do opóźniania uruchamiania do momentu zasygnaliowania zdarzenia zewnętrznego.

StopAsync

StopAsync próbuje zatrzymać hosta w ramach podanego limitu czasu.

WaitForShutdown

WaitForShutdownblokuje wątek wywołujący do momentu wyzwolenia zamknięcia przez interfejs IHostLifetime, na przykład za pomocą Ctrl+C/SIGINT (Windows), ⌘+C (macOS) lub SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync Zwraca wartość Task , która kończy się po wyzwoleniu zamknięcia za pośrednictwem danego tokenu i wywołuje metodę StopAsync.

Kontrola zewnętrzna

Bezpośrednią kontrolę nad okresem istnienia hosta można osiągnąć przy użyciu metod, które mogą być wywoływane zewnętrznie:

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));
        }
    }
}

Dodatkowe zasoby