ASP.NET Core-Webhost

Durch ASP.NET Core-Apps kann ein Host gestartet und konfiguriert werden. Der Host ist verantwortlich für das Starten der App und das Verwalten der Lebensdauer. Der Host konfiguriert mindestens einen Server und eine Pipeline für die Anforderungsverarbeitung. Der Host kann auch die Protokollierung, die Dependency Injection und die Konfiguration einrichten.

In diesem Artikel wird der Webhost behandelt, der nur aus Gründen der Abwärtskompatibilität verfügbar bleibt. Die ASP.NET Core-Vorlagen erstellen einen generischen .NET-Host, der für alle App-Typen empfohlen wird.

In diesem Artikel wird der Webhost behandelt, der zum Hosten von Web-Apps dient. Verwenden Sie für andere Arten von Apps den generischen Host.

Einrichten eines Hosts

Erstellen Sie einen Host mithilfe einer Instanz von IWebHostBuilder. Dies wird üblicherweise am Einstiegspunkt der App (die Main-Methode) durchgeführt.

In den Projektvorlagen befindet Main sich in Program.cs. Eine typische App ruft CreateDefaultBuilder auf, um die Einrichtung eines Hosts zu starten:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Der Code, der CreateDefaultBuilder aufruft, befindet sich in einer Methode namens CreateWebHostBuilder, die diesen Code von dem Code in Main trennt, der Run im Generatorobjekt aufruft. Diese Trennung ist erforderlich, wenn Sie Entity Framework Core-Tools verwenden. Die Tools erwarten eine CreateWebHostBuilder-Methode, die sie zur Entwurfszeit aufrufen können, um den Host zu konfigurieren, ohne die App auszuführen. Eine Alternative dazu ist die Implementierung vonIDesignTimeDbContextFactory. Weitere Informationen finden Sie unter DbContext-Instanzerstellung zur Entwurfszeit.

CreateDefaultBuilder führt folgende Ausgaben aus:

Die durch CreateDefaultBuilder definierte Konfiguration kann von ConfigureAppConfiguration, ConfigureLogging und anderen Methoden sowie Erweiterungsmethoden von IWebHostBuilder überschrieben und erweitert werden. Es folgen einige Beispiele:

  • ConfigureAppConfiguration wird zum zusätzlichen Festlegen von IConfiguration für die App verwendet. Der folgende ConfigureAppConfiguration-Aufruf fügt einen Delegaten hinzu, um die App-Konfiguration in die Datei appsettings.xml einzufügen. ConfigureAppConfiguration kann mehrmals aufgerufen werden. Beachten Sie, dass diese Konfiguration nicht für den Host gilt (z.B. Server-URLs oder Umgebungen). Informationen finden Sie im Abschnitt Hostkonfigurationswerte.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • Der folgende ConfigureLogging-Aufruf fügt einen Delegaten hinzu, um den Mindestprotokolliergrad (SetMinimumLevel) auf LogLevel.Warning zu konfigurieren. Diese Einstellung überschreibt die Einstellungen in appsettings.Development.json (LogLevel.Debug) und appsettings.Production.json (LogLevel.Error), die durch CreateDefaultBuilder konfiguriert wurden. ConfigureLogging kann mehrmals aufgerufen werden.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • Der folgende Aufruf von ConfigureKestrel überschreibt den Standardwert von 30.000.000 Bytes von Limits.MaxRequestBodySize, der festgelegt wurde, als Kestrel durch CreateDefaultBuilder konfiguriert wurde:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    
  • Der folgende Aufruf von UseKestrel überschreibt den Standardwert von 30.000.000 Bytes von Limits.MaxRequestBodySize, der festgelegt wurde, als Kestrel durch CreateDefaultBuilder konfiguriert wurde:

    WebHost.CreateDefaultBuilder(args)
        .UseKestrel(options =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

Das Inhaltsstammverzeichnis bestimmt, wo der Host nach Inhaltsdateien (z.B. MVC-Ansichtsdateien) sucht. Wenn die App aus dem Stammordner des Projekts gestartet wird, wird dieser als Inhaltsstammverzeichnis verwendet. Dies ist die Standardeinstellung in Visual Studio und für neue .NET-Vorlagen.

Weitere Informationen zur App-Konfiguration finden Sie unter Konfiguration in ASP.NET Core.

Hinweis

Als Alternative zur Verwendung der statischen CreateDefaultBuilder-Methode ist das Erstellen eines Hosts von WebHostBuilder ein unterstützter Ansatz mit ASP.NET Core 2.x.

Beim Einrichten eines Hosts können die Methoden Configure und ConfigureServices bereitgestellt werden. Wenn eine Startup-Klasse angegeben wird, muss diese eine Configure-Methode definieren. Weitere Informationen finden Sie unter Anwendungsstart in ASP.NET Core. Wenn ConfigureServices mehrmals aufgerufen wird, werden diese Aufrufe einander angefügt. Durch mehrere Aufrufe von Configure oder UseStartup in WebHostBuilder werden die vorherigen Einstellungen ersetzt.

Hostkonfigurationswerte

WebHostBuilder basiert auf folgenden Ansätzen, um die Hostkonfigurationswerte festzulegen:

  • Hostbuilderkonfigurationen, die Umgebungsvariablen im Format ASPNETCORE_{configurationKey} enthalten. Beispielsweise ASPNETCORE_ENVIRONMENT.
  • Erweiterungen wie UseContentRoot und UseConfiguration (siehe Abschnitt Überschreiben der Konfiguration).
  • UseSetting und der zugeordnete Schlüssel. Wenn Sie einen Wert mit UseSetting festlegen, wird dieser unabhängig vom Typ als Zeichenfolge festgelegt.

Der Host verwendet die Option, die zuletzt einen Wert festlegt. Weitere Informationen finden Sie im nächsten Abschnitt unter Außerkraftsetzen der Konfiguration.

Anwendungsschlüssel (Name)

Die Eigenschaft IWebHostEnvironment.ApplicationName wird automatisch festgelegt, wenn UseStartup oder Configure während der Hosterstellung aufgerufen wird. Der Wert wird auf den Namen der Assembly festgelegt, die den Einstiegspunkt der App enthält. Um den Wert explizit festzulegen, verwenden Sie den WebHostDefaults.ApplicationKey:

Die Eigenschaft IHostingEnvironment.ApplicationName wird automatisch festgelegt, wenn UseStartup oder Configure während der Hosterstellung aufgerufen wird. Der Wert wird auf den Namen der Assembly festgelegt, die den Einstiegspunkt der App enthält. Um den Wert explizit festzulegen, verwenden Sie den WebHostDefaults.ApplicationKey:

Schlüssel: Anwendungsname
Typ: Zeichenfolge
Standardwert: Der Name der Assembly, die den Einstiegspunkt der App enthält.
Festlegen mit: UseSetting
Umgebungsvariable: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Erfassen von Startfehlern

Diese Einstellung steuert das Erfassen von Startfehlern.

Schlüssel: captureStartupErrors
Typ: Boolesch (true or 1)
Standard: Die Standardeinstellung ist false, wenn die App nicht mit Kestrel im Hintergrund von IIS ausgeführt wird, dann ist diese true.
Festlegen mit: CaptureStartupErrors
Umgebungsvariable: ASPNETCORE_CAPTURESTARTUPERRORS

Wenn diese false ist, führen Fehler beim Start zum Beenden des Hosts. Wenn diese true ist, erfasst der Host Ausnahmen während des Starts und versucht, den Server zu starten.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Inhaltsstammverzeichnis

Diese Einstellung bestimmt, wo ASP.NET mit der Suche nach Inhaltsdateien beginnt.

Schlüssel: contentRoot
Typ: Zeichenfolge
Standard: Entspricht standardmäßig dem Ordner, in dem die App-Assembly gespeichert ist.
Festlegen mit: UseContentRoot
Umgebungsvariable: ASPNETCORE_CONTENTROOT

Das Inhaltsstammverzeichnis wird ebenfalls als Basispfad für das Webstammverzeichnis verwendet. Wenn der Pfad des Inhaltsstammverzeichnisses nicht vorhanden ist, kann der Host nicht gestartet werden.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Weitere Informationen finden Sie unter:

Detaillierte Fehler

Bestimmt, ob detaillierte Fehler erfasst werden sollen.

Schlüssel: detailedErrors
Typ: Boolesch (true or 1)
Standard: FALSE
Festlegen mit: UseSetting
Umgebungsvariable: ASPNETCORE_DETAILEDERRORS

Wenn diese Einstellung aktiviert ist (oder die Umgebung auf Development festgelegt ist), erfasst die App detaillierte Ausnahmen.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Umgebung

Legt die Umgebung der App fest.

Schlüssel: environment
Typ: Zeichenfolge
Standard: Produktion
Festlegen mit: UseEnvironment
Umgebungsvariable: ASPNETCORE_ENVIRONMENT

Die Umgebung kann auf einen beliebigen Wert festgelegt werden. Zu den durch Frameworks definierten Werten zählen Development, Staging und Production. Die Groß-/Kleinschreibung wird bei Werten nicht beachtet. Standardmäßig wird die Umgebung aus der ASPNETCORE_ENVIRONMENT-Umgebungsvariablen gelesen. Wenn Sie Visual Studio verwenden, werden Umgebungsvariablen möglicherweise in der Datei launchSettings.json festgelegt. Weitere Informationen finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Hostingstartassemblys

Legt die Hostingstartassemblys der App fest.

Schlüssel: hostingStartupAssemblies
Typ: Zeichenfolge
Standard: Leere Zeichenfolge
Festlegen mit: UseSetting
Umgebungsvariable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Eine durch Semikolons getrennte Zeichenfolge der Hostingstartassemblys, die beim Start geladen werden soll.

Obwohl der Konfigurationswert standardmäßig auf eine leere Zeichenfolge festgelegt ist, enthalten die Hostingstartassemblys immer die Assembly der App. Wenn Hostingstartassemblys bereitgestellt werden, werden diese zur Assembly der App hinzugefügt, damit diese geladen werden, wenn die App während des Starts die allgemeinen Dienste erstellt.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

HTTPS-Anschluss

Legen Sie den HTTPS-Umleitungsport fest. Wird in Erzwingen von HTTPS verwendet.

Schlüssel: https_port
Typ: Zeichenfolge
Standard: Es ist kein Standardwert festgelegt.
Festlegen mit: UseSetting
Umgebungsvariable: ASPNETCORE_HTTPS_PORT

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Auszuschließende Hostingstartassemblys

Eine durch Semikolons getrennte Zeichenfolge der Hostingstartassemblys, die beim Start ausgeschlossen werden sollen.

Schlüssel: hostingStartupExcludeAssemblies
Typ: Zeichenfolge
Standard: Leere Zeichenfolge
Festlegen mit: UseSetting
Umgebungsvariable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Bevorzugen von Hosting-URLs

Gibt an, ob der Hosts den URLs lauschen soll, die mit WebHostBuilder konfiguriert wurden, statt denen, die mit der IServer-Implementierung konfiguriert wurden.

Schlüssel: preferHostingUrls
Typ: Boolesch (true or 1)
Standard: TRUE
Festlegen mit: PreferHostingUrls
Umgebungsvariable: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

Verhindern des Hostingstarts

Verhindert das automatische Laden der Hostingstartassemblys, einschließlich denen, die von der Assembly der App konfiguriert wurden. Weitere Informationen finden Sie unter Verwenden von Hostingstartassemblys in ASP.NET Core.

Schlüssel: preventHostingStartup
Typ: Boolesch (true or 1)
Standard: FALSE
Festlegen mit: UseSetting
Umgebungsvariable: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

Server-URLs

Gibt die IP-Adressen oder Hostadressen mit Ports und Protokollen an, denen der Server für Anforderungen lauschen soll.

Schlüssel: urls
Typ: Zeichenfolge
Standard: http://localhost:5000
Festlegen mit: UseUrls
Umgebungsvariable: ASPNETCORE_URLS

Legt die Einstellung auf eine durch Semikolons (;) getrennte Liste von URL-Präfixen fest, auf die der Server reagieren soll. Beispielsweise http://localhost:123. Verwenden Sie *, um anzugeben, dass der Server mithilfe des angegebenen Ports und Protokolls (z.B. http://*:5000) den Anfragen aller IP-Adressen oder Hostnamen lauschen soll. Das Protokoll (http:// oder https://) muss in jeder URL enthalten sein. Die unterstützten Formate variieren bei den verschiedenen Servern.

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

Kestrel verfügt über eine eigene API für die Endpunktkonfiguration. Weitere Informationen finden Sie unter Konfigurieren von Endpunkten für den ASP.NET Core-Kestrel-Webserver.

Kestrel verfügt über eine eigene API für die Endpunktkonfiguration. Weitere Informationen finden Sie unter Implementierung des Webservers Kestrel in ASP.NET Core.

Timeout beim Herunterfahren

Gibt die Wartezeit an, bis der Webhost heruntergefahren wird.

Schlüssel: shutdownTimeoutSeconds
Typ: Ganze Zahl
Standard: 5
Festlegen mit: UseShutdownTimeout
Umgebungsvariable: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Obwohl der Schlüssel eine ganze Zahl mit UseSetting (z.B. .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")) akzeptiert, akzeptiert die Erweiterungsmethode UseShutdownTimeout ein TimeSpan-Objekt.

Während des Zeitlimits, verhält sich das Hosting folgendermaßen:

Wenn das Zeitlimit abläuft bevor alle gehosteten Dienste beendet sind, werden alle verbleibenden aktiven Dienste beendet, wenn die App herunterfährt. Die Dienste werden beendet, selbst wenn die Verarbeitung noch nicht abgeschlossen ist. Wenn die Dienste mehr Zeit zum Beenden benötigen, sollten Sie das Zeitlimit erhöhen.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Startassembly

Bestimmt die Assembly, die nach der Startup-Klasse suchen soll.

Schlüssel: startupAssembly
Typ: Zeichenfolge
Standard: Die Assembly der App
Festlegen mit: UseStartup
Umgebungsvariable: ASPNETCORE_STARTUPASSEMBLY

Es kann auf die Assembly nach Name (string) oder Typ (TStartup) verwiesen werden. Wenn mehrere UseStartup-Methoden aufgerufen werden, hat die letzte Vorrang.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Webstammverzeichnis

Legt den relativen Pfad für die statischen Objekte der App fest.

Schlüssel: webroot
Typ: Zeichenfolge
Standard: Der Standardwert ist wwwroot. Der Pfad zu {Inhaltsstammverzeichnis}/wwwroot muss vorhanden sein. Wenn der Pfad nicht vorhanden ist, wird ein Dateianbieter ohne Funktion verwendet.
Festlegen mit: UseWebRoot
Umgebungsvariable: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Weitere Informationen finden Sie unter:

Außerkraftsetzen der Konfiguration

Verwenden Sie die Konfiguration, um den Webhost zu konfigurieren. Im folgenden Beispiel wird die Hostkonfiguration optional in einer hostsettings.json-Datei angegeben. Jede Konfiguration, die aus der Datei hostsettings.json geladen wird, kann von Befehlszeilenargumenten überschrieben werden. Die erstellte Konfiguration (in config) wird verwendet, um den Host mit UseConfiguration zu konfigurieren. Der Konfiguration der App wird die IWebHostBuilder-Konfiguration hinzugefügt, das Gegenteil gilt jedoch nicht. ConfigureAppConfiguration hat keinen Einfluss auf die IWebHostBuilder-Konfiguration.

Das Überschreiben der Konfiguration wird von UseUrls bereitgestellt, hierbei kommt die Konfiguration hostsettings.json zuerst und anschließend die Konfiguration der Befehlszeilenargumente:

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"
}

Hinweis

UseConfiguration kopiert nur Schlüssel aus der bereitgestellten IConfiguration-Schnittstelle in die Konfiguration des Host-Generators. Daher hat das Festlegen von reloadOnChange: true für JSON-, INI- und XML-Einstellungsdateien keine Auswirkung.

Damit der Host auf einer bestimmten URL ausgeführt wird, kann der gewünschte Wert von der Befehlszeile aus übergeben werden, wenn dotnet run ausgeführt wird. Das Befehlszeilenargument überschreibt den urls-Wert der hostsettings.json-Datei, und der Server lauscht Port 8080:

dotnet run --urls "http://*:8080"

Verwalten des Hosts

Run

Die Run-Methode startet die Web-App und blockiert den aufrufenden Thread, bis der Host heruntergefahren wird:

host.Run();

Starten

Führen Sie den Host auf nicht blockierende Weise aus, indem Sie dessen Start-Methode aufrufen:

using (host)
{
    host.Start();
    Console.ReadLine();
}

Wenn eine Liste mit URLs an die Start-Methode übergeben wird, lauscht diese den angegebenen URLs:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

Die App kann einen neuen Host, der die vorab konfigurierten Standardwerte von CreateDefaultBuilder verwendet, mithilfe einer statischen Hilfsmethode initialisieren und starten. Diese Methoden starten den Server ohne Konsolenausgabe und mit der WaitForShutdown-Methode, die auf eine Unterbrechung wartet (STRG+C/SIGINT oder SIGTERM):

Start(RequestDelegate app)

Beginnend mit einer RequestDelegate-Funktion:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Stellen Sie im Browser eine Anforderung an http://localhost:5000, um die Antwort „Hello World!“ zu erhalten. WaitForShutdown blockiert, bis eine Unterbrechung (STRG+C/SIGINT oder SIGTERM) ausgelöst wird. Die App zeigt die Console.WriteLine-Meldung an und wartet, bis diese durch Tastendruck beendet wird.

Start(string url, RequestDelegate app)

Beginnend mit einer URL und 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();
}

Erzeugt das gleiche Ergebnis wie Start(RequestDelegate app) , mit dem Unterschied, dass die App auf http://localhost:8080 reagiert.

Start(Action<IRouteBuilder> routeBuilder)

Verwenden Sie eine Instanz von IRouteBuilder (Microsoft.AspNetCore.Routing), um Routingmiddleware zu verwenden:

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

Verwenden Sie folgende Browseranforderung mit dem Beispiel:

Anforderung Antwort
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Löst eine Ausnahme mit der Zeichenfolge „ooops!“ aus.
http://localhost:5000/throw Löst eine Ausnahme mit der Zeichenfolge „Uh oh!“ aus.
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown blockiert, bis eine Unterbrechung (STRG+C/SIGINT oder SIGTERM) ausgelöst wird. Die App zeigt die Console.WriteLine-Meldung an und wartet, bis diese durch Tastendruck beendet wird.

Start(string url, Action<IRouteBuilder> routeBuilder)

Verwenden Sie eine URL und eine Instanz von 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();
}

Erzeugt das gleiche Ergebnis wie Start(Action<IRouteBuilder> routeBuilder) , mit dem Unterschied, dass die App auf http://localhost:8080 reagiert.

StartWith(Action<IApplicationBuilder> app)

Stellen Sie einen Delegaten bereit, um eine IApplicationBuilder-Schnittstelle zu konfigurieren:

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

Stellen Sie im Browser eine Anforderung an http://localhost:5000, um die Antwort „Hello World!“ zu erhalten. WaitForShutdown blockiert, bis eine Unterbrechung (STRG+C/SIGINT oder SIGTERM) ausgelöst wird. Die App zeigt die Console.WriteLine-Meldung an und wartet, bis diese durch Tastendruck beendet wird.

StartWith(string url, Action<IApplicationBuilder> app)

Stellen Sie eine URL und einen Delegaten bereit, um eine IApplicationBuilder-Schnittstelle zu konfigurieren:

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

Erzeugt das gleiche Ergebnis wie StartWith(Action<IApplicationBuilder> app) , mit dem Unterschied, dass die App auf http://localhost:8080 reagiert.

IWebHostEnvironment-Schnittstelle

Die IWebHostEnvironment-Schnittstelle stellt Informationen über die Webhostingumgebung der App bereit. Verwenden Sie Constructor Injection zum Abrufen der IWebHostEnvironment-Schnittstelle, um deren Eigenschaften und Erweiterungsmethoden zu verwenden:

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

Ein konventionsbasierter Ansatz kann verwendet werden, um die App beim Start je nach Umgebung zu konfigurieren. Fügen Sie alternativ die IWebHostEnvironment-Schnittstelle in den Startup-Konstruktor für die Verwendung in ConfigureServices ein:

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

Hinweis

Zusätzlich zur IsDevelopment-Erweiterungsmethode stellt die IWebHostEnvironment-Schnittstelle die IsStaging-, IsProduction- und IsEnvironment(string environmentName)-Methoden bereit. Weitere Informationen finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.

Der IWebHostEnvironment-Dienst kann ebenfalls direkt in die Configure-Methode eingefügt werden, um die Verarbeitungspipeline einzurichten:

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 kann in die Invoke-Methode eingefügt werden, wenn eine benutzerdefinierte Middleware erstellt wird:

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

IHostingEnvironment-Schnittstelle

Die IHostingEnvironment-Schnittstelle stellt Informationen über die Webhostingumgebung der App bereit. Verwenden Sie Constructor Injection zum Abrufen der IHostingEnvironment-Schnittstelle, um deren Eigenschaften und Erweiterungsmethoden zu verwenden:

public class CustomFileReader
{
    private readonly IHostingEnvironment _env;

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

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Ein konventionsbasierter Ansatz kann verwendet werden, um die App beim Start je nach Umgebung zu konfigurieren. Fügen Sie alternativ die IHostingEnvironment-Schnittstelle in den Startup-Konstruktor für die Verwendung in ConfigureServices ein:

public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IHostingEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Hinweis

Zusätzlich zur IsDevelopment-Erweiterungsmethode stellt die IHostingEnvironment-Schnittstelle die IsStaging-, IsProduction- und IsEnvironment(string environmentName)-Methoden bereit. Weitere Informationen finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.

Der IHostingEnvironment-Dienst kann ebenfalls direkt in die Configure-Methode eingefügt werden, um die Verarbeitungspipeline einzurichten:

public void Configure(IApplicationBuilder app, IHostingEnvironment 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;
}

IHostingEnvironment kann in die Invoke-Methode eingefügt werden, wenn eine benutzerdefinierte Middleware erstellt wird:

public async Task Invoke(HttpContext context, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

IHostApplicationLifetime-Schnittstelle

IHostApplicationLifetime ermöglicht Aktivitäten nach dem Starten und beim Herunterfahren. Bei drei der Eigenschaften der Schnittstelle handelt es sich um Abbruchtokens, die zum Registrieren von Action-Methoden verwendet werden, durch die Ereignisse beim Starten und Herunterfahren definiert werden.

Abbruchtoken Wird ausgelöst, wenn…
ApplicationStarted Der Host vollständig gestartet wurde.
ApplicationStopped Der Host ein ordnungsgemäßes Herunterfahren abschließt. Alle Anforderungen sollten verarbeitet worden sein. Das Herunterfahren wird blockiert, bis das Ereignis abgeschlossen ist.
ApplicationStopping Der Host ein ordnungsgemäßes Herunterfahren ausführt. Anforderungen möglicherweise noch verarbeitet werden. Das Herunterfahren wird blockiert, bis das Ereignis abgeschlossen ist.
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 fordert das Beenden der App an. Die folgende Klasse verwendet StopApplication, um eine App ordnungsgemäß herunterzufahren, wenn die Shutdown-Methode der Klasse aufgerufen wird:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

IApplicationLifetime-Schnittstelle

IApplicationLifetime ermöglicht Aktivitäten nach dem Starten und beim Herunterfahren. Bei drei der Eigenschaften der Schnittstelle handelt es sich um Abbruchtokens, die zum Registrieren von Action-Methoden verwendet werden, durch die Ereignisse beim Starten und Herunterfahren definiert werden.

Abbruchtoken Wird ausgelöst, wenn…
ApplicationStarted Der Host vollständig gestartet wurde.
ApplicationStopped Der Host ein ordnungsgemäßes Herunterfahren abschließt. Alle Anforderungen sollten verarbeitet worden sein. Das Herunterfahren wird blockiert, bis das Ereignis abgeschlossen ist.
ApplicationStopping Der Host ein ordnungsgemäßes Herunterfahren ausführt. Anforderungen möglicherweise noch verarbeitet werden. Das Herunterfahren wird blockiert, bis das Ereignis abgeschlossen ist.
public class Startup
{
    public void Configure(IApplicationBuilder app, IApplicationLifetime 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 fordert das Beenden der Anwendung an. Die folgende Klasse verwendet StopApplication, um eine App ordnungsgemäß herunterzufahren, wenn die Shutdown-Methode der Klasse aufgerufen wird:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

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

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

Bereichsvalidierung

CreateDefaultBuilder legt ServiceProviderOptions.ValidateScopes auf true fest, wenn die Umgebung der App „Entwicklung“ ist.

Wenn ValidateScopes auf true festgelegt wird, führt der Standarddienstanbieter Überprüfungen durch, um sicherzustellen, dass:

  • Bereichsbezogene Dienste nicht direkt oder indirekt vom Stammdienstanbieter aufgelöst werden
  • Bereichsbezogene Dienste nicht direkt oder indirekt in Singletons eingefügt werden

Der Stammdienstanbieter wird erstellt, wenn BuildServiceProvider aufgerufen wird. Die Lebensdauer des Stammdienstanbieters entspricht der Lebensdauer der App/des Servers, wenn der Anbieter mit der App erstellt wird und verworfen wird, wenn die App beendet wird.

Bereichsbezogene Dienste werden von dem Container verworfen, der sie erstellt hat. Wenn ein bereichsbezogener Dienst im Stammcontainer erstellt wird, wird die Lebensdauer effektiv auf Singleton heraufgestuft, da er nur vom Stammcontainer verworfen wird, wenn die App/der Server heruntergefahren wird. Die Überprüfung bereichsbezogener Dienste erfasst diese Situationen, wenn BuildServiceProvider aufgerufen wird.

Konfigurieren Sie ServiceProviderOptions mit UseDefaultServiceProvider auf dem Hostbuilder, um Bereiche immer zu validieren, auch in der Produktionsumgebung:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Zusätzliche Ressourcen