Host internetowy platformy ASP.NET Core

  • Artykuł

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.cspliku . 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 IDesignTimeDbContextFactoryelementu . Aby uzyskać więcej informacji, zobacz Design-time DbContext Creation (Tworzenie elementu DbContext w czasie projektowania).

Metoda CreateDefaultBuilder wykonuje następujące zadania:

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ące ConfigureAppConfiguration wywołanie dodaje delegata w celu uwzględnienia konfiguracji aplikacji w appsettings.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 programie appsettings.Development.json (LogLevel.Debug) i appsettings.Production.json (LogLevel.Error) skonfigurowanym przez CreateDefaultBuilderprogram . 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 przez CreateDefaultBuilderprogram :

    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ład ASPNETCORE_ENVIRONMENT.
  • Rozszerzenia, takie jak UseContentRoot i UseConfiguration (zobacz sekcję Przesłoń konfigurację).
  • UseSetting i skojarzony klucz. Podczas ustawiania wartości za pomocą UseSettingparametru 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 truehost 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 Developmentwartość ) 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, Stagingi 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:

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 UseUrlshostsettings.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 IWebHostEnvironmentStartup do użycia w ConfigureServicespliku :

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 IsStagingmetody , IsProductioni 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;
}

IWebHostEnvironmentmoż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.cslokalizacji . 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 IDesignTimeDbContextFactoryelementu . Aby uzyskać więcej informacji, zobacz Design-time DbContext Creation (Tworzenie elementu DbContext w czasie projektowania).

Metoda CreateDefaultBuilder wykonuje następujące zadania:

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ące ConfigureAppConfiguration wywołanie dodaje delegata w celu uwzględnienia konfiguracji aplikacji w appsettings.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 programie appsettings.Development.json (LogLevel.Debug) i appsettings.Production.json (LogLevel.Error) skonfigurowanym przez CreateDefaultBuilderprogram . 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 przez CreateDefaultBuilderprogram :

    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ład ASPNETCORE_ENVIRONMENT.
  • Rozszerzenia, takie jak UseContentRoot i UseConfiguration (zobacz sekcję Przesłoń konfigurację).
  • UseSetting i skojarzony klucz. Podczas ustawiania wartości za pomocą UseSettingparametru 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 truehost 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 Developmentwartość ) 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, Stagingi 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:

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 UseUrlshostsettings.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 IWebHostEnvironmentStartup do użycia w ConfigureServicespliku :

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 IsStagingmetody , IsProductioni 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;
}

IWebHostEnvironmentmoż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.cslokalizacji . 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 IDesignTimeDbContextFactoryelementu . Aby uzyskać więcej informacji, zobacz Design-time DbContext Creation (Tworzenie elementu DbContext w czasie projektowania).

Metoda CreateDefaultBuilder wykonuje następujące zadania:

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ące ConfigureAppConfiguration wywołanie dodaje delegata w celu uwzględnienia konfiguracji aplikacji w appsettings.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 programie appsettings.Development.json (LogLevel.Debug) i appsettings.Production.json (LogLevel.Error) skonfigurowanym przez CreateDefaultBuilderprogram . 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 przez CreateDefaultBuilderprogram :

    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ład ASPNETCORE_ENVIRONMENT.
  • Rozszerzenia, takie jak UseContentRoot i UseConfiguration (zobacz sekcję Przesłoń konfigurację).
  • UseSetting i skojarzony klucz. Podczas ustawiania wartości za pomocą UseSettingparametru 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 truehost 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 Developmentwartość ) 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, Stagingi 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:

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 UseUrlshostsettings.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 IWebHostEnvironmentStartup do użycia w ConfigureServicespliku :

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 IsStagingmetody , IsProductioni 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;
}

IWebHostEnvironmentmoż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