Host internetowy platformy 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.
Aplikacje ASP.NET Core konfigurują i uruchamiają hosta. Host jest odpowiedzialny za zarządzanie uruchamianiem i okresem istnienia aplikacji. Co najmniej host konfiguruje serwer i potok przetwarzania żądań. Host może również skonfigurować rejestrowanie, wstrzykiwanie zależności i konfigurację.
W tym artykule opisano hosta sieci Web, który pozostaje dostępny tylko w celu zapewnienia zgodności z poprzednimi wersjami. Szablony ASP.NET Core tworzą WebApplicationBuilder szablony i WebApplication, które są zalecane w przypadku aplikacji internetowych. Aby uzyskać więcej informacji o systemach WebApplicationBuilder
i WebApplication
, zobacz Migrowanie z platformy ASP.NET Core 5.0 do 6.0
Konfigurowanie hosta
Utwórz hosta przy użyciu wystąpienia IWebHostBuilderklasy . Jest to zwykle wykonywane w punkcie wejścia aplikacji, czyli metodzie Main
w Program.cs
pliku . Typowe wywołania CreateDefaultBuilder aplikacji umożliwiające rozpoczęcie konfigurowania hosta:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
Kod, który wywołuje CreateDefaultBuilder
, znajduje się w metodzie o nazwie CreateWebHostBuilder
, która oddziela go od kodu, który Main
wywołuje Run
obiekt konstruktora. Ta separacja jest wymagana, jeśli używasz narzędzi Entity Framework Core. Narzędzia oczekują znalezienia CreateWebHostBuilder
metody, którą mogą wywołać w czasie projektowania w celu skonfigurowania hosta bez uruchamiania aplikacji. Alternatywą jest zaimplementowanie IDesignTimeDbContextFactory
elementu . Aby uzyskać więcej informacji, zobacz Design-time DbContext Creation (Tworzenie elementu DbContext w czasie projektowania).
Metoda CreateDefaultBuilder
wykonuje następujące zadania:
- Konfiguruje Kestrel serwer jako serwer internetowy przy użyciu dostawców konfiguracji hostingu aplikacji. Kestrel Aby uzyskać opcje domyślne serwera, zobacz Konfigurowanie opcji dla serwera internetowego ASP.NET CoreKestrel.
- Ustawia katalog główny zawartości na ścieżkę zwróconą przez Directory.GetCurrentDirectory.
- Ładuje konfigurację hosta z:
- Zmienne środowiskowe poprzedzone prefiksem
ASPNETCORE_
(na przykładASPNETCORE_ENVIRONMENT
). - Argumenty wiersza polecenia.
- Zmienne środowiskowe poprzedzone prefiksem
- Ładuje konfigurację aplikacji w następującej kolejności:
appsettings.json
.appsettings.{Environment}.json
.- Wpisy tajne użytkownika, gdy aplikacja jest uruchamiana w
Development
środowisku przy użyciu zestawu wpisu. - Zmienne środowiskowe.
- Argumenty wiersza polecenia.
- Konfiguruje rejestrowanie dla konsoli i danych wyjściowych debugowania. Rejestrowanie obejmuje reguły filtrowania dzienników określone w sekcji Konfiguracja rejestrowania pliku
appsettings.json
lubappsettings.{Environment}.json
. - W przypadku uruchamiania za usługami IIS przy użyciu modułu podstawowego ASP.NET
CreateDefaultBuilder
włącza integrację usług IIS, która konfiguruje podstawowy adres i port aplikacji. Integracja z usługami IIS konfiguruje również aplikację w celu przechwytywania błędów uruchamiania. Aby uzyskać opcje domyślne usług IIS, zobacz Host ASP.NET Core w systemie Windows z usługami IIS. - Ustawia ServiceProviderOptions.ValidateScopes wartość ,
true
jeśli środowisko aplikacji to Programowanie. Aby uzyskać więcej informacji, zobacz Walidacja zakresu.
Konfigurację zdefiniowaną przez CreateDefaultBuilder
program można zastąpić i rozszerzyć za pomocą ConfigureAppConfigurationmetod , ConfigureLoggingi innych metod rozszerzeń programu IWebHostBuilder. Poniżej przedstawiono kilka przykładów:
ConfigureAppConfiguration służy do określania dodatkowych
IConfiguration
dla aplikacji. NastępująceConfigureAppConfiguration
wywołanie dodaje delegata w celu uwzględnienia konfiguracji aplikacji wappsettings.xml
pliku.ConfigureAppConfiguration
może być wywoływany wiele razy. Należy pamiętać, że ta konfiguracja nie ma zastosowania do hosta (na przykład adresów URL serwera lub środowiska). Zobacz sekcję Wartości konfiguracji hosta.WebHost.CreateDefaultBuilder(args) .ConfigureAppConfiguration((hostingContext, config) => { config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true); }) ...
Następujące
ConfigureLogging
wywołanie dodaje delegata w celu skonfigurowania minimalnego poziomu rejestrowania (SetMinimumLevel) na LogLevel.Warning. To ustawienie zastępuje ustawienia w programieappsettings.Development.json
(LogLevel.Debug
) iappsettings.Production.json
(LogLevel.Error
) skonfigurowanym przezCreateDefaultBuilder
program .ConfigureLogging
może być wywoływany wiele razy.WebHost.CreateDefaultBuilder(args) .ConfigureLogging(logging => { logging.SetMinimumLevel(LogLevel.Warning); }) ...
Następujące wywołanie w celu
ConfigureKestrel
zastąpienia domyślnego elementu Limits.MaxRequestBodySize o wartości 30 000 000 bajtów ustanowionych podczas Kestrel konfigurowania przezCreateDefaultBuilder
program :WebHost.CreateDefaultBuilder(args) .ConfigureKestrel((context, options) => { options.Limits.MaxRequestBodySize = 20000000; });
Katalog główny zawartości określa, gdzie host wyszukuje pliki zawartości, takie jak pliki widoku MVC. Po uruchomieniu aplikacji z folderu głównego projektu folder główny projektu jest używany jako katalog główny zawartości. Jest to wartość domyślna używana w programie Visual Studio i nowych szablonach dotnet.
Aby uzyskać więcej informacji na temat konfiguracji aplikacji, zobacz Configuration in ASP.NET Core (Konfiguracja w programie ASP.NET Core).
Uwaga
Alternatywą dla używania metody statycznej CreateDefaultBuilder
jest utworzenie hosta na podstawie WebHostBuilder jest obsługiwane podejście z platformą ASP.NET Core 2.x.
Podczas konfigurowania hosta Configure można podać metody i ConfigureServices . Jeśli określono klasę Startup
, musi ona zdefiniować metodę Configure
. Aby uzyskać więcej informacji, zobacz Uruchamianie aplikacji na platformie ASP.NET Core. Wiele wywołań dołączania ConfigureServices
do siebie. Wiele wywołań do Configure
lub UseStartup
zastąp WebHostBuilder
poprzednie ustawienia.
Wartości konfiguracji hosta
WebHostBuilder opiera się na następujących podejściach do ustawiania wartości konfiguracji hosta:
- Konfiguracja konstruktora hostów, która zawiera zmienne środowiskowe w formacie
ASPNETCORE_{configurationKey}
. Na przykładASPNETCORE_ENVIRONMENT
. - Rozszerzenia, takie jak UseContentRoot i UseConfiguration (zobacz sekcję Przesłoń konfigurację).
- UseSetting i skojarzony klucz. Podczas ustawiania wartości za pomocą
UseSetting
parametru wartość jest ustawiana jako ciąg niezależnie od typu.
Host używa dowolnej opcji ustawia ostatnią wartość. Aby uzyskać więcej informacji, zobacz Zastępowanie konfiguracji w następnej sekcji.
Klucz aplikacji (nazwa)
Właściwość IWebHostEnvironment.ApplicationName
jest ustawiana automatycznie, gdy UseStartup obiekt lub Configure jest wywoływany podczas budowy hosta. Wartość jest ustawiona na nazwę zestawu zawierającego punkt wejścia aplikacji. Aby jawnie ustawić wartość, użyj polecenia WebHostDefaults.ApplicationKey:
Klucz: applicationName
Typ: ciąg
Ustawienie domyślne: nazwa zestawu zawierającego punkt wejścia aplikacji.
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_APPLICATIONNAME
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")
Przechwyć błędy uruchamiania
To ustawienie steruje przechwytywaniem błędów uruchamiania.
Klucz: captureStartupErrors
Typ: bool (true
lub 1
)
Ustawienie domyślne: wartość domyślna to false
, chyba że aplikacja jest uruchamiana za usługami Kestrel IIS, gdzie wartość domyślna to true
.
Ustaw przy użyciu: CaptureStartupErrors
Zmienna środowiskowa: ASPNETCORE_CAPTURESTARTUPERRORS
W przypadku false
, błędy podczas uruchamiania powodują zamknięcie hosta. Gdy true
host przechwytuje wyjątki podczas uruchamiania i próbuje uruchomić serwer.
WebHost.CreateDefaultBuilder(args)
.CaptureStartupErrors(true)
Katalog główny zawartości
To ustawienie określa, gdzie ASP.NET Core rozpoczyna wyszukiwanie plików zawartości.
Klucz: contentRoot
Typ: ciąg
Ustawienie domyślne: domyślnie jest to folder, w którym znajduje się zestaw aplikacji.
Ustaw przy użyciu: UseContentRoot
Zmienna środowiskowa: ASPNETCORE_CONTENTROOT
Główny katalog zawartości jest również używany jako ścieżka podstawowa katalogu głównego sieci Web. Jeśli ścieżka główna zawartości nie istnieje, uruchomienie hosta nie powiedzie się.
WebHost.CreateDefaultBuilder(args)
.UseContentRoot("c:\\<content-root>")
Aby uzyskać więcej informacji, zobacz:
Szczegółowe błędy
Określa, czy należy przechwycić szczegółowe błędy.
Klucz: detailsErrors
Typ: bool (true
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_DETAILEDERRORS
Po włączeniu (lub po ustawieniu środowiska na Development
wartość ) aplikacja przechwytuje szczegółowe wyjątki.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
Środowisko
Ustawia środowisko aplikacji.
Klucz: środowisko
Typ: ciąg
Ustawienie domyślne: Produkcja
Ustaw przy użyciu: UseEnvironment
Zmienna środowiskowa: ASPNETCORE_ENVIRONMENT
Środowisko można ustawić na dowolną wartość. Zdefiniowane przez platformę wartości obejmują Development
, Staging
i Production
. W wartościach nie jest uwzględniana wielkość liter. Domyślnie środowisko jest odczytywane ze zmiennej środowiskowej ASPNETCORE_ENVIRONMENT
. W przypadku korzystania z programu Visual Studio zmienne środowiskowe mogą być ustawiane w launchSettings.json
pliku. Więcej informacji można znaleźć w temacie Używanie wielu środowisk na platformie ASP.NET Core.
WebHost.CreateDefaultBuilder(args)
.UseEnvironment(EnvironmentName.Development)
Hostowanie zestawów startowych
Ustawia zestawy uruchamiania aplikacji hostowania.
Klucz: hostingStartupAssemblies
Typ: ciąg
Ustawienie domyślne: Pusty ciąg
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_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.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")
HTTPS Port
Ustaw port przekierowania HTTPS. Używany w wymuszaniu protokołu HTTPS.
Klucz: https_port
Typ: ciąg
Ustawienie domyślne: wartość domyślna nie jest ustawiona.
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_HTTPS_PORTS
WebHost.CreateDefaultBuilder(args)
.UseSetting("https_port", "8080")
Hostowanie zestawów wykluczania uruchamiania
Rozdzielany średnikami ciąg hostowania zestawów startowych do wykluczenia podczas uruchamiania.
Klucz: hostingStartupExcludeAssemblies
Typ: ciąg
Ustawienie domyślne: Pusty ciąg
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")
Preferuj adresy URL hostingu
Wskazuje, czy host powinien nasłuchiwać adresów URL skonfigurowanych przy WebHostBuilder
użyciu wartości zamiast skonfigurowanych przy użyciu implementacji IServer
.
Klucz: preferujHostingUrls
Typ: bool (true
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: PreferHostingUrls
Zmienna środowiskowa: ASPNETCORE_PREFERHOSTINGURLS
WebHost.CreateDefaultBuilder(args)
.PreferHostingUrls(true)
Zapobieganie uruchamianiu hostingu
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
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_PREVENTHOSTINGSTARTUP
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")
Adresy URL serwera
Wskazuje adresy IP lub adresy hostów z portami i protokołami, na których serwer powinien nasłuchiwać żądań.
Klucz: adresy URL
Typ: ciąg
Ustawienie domyślne: http://localhost:5000
Ustaw przy użyciu: UseUrls
Zmienna środowiskowa: ASPNETCORE_URLS
Ustaw wartość rozdzielaną średnikami (;) listę prefiksów adresów URL, na które serwer powinien odpowiadać. 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.
WebHost.CreateDefaultBuilder(args)
.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.
Limit czasu zamknięcia
Określa czas oczekiwania na zamknięcie hosta sieci Web.
Klucz: shutdownTimeoutSeconds
Typ: int
Ustawienie domyślne: 5
Ustaw przy użyciu: UseShutdownTimeout
Zmienna środowiskowa: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS
Mimo że klucz akceptuje int z UseSetting
(na przykład .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")
), UseShutdownTimeout metoda rozszerzenia przyjmuje TimeSpanwartość .
W okresie przekroczenia limitu czasu hostowanie:
- Wyzwalacze IApplicationLifetime.ApplicationStopping.
- Próbuje zatrzymać hostowane usługi i rejestrować wszelkie błędy dotyczące 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ą dodatkowego czasu do zatrzymania, zwiększ limit czasu.
WebHost.CreateDefaultBuilder(args)
.UseShutdownTimeout(TimeSpan.FromSeconds(10))
Zestaw startowy
Określa zestaw do wyszukiwania Startup
klasy.
Klucz: startupAssembly
Typ: ciąg
Ustawienie domyślne: zestaw aplikacji
Ustaw przy użyciu: UseStartup
Zmienna środowiskowa: ASPNETCORE_STARTUPASSEMBLY
Można odwołać się do zestawu według nazwy (string
) lub typu (TStartup
). Jeśli wywoływano wiele UseStartup
metod, ostatni z nich ma pierwszeństwo.
WebHost.CreateDefaultBuilder(args)
.UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
.UseStartup<TStartup>()
Internetowy katalog główny
Ustawia ścieżkę względną do zasobów statycznych aplikacji.
Klucz: webroot
Typ: ciąg
Ustawienie domyślne: wartość domyślna to wwwroot
. Ścieżka do katalogu {content root}/wwwroot musi istnieć. Jeśli ścieżka nie istnieje, zostanie użyty dostawca plików bez operacji.
Ustaw przy użyciu: UseWebRoot
Zmienna środowiskowa: ASPNETCORE_WEBROOT
WebHost.CreateDefaultBuilder(args)
.UseWebRoot("public")
Aby uzyskać więcej informacji, zobacz:
Przesłoń konfigurację
Konfigurowanie hosta sieci Web przy użyciu konfiguracji . W poniższym przykładzie konfiguracja hosta jest opcjonalnie określona hostsettings.json
w pliku. Każda konfiguracja załadowana z hostsettings.json
pliku może zostać zastąpiona przez argumenty wiersza polecenia. Wbudowana konfiguracja (w systemie config
) służy do konfigurowania hosta za pomocą UseConfigurationpolecenia . IWebHostBuilder
konfiguracja jest dodawana do konfiguracji aplikacji, ale odwrotnie nie ma to wpływuConfigureAppConfiguration
na konfigurację IWebHostBuilder
.
Przesłanianie konfiguracji dostarczonej przez UseUrls
hostsettings.json
element config first, command-line argument config sekundy:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
var config = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("hostsettings.json", optional: true)
.AddCommandLine(args)
.Build();
return WebHost.CreateDefaultBuilder(args)
.UseUrls("http://*:5000")
.UseConfiguration(config)
.Configure(app =>
{
app.Run(context =>
context.Response.WriteAsync("Hello, World!"));
});
}
}
hostsettings.json
:
{
urls: "http://*:5005"
}
Uwaga
UseConfiguration Kopiuje tylko klucze z dostarczonego IConfiguration
do konfiguracji konstruktora hosta. W związku z tym ustawienie reloadOnChange: true
dla JSplików ustawień ON, INI i XML nie ma wpływu.
Aby określić uruchomienie hosta w określonym adresie URL, żądana wartość może zostać przekazana z wiersza polecenia podczas wykonywania polecenia dotnet run. Argument wiersza polecenia zastępuje urls
wartość z hostsettings.json
pliku, a serwer nasłuchuje na porcie 8080:
dotnet run --urls "http://*:8080"
Zarządzanie hostem
Run
Metoda Run
uruchamia aplikację internetową i blokuje wątek wywołujący do czasu zamknięcia hosta:
host.Run();
Uruchom
Uruchom hosta w sposób nieblokjący, wywołując jego Start
metodę:
using (host)
{
host.Start();
Console.ReadLine();
}
Jeśli lista adresów URL jest przekazywana do Start
metody, nasłuchuje określonych adresów URL:
var urls = new List<string>()
{
"http://*:5000",
"http://localhost:5001"
};
var host = new WebHostBuilder()
.UseKestrel()
.UseStartup<Startup>()
.Start(urls.ToArray());
using (host)
{
Console.ReadLine();
}
Aplikacja może zainicjować i uruchomić nowego hosta przy użyciu wstępnie skonfigurowanych wartości domyślnych CreateDefaultBuilder
przy użyciu statycznej metody wygody. Te metody uruchamiają serwer bez danych wyjściowych konsoli i zaczekają WaitForShutdown na przerwę (Ctrl-C/SIGINT lub SIGTERM):
Start(RequestDelegate app)
Zacznij od elementu RequestDelegate
:
using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Prześlij żądanie w przeglądarce, aby http://localhost:5000
otrzymać odpowiedź "Hello World!", WaitForShutdown
dopóki nie zostanie wystawiona przerwa (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
Start(adres URL ciągu, aplikacja RequestDelegate)
Zacznij od adresu URL i RequestDelegate
:
using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Generuje taki sam wynik jak Start(RequestDelegate app), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
Start(Action<IRouteBuilder routeBuilder> )
Użyj wystąpienia IRouteBuilder
programu (Microsoft.AspNetCore.Routing), aby użyć oprogramowania pośredniczącego routingu:
using (var host = WebHost.Start(router => router
.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Użyj następujących żądań przeglądarki w przykładzie:
Zażądaj | Response |
---|---|
http://localhost:5000/hello/Martin |
Witaj, Martin! |
http://localhost:5000/buenosdias/Catrina |
Buenos dias, Catrina! |
http://localhost:5000/throw/ooops! |
Zgłasza wyjątek z ciągiem "ooops!" |
http://localhost:5000/throw |
Zgłasza wyjątek z ciągiem "Uh oh!" |
http://localhost:5000/Sante/Kevin |
Sante, Kevin! |
http://localhost:5000 |
Hello World! |
WaitForShutdown
blokuje do momentu wydania przerwy (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
Start(adres URL ciągu, akcja<IRouteBuilder routeBuilder> )
Użyj adresu URL i wystąpienia elementu IRouteBuilder
:
using (var host = WebHost.Start("http://localhost:8080", router => router
.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Generuje taki sam wynik jak Start(Action<IRouteBuilder routeBuilder> ), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
StartWith(Action<IApplicationBuilder> app)
Podaj pełnomocnika, aby skonfigurować element IApplicationBuilder
:
using (var host = WebHost.StartWith(app =>
app.Use(next =>
{
return async context =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Prześlij żądanie w przeglądarce, aby http://localhost:5000
otrzymać odpowiedź "Hello World!", WaitForShutdown
dopóki nie zostanie wystawiona przerwa (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
StartWith(adres URL ciągu, aplikacja Action<IApplicationBuilder> )
Podaj adres URL i pełnomocnika do skonfigurowania elementu IApplicationBuilder
:
using (var host = WebHost.StartWith("http://localhost:8080", app =>
app.Use(next =>
{
return async context =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Tworzy taki sam wynik jak StartWith(Action<IApplicationBuilder> app), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
IWebHostEnvironment, interfejs
Interfejs IWebHostEnvironment
zawiera informacje o środowisku hostingu internetowego aplikacji. Użyj iniekcji konstruktora, aby uzyskać IWebHostEnvironment
metodę w celu użycia jej właściwości i metod rozszerzenia:
public class CustomFileReader
{
private readonly IWebHostEnvironment _env;
public CustomFileReader(IWebHostEnvironment env)
{
_env = env;
}
public string ReadFile(string filePath)
{
var fileProvider = _env.WebRootFileProvider;
// Process the file here
}
}
Podejście oparte na konwencji może służyć do konfigurowania aplikacji podczas uruchamiania na podstawie środowiska. Alternatywnie należy wstrzyknąć element do konstruktora IWebHostEnvironment
Startup
do użycia w ConfigureServices
pliku :
public class Startup
{
public Startup(IWebHostEnvironment env)
{
HostingEnvironment = env;
}
public IWebHostEnvironment HostingEnvironment { get; }
public void ConfigureServices(IServiceCollection services)
{
if (HostingEnvironment.IsDevelopment())
{
// Development configuration
}
else
{
// Staging/Production configuration
}
var contentRootPath = HostingEnvironment.ContentRootPath;
}
}
Uwaga
Oprócz IsDevelopment
metody IWebHostEnvironment
rozszerzenia oferuje IsStaging
metody , IsProduction
i IsEnvironment(string environmentName)
. Więcej informacji można znaleźć w temacie Używanie wielu środowisk na platformie ASP.NET Core.
Usługę IWebHostEnvironment
można również wstrzyknąć bezpośrednio do Configure
metody konfigurowania potoku przetwarzania:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
// In Development, use the Developer Exception Page
app.UseDeveloperExceptionPage();
}
else
{
// In Staging/Production, route exceptions to /error
app.UseExceptionHandler("/error");
}
var contentRootPath = env.ContentRootPath;
}
IWebHostEnvironment
można wstrzyknąć do Invoke
metody podczas tworzenia niestandardowego oprogramowania pośredniczącego:
public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
// Configure middleware for Development
}
else
{
// Configure middleware for Staging/Production
}
var contentRootPath = env.ContentRootPath;
}
IHostApplicationLifetime, interfejs
IHostApplicationLifetime
umożliwia wykonywanie działań po uruchomieniu i zamykaniu. Trzy właściwości interfejsu to tokeny anulowania używane do rejestrowania Action
metod definiujących zdarzenia uruchamiania i zamykania.
Token anulowania | Wyzwalane, gdy... |
---|---|
ApplicationStarted |
Host został w pełni uruchomiony. |
ApplicationStopped |
Host kończy bezproblemowe zamknięcie. Wszystkie żądania powinny być przetwarzane. Zamknij bloki do momentu zakończenia tego zdarzenia. |
ApplicationStopping |
Host wykonuje bezproblemowe zamknięcie. Żądania mogą nadal być przetwarzane. Zamknij bloki do momentu zakończenia tego zdarzenia. |
public class Startup
{
public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
{
appLifetime.ApplicationStarted.Register(OnStarted);
appLifetime.ApplicationStopping.Register(OnStopping);
appLifetime.ApplicationStopped.Register(OnStopped);
Console.CancelKeyPress += (sender, eventArgs) =>
{
appLifetime.StopApplication();
// Don't terminate the process immediately, wait for the Main thread to exit gracefully.
eventArgs.Cancel = true;
};
}
private void OnStarted()
{
// Perform post-startup activities here
}
private void OnStopping()
{
// Perform on-stopping activities here
}
private void OnStopped()
{
// Perform post-stopped activities here
}
}
StopApplication
żąda zakończenia aplikacji. Następująca klasa używa StopApplication
metody , aby bezpiecznie zamknąć aplikację, gdy wywoływana Shutdown
jest metoda klasy:
public class MyClass
{
private readonly IHostApplicationLifetime _appLifetime;
public MyClass(IHostApplicationLifetime appLifetime)
{
_appLifetime = appLifetime;
}
public void Shutdown()
{
_appLifetime.StopApplication();
}
}
Walidacja zakresu
CreateDefaultBuilder ustawia ServiceProviderOptions.ValidateScopes wartość na true
wartość , jeśli środowisko aplikacji to Programowanie.
Gdy ValidateScopes
jest ustawiona wartość true
, domyślny dostawca usług przeprowadza kontrole w celu sprawdzenia, czy:
- Usługi o określonym zakresie nie są bezpośrednio ani pośrednio rozwiązywane przez głównego dostawcę usług.
- Usługi o określonym zakresie nie są bezpośrednio ani pośrednio wstrzykiwane do pojedynczychtonów.
Dostawca usługi głównej jest tworzony, gdy BuildServiceProvider jest wywoływany. Okres istnienia głównego dostawcy usług odpowiada okresowi istnienia aplikacji/serwera, gdy dostawca rozpoczyna się od aplikacji i jest usuwany po zamknięciu aplikacji.
Usługi o określonym zakresie są usuwane przez kontener, który je utworzył. Jeśli usługa o określonym zakresie jest tworzona w kontenerze głównym, okres istnienia usługi jest skutecznie promowany do pojedynczegotonu, ponieważ jest on usuwany tylko przez kontener główny po zamknięciu aplikacji/serwera. Sprawdzanie poprawności zakresów usługi przechwytuje te sytuacje, gdy BuildServiceProvider
jest wywoływana.
Aby zawsze weryfikować zakresy, w tym w środowisku produkcyjnym, skonfiguruj element ServiceProviderOptions w UseDefaultServiceProvider konstruktorze hosta:
WebHost.CreateDefaultBuilder(args)
.UseDefaultServiceProvider((context, options) => {
options.ValidateScopes = true;
})
Dodatkowe zasoby
Aplikacje ASP.NET Core konfigurują i uruchamiają hosta. Host jest odpowiedzialny za zarządzanie uruchamianiem i okresem istnienia aplikacji. Co najmniej host konfiguruje serwer i potok przetwarzania żądań. Host może również skonfigurować rejestrowanie, wstrzykiwanie zależności i konfigurację.
W tym artykule opisano hosta sieci Web, który pozostaje dostępny tylko w celu zapewnienia zgodności z poprzednimi wersjami. Szablony ASP.NET Core tworzą hosta ogólnego platformy .NET, który jest zalecany dla wszystkich typów aplikacji.
Konfigurowanie hosta
Utwórz hosta przy użyciu wystąpienia IWebHostBuilderklasy . Jest to zwykle wykonywane w punkcie wejścia aplikacji— metodzie Main
.
W szablonach Main
projektów znajduje się w Program.cs
lokalizacji . Typowe wywołania CreateDefaultBuilder aplikacji umożliwiające rozpoczęcie konfigurowania hosta:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
Kod, który wywołuje CreateDefaultBuilder
, znajduje się w metodzie o nazwie CreateWebHostBuilder
, która oddziela go od kodu, który Main
wywołuje Run
obiekt konstruktora. Ta separacja jest wymagana, jeśli używasz narzędzi Entity Framework Core. Narzędzia oczekują znalezienia CreateWebHostBuilder
metody, którą mogą wywołać w czasie projektowania w celu skonfigurowania hosta bez uruchamiania aplikacji. Alternatywą jest zaimplementowanie IDesignTimeDbContextFactory
elementu . Aby uzyskać więcej informacji, zobacz Design-time DbContext Creation (Tworzenie elementu DbContext w czasie projektowania).
Metoda CreateDefaultBuilder
wykonuje następujące zadania:
- Konfiguruje Kestrel serwer jako serwer internetowy przy użyciu dostawców konfiguracji hostingu aplikacji. Kestrel Aby uzyskać opcje domyślne serwera, zobacz Konfigurowanie opcji dla serwera internetowego ASP.NET CoreKestrel.
- Ustawia katalog główny zawartości na ścieżkę zwróconą przez Directory.GetCurrentDirectory.
- Ładuje konfigurację hosta z:
- Zmienne środowiskowe poprzedzone prefiksem
ASPNETCORE_
(na przykładASPNETCORE_ENVIRONMENT
). - Argumenty wiersza polecenia.
- Zmienne środowiskowe poprzedzone prefiksem
- Ładuje konfigurację aplikacji w następującej kolejności:
appsettings.json
.appsettings.{Environment}.json
.- Wpisy tajne użytkownika, gdy aplikacja jest uruchamiana w
Development
środowisku przy użyciu zestawu wpisu. - Zmienne środowiskowe.
- Argumenty wiersza polecenia.
- Konfiguruje rejestrowanie dla konsoli i danych wyjściowych debugowania. Rejestrowanie obejmuje reguły filtrowania dzienników określone w sekcji Konfiguracja rejestrowania pliku
appsettings.json
lubappsettings.{Environment}.json
. - W przypadku uruchamiania za usługami IIS przy użyciu modułu podstawowego ASP.NET
CreateDefaultBuilder
włącza integrację usług IIS, która konfiguruje podstawowy adres i port aplikacji. Integracja z usługami IIS konfiguruje również aplikację w celu przechwytywania błędów uruchamiania. Aby uzyskać opcje domyślne usług IIS, zobacz Host ASP.NET Core w systemie Windows z usługami IIS. - Ustawia ServiceProviderOptions.ValidateScopes wartość ,
true
jeśli środowisko aplikacji to Programowanie. Aby uzyskać więcej informacji, zobacz Walidacja zakresu.
Konfigurację zdefiniowaną przez CreateDefaultBuilder
program można zastąpić i rozszerzyć za pomocą ConfigureAppConfigurationmetod , ConfigureLoggingi innych metod rozszerzeń programu IWebHostBuilder. Poniżej przedstawiono kilka przykładów:
ConfigureAppConfiguration służy do określania dodatkowych
IConfiguration
dla aplikacji. NastępująceConfigureAppConfiguration
wywołanie dodaje delegata w celu uwzględnienia konfiguracji aplikacji wappsettings.xml
pliku.ConfigureAppConfiguration
może być wywoływany wiele razy. Należy pamiętać, że ta konfiguracja nie ma zastosowania do hosta (na przykład adresów URL serwera lub środowiska). Zobacz sekcję Wartości konfiguracji hosta.WebHost.CreateDefaultBuilder(args) .ConfigureAppConfiguration((hostingContext, config) => { config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true); }) ...
Następujące
ConfigureLogging
wywołanie dodaje delegata w celu skonfigurowania minimalnego poziomu rejestrowania (SetMinimumLevel) na LogLevel.Warning. To ustawienie zastępuje ustawienia w programieappsettings.Development.json
(LogLevel.Debug
) iappsettings.Production.json
(LogLevel.Error
) skonfigurowanym przezCreateDefaultBuilder
program .ConfigureLogging
może być wywoływany wiele razy.WebHost.CreateDefaultBuilder(args) .ConfigureLogging(logging => { logging.SetMinimumLevel(LogLevel.Warning); }) ...
Następujące wywołanie w celu
ConfigureKestrel
zastąpienia domyślnego elementu Limits.MaxRequestBodySize o wartości 30 000 000 bajtów ustanowionych podczas Kestrel konfigurowania przezCreateDefaultBuilder
program :WebHost.CreateDefaultBuilder(args) .ConfigureKestrel((context, options) => { options.Limits.MaxRequestBodySize = 20000000; });
Katalog główny zawartości określa, gdzie host wyszukuje pliki zawartości, takie jak pliki widoku MVC. Po uruchomieniu aplikacji z folderu głównego projektu folder główny projektu jest używany jako katalog główny zawartości. Jest to wartość domyślna używana w programie Visual Studio i nowych szablonach dotnet.
Aby uzyskać więcej informacji na temat konfiguracji aplikacji, zobacz Configuration in ASP.NET Core (Konfiguracja w programie ASP.NET Core).
Uwaga
Alternatywą dla używania metody statycznej CreateDefaultBuilder
jest utworzenie hosta na podstawie WebHostBuilder jest obsługiwane podejście z platformą ASP.NET Core 2.x.
Podczas konfigurowania hosta Configure można podać metody i ConfigureServices . Jeśli określono klasę Startup
, musi ona zdefiniować metodę Configure
. Aby uzyskać więcej informacji, zobacz Uruchamianie aplikacji na platformie ASP.NET Core. Wiele wywołań dołączania ConfigureServices
do siebie. Wiele wywołań do Configure
lub UseStartup
zastąp WebHostBuilder
poprzednie ustawienia.
Wartości konfiguracji hosta
WebHostBuilder opiera się na następujących podejściach do ustawiania wartości konfiguracji hosta:
- Konfiguracja konstruktora hostów, która zawiera zmienne środowiskowe w formacie
ASPNETCORE_{configurationKey}
. Na przykładASPNETCORE_ENVIRONMENT
. - Rozszerzenia, takie jak UseContentRoot i UseConfiguration (zobacz sekcję Przesłoń konfigurację).
- UseSetting i skojarzony klucz. Podczas ustawiania wartości za pomocą
UseSetting
parametru wartość jest ustawiana jako ciąg niezależnie od typu.
Host używa dowolnej opcji ustawia ostatnią wartość. Aby uzyskać więcej informacji, zobacz Zastępowanie konfiguracji w następnej sekcji.
Klucz aplikacji (nazwa)
Właściwość IWebHostEnvironment.ApplicationName
jest ustawiana automatycznie, gdy UseStartup obiekt lub Configure jest wywoływany podczas budowy hosta. Wartość jest ustawiona na nazwę zestawu zawierającego punkt wejścia aplikacji. Aby jawnie ustawić wartość, użyj polecenia WebHostDefaults.ApplicationKey:
Klucz: applicationName
Typ: ciąg
Ustawienie domyślne: nazwa zestawu zawierającego punkt wejścia aplikacji.
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_APPLICATIONNAME
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")
Przechwyć błędy uruchamiania
To ustawienie steruje przechwytywaniem błędów uruchamiania.
Klucz: captureStartupErrors
Typ: bool (true
lub 1
)
Ustawienie domyślne: wartość domyślna to false
, chyba że aplikacja jest uruchamiana za usługami Kestrel IIS, gdzie wartość domyślna to true
.
Ustaw przy użyciu: CaptureStartupErrors
Zmienna środowiskowa: ASPNETCORE_CAPTURESTARTUPERRORS
W przypadku false
, błędy podczas uruchamiania powodują zamknięcie hosta. Gdy true
host przechwytuje wyjątki podczas uruchamiania i próbuje uruchomić serwer.
WebHost.CreateDefaultBuilder(args)
.CaptureStartupErrors(true)
Katalog główny zawartości
To ustawienie określa, gdzie ASP.NET Core rozpoczyna wyszukiwanie plików zawartości.
Klucz: contentRoot
Typ: ciąg
Ustawienie domyślne: domyślnie jest to folder, w którym znajduje się zestaw aplikacji.
Ustaw przy użyciu: UseContentRoot
Zmienna środowiskowa: ASPNETCORE_CONTENTROOT
Główny katalog zawartości jest również używany jako ścieżka podstawowa katalogu głównego sieci Web. Jeśli ścieżka główna zawartości nie istnieje, uruchomienie hosta nie powiedzie się.
WebHost.CreateDefaultBuilder(args)
.UseContentRoot("c:\\<content-root>")
Aby uzyskać więcej informacji, zobacz:
Szczegółowe błędy
Określa, czy należy przechwycić szczegółowe błędy.
Klucz: detailsErrors
Typ: bool (true
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_DETAILEDERRORS
Po włączeniu (lub po ustawieniu środowiska na Development
wartość ) aplikacja przechwytuje szczegółowe wyjątki.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
Środowisko
Ustawia środowisko aplikacji.
Klucz: środowisko
Typ: ciąg
Ustawienie domyślne: Produkcja
Ustaw przy użyciu: UseEnvironment
Zmienna środowiskowa: ASPNETCORE_ENVIRONMENT
Środowisko można ustawić na dowolną wartość. Zdefiniowane przez platformę wartości obejmują Development
, Staging
i Production
. W wartościach nie jest uwzględniana wielkość liter. Domyślnie środowisko jest odczytywane ze zmiennej środowiskowej ASPNETCORE_ENVIRONMENT
. W przypadku korzystania z programu Visual Studio zmienne środowiskowe mogą być ustawiane w launchSettings.json
pliku. Więcej informacji można znaleźć w temacie Używanie wielu środowisk na platformie ASP.NET Core.
WebHost.CreateDefaultBuilder(args)
.UseEnvironment(EnvironmentName.Development)
Hostowanie zestawów startowych
Ustawia zestawy uruchamiania aplikacji hostowania.
Klucz: hostingStartupAssemblies
Typ: ciąg
Ustawienie domyślne: Pusty ciąg
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_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.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")
HTTPS Port
Ustaw port przekierowania HTTPS. Używany w wymuszaniu protokołu HTTPS.
Klucz: https_port
Typ: ciąg
Ustawienie domyślne: wartość domyślna nie jest ustawiona.
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_HTTPS_PORTS
WebHost.CreateDefaultBuilder(args)
.UseSetting("https_port", "8080")
Hostowanie zestawów wykluczania uruchamiania
Rozdzielany średnikami ciąg hostowania zestawów startowych do wykluczenia podczas uruchamiania.
Klucz: hostingStartupExcludeAssemblies
Typ: ciąg
Ustawienie domyślne: Pusty ciąg
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")
Preferuj adresy URL hostingu
Wskazuje, czy host powinien nasłuchiwać adresów URL skonfigurowanych przy WebHostBuilder
użyciu wartości zamiast skonfigurowanych przy użyciu implementacji IServer
.
Klucz: preferujHostingUrls
Typ: bool (true
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: PreferHostingUrls
Zmienna środowiskowa: ASPNETCORE_PREFERHOSTINGURLS
WebHost.CreateDefaultBuilder(args)
.PreferHostingUrls(true)
Zapobieganie uruchamianiu hostingu
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
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_PREVENTHOSTINGSTARTUP
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")
Adresy URL serwera
Wskazuje adresy IP lub adresy hostów z portami i protokołami, na których serwer powinien nasłuchiwać żądań.
Klucz: adresy URL
Typ: ciąg
Ustawienie domyślne: http://localhost:5000
Ustaw przy użyciu: UseUrls
Zmienna środowiskowa: ASPNETCORE_URLS
Ustaw wartość rozdzielaną średnikami (;) listę prefiksów adresów URL, na które serwer powinien odpowiadać. 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.
WebHost.CreateDefaultBuilder(args)
.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.
Limit czasu zamknięcia
Określa czas oczekiwania na zamknięcie hosta sieci Web.
Klucz: shutdownTimeoutSeconds
Typ: int
Ustawienie domyślne: 5
Ustaw przy użyciu: UseShutdownTimeout
Zmienna środowiskowa: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS
Mimo że klucz akceptuje int z UseSetting
(na przykład .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")
), UseShutdownTimeout metoda rozszerzenia przyjmuje TimeSpanwartość .
W okresie przekroczenia limitu czasu hostowanie:
- Wyzwalacze IApplicationLifetime.ApplicationStopping.
- Próbuje zatrzymać hostowane usługi i rejestrować wszelkie błędy dotyczące 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ą dodatkowego czasu do zatrzymania, zwiększ limit czasu.
WebHost.CreateDefaultBuilder(args)
.UseShutdownTimeout(TimeSpan.FromSeconds(10))
Zestaw startowy
Określa zestaw do wyszukiwania Startup
klasy.
Klucz: startupAssembly
Typ: ciąg
Ustawienie domyślne: zestaw aplikacji
Ustaw przy użyciu: UseStartup
Zmienna środowiskowa: ASPNETCORE_STARTUPASSEMBLY
Można odwołać się do zestawu według nazwy (string
) lub typu (TStartup
). Jeśli wywoływano wiele UseStartup
metod, ostatni z nich ma pierwszeństwo.
WebHost.CreateDefaultBuilder(args)
.UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
.UseStartup<TStartup>()
Internetowy katalog główny
Ustawia ścieżkę względną do zasobów statycznych aplikacji.
Klucz: webroot
Typ: ciąg
Ustawienie domyślne: wartość domyślna to wwwroot
. Ścieżka do katalogu {content root}/wwwroot musi istnieć. Jeśli ścieżka nie istnieje, zostanie użyty dostawca plików bez operacji.
Ustaw przy użyciu: UseWebRoot
Zmienna środowiskowa: ASPNETCORE_WEBROOT
WebHost.CreateDefaultBuilder(args)
.UseWebRoot("public")
Aby uzyskać więcej informacji, zobacz:
Przesłoń konfigurację
Konfigurowanie hosta sieci Web przy użyciu konfiguracji . W poniższym przykładzie konfiguracja hosta jest opcjonalnie określona hostsettings.json
w pliku. Każda konfiguracja załadowana z hostsettings.json
pliku może zostać zastąpiona przez argumenty wiersza polecenia. Wbudowana konfiguracja (w systemie config
) służy do konfigurowania hosta za pomocą UseConfigurationpolecenia . IWebHostBuilder
konfiguracja jest dodawana do konfiguracji aplikacji, ale odwrotnie nie ma to wpływuConfigureAppConfiguration
na konfigurację IWebHostBuilder
.
Przesłanianie konfiguracji dostarczonej przez UseUrls
hostsettings.json
element config first, command-line argument config sekundy:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
var config = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("hostsettings.json", optional: true)
.AddCommandLine(args)
.Build();
return WebHost.CreateDefaultBuilder(args)
.UseUrls("http://*:5000")
.UseConfiguration(config)
.Configure(app =>
{
app.Run(context =>
context.Response.WriteAsync("Hello, World!"));
});
}
}
hostsettings.json
:
{
urls: "http://*:5005"
}
Uwaga
UseConfiguration Kopiuje tylko klucze z dostarczonego IConfiguration
do konfiguracji konstruktora hosta. W związku z tym ustawienie reloadOnChange: true
dla JSplików ustawień ON, INI i XML nie ma wpływu.
Aby określić uruchomienie hosta w określonym adresie URL, żądana wartość może zostać przekazana z wiersza polecenia podczas wykonywania polecenia dotnet run. Argument wiersza polecenia zastępuje urls
wartość z hostsettings.json
pliku, a serwer nasłuchuje na porcie 8080:
dotnet run --urls "http://*:8080"
Zarządzanie hostem
Run
Metoda Run
uruchamia aplikację internetową i blokuje wątek wywołujący do czasu zamknięcia hosta:
host.Run();
Uruchom
Uruchom hosta w sposób nieblokjący, wywołując jego Start
metodę:
using (host)
{
host.Start();
Console.ReadLine();
}
Jeśli lista adresów URL jest przekazywana do Start
metody, nasłuchuje określonych adresów URL:
var urls = new List<string>()
{
"http://*:5000",
"http://localhost:5001"
};
var host = new WebHostBuilder()
.UseKestrel()
.UseStartup<Startup>()
.Start(urls.ToArray());
using (host)
{
Console.ReadLine();
}
Aplikacja może zainicjować i uruchomić nowego hosta przy użyciu wstępnie skonfigurowanych wartości domyślnych CreateDefaultBuilder
przy użyciu statycznej metody wygody. Te metody uruchamiają serwer bez danych wyjściowych konsoli i zaczekają WaitForShutdown na przerwę (Ctrl-C/SIGINT lub SIGTERM):
Start(RequestDelegate app)
Zacznij od elementu RequestDelegate
:
using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Prześlij żądanie w przeglądarce, aby http://localhost:5000
otrzymać odpowiedź "Hello World!", WaitForShutdown
dopóki nie zostanie wystawiona przerwa (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
Start(adres URL ciągu, aplikacja RequestDelegate)
Zacznij od adresu URL i RequestDelegate
:
using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Generuje taki sam wynik jak Start(RequestDelegate app), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
Start(Action<IRouteBuilder routeBuilder> )
Użyj wystąpienia IRouteBuilder
programu (Microsoft.AspNetCore.Routing), aby użyć oprogramowania pośredniczącego routingu:
using (var host = WebHost.Start(router => router
.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Użyj następujących żądań przeglądarki w przykładzie:
Zażądaj | Response |
---|---|
http://localhost:5000/hello/Martin |
Witaj, Martin! |
http://localhost:5000/buenosdias/Catrina |
Buenos dias, Catrina! |
http://localhost:5000/throw/ooops! |
Zgłasza wyjątek z ciągiem "ooops!" |
http://localhost:5000/throw |
Zgłasza wyjątek z ciągiem "Uh oh!" |
http://localhost:5000/Sante/Kevin |
Sante, Kevin! |
http://localhost:5000 |
Hello World! |
WaitForShutdown
blokuje do momentu wydania przerwy (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
Start(adres URL ciągu, akcja<IRouteBuilder routeBuilder> )
Użyj adresu URL i wystąpienia elementu IRouteBuilder
:
using (var host = WebHost.Start("http://localhost:8080", router => router
.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Generuje taki sam wynik jak Start(Action<IRouteBuilder routeBuilder> ), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
StartWith(Action<IApplicationBuilder> app)
Podaj pełnomocnika, aby skonfigurować element IApplicationBuilder
:
using (var host = WebHost.StartWith(app =>
app.Use(next =>
{
return async context =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Prześlij żądanie w przeglądarce, aby http://localhost:5000
otrzymać odpowiedź "Hello World!", WaitForShutdown
dopóki nie zostanie wystawiona przerwa (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
StartWith(adres URL ciągu, aplikacja Action<IApplicationBuilder> )
Podaj adres URL i pełnomocnika do skonfigurowania elementu IApplicationBuilder
:
using (var host = WebHost.StartWith("http://localhost:8080", app =>
app.Use(next =>
{
return async context =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Tworzy taki sam wynik jak StartWith(Action<IApplicationBuilder> app), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
IWebHostEnvironment, interfejs
Interfejs IWebHostEnvironment
zawiera informacje o środowisku hostingu internetowego aplikacji. Użyj iniekcji konstruktora, aby uzyskać IWebHostEnvironment
metodę w celu użycia jej właściwości i metod rozszerzenia:
public class CustomFileReader
{
private readonly IWebHostEnvironment _env;
public CustomFileReader(IWebHostEnvironment env)
{
_env = env;
}
public string ReadFile(string filePath)
{
var fileProvider = _env.WebRootFileProvider;
// Process the file here
}
}
Podejście oparte na konwencji może służyć do konfigurowania aplikacji podczas uruchamiania na podstawie środowiska. Alternatywnie należy wstrzyknąć element do konstruktora IWebHostEnvironment
Startup
do użycia w ConfigureServices
pliku :
public class Startup
{
public Startup(IWebHostEnvironment env)
{
HostingEnvironment = env;
}
public IWebHostEnvironment HostingEnvironment { get; }
public void ConfigureServices(IServiceCollection services)
{
if (HostingEnvironment.IsDevelopment())
{
// Development configuration
}
else
{
// Staging/Production configuration
}
var contentRootPath = HostingEnvironment.ContentRootPath;
}
}
Uwaga
Oprócz IsDevelopment
metody IWebHostEnvironment
rozszerzenia oferuje IsStaging
metody , IsProduction
i IsEnvironment(string environmentName)
. Więcej informacji można znaleźć w temacie Używanie wielu środowisk na platformie ASP.NET Core.
Usługę IWebHostEnvironment
można również wstrzyknąć bezpośrednio do Configure
metody konfigurowania potoku przetwarzania:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
// In Development, use the Developer Exception Page
app.UseDeveloperExceptionPage();
}
else
{
// In Staging/Production, route exceptions to /error
app.UseExceptionHandler("/error");
}
var contentRootPath = env.ContentRootPath;
}
IWebHostEnvironment
można wstrzyknąć do Invoke
metody podczas tworzenia niestandardowego oprogramowania pośredniczącego:
public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
// Configure middleware for Development
}
else
{
// Configure middleware for Staging/Production
}
var contentRootPath = env.ContentRootPath;
}
IHostApplicationLifetime, interfejs
IHostApplicationLifetime
umożliwia wykonywanie działań po uruchomieniu i zamykaniu. Trzy właściwości interfejsu to tokeny anulowania używane do rejestrowania Action
metod definiujących zdarzenia uruchamiania i zamykania.
Token anulowania | Wyzwalane, gdy... |
---|---|
ApplicationStarted |
Host został w pełni uruchomiony. |
ApplicationStopped |
Host kończy bezproblemowe zamknięcie. Wszystkie żądania powinny być przetwarzane. Zamknij bloki do momentu zakończenia tego zdarzenia. |
ApplicationStopping |
Host wykonuje bezproblemowe zamknięcie. Żądania mogą nadal być przetwarzane. Zamknij bloki do momentu zakończenia tego zdarzenia. |
public class Startup
{
public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
{
appLifetime.ApplicationStarted.Register(OnStarted);
appLifetime.ApplicationStopping.Register(OnStopping);
appLifetime.ApplicationStopped.Register(OnStopped);
Console.CancelKeyPress += (sender, eventArgs) =>
{
appLifetime.StopApplication();
// Don't terminate the process immediately, wait for the Main thread to exit gracefully.
eventArgs.Cancel = true;
};
}
private void OnStarted()
{
// Perform post-startup activities here
}
private void OnStopping()
{
// Perform on-stopping activities here
}
private void OnStopped()
{
// Perform post-stopped activities here
}
}
StopApplication
żąda zakończenia aplikacji. Następująca klasa używa StopApplication
metody , aby bezpiecznie zamknąć aplikację, gdy wywoływana Shutdown
jest metoda klasy:
public class MyClass
{
private readonly IHostApplicationLifetime _appLifetime;
public MyClass(IHostApplicationLifetime appLifetime)
{
_appLifetime = appLifetime;
}
public void Shutdown()
{
_appLifetime.StopApplication();
}
}
Walidacja zakresu
CreateDefaultBuilder ustawia ServiceProviderOptions.ValidateScopes wartość na true
wartość , jeśli środowisko aplikacji to Programowanie.
Gdy ValidateScopes
jest ustawiona wartość true
, domyślny dostawca usług przeprowadza kontrole w celu sprawdzenia, czy:
- Usługi o określonym zakresie nie są bezpośrednio ani pośrednio rozwiązywane przez głównego dostawcę usług.
- Usługi o określonym zakresie nie są bezpośrednio ani pośrednio wstrzykiwane do pojedynczychtonów.
Dostawca usługi głównej jest tworzony, gdy BuildServiceProvider jest wywoływany. Okres istnienia głównego dostawcy usług odpowiada okresowi istnienia aplikacji/serwera, gdy dostawca rozpoczyna się od aplikacji i jest usuwany po zamknięciu aplikacji.
Usługi o określonym zakresie są usuwane przez kontener, który je utworzył. Jeśli usługa o określonym zakresie jest tworzona w kontenerze głównym, okres istnienia usługi jest skutecznie promowany do pojedynczegotonu, ponieważ jest on usuwany tylko przez kontener główny po zamknięciu aplikacji/serwera. Sprawdzanie poprawności zakresów usługi przechwytuje te sytuacje, gdy BuildServiceProvider
jest wywoływana.
Aby zawsze weryfikować zakresy, w tym w środowisku produkcyjnym, skonfiguruj element ServiceProviderOptions w UseDefaultServiceProvider konstruktorze hosta:
WebHost.CreateDefaultBuilder(args)
.UseDefaultServiceProvider((context, options) => {
options.ValidateScopes = true;
})
Dodatkowe zasoby
Aplikacje ASP.NET Core konfigurują i uruchamiają hosta. Host jest odpowiedzialny za zarządzanie uruchamianiem i okresem istnienia aplikacji. Co najmniej host konfiguruje serwer i potok przetwarzania żądań. Host może również skonfigurować rejestrowanie, wstrzykiwanie zależności i konfigurację.
W tym artykule opisano hosta sieci Web, który pozostaje dostępny tylko w celu zapewnienia zgodności z poprzednimi wersjami. Szablony ASP.NET Core tworzą hosta ogólnego platformy .NET, który jest zalecany dla wszystkich typów aplikacji.
Konfigurowanie hosta
Utwórz hosta przy użyciu wystąpienia IWebHostBuilderklasy . Jest to zwykle wykonywane w punkcie wejścia aplikacji— metodzie Main
.
W szablonach Main
projektów znajduje się w Program.cs
lokalizacji . Typowe wywołania CreateDefaultBuilder aplikacji umożliwiające rozpoczęcie konfigurowania hosta:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
Kod, który wywołuje CreateDefaultBuilder
, znajduje się w metodzie o nazwie CreateWebHostBuilder
, która oddziela go od kodu, który Main
wywołuje Run
obiekt konstruktora. Ta separacja jest wymagana, jeśli używasz narzędzi Entity Framework Core. Narzędzia oczekują znalezienia CreateWebHostBuilder
metody, którą mogą wywołać w czasie projektowania w celu skonfigurowania hosta bez uruchamiania aplikacji. Alternatywą jest zaimplementowanie IDesignTimeDbContextFactory
elementu . Aby uzyskać więcej informacji, zobacz Design-time DbContext Creation (Tworzenie elementu DbContext w czasie projektowania).
Metoda CreateDefaultBuilder
wykonuje następujące zadania:
- Konfiguruje Kestrel serwer jako serwer internetowy przy użyciu dostawców konfiguracji hostingu aplikacji. Kestrel Aby uzyskać domyślne opcje serwera, zobacz Kestrel serwer internetowy w programie ASP.NET Core.
- Ustawia katalog główny zawartości na ścieżkę zwróconą przez Directory.GetCurrentDirectory.
- Ładuje konfigurację hosta z:
- Zmienne środowiskowe poprzedzone prefiksem
ASPNETCORE_
(na przykładASPNETCORE_ENVIRONMENT
). - Argumenty wiersza polecenia.
- Zmienne środowiskowe poprzedzone prefiksem
- Ładuje konfigurację aplikacji w następującej kolejności:
appsettings.json
.appsettings.{Environment}.json
.- Wpisy tajne użytkownika, gdy aplikacja jest uruchamiana w
Development
środowisku przy użyciu zestawu wpisu. - Zmienne środowiskowe.
- Argumenty wiersza polecenia.
- Konfiguruje rejestrowanie dla konsoli i danych wyjściowych debugowania. Rejestrowanie obejmuje reguły filtrowania dzienników określone w sekcji Konfiguracja rejestrowania pliku
appsettings.json
lubappsettings.{Environment}.json
. - W przypadku uruchamiania za usługami IIS przy użyciu modułu podstawowego ASP.NET
CreateDefaultBuilder
włącza integrację usług IIS, która konfiguruje podstawowy adres i port aplikacji. Integracja z usługami IIS konfiguruje również aplikację w celu przechwytywania błędów uruchamiania. Aby uzyskać opcje domyślne usług IIS, zobacz Host ASP.NET Core w systemie Windows z usługami IIS. - Ustawia ServiceProviderOptions.ValidateScopes wartość ,
true
jeśli środowisko aplikacji to Programowanie. Aby uzyskać więcej informacji, zobacz Walidacja zakresu.
Konfigurację zdefiniowaną przez CreateDefaultBuilder
program można zastąpić i rozszerzyć za pomocą ConfigureAppConfigurationmetod , ConfigureLoggingi innych metod rozszerzeń programu IWebHostBuilder. Poniżej przedstawiono kilka przykładów:
ConfigureAppConfiguration służy do określania dodatkowych
IConfiguration
dla aplikacji. NastępująceConfigureAppConfiguration
wywołanie dodaje delegata w celu uwzględnienia konfiguracji aplikacji wappsettings.xml
pliku.ConfigureAppConfiguration
może być wywoływany wiele razy. Należy pamiętać, że ta konfiguracja nie ma zastosowania do hosta (na przykład adresów URL serwera lub środowiska). Zobacz sekcję Wartości konfiguracji hosta.WebHost.CreateDefaultBuilder(args) .ConfigureAppConfiguration((hostingContext, config) => { config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true); }) ...
Następujące
ConfigureLogging
wywołanie dodaje delegata w celu skonfigurowania minimalnego poziomu rejestrowania (SetMinimumLevel) na LogLevel.Warning. To ustawienie zastępuje ustawienia w programieappsettings.Development.json
(LogLevel.Debug
) iappsettings.Production.json
(LogLevel.Error
) skonfigurowanym przezCreateDefaultBuilder
program .ConfigureLogging
może być wywoływany wiele razy.WebHost.CreateDefaultBuilder(args) .ConfigureLogging(logging => { logging.SetMinimumLevel(LogLevel.Warning); }) ...
Następujące wywołanie w celu
ConfigureKestrel
zastąpienia domyślnego elementu Limits.MaxRequestBodySize o wartości 30 000 000 bajtów ustanowionych podczas Kestrel konfigurowania przezCreateDefaultBuilder
program :WebHost.CreateDefaultBuilder(args) .ConfigureKestrel((context, options) => { options.Limits.MaxRequestBodySize = 20000000; });
Katalog główny zawartości określa, gdzie host wyszukuje pliki zawartości, takie jak pliki widoku MVC. Po uruchomieniu aplikacji z folderu głównego projektu folder główny projektu jest używany jako katalog główny zawartości. Jest to wartość domyślna używana w programie Visual Studio i nowych szablonach dotnet.
Aby uzyskać więcej informacji na temat konfiguracji aplikacji, zobacz Configuration in ASP.NET Core (Konfiguracja w programie ASP.NET Core).
Uwaga
Alternatywą dla używania metody statycznej CreateDefaultBuilder
jest utworzenie hosta na podstawie WebHostBuilder jest obsługiwane podejście z platformą ASP.NET Core 2.x.
Podczas konfigurowania hosta Configure można podać metody i ConfigureServices . Jeśli określono klasę Startup
, musi ona zdefiniować metodę Configure
. Aby uzyskać więcej informacji, zobacz Uruchamianie aplikacji na platformie ASP.NET Core. Wiele wywołań dołączania ConfigureServices
do siebie. Wiele wywołań do Configure
lub UseStartup
zastąp WebHostBuilder
poprzednie ustawienia.
Wartości konfiguracji hosta
WebHostBuilder opiera się na następujących podejściach do ustawiania wartości konfiguracji hosta:
- Konfiguracja konstruktora hostów, która zawiera zmienne środowiskowe w formacie
ASPNETCORE_{configurationKey}
. Na przykładASPNETCORE_ENVIRONMENT
. - Rozszerzenia, takie jak UseContentRoot i UseConfiguration (zobacz sekcję Przesłoń konfigurację).
- UseSetting i skojarzony klucz. Podczas ustawiania wartości za pomocą
UseSetting
parametru wartość jest ustawiana jako ciąg niezależnie od typu.
Host używa dowolnej opcji ustawia ostatnią wartość. Aby uzyskać więcej informacji, zobacz Zastępowanie konfiguracji w następnej sekcji.
Klucz aplikacji (nazwa)
Właściwość IWebHostEnvironment.ApplicationName
jest ustawiana automatycznie, gdy UseStartup obiekt lub Configure jest wywoływany podczas budowy hosta. Wartość jest ustawiona na nazwę zestawu zawierającego punkt wejścia aplikacji. Aby jawnie ustawić wartość, użyj polecenia WebHostDefaults.ApplicationKey:
Klucz: applicationName
Typ: ciąg
Ustawienie domyślne: nazwa zestawu zawierającego punkt wejścia aplikacji.
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_APPLICATIONNAME
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")
Przechwyć błędy uruchamiania
To ustawienie steruje przechwytywaniem błędów uruchamiania.
Klucz: captureStartupErrors
Typ: bool (true
lub 1
)
Ustawienie domyślne: wartość domyślna to false
, chyba że aplikacja jest uruchamiana za usługami Kestrel IIS, gdzie wartość domyślna to true
.
Ustaw przy użyciu: CaptureStartupErrors
Zmienna środowiskowa: ASPNETCORE_CAPTURESTARTUPERRORS
W przypadku false
, błędy podczas uruchamiania powodują zamknięcie hosta. Gdy true
host przechwytuje wyjątki podczas uruchamiania i próbuje uruchomić serwer.
WebHost.CreateDefaultBuilder(args)
.CaptureStartupErrors(true)
Katalog główny zawartości
To ustawienie określa, gdzie ASP.NET Core rozpoczyna wyszukiwanie plików zawartości.
Klucz: contentRoot
Typ: ciąg
Ustawienie domyślne: domyślnie jest to folder, w którym znajduje się zestaw aplikacji.
Ustaw przy użyciu: UseContentRoot
Zmienna środowiskowa: ASPNETCORE_CONTENTROOT
Główny katalog zawartości jest również używany jako ścieżka podstawowa katalogu głównego sieci Web. Jeśli ścieżka główna zawartości nie istnieje, uruchomienie hosta nie powiedzie się.
WebHost.CreateDefaultBuilder(args)
.UseContentRoot("c:\\<content-root>")
Aby uzyskać więcej informacji, zobacz:
Szczegółowe błędy
Określa, czy należy przechwycić szczegółowe błędy.
Klucz: detailsErrors
Typ: bool (true
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_DETAILEDERRORS
Po włączeniu (lub po ustawieniu środowiska na Development
wartość ) aplikacja przechwytuje szczegółowe wyjątki.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
Środowisko
Ustawia środowisko aplikacji.
Klucz: środowisko
Typ: ciąg
Ustawienie domyślne: Produkcja
Ustaw przy użyciu: UseEnvironment
Zmienna środowiskowa: ASPNETCORE_ENVIRONMENT
Środowisko można ustawić na dowolną wartość. Zdefiniowane przez platformę wartości obejmują Development
, Staging
i Production
. W wartościach nie jest uwzględniana wielkość liter. Domyślnie środowisko jest odczytywane ze zmiennej środowiskowej ASPNETCORE_ENVIRONMENT
. W przypadku korzystania z programu Visual Studio zmienne środowiskowe mogą być ustawiane w launchSettings.json
pliku. Więcej informacji można znaleźć w temacie Używanie wielu środowisk na platformie ASP.NET Core.
WebHost.CreateDefaultBuilder(args)
.UseEnvironment(EnvironmentName.Development)
Hostowanie zestawów startowych
Ustawia zestawy uruchamiania aplikacji hostowania.
Klucz: hostingStartupAssemblies
Typ: ciąg
Ustawienie domyślne: Pusty ciąg
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_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.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")
HTTPS Port
Ustaw port przekierowania HTTPS. Używany w wymuszaniu protokołu HTTPS.
Klucz: https_port
Typ: ciąg
Ustawienie domyślne: wartość domyślna nie jest ustawiona.
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_HTTPS_PORTS
WebHost.CreateDefaultBuilder(args)
.UseSetting("https_port", "8080")
Hostowanie zestawów wykluczania uruchamiania
Rozdzielany średnikami ciąg hostowania zestawów startowych do wykluczenia podczas uruchamiania.
Klucz: hostingStartupExcludeAssemblies
Typ: ciąg
Ustawienie domyślne: Pusty ciąg
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")
Preferuj adresy URL hostingu
Wskazuje, czy host powinien nasłuchiwać adresów URL skonfigurowanych przy WebHostBuilder
użyciu wartości zamiast skonfigurowanych przy użyciu implementacji IServer
.
Klucz: preferujHostingUrls
Typ: bool (true
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: PreferHostingUrls
Zmienna środowiskowa: ASPNETCORE_PREFERHOSTINGURLS
WebHost.CreateDefaultBuilder(args)
.PreferHostingUrls(true)
Zapobieganie uruchamianiu hostingu
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
lub 1
)
Ustawienie domyślne: false
Ustaw przy użyciu: UseSetting
Zmienna środowiskowa: ASPNETCORE_PREVENTHOSTINGSTARTUP
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")
Adresy URL serwera
Wskazuje adresy IP lub adresy hostów z portami i protokołami, na których serwer powinien nasłuchiwać żądań.
Klucz: adresy URL
Typ: ciąg
Ustawienie domyślne: http://localhost:5000
Ustaw przy użyciu: UseUrls
Zmienna środowiskowa: ASPNETCORE_URLS
Ustaw wartość rozdzielaną średnikami (;) listę prefiksów adresów URL, na które serwer powinien odpowiadać. 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.
WebHost.CreateDefaultBuilder(args)
.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.
Limit czasu zamknięcia
Określa czas oczekiwania na zamknięcie hosta sieci Web.
Klucz: shutdownTimeoutSeconds
Typ: int
Ustawienie domyślne: 5
Ustaw przy użyciu: UseShutdownTimeout
Zmienna środowiskowa: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS
Mimo że klucz akceptuje int z UseSetting
(na przykład .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")
), UseShutdownTimeout metoda rozszerzenia przyjmuje TimeSpanwartość .
W okresie przekroczenia limitu czasu hostowanie:
- Wyzwalacze IApplicationLifetime.ApplicationStopping.
- Próbuje zatrzymać hostowane usługi i rejestrować wszelkie błędy dotyczące 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ą dodatkowego czasu do zatrzymania, zwiększ limit czasu.
WebHost.CreateDefaultBuilder(args)
.UseShutdownTimeout(TimeSpan.FromSeconds(10))
Zestaw startowy
Określa zestaw do wyszukiwania Startup
klasy.
Klucz: startupAssembly
Typ: ciąg
Ustawienie domyślne: zestaw aplikacji
Ustaw przy użyciu: UseStartup
Zmienna środowiskowa: ASPNETCORE_STARTUPASSEMBLY
Można odwołać się do zestawu według nazwy (string
) lub typu (TStartup
). Jeśli wywoływano wiele UseStartup
metod, ostatni z nich ma pierwszeństwo.
WebHost.CreateDefaultBuilder(args)
.UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
.UseStartup<TStartup>()
Internetowy katalog główny
Ustawia ścieżkę względną do zasobów statycznych aplikacji.
Klucz: webroot
Typ: ciąg
Ustawienie domyślne: wartość domyślna to wwwroot
. Ścieżka do katalogu {content root}/wwwroot musi istnieć. Jeśli ścieżka nie istnieje, zostanie użyty dostawca plików bez operacji.
Ustaw przy użyciu: UseWebRoot
Zmienna środowiskowa: ASPNETCORE_WEBROOT
WebHost.CreateDefaultBuilder(args)
.UseWebRoot("public")
Aby uzyskać więcej informacji, zobacz:
Przesłoń konfigurację
Konfigurowanie hosta sieci Web przy użyciu konfiguracji . W poniższym przykładzie konfiguracja hosta jest opcjonalnie określona hostsettings.json
w pliku. Każda konfiguracja załadowana z hostsettings.json
pliku może zostać zastąpiona przez argumenty wiersza polecenia. Wbudowana konfiguracja (w systemie config
) służy do konfigurowania hosta za pomocą UseConfigurationpolecenia . IWebHostBuilder
konfiguracja jest dodawana do konfiguracji aplikacji, ale odwrotnie nie ma to wpływuConfigureAppConfiguration
na konfigurację IWebHostBuilder
.
Przesłanianie konfiguracji dostarczonej przez UseUrls
hostsettings.json
element config first, command-line argument config sekundy:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args)
{
var config = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("hostsettings.json", optional: true)
.AddCommandLine(args)
.Build();
return WebHost.CreateDefaultBuilder(args)
.UseUrls("http://*:5000")
.UseConfiguration(config)
.Configure(app =>
{
app.Run(context =>
context.Response.WriteAsync("Hello, World!"));
});
}
}
hostsettings.json
:
{
urls: "http://*:5005"
}
Uwaga
UseConfiguration Kopiuje tylko klucze z dostarczonego IConfiguration
do konfiguracji konstruktora hosta. W związku z tym ustawienie reloadOnChange: true
dla JSplików ustawień ON, INI i XML nie ma wpływu.
Aby określić uruchomienie hosta w określonym adresie URL, żądana wartość może zostać przekazana z wiersza polecenia podczas wykonywania polecenia dotnet run. Argument wiersza polecenia zastępuje urls
wartość z hostsettings.json
pliku, a serwer nasłuchuje na porcie 8080:
dotnet run --urls "http://*:8080"
Zarządzanie hostem
Run
Metoda Run
uruchamia aplikację internetową i blokuje wątek wywołujący do czasu zamknięcia hosta:
host.Run();
Uruchom
Uruchom hosta w sposób nieblokjący, wywołując jego Start
metodę:
using (host)
{
host.Start();
Console.ReadLine();
}
Jeśli lista adresów URL jest przekazywana do Start
metody, nasłuchuje określonych adresów URL:
var urls = new List<string>()
{
"http://*:5000",
"http://localhost:5001"
};
var host = new WebHostBuilder()
.UseKestrel()
.UseStartup<Startup>()
.Start(urls.ToArray());
using (host)
{
Console.ReadLine();
}
Aplikacja może zainicjować i uruchomić nowego hosta przy użyciu wstępnie skonfigurowanych wartości domyślnych CreateDefaultBuilder
przy użyciu statycznej metody wygody. Te metody uruchamiają serwer bez danych wyjściowych konsoli i zaczekają WaitForShutdown na przerwę (Ctrl-C/SIGINT lub SIGTERM):
Start(RequestDelegate app)
Zacznij od elementu RequestDelegate
:
using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Prześlij żądanie w przeglądarce, aby http://localhost:5000
otrzymać odpowiedź "Hello World!", WaitForShutdown
dopóki nie zostanie wystawiona przerwa (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
Start(adres URL ciągu, aplikacja RequestDelegate)
Zacznij od adresu URL i RequestDelegate
:
using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Generuje taki sam wynik jak Start(RequestDelegate app), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
Start(Action<IRouteBuilder routeBuilder> )
Użyj wystąpienia IRouteBuilder
programu (Microsoft.AspNetCore.Routing), aby użyć oprogramowania pośredniczącego routingu:
using (var host = WebHost.Start(router => router
.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
Console.WriteLine("Use Ctrl-C to shutdown the host...");
host.WaitForShutdown();
}
Użyj następujących żądań przeglądarki w przykładzie:
Zażądaj | Response |
---|---|
http://localhost:5000/hello/Martin |
Witaj, Martin! |
http://localhost:5000/buenosdias/Catrina |
Buenos dias, Catrina! |
http://localhost:5000/throw/ooops! |
Zgłasza wyjątek z ciągiem "ooops!" |
http://localhost:5000/throw |
Zgłasza wyjątek z ciągiem "Uh oh!" |
http://localhost:5000/Sante/Kevin |
Sante, Kevin! |
http://localhost:5000 |
Hello World! |
WaitForShutdown
blokuje do momentu wydania przerwy (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
Start(adres URL ciągu, akcja<IRouteBuilder routeBuilder> )
Użyj adresu URL i wystąpienia elementu IRouteBuilder
:
using (var host = WebHost.Start("http://localhost:8080", router => router
.MapGet("hello/{name}", (req, res, data) =>
res.WriteAsync($"Hello, {data.Values["name"]}!"))
.MapGet("buenosdias/{name}", (req, res, data) =>
res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
.MapGet("throw/{message?}", (req, res, data) =>
throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
.MapGet("{greeting}/{name}", (req, res, data) =>
res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
.MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Generuje taki sam wynik jak Start(Action<IRouteBuilder routeBuilder> ), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
StartWith(Action<IApplicationBuilder> app)
Podaj pełnomocnika, aby skonfigurować element IApplicationBuilder
:
using (var host = WebHost.StartWith(app =>
app.Use(next =>
{
return async context =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Prześlij żądanie w przeglądarce, aby http://localhost:5000
otrzymać odpowiedź "Hello World!", WaitForShutdown
dopóki nie zostanie wystawiona przerwa (Ctrl-C/SIGINT lub SIGTERM). Aplikacja wyświetla Console.WriteLine
komunikat i czeka na zakończenie działania platformy keypress.
StartWith(adres URL ciągu, aplikacja Action<IApplicationBuilder> )
Podaj adres URL i pełnomocnika do skonfigurowania elementu IApplicationBuilder
:
using (var host = WebHost.StartWith("http://localhost:8080", app =>
app.Use(next =>
{
return async context =>
{
await context.Response.WriteAsync("Hello World!");
};
})))
{
Console.WriteLine("Use Ctrl-C to shut down the host...");
host.WaitForShutdown();
}
Tworzy taki sam wynik jak StartWith(Action<IApplicationBuilder> app), z wyjątkiem aplikacji odpowiada na http://localhost:8080
.
IWebHostEnvironment, interfejs
Interfejs IWebHostEnvironment
zawiera informacje o środowisku hostingu internetowego aplikacji. Użyj iniekcji konstruktora, aby uzyskać IWebHostEnvironment
metodę w celu użycia jej właściwości i metod rozszerzenia:
public class CustomFileReader
{
private readonly IWebHostEnvironment _env;
public CustomFileReader(IWebHostEnvironment env)
{
_env = env;
}
public string ReadFile(string filePath)
{
var fileProvider = _env.WebRootFileProvider;
// Process the file here
}
}
Podejście oparte na konwencji może służyć do konfigurowania aplikacji podczas uruchamiania na podstawie środowiska. Alternatywnie należy wstrzyknąć element do konstruktora IWebHostEnvironment
Startup
do użycia w ConfigureServices
pliku :
public class Startup
{
public Startup(IWebHostEnvironment env)
{
HostingEnvironment = env;
}
public IWebHostEnvironment HostingEnvironment { get; }
public void ConfigureServices(IServiceCollection services)
{
if (HostingEnvironment.IsDevelopment())
{
// Development configuration
}
else
{
// Staging/Production configuration
}
var contentRootPath = HostingEnvironment.ContentRootPath;
}
}
Uwaga
Oprócz IsDevelopment
metody IWebHostEnvironment
rozszerzenia oferuje IsStaging
metody , IsProduction
i IsEnvironment(string environmentName)
. Więcej informacji można znaleźć w temacie Używanie wielu środowisk na platformie ASP.NET Core.
Usługę IWebHostEnvironment
można również wstrzyknąć bezpośrednio do Configure
metody konfigurowania potoku przetwarzania:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
// In Development, use the Developer Exception Page
app.UseDeveloperExceptionPage();
}
else
{
// In Staging/Production, route exceptions to /error
app.UseExceptionHandler("/error");
}
var contentRootPath = env.ContentRootPath;
}
IWebHostEnvironment
można wstrzyknąć do Invoke
metody podczas tworzenia niestandardowego oprogramowania pośredniczącego:
public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
// Configure middleware for Development
}
else
{
// Configure middleware for Staging/Production
}
var contentRootPath = env.ContentRootPath;
}
IHostApplicationLifetime, interfejs
IHostApplicationLifetime
umożliwia wykonywanie działań po uruchomieniu i zamykaniu. Trzy właściwości interfejsu to tokeny anulowania używane do rejestrowania Action
metod definiujących zdarzenia uruchamiania i zamykania.
Token anulowania | Wyzwalane, gdy... |
---|---|
ApplicationStarted |
Host został w pełni uruchomiony. |
ApplicationStopped |
Host kończy bezproblemowe zamknięcie. Wszystkie żądania powinny być przetwarzane. Zamknij bloki do momentu zakończenia tego zdarzenia. |
ApplicationStopping |
Host wykonuje bezproblemowe zamknięcie. Żądania mogą nadal być przetwarzane. Zamknij bloki do momentu zakończenia tego zdarzenia. |
public class Startup
{
public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
{
appLifetime.ApplicationStarted.Register(OnStarted);
appLifetime.ApplicationStopping.Register(OnStopping);
appLifetime.ApplicationStopped.Register(OnStopped);
Console.CancelKeyPress += (sender, eventArgs) =>
{
appLifetime.StopApplication();
// Don't terminate the process immediately, wait for the Main thread to exit gracefully.
eventArgs.Cancel = true;
};
}
private void OnStarted()
{
// Perform post-startup activities here
}
private void OnStopping()
{
// Perform on-stopping activities here
}
private void OnStopped()
{
// Perform post-stopped activities here
}
}
StopApplication
żąda zakończenia aplikacji. Następująca klasa używa StopApplication
metody , aby bezpiecznie zamknąć aplikację, gdy wywoływana Shutdown
jest metoda klasy:
public class MyClass
{
private readonly IHostApplicationLifetime _appLifetime;
public MyClass(IHostApplicationLifetime appLifetime)
{
_appLifetime = appLifetime;
}
public void Shutdown()
{
_appLifetime.StopApplication();
}
}
Walidacja zakresu
CreateDefaultBuilder ustawia ServiceProviderOptions.ValidateScopes wartość na true
wartość , jeśli środowisko aplikacji to Programowanie.
Gdy ValidateScopes
jest ustawiona wartość true
, domyślny dostawca usług przeprowadza kontrole w celu sprawdzenia, czy:
- Usługi o określonym zakresie nie są bezpośrednio ani pośrednio rozwiązywane przez głównego dostawcę usług.
- Usługi o określonym zakresie nie są bezpośrednio ani pośrednio wstrzykiwane do pojedynczychtonów.
Dostawca usługi głównej jest tworzony, gdy BuildServiceProvider jest wywoływany. Okres istnienia głównego dostawcy usług odpowiada okresowi istnienia aplikacji/serwera, gdy dostawca rozpoczyna się od aplikacji i jest usuwany po zamknięciu aplikacji.
Usługi o określonym zakresie są usuwane przez kontener, który je utworzył. Jeśli usługa o określonym zakresie jest tworzona w kontenerze głównym, okres istnienia usługi jest skutecznie promowany do pojedynczegotonu, ponieważ jest on usuwany tylko przez kontener główny po zamknięciu aplikacji/serwera. Sprawdzanie poprawności zakresów usługi przechwytuje te sytuacje, gdy BuildServiceProvider
jest wywoływana.
Aby zawsze weryfikować zakresy, w tym w środowisku produkcyjnym, skonfiguruj element ServiceProviderOptions w UseDefaultServiceProvider konstruktorze hosta:
WebHost.CreateDefaultBuilder(args)
.UseDefaultServiceProvider((context, options) => {
options.ValidateScopes = true;
})