Host ogólny platformy .NET w programie ASP.NET Core
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
IHostedServiceImplementacje
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.
- Zmienne środowiskowe poprzedzone prefiksem
- Ł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_ENABLEDjest równetrue. - 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.
W dalszej części tego artykułu Ustawienia dla wszystkich typów aplikacji i Ustawienia dla aplikacji internetowych pokazano, 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:
- Nasłuchuje klawiszy Ctrl+C/SIGINT (Windows), ⌘+C (macOS) lub SIGTERM i wywołuje StopApplication metodę uruchamiania procesu zamykania.
- Odblokuje rozszerzenia, takie jak RunAsync i WaitForShutdownAsync.
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 pięć sekund. W okresie przekroczenia limitu czasu host:
- Wyzwalacze IHostApplicationLifetime.ApplicationStopping.
- Próbuje zatrzymać hostowane usługi i rejestrować błędy dla usług, które nie mogą się zatrzymać.
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 dla 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
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 klawiszy 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ą klawiszy 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
IHostedServiceImplementacje
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
CreateHostBuilderi skonfigurowania obiektu konstruktora. - Wywołuje
Buildmetody iRunw 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.
- Zmienne środowiskowe poprzedzone prefiksem
- Ł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_ENABLEDjest równetrue. - 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.
W dalszej części tego artykułu Ustawienia dla wszystkich typów aplikacji i Ustawienia dla aplikacji internetowych pokazano, 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:
- Nasłuchuje klawiszy Ctrl+C/SIGINT (Windows), ⌘+C (macOS) lub SIGTERM i wywołuje StopApplication metodę uruchamiania procesu zamykania.
- Odblokuje rozszerzenia, takie jak RunAsync i WaitForShutdownAsync.
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:
- Wyzwalacze IHostApplicationLifetime.ApplicationStopping.
- Próbuje zatrzymać hostowane usługi i rejestrować błędy dla usług, które nie mogą się zatrzymać.
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 dla 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 klawiszy 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ą klawiszy 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
IHostedServiceImplementacje
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
CreateHostBuilderi skonfigurowania obiektu konstruktora. - Wywołuje
Buildmetody iRunw 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.
- Zmienne środowiskowe poprzedzone prefiksem
- Ł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ć domyślne opcje serwera, zobacz Kestrel serwer internetowy w programie ASP.NET Core.
- Dodaje oprogramowanie pośredniczące filtrowania hostów.
- Dodaje oprogramowanie pośredniczące Nagłówki przekazane, jeśli
ASPNETCORE_FORWARDEDHEADERS_ENABLEDjest równetrue. - 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.
W dalszej części tego artykułu Ustawienia dla wszystkich typów aplikacji i Ustawienia dla aplikacji internetowych pokazano, 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:
- Nasłuchuje klawiszy Ctrl+C/SIGINT (Windows), ⌘+C (macOS) lub SIGTERM i wywołuje StopApplication metodę uruchamiania procesu zamykania.
- Odblokuje rozszerzenia, takie jak RunAsync i WaitForShutdownAsync.
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:
- Wyzwalacze IHostApplicationLifetime.ApplicationStopping.
- Próbuje zatrzymać hostowane usługi i rejestrować błędy dla usług, które nie mogą się zatrzymać.
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 dla 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 klawiszy 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ą klawiszy 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
- Zadania w tle z hostowanymi usługami w ASP.NET Core
- Link usługi GitHub do źródła hosta ogólnego
Uwaga
Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla