Generischer .NET-Host in ASP.NET Core

Dieser Artikel stellt Informationen zur Verwendung des generischen .NET-Hosts in ASP.NET Core bereit.

Mit den ASP.NET Core-Vorlagen werden WebApplicationBuilder und WebApplication erstellt, die eine optimierte Möglichkeit zum Konfigurieren und Ausführen von Webanwendungen ohne eine Startup-Klasse bieten. Weitere Informationen zu WebApplicationBuilder und WebApplication finden Sie unter WebApplicationBuilder.

Informationen zur Verwendung des generischen .NET-Hosts in Konsolen-Apps finden Sie unter Generischer .NET-Host.

Hostdefinition

Der Host ist ein Objekt, das alle Ressourcen der App kapselt, z. B.:

  • Abhängigkeitsinjektion
  • Protokollierung
  • Konfiguration
  • IHostedService-Implementierungen

Beim Starten eines Hosts wird IHostedService.StartAsync für jede Implementierung von IHostedService aufgerufen, die in der Sammlung gehosteter Dienste des Dienstcontainers registriert ist. In einer Web-App ist eine der IHostedService-Implementierungen ein Webdienst, der eine IHostedService startet.

Die Einbindung aller voneinander abhängigen Ressourcen der App in ein Objekt ermöglicht die Kontrolle über den Start der Anwendung und das ordnungsgemäße Herunterfahren.

Einrichten eines Hosts

Der Host wird in der Regel per Code in Program.cs konfiguriert, erstellt und ausgeführt. Der folgende Code erstellt einen Host mit einer IHostedService-Implementierung, die dem DI-Container hinzugefügt wird:

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

Rufen Sie für eine HTTP-Workload ConfigureWebHostDefaults nach CreateDefaultBuilder auf:

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

Standardeinstellungen für den Generator

Die CreateDefaultBuilder-Methode:

Die ConfigureWebHostDefaults-Methode:

In den Abschnitten Einstellungen für alle App-Typen und Einstellungen für Web-Apps weiter unten in diesem Artikel wird beschrieben, wie die Standardeinstellungen des Generators außer Kraft gesetzt werden.

Von Frameworks bereitgestellte Dienste

Die folgenden Dienste werden automatisch registriert:

Weitere Informationen zu vom Framework bereitgestellten Diensten finden Sie unter Abhängigkeitsinjektion in ASP.NET Core.

IHostApplicationLifetime

Fügt den IHostApplicationLifetime-Dienst (vorher IApplicationLifetime-Dienst) in eine beliebige Klasse ein, um die Aktivitäten nach dem Starten und die Aufgaben für ordnungsgemäßes Herunterfahren zu verarbeiten. Bei drei der Eigenschaften der Schnittstelle handelt es sich um Abbruchtokens, die zum Registrieren von Ereignishandlermethoden zum Starten und Beenden von Apps verwendet werden. Die Schnittstelle umfasst außerdem eine StopApplication-Methode, mit der Apps ein ordnungsgemäßes Herunterfahren anfordern können.

Beim ordnungsgemäßen Herunterfahren führt der Host die folgenden Aufgaben aus:

  • Er löst die ApplicationStopping-Ereignishandler aus, wodurch die App Logik ausführen kann, bevor das Herunterfahren eingeleitet wird.
  • Der Host beendet den Server, wodurch neue Verbindungen deaktiviert werden. Der Server wartet auf den Abschluss von Anforderungen für vorhandene Verbindungen, solange das Timeout für das Herunterfahren dies zulässt. Der Server sendet bei weiteren Anforderungen für vorhandene Verbindungen den Header zur Verbindungstrennung.
  • Der Host löst die ApplicationStopped-Ereignishandler aus, wodurch die App nach dem Herunterfahren Logik ausführen kann.

Das folgende Beispiel zeigt eine IHostedService-Implementierung, die IHostApplicationLifetime-Ereignishandler registriert:

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _hostApplicationLifetime.ApplicationStarted.Register(OnStarted);
        _hostApplicationLifetime.ApplicationStopping.Register(OnStopping);
        _hostApplicationLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

Die IHostLifetime-Implementierung steuert, wann der Host gestartet und beendet wird. Die zuletzt registrierte Implementierung wird verwendet.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime ist die IHostLifetime-Standardimplementierung. ConsoleLifetime:

  • Lauscht auf STRGC/SIGINT (Windows), C (macOS) oder SIGTERM und ruft auf, um den Vorgang zum Herunterfahren einzuleiten.
  • Hebt die Blockierung von Erweiterungen wie RunAsync und WaitForShutdownAsync auf.

IHostEnvironment

Fügt den IHostEnvironment-Dienst in eine Klasse ein, um Informationen über die folgenden Einstellungen abzurufen:

Web-Apps implementieren die IWebHostEnvironment-Schnittstelle, die IHostEnvironment erbt und IWebHostEnvironment hinzufügt.

Konfiguration des Hosts

Die Hostkonfiguration wird für die Eigenschaften der IHostEnvironment-Implementierung verwendet.

Die Hostkonfiguration ist über HostBuilderContext.Configuration in ConfigureAppConfiguration verfügbar. Nach ConfigureAppConfiguration wird HostBuilderContext.Configuration durch die App-Konfiguration ersetzt.

Rufen Sie ConfigureHostConfiguration für IHostBuilder auf, um die Hostkonfiguration hinzuzufügen. ConfigureHostConfiguration kann mehrfach mit additiven Ergebnissen aufgerufen werden. Der Host verwendet die Option, die zuletzt einen Wert für einen bestimmten Schlüssel festlegt.

Der Umgebungsvariablenanbieter mit dem Präfix DOTNET_ und die Befehlszeilenargumente sind in CreateDefaultBuilder enthalten. Für Web-Apps wird der Umgebungsvariablenanbieter mit dem Präfix ASPNETCORE_ hinzugefügt. Das Präfix wird entfernt, wenn die Umgebungsvariablen gelesen werden. Der Wert der Umgebungsvariable für ASPNETCORE_ENVIRONMENT wird z. B. der Hostkonfigurationswert für den environment-Schlüssel.

Im folgenden Beispiel wird eine Hostkonfiguration erstellt:

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

App-Konfiguration

Die App-Konfiguration wird durch Aufrufen von ConfigureAppConfiguration für IHostBuilder erstellt. ConfigureAppConfiguration kann mehrfach mit additiven Ergebnissen aufgerufen werden. Die App verwendet die Option, die zuletzt einen Wert für einen bestimmten Schlüssel festlegt.

Die von ConfigureAppConfiguration erstellte Konfiguration steht für nachfolgende Vorgänge unter HostBuilderContext.Configuration und als Dienst über DI zur Verfügung. Die Hostkonfiguration wird ebenfalls der App-Konfiguration hinzugefügt.

Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.

Einstellungen für alle App-Typen

In diesem Abschnitt werden Hosteinstellungen aufgeführt, die sowohl für HTTP- als auch für Nicht-HTTP-Workloads gelten. Standardmäßig können die zum Konfigurieren dieser Einstellungen verwendeten Umgebungsvariablen ein DOTNET_- oder ASPNETCORE_-Präfix aufweisen, das in der folgenden Liste der Einstellungen als Platzhalter {PREFIX_} angezeigt wird. Weitere Informationen finden Sie im Abschnitt Standardeinstellungen für den Generator und Konfiguration: Umgebungsvariablen.

ApplicationName

Die Eigenschaft IHostEnvironment.ApplicationName wird über die Hostkonfiguration während der Hosterstellung festgelegt.

Schlüssel:
Typ:
Standard: Der Name der Assembly, die den Einstiegspunkt der App enthält.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, um diesen Wert festzulegen.

ContentRoot

Die Eigenschaft IHostEnvironment.ContentRootPath bestimmt, wo der Host mit der Suche nach Inhaltsdateien beginnt. Wenn der Pfad nicht vorhanden ist, kann der Host nicht gestartet werden.

Schlüssel:
Typ:
Standard: Der Ordner, in dem die App-Assembly gespeichert ist.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseContentRoot für IHostBuilder auf, um diesen Wert festzulegen:

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

Weitere Informationen finden Sie unter:

EnvironmentName

Die Eigenschaft IHostEnvironment.EnvironmentName 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.

Schlüssel:
Typ:
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseEnvironment für IHostBuilder auf, um diesen Wert festzulegen:

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

ShutdownTimeout

HostOptions.ShutdownTimeout legt den Timeout für StopAsync fest. Der Standardwert beträgt fünf Sekunden. Während des Zeitlimits verhält sich der Host 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, erhöhen Sie den Timeoutwert.

Schlüssel:
Typ:
Standard: 5 Sekunden
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder konfigurieren Sie HostOptions, um diesen Wert festzulegen. Im folgenden Beispiel wird das Zeitlimit auf 20 Sekunden festgelegt:

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

Deaktivieren des Neuladens der App-Konfiguration bei Änderungen

Die Dateien appsettings.json und appsettings.{Environment}.json werden standardmäßig neu geladen, wenn die Datei geändert wird. Zum Deaktivieren dieses Verhaltens in ASP.NET Core 5.0 oder höher müssen Sie den Schlüssel hostBuilder:reloadConfigOnChange auf false festlegen.

Schlüssel:
Typ: (true oder false)
Standard:
Befehlszeilenargument:
Umgebungsvariable:

Warnung

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen. Weitere Informationen finden Sie unter Umgebungsvariablen.

Einstellungen für Web-Apps

Einige Hosteinstellungen gelten nur für HTTP-Workloads. Standardmäßig können die zum Konfigurieren dieser Einstellungen verwendeten Umgebungsvariablen ein DOTNET_- oder ASPNETCORE_-Präfix aufweisen, das in der folgenden Liste der Einstellungen als Platzhalter {PREFIX_} angezeigt wird.

Für diese Einstellungen sind Erweiterungsmethoden in IWebHostBuilder verfügbar. In den Codebeispielen, die zeigen, wie Sie die Erweiterungsmethoden aufrufen können, wird davon ausgegangen, dass webBuilder eine Instanz von IWebHostBuilder ist. Sehen Sie hierzu das folgende Beispiel:

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

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.

Schlüssel:
Typ: (true/1 oder false/0)
Standard: Die Standardeinstellung ist , wenn die App nicht mit Kestrel im Hintergrund von IIS ausgeführt wird, dann ist diese true.
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie CaptureStartupErrors auf, um diesen Wert festzulegen:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

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.

Schlüssel:
Typ:
Standard: Leere Zeichenfolge
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

HostingStartupExcludeAssemblies

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

Schlüssel:
Typ:
Standard: Leere Zeichenfolge
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

HTTPS_Port

Der HTTPS-Umleitungsport. Wird in Erzwingen von HTTPS verwendet.

Schlüssel:
Typ:
Standard: Es ist kein Standardwert festgelegt.
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

PreferHostingUrls

Gibt an, ob der Host auf die URLs lauschen soll, die mit IWebHostBuilder konfiguriert wurden, anstatt auf die URLs zu lauschen, die mit der IServer-Implementierung konfiguriert wurden.

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie PreferHostingUrls auf, um diesen Wert festzulegen:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

StartupAssembly

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

Schlüssel:
Typ:
Standard: Die Assembly der App
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseStartup auf, um diesen Wert festzulegen. UseStartup kann einen Assemblynamen (string) oder einen Typ (TStartup) annehmen. Wenn mehrere UseStartup-Methoden aufgerufen werden, hat die letzte Vorrang.

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

SuppressStatusMessages

Wenn diese Option aktiviert ist, werden Statusmeldungen zum Hostingstart unterdrückt.

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

URLs

Eine durch Semikolons getrennte Liste mit IP-Adressen oder Hostadressen mit Ports und Protokollen, denen der Server für Anforderungen lauschen 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.

Schlüssel:
Typ:
Standard: und https://localhost:5001
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseUrls auf, um diesen Wert festzulegen:

webBuilder.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 -Webserver in ASP.NET Core.

WebRoot

Die IWebHostEnvironment.WebRootPath--Eigenschaft bestimmt den relativen Pfad zu den statischen Objekten der App. Wenn der Pfad nicht vorhanden ist, wird ein Dateianbieter ohne Funktion verwendet.

Schlüssel:
Typ:
Standard: Der Standardwert ist wwwroot. Der Pfad zu {Inhaltsstammverzeichnis}/wwwroot muss vorhanden sein.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseWebRoot für IWebHostBuilder auf, um diesen Wert festzulegen:

webBuilder.UseWebRoot("public");

Weitere Informationen finden Sie unter:

Verwalten der Lebensdauer des Hosts

Rufen Sie Methoden für die erstellte IHost-Implementierung auf, um die App zu starten und zu beenden. Diese Methoden wirken sich auf alle IHostedService-Implementierungen aus, die im Dienstcontainer registriert sind.

Run

Durch Run wird die App gestartet und der aufrufende Thread blockiert, bis der Host heruntergefahren wird.

RunAsync

Durch RunAsync wird die App ausgeführt und eine Task-Methode ausgegeben, die abgeschlossen wird, wenn das Abbruchtoken oder das Herunterfahren ausgelöst wird.

RunConsoleAsync

RunConsoleAsync aktiviert die Unterstützung der Konsole, erstellt und startet den Host und lauscht auf RunConsoleAsync++/SIGINT (Windows), C (macOS) oder SIGTERM, um das Herunterfahren auszulösen.

Starten

Start startet den Host synchron.

StartAsync

Durch StartAsync wird der Host gestartet und eine Task-Methode ausgegeben, die abgeschlossen wird, wenn das Abbruchtoken oder das Herunterfahren ausgelöst wird.

WaitForStartAsync wird am Anfang der StartAsync-Methode aufgerufen, die den Vorgang erst fortsetzt, wenn sie abgeschlossen ist. Diese Methode kann verwendet werden, um den Start zu verzögern, bis dieser durch ein externes Ereignis eingeleitet wird.

StopAsync

StopAsync versucht, den Host innerhalb des angegebenen Timeouts zu beenden.

WaitForShutdown

WaitForShutdown blockiert den aufrufenden Thread, bis das Herunterfahren durch IHostLifetime, z. B. über WaitForShutdown++/SIGINT (Windows), C (macOS) oder SIGTERM, ausgelöst wird.

WaitForShutdownAsync

WaitForShutdownAsync gibt eine Task-Methode zurück, die abgeschlossen wird, wenn das Herunterfahren über das angegebene Token ausgelöst wird, und ruft StopAsync auf.

Die ASP.NET Core-Vorlagen erstellen einen generischen .NET Core-Host (HostBuilder).

Dieser Artikel stellt Informationen zur Verwendung des generischen .NET-Hosts in ASP.NET Core bereit. Informationen zur Verwendung des generischen .NET-Hosts in Konsolen-Apps finden Sie unter Generischer .NET-Host.

Hostdefinition

Der Host ist ein Objekt, das alle Ressourcen der App kapselt, z. B.:

  • Abhängigkeitsinjektion
  • Protokollierung
  • Konfiguration
  • IHostedService-Implementierungen

Beim Starten eines Hosts wird IHostedService.StartAsync für jede Implementierung von IHostedService aufgerufen, die in der Sammlung gehosteter Dienste des Dienstcontainers registriert ist. In einer Web-App ist eine der IHostedService-Implementierungen ein Webdienst, der eine IHostedService startet.

Der wichtigste Grund für das Einschließen aller unabhängigen Ressourcen der App in einem Objekt ist die Verwaltung der Lebensdauer: steuern von Start und ordnungsgemäßem Herunterfahren der App.

Einrichten eines Hosts

Der Host wird in der Regel per Code in der Program-Klasse konfiguriert, erstellt und ausgeführt. Die Main-Methode:

  • Ruft eine CreateHostBuilder-Methode zum Erstellen und Konfigurieren eines Generatorobjekts auf.
  • Ruft Build- und Run-Methoden für das Generatorobjekt auf.

Die ASP.NET Core-Webvorlagen generieren den folgenden Code zum Erstellen eines Hosts:

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

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

Der folgende Code erstellt eine Nicht-HTTP-Workload mit einer dem DI-Container hinzugefügten IHostedService-Implementierung.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

Für einen HTTP-Workload ist die Main-Methode die gleiche, CreateHostBuilder ruft jedoch ConfigureWebHostDefaults auf:

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

Ändern Sie nicht den Namen bzw. die Signatur der CreateHostBuilder-Methode, wenn die App Entity Framework Core verwendet. Die Entity Framework Core-Tools erwarten eine -Methode, die den Host konfiguriert, ohne die App auszuführen. Weitere Informationen finden Sie unter DbContext-Instanzerstellung zur Entwurfszeit.

Standardeinstellungen für den Generator

Die CreateDefaultBuilder-Methode:

Die ConfigureWebHostDefaults-Methode:

In den Abschnitten Einstellungen für alle App-Typen und Einstellungen für Web-Apps weiter unten in diesem Artikel wird beschrieben, wie die Standardeinstellungen des Generators außer Kraft gesetzt werden.

Von Frameworks bereitgestellte Dienste

Die folgenden Dienste werden automatisch registriert:

Weitere Informationen zu vom Framework bereitgestellten Diensten finden Sie unter Abhängigkeitsinjektion in ASP.NET Core.

IHostApplicationLifetime

Fügt den IHostApplicationLifetime-Dienst (vorher IApplicationLifetime-Dienst) in eine beliebige Klasse ein, um die Aktivitäten nach dem Starten und die Aufgaben für ordnungsgemäßes Herunterfahren zu verarbeiten. Bei drei der Eigenschaften der Schnittstelle handelt es sich um Abbruchtokens, die zum Registrieren von Ereignishandlermethoden zum Starten und Beenden von Apps verwendet werden. Die Benutzeroberfläche umfasst auch eine StopApplication-Methode.

Das folgende Beispiel zeigt eine IHostedService-Implementierung, die IHostApplicationLifetime-Ereignisse registriert:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetime

Die IHostLifetime-Implementierung steuert, wann der Host gestartet und beendet wird. Die zuletzt registrierte Implementierung wird verwendet.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime ist die IHostLifetime-Standardimplementierung. ConsoleLifetime:

  • Lauscht auf STRGC/SIGINT (Windows), C (macOS) oder SIGTERM und ruft auf, um den Vorgang zum Herunterfahren einzuleiten.
  • Hebt die Blockierung von Erweiterungen wie RunAsync und WaitForShutdownAsync auf.

IHostEnvironment

Fügt den IHostEnvironment-Dienst in eine Klasse ein, um Informationen über die folgenden Einstellungen abzurufen:

Web-Apps implementieren die IWebHostEnvironment-Schnittstelle, die IHostEnvironment erbt und IWebHostEnvironment hinzufügt.

Konfiguration des Hosts

Die Hostkonfiguration wird für die Eigenschaften der IHostEnvironment-Implementierung verwendet.

Die Hostkonfiguration ist über HostBuilderContext.Configuration in ConfigureAppConfiguration verfügbar. Nach ConfigureAppConfiguration wird HostBuilderContext.Configuration durch die App-Konfiguration ersetzt.

Rufen Sie ConfigureHostConfiguration für IHostBuilder auf, um die Hostkonfiguration hinzuzufügen. ConfigureHostConfiguration kann mehrfach mit additiven Ergebnissen aufgerufen werden. Der Host verwendet die Option, die zuletzt einen Wert für einen bestimmten Schlüssel festlegt.

Der Umgebungsvariablenanbieter mit dem Präfix DOTNET_ und die Befehlszeilenargumente sind in CreateDefaultBuilder enthalten. Für Web-Apps wird der Umgebungsvariablenanbieter mit dem Präfix ASPNETCORE_ hinzugefügt. Das Präfix wird entfernt, wenn die Umgebungsvariablen gelesen werden. Der Wert der Umgebungsvariable für ASPNETCORE_ENVIRONMENT wird z. B. der Hostkonfigurationswert für den environment-Schlüssel.

Im folgenden Beispiel wird eine Hostkonfiguration erstellt:

// using Microsoft.Extensions.Configuration;

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

App-Konfiguration

Die App-Konfiguration wird durch Aufrufen von ConfigureAppConfiguration für IHostBuilder erstellt. ConfigureAppConfiguration kann mehrfach mit additiven Ergebnissen aufgerufen werden. Die App verwendet die Option, die zuletzt einen Wert für einen bestimmten Schlüssel festlegt.

Die von ConfigureAppConfiguration erstellte Konfiguration steht für nachfolgende Vorgänge unter HostBuilderContext.Configuration und als Dienst über DI zur Verfügung. Die Hostkonfiguration wird ebenfalls der App-Konfiguration hinzugefügt.

Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.

Einstellungen für alle App-Typen

In diesem Abschnitt werden Hosteinstellungen aufgeführt, die sowohl für HTTP- als auch für Nicht-HTTP-Workloads gelten. Standardmäßig können die zum Konfigurieren dieser Einstellungen verwendeten Umgebungsvariablen ein DOTNET_- oder ASPNETCORE_-Präfix aufweisen, das in der folgenden Liste der Einstellungen als Platzhalter {PREFIX_} angezeigt wird. Weitere Informationen finden Sie im Abschnitt Standardeinstellungen für den Generator und Konfiguration: Umgebungsvariablen.

ApplicationName

Die Eigenschaft IHostEnvironment.ApplicationName wird über die Hostkonfiguration während der Hosterstellung festgelegt.

Schlüssel:
Typ:
Standard: Der Name der Assembly, die den Einstiegspunkt der App enthält.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, um diesen Wert festzulegen.

ContentRoot

Die Eigenschaft IHostEnvironment.ContentRootPath bestimmt, wo der Host mit der Suche nach Inhaltsdateien beginnt. Wenn der Pfad nicht vorhanden ist, kann der Host nicht gestartet werden.

Schlüssel:
Typ:
Standard: Der Ordner, in dem die App-Assembly gespeichert ist.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseContentRoot für IHostBuilder auf, um diesen Wert festzulegen:

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

Weitere Informationen finden Sie unter:

EnvironmentName

Die Eigenschaft IHostEnvironment.EnvironmentName 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.

Schlüssel:
Typ:
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseEnvironment für IHostBuilder auf, um diesen Wert festzulegen:

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

ShutdownTimeout

HostOptions.ShutdownTimeout legt den Timeout für StopAsync fest. Der Standardwert beträgt fünf Sekunden. Während des Zeitlimits verhält sich der Host 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, erhöhen Sie den Timeoutwert.

Schlüssel:
Typ:
Standard: 5 Sekunden
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder konfigurieren Sie HostOptions, um diesen Wert festzulegen. Im folgenden Beispiel wird das Zeitlimit auf 20 Sekunden festgelegt:

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

Deaktivieren des Neuladens der App-Konfiguration bei Änderungen

Die Dateien appsettings.json und appsettings.{Environment}.json werden standardmäßig neu geladen, wenn die Datei geändert wird. Zum Deaktivieren dieses Verhaltens in ASP.NET Core 5.0 oder höher müssen Sie den Schlüssel hostBuilder:reloadConfigOnChange auf false festlegen.

Schlüssel:
Typ: (true oder false)
Standard:
Befehlszeilenargument:
Umgebungsvariable:

Warnung

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen. Weitere Informationen finden Sie unter Umgebungsvariablen.

Einstellungen für Web-Apps

Einige Hosteinstellungen gelten nur für HTTP-Workloads. Standardmäßig können die zum Konfigurieren dieser Einstellungen verwendeten Umgebungsvariablen ein DOTNET_- oder ASPNETCORE_-Präfix aufweisen, das in der folgenden Liste der Einstellungen als Platzhalter {PREFIX_} angezeigt wird.

Für diese Einstellungen sind Erweiterungsmethoden in IWebHostBuilder verfügbar. In den Codebeispielen, die zeigen, wie Sie die Erweiterungsmethoden aufrufen können, wird davon ausgegangen, dass webBuilder eine Instanz von IWebHostBuilder ist. Sehen Sie hierzu das folgende Beispiel:

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

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.

Schlüssel:
Typ: (true/1 oder false/0)
Standard: Die Standardeinstellung ist , wenn die App nicht mit Kestrel im Hintergrund von IIS ausgeführt wird, dann ist diese true.
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie CaptureStartupErrors auf, um diesen Wert festzulegen:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

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.

Schlüssel:
Typ:
Standard: Leere Zeichenfolge
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

HostingStartupExcludeAssemblies

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

Schlüssel:
Typ:
Standard: Leere Zeichenfolge
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

HTTPS_Port

Der HTTPS-Umleitungsport. Wird in Erzwingen von HTTPS verwendet.

Schlüssel:
Typ:
Standard: Es ist kein Standardwert festgelegt.
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

PreferHostingUrls

Gibt an, ob der Host auf die URLs lauschen soll, die mit IWebHostBuilder konfiguriert wurden, anstatt auf die URLs zu lauschen, die mit der IServer-Implementierung konfiguriert wurden.

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie PreferHostingUrls auf, um diesen Wert festzulegen:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

StartupAssembly

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

Schlüssel:
Typ:
Standard: Die Assembly der App
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseStartup auf, um diesen Wert festzulegen. UseStartup kann einen Assemblynamen (string) oder einen Typ (TStartup) annehmen. Wenn mehrere UseStartup-Methoden aufgerufen werden, hat die letzte Vorrang.

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

SuppressStatusMessages

Wenn diese Option aktiviert ist, werden Statusmeldungen zum Hostingstart unterdrückt.

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

URLs

Eine durch Semikolons getrennte Liste mit IP-Adressen oder Hostadressen mit Ports und Protokollen, denen der Server für Anforderungen lauschen 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.

Schlüssel:
Typ:
Standard: und https://localhost:5001
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseUrls auf, um diesen Wert festzulegen:

webBuilder.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 -Webserver in ASP.NET Core.

WebRoot

Die IWebHostEnvironment.WebRootPath--Eigenschaft bestimmt den relativen Pfad zu den statischen Objekten der App. Wenn der Pfad nicht vorhanden ist, wird ein Dateianbieter ohne Funktion verwendet.

Schlüssel:
Typ:
Standard: Der Standardwert ist wwwroot. Der Pfad zu {Inhaltsstammverzeichnis}/wwwroot muss vorhanden sein.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseWebRoot für IWebHostBuilder auf, um diesen Wert festzulegen:

webBuilder.UseWebRoot("public");

Weitere Informationen finden Sie unter:

Verwalten der Lebensdauer des Hosts

Rufen Sie Methoden für die erstellte IHost-Implementierung auf, um die App zu starten und zu beenden. Diese Methoden wirken sich auf alle IHostedService-Implementierungen aus, die im Dienstcontainer registriert sind.

Run

Durch Run wird die App gestartet und der aufrufende Thread blockiert, bis der Host heruntergefahren wird.

RunAsync

Durch RunAsync wird die App ausgeführt und eine Task-Methode ausgegeben, die abgeschlossen wird, wenn das Abbruchtoken oder das Herunterfahren ausgelöst wird.

RunConsoleAsync

RunConsoleAsync aktiviert die Unterstützung der Konsole, erstellt und startet den Host und lauscht auf RunConsoleAsync++/SIGINT (Windows), C (macOS) oder SIGTERM, um das Herunterfahren auszulösen.

Starten

Start startet den Host synchron.

StartAsync

Durch StartAsync wird der Host gestartet und eine Task-Methode ausgegeben, die abgeschlossen wird, wenn das Abbruchtoken oder das Herunterfahren ausgelöst wird.

WaitForStartAsync wird am Anfang der StartAsync-Methode aufgerufen, die den Vorgang erst fortsetzt, wenn sie abgeschlossen ist. Diese Methode kann verwendet werden, um den Start zu verzögern, bis dieser durch ein externes Ereignis eingeleitet wird.

StopAsync

StopAsync versucht, den Host innerhalb des angegebenen Timeouts zu beenden.

WaitForShutdown

WaitForShutdown blockiert den aufrufenden Thread, bis das Herunterfahren durch IHostLifetime, z. B. über WaitForShutdown++/SIGINT (Windows), C (macOS) oder SIGTERM, ausgelöst wird.

WaitForShutdownAsync

WaitForShutdownAsync gibt eine Task-Methode zurück, die abgeschlossen wird, wenn das Herunterfahren über das angegebene Token ausgelöst wird, und ruft StopAsync auf.

Externe Steuerung

Die Lebensdauer des Hosts kann mithilfe von Methoden, die extern aufgerufen werden können, direkt gesteuert werden:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

Die ASP.NET Core-Vorlagen erstellen einen generischen .NET Core-Host (HostBuilder).

Dieser Artikel stellt Informationen zur Verwendung des generischen .NET-Hosts in ASP.NET Core bereit. Informationen zur Verwendung des generischen .NET-Hosts in Konsolen-Apps finden Sie unter Generischer .NET-Host.

Hostdefinition

Der Host ist ein Objekt, das alle Ressourcen der App kapselt, z. B.:

  • Abhängigkeitsinjektion
  • Protokollierung
  • Konfiguration
  • IHostedService-Implementierungen

Beim Starten eines Hosts wird IHostedService.StartAsync für jede Implementierung von IHostedService aufgerufen, die in der Sammlung gehosteter Dienste des Dienstcontainers registriert ist. In einer Web-App ist eine der IHostedService-Implementierungen ein Webdienst, der eine IHostedService startet.

Der wichtigste Grund für das Einschließen aller unabhängigen Ressourcen der App in einem Objekt ist die Verwaltung der Lebensdauer: steuern von Start und ordnungsgemäßem Herunterfahren der App.

Einrichten eines Hosts

Der Host wird in der Regel per Code in der Program-Klasse konfiguriert, erstellt und ausgeführt. Die Main-Methode:

  • Ruft eine CreateHostBuilder-Methode zum Erstellen und Konfigurieren eines Generatorobjekts auf.
  • Ruft Build- und Run-Methoden für das Generatorobjekt auf.

Die ASP.NET Core-Webvorlagen generieren den folgenden Code zum Erstellen eines generischen Hosts:

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

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

Der folgende Code erstellt einen generischen Host mithilfe einer Nicht-HTTP-Workload. Die IHostedService-Implementierung wird dem DI-Container hinzugefügt:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

Für einen HTTP-Workload ist die Main-Methode die gleiche, CreateHostBuilder ruft jedoch ConfigureWebHostDefaults auf:

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

Der voranstehende Code wird von den ASP.NET Core-Vorlagen generiert.

Ändern Sie nicht den Namen bzw. die Signatur der CreateHostBuilder-Methode, wenn die App Entity Framework Core verwendet. Die Entity Framework Core-Tools erwarten eine -Methode, die den Host konfiguriert, ohne die App auszuführen. Weitere Informationen finden Sie unter DbContext-Instanzerstellung zur Entwurfszeit.

Standardeinstellungen für den Generator

Die CreateDefaultBuilder-Methode:

Die ConfigureWebHostDefaults-Methode:

In den Abschnitten Einstellungen für alle App-Typen und Einstellungen für Web-Apps weiter unten in diesem Artikel wird beschrieben, wie die Standardeinstellungen des Generators außer Kraft gesetzt werden.

Von Frameworks bereitgestellte Dienste

Die folgenden Dienste werden automatisch registriert:

Weitere Informationen zu vom Framework bereitgestellten Diensten finden Sie unter Abhängigkeitsinjektion in ASP.NET Core.

IHostApplicationLifetime

Fügt den IHostApplicationLifetime-Dienst (vorher IApplicationLifetime-Dienst) in eine beliebige Klasse ein, um die Aktivitäten nach dem Starten und die Aufgaben für ordnungsgemäßes Herunterfahren zu verarbeiten. Bei drei der Eigenschaften der Schnittstelle handelt es sich um Abbruchtokens, die zum Registrieren von Ereignishandlermethoden zum Starten und Beenden von Apps verwendet werden. Die Benutzeroberfläche umfasst auch eine StopApplication-Methode.

Das folgende Beispiel zeigt eine IHostedService-Implementierung, die IHostApplicationLifetime-Ereignisse registriert:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetime

Die IHostLifetime-Implementierung steuert, wann der Host gestartet und beendet wird. Die zuletzt registrierte Implementierung wird verwendet.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime ist die IHostLifetime-Standardimplementierung. ConsoleLifetime:

  • Lauscht auf STRGC/SIGINT (Windows), C (macOS) oder SIGTERM und ruft auf, um den Vorgang zum Herunterfahren einzuleiten.
  • Hebt die Blockierung von Erweiterungen wie RunAsync und WaitForShutdownAsync auf.

IHostEnvironment

Fügt den IHostEnvironment-Dienst in eine Klasse ein, um Informationen über die folgenden Einstellungen abzurufen:

Web-Apps implementieren die IWebHostEnvironment-Schnittstelle, die IHostEnvironment erbt und IWebHostEnvironment hinzufügt.

Konfiguration des Hosts

Die Hostkonfiguration wird für die Eigenschaften der IHostEnvironment-Implementierung verwendet.

Die Hostkonfiguration ist über HostBuilderContext.Configuration in ConfigureAppConfiguration verfügbar. Nach ConfigureAppConfiguration wird HostBuilderContext.Configuration durch die App-Konfiguration ersetzt.

Rufen Sie ConfigureHostConfiguration für IHostBuilder auf, um die Hostkonfiguration hinzuzufügen. ConfigureHostConfiguration kann mehrfach mit additiven Ergebnissen aufgerufen werden. Der Host verwendet die Option, die zuletzt einen Wert für einen bestimmten Schlüssel festlegt.

Der Umgebungsvariablenanbieter mit dem Präfix DOTNET_ und die Befehlszeilenargumente sind in CreateDefaultBuilder enthalten. Für Web-Apps wird der Umgebungsvariablenanbieter mit dem Präfix ASPNETCORE_ hinzugefügt. Das Präfix wird entfernt, wenn die Umgebungsvariablen gelesen werden. Der Wert der Umgebungsvariable für ASPNETCORE_ENVIRONMENT wird z. B. der Hostkonfigurationswert für den environment-Schlüssel.

Im folgenden Beispiel wird eine Hostkonfiguration erstellt:

// using Microsoft.Extensions.Configuration;

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

App-Konfiguration

Die App-Konfiguration wird durch Aufrufen von ConfigureAppConfiguration für IHostBuilder erstellt. ConfigureAppConfiguration kann mehrfach mit additiven Ergebnissen aufgerufen werden. Die App verwendet die Option, die zuletzt einen Wert für einen bestimmten Schlüssel festlegt.

Die von ConfigureAppConfiguration erstellte Konfiguration steht für nachfolgende Vorgänge unter HostBuilderContext.Configuration und als Dienst über DI zur Verfügung. Die Hostkonfiguration wird ebenfalls der App-Konfiguration hinzugefügt.

Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.

Einstellungen für alle App-Typen

In diesem Abschnitt werden Hosteinstellungen aufgeführt, die sowohl für HTTP- als auch für Nicht-HTTP-Workloads gelten. Standardmäßig können die zum Konfigurieren dieser Einstellungen verwendeten Umgebungsvariablen ein DOTNET_- oder ASPNETCORE_-Präfix aufweisen, das in der folgenden Konfiguration für den Platzhalter {PREFIX_} angezeigt wird.

ApplicationName

Die Eigenschaft IHostEnvironment.ApplicationName wird über die Hostkonfiguration während der Hosterstellung festgelegt.

Schlüssel:
Typ:
Standard: Der Name der Assembly, die den Einstiegspunkt der App enthält.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, um diesen Wert festzulegen.

ContentRoot

Die Eigenschaft IHostEnvironment.ContentRootPath bestimmt, wo der Host mit der Suche nach Inhaltsdateien beginnt. Wenn der Pfad nicht vorhanden ist, kann der Host nicht gestartet werden.

Schlüssel:
Typ:
Standard: Der Ordner, in dem die App-Assembly gespeichert ist.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseContentRoot für IHostBuilder auf, um diesen Wert festzulegen:

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

Weitere Informationen finden Sie unter:

EnvironmentName

Die Eigenschaft IHostEnvironment.EnvironmentName 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.

Schlüssel:
Typ:
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseEnvironment für IHostBuilder auf, um diesen Wert festzulegen:

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

ShutdownTimeout

HostOptions.ShutdownTimeout legt den Timeout für StopAsync fest. Der Standardwert beträgt fünf Sekunden. Während des Zeitlimits verhält sich der Host 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, erhöhen Sie den Timeoutwert.

Schlüssel:
Typ:
Standard: 5 Sekunden
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder konfigurieren Sie HostOptions, um diesen Wert festzulegen. Im folgenden Beispiel wird das Zeitlimit auf 20 Sekunden festgelegt:

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

Einstellungen für Web-Apps

Einige Hosteinstellungen gelten nur für HTTP-Workloads. Standardmäßig können Umgebungsvariablen, die zur Konfiguration dieser Einstellungen verwendet werden, ein DOTNET_- oder ASPNETCORE_-Präfix haben.

Für diese Einstellungen sind Erweiterungsmethoden in IWebHostBuilder verfügbar. In den Codebeispielen, die zeigen, wie Sie die Erweiterungsmethoden aufrufen können, wird davon ausgegangen, dass webBuilder eine Instanz von IWebHostBuilder ist. Sehen Sie hierzu das folgende Beispiel:

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

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.

Schlüssel:
Typ: (true/1 oder false/0)
Standard: Die Standardeinstellung ist , wenn die App nicht mit Kestrel im Hintergrund von IIS ausgeführt wird, dann ist diese true.
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie CaptureStartupErrors auf, um diesen Wert festzulegen:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

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.

Schlüssel:
Typ:
Standard: Leere Zeichenfolge
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

HostingStartupExcludeAssemblies

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

Schlüssel:
Typ:
Standard: Leere Zeichenfolge
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

HTTPS_Port

Der HTTPS-Umleitungsport. Wird in Erzwingen von HTTPS verwendet.

Schlüssel:
Typ:
Standard: Es ist kein Standardwert festgelegt.
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

PreferHostingUrls

Gibt an, ob der Host auf die URLs lauschen soll, die mit IWebHostBuilder konfiguriert wurden, anstatt auf die URLs zu lauschen, die mit der IServer-Implementierung konfiguriert wurden.

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie PreferHostingUrls auf, um diesen Wert festzulegen:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

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:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

StartupAssembly

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

Schlüssel:
Typ:
Standard: Die Assembly der App
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseStartup auf, um diesen Wert festzulegen. UseStartup kann einen Assemblynamen (string) oder einen Typ (TStartup) annehmen. Wenn mehrere UseStartup-Methoden aufgerufen werden, hat die letzte Vorrang.

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

SuppressStatusMessages

Wenn diese Option aktiviert ist, werden Statusmeldungen zum Hostingstart unterdrückt.

Schlüssel:
Typ: (true/1 oder false/0)
Standard:
Umgebungsvariable:

Verwenden Sie die Konfiguration, oder rufen Sie UseSetting auf, um diesen Wert festzulegen:

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

URLs

Eine durch Semikolons getrennte Liste mit IP-Adressen oder Hostadressen mit Ports und Protokollen, denen der Server für Anforderungen lauschen 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.

Schlüssel:
Typ:
Standard: und https://localhost:5001
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseUrls auf, um diesen Wert festzulegen:

webBuilder.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 Implementierung des Webservers in ASP.NET Core.

WebRoot

Die IWebHostEnvironment.WebRootPath--Eigenschaft bestimmt den relativen Pfad zu den statischen Objekten der App. Wenn der Pfad nicht vorhanden ist, wird ein Dateianbieter ohne Funktion verwendet.

Schlüssel:
Typ:
Standard: Der Standardwert ist wwwroot. Der Pfad zu {Inhaltsstammverzeichnis}/wwwroot muss vorhanden sein.
Umgebungsvariable:

Verwenden Sie die Umgebungsvariable, oder rufen Sie UseWebRoot für IWebHostBuilder auf, um diesen Wert festzulegen:

webBuilder.UseWebRoot("public");

Weitere Informationen finden Sie unter:

Verwalten der Lebensdauer des Hosts

Rufen Sie Methoden für die erstellte IHost-Implementierung auf, um die App zu starten und zu beenden. Diese Methoden wirken sich auf alle IHostedService-Implementierungen aus, die im Dienstcontainer registriert sind.

Run

Durch Run wird die App gestartet und der aufrufende Thread blockiert, bis der Host heruntergefahren wird.

RunAsync

Durch RunAsync wird die App ausgeführt und eine Task-Methode ausgegeben, die abgeschlossen wird, wenn das Abbruchtoken oder das Herunterfahren ausgelöst wird.

RunConsoleAsync

RunConsoleAsync aktiviert die Unterstützung der Konsole, erstellt und startet den Host und lauscht auf RunConsoleAsync++/SIGINT (Windows), C (macOS) oder SIGTERM, um das Herunterfahren auszulösen.

Starten

Start startet den Host synchron.

StartAsync

Durch StartAsync wird der Host gestartet und eine Task-Methode ausgegeben, die abgeschlossen wird, wenn das Abbruchtoken oder das Herunterfahren ausgelöst wird.

WaitForStartAsync wird am Anfang der StartAsync-Methode aufgerufen, die den Vorgang erst fortsetzt, wenn sie abgeschlossen ist. Diese Methode kann verwendet werden, um den Start zu verzögern, bis dieser durch ein externes Ereignis eingeleitet wird.

StopAsync

StopAsync versucht, den Host innerhalb des angegebenen Timeouts zu beenden.

WaitForShutdown

WaitForShutdown blockiert den aufrufenden Thread, bis das Herunterfahren durch IHostLifetime, z. B. über WaitForShutdown++/SIGINT (Windows), C (macOS) oder SIGTERM, ausgelöst wird.

WaitForShutdownAsync

WaitForShutdownAsync gibt eine Task-Methode zurück, die abgeschlossen wird, wenn das Herunterfahren über das angegebene Token ausgelöst wird, und ruft StopAsync auf.

Externe Steuerung

Die Lebensdauer des Hosts kann mithilfe von Methoden, die extern aufgerufen werden können, direkt gesteuert werden:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

Zusätzliche Ressourcen