Generischer .NET-Host in ASP.NET Core

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

Dieses Thema enthält Informationen zur Verwendung des generischen .NET-Hosts in ASP.NET Core. 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 HTTP-Serverimplementierung 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 CreateHostBuilder-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 den vom Framework bereitgestellten Diensten finden Sie unter Dependency Injection 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:

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 WebRootPath hinzufügt.

Konfiguration des Hosts

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

Sie 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 ist unter HostBuilderContext.Configuration verfügbar und kann für nachfolgende Vorgänge und als Dienst für die Abhängigkeitsinjektion verwendet werden. 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 Umgebungsvariablen, die zur Konfiguration dieser Einstellungen verwendet werden, ein DOTNET_- oder ASPNETCORE_-Präfix haben. Weitere Informationen finden Sie im Abschnitt Standardeinstellungen für den Generator.

ApplicationName

Die Eigenschaft IHostEnvironment.ApplicationName wird von der Hostkonfiguration während der Hosterstellung festgelegt.

Schlüssel: applicationName
Typ: string
Standard: Der Name der Assembly, die den Einstiegspunkt der App enthält.
Umgebungsvariable: <PREFIX_>APPLICATIONNAME

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: contentRoot
Typ: string
Standard: Der Ordner, in dem die App-Assembly gespeichert ist.
Umgebungsvariable: <PREFIX_>CONTENTROOT

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: environment
Typ: string
Standard: Production
Umgebungsvariable: <PREFIX_>ENVIRONMENT

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 das Zeitlimit 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, sollten Sie das Zeitlimit erhöhen.

Schlüssel: shutdownTimeoutSeconds
Typ: int
Standard: 5 Sekunden
Umgebungsvariable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

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: hostBuilder:reloadConfigOnChange
Typ: bool (true oder 1)
Standard: true
Befehlszeilenargument: hostBuilder:reloadConfigOnChange
Umgebungsvariable: <PREFIX_>hostBuilder:reloadConfigOnChange

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 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: captureStartupErrors
Typ: bool (true oder 1)
Standard: Die Standardeinstellung ist false, wenn die App nicht mit Kestrel im Hintergrund von IIS ausgeführt wird, dann ist diese true.
Umgebungsvariable: <PREFIX_>CAPTURESTARTUPERRORS

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: detailedErrors
Typ: bool (true oder 1)
Standard: false
Umgebungsvariable: <PREFIX_>_DETAILEDERRORS

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: hostingStartupAssemblies
Typ: string
Standard: Leere Zeichenfolge
Umgebungsvariable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

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: hostingStartupExcludeAssemblies
Typ: string
Standard: Leere Zeichenfolge
Umgebungsvariable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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: https_port
Typ: string
Standard: Es ist kein Standardwert festgelegt.
Umgebungsvariable: <PREFIX_>HTTPS_PORT

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: preferHostingUrls
Typ: bool (true oder 1)
Standard: true
Umgebungsvariable: <PREFIX_>_PREFERHOSTINGURLS

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: preventHostingStartup
Typ: bool (true oder 1)
Standard: false
Umgebungsvariable: <PREFIX_>_PREVENTHOSTINGSTARTUP

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: startupAssembly
Typ: string
Standard: Die Assembly der App
Umgebungsvariable: <PREFIX_>STARTUPASSEMBLY

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

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: urls
Typ: string
Standard: http://localhost:5000 und https://localhost:5001
Umgebungsvariable: <PREFIX_>URLS

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

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: webroot
Typ: string
Standard: Der Standardwert ist wwwroot. Der Pfad zu {Inhaltsstammverzeichnis}/wwwroot muss vorhanden sein.
Umgebungsvariable: <PREFIX_>WEBROOT

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 STRG+C/SIGINT 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. Dies kann verwendet werden, um den Start zu verzögern, bis dieser durch ein externes Ereignis initiiert wird.

StopAsync

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

WaitForShutdown

WaitForShutdown blockiert den aufrufenden Thread, bis das Herunterfahren durch den IHostLifetime, z. B. über STRG+C/SIGINT 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).

Dieses Thema enthält Informationen zur Verwendung des generischen .NET-Hosts in ASP.NET Core. 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 HTTP-Serverimplementierung 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 CreateHostBuilder-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 den vom Framework bereitgestellten Diensten finden Sie unter Dependency Injection 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:

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 WebRootPath hinzufügt.

Konfiguration des Hosts

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

Sie 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 ist unter HostBuilderContext.Configuration verfügbar und kann für nachfolgende Vorgänge und als Dienst für die Abhängigkeitsinjektion verwendet werden. 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 Umgebungsvariablen, die zur Konfiguration dieser Einstellungen verwendet werden, ein DOTNET_- oder ASPNETCORE_-Präfix haben.

ApplicationName

Die Eigenschaft IHostEnvironment.ApplicationName wird von der Hostkonfiguration während der Hosterstellung festgelegt.

Schlüssel: applicationName
Typ: string
Standard: Der Name der Assembly, die den Einstiegspunkt der App enthält.
Umgebungsvariable: <PREFIX_>APPLICATIONNAME

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: contentRoot
Typ: string
Standard: Der Ordner, in dem die App-Assembly gespeichert ist.
Umgebungsvariable: <PREFIX_>CONTENTROOT

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: environment
Typ: string
Standard: Production
Umgebungsvariable: <PREFIX_>ENVIRONMENT

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 das Zeitlimit 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, sollten Sie das Zeitlimit erhöhen.

Schlüssel: shutdownTimeoutSeconds
Typ: int
Standard: 5 Sekunden
Umgebungsvariable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

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: captureStartupErrors
Typ: bool (true oder 1)
Standard: Die Standardeinstellung ist false, wenn die App nicht mit Kestrel im Hintergrund von IIS ausgeführt wird, dann ist diese true.
Umgebungsvariable: <PREFIX_>CAPTURESTARTUPERRORS

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: detailedErrors
Typ: bool (true oder 1)
Standard: false
Umgebungsvariable: <PREFIX_>_DETAILEDERRORS

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: hostingStartupAssemblies
Typ: string
Standard: Leere Zeichenfolge
Umgebungsvariable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

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: hostingStartupExcludeAssemblies
Typ: string
Standard: Leere Zeichenfolge
Umgebungsvariable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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: https_port
Typ: string
Standard: Es ist kein Standardwert festgelegt.
Umgebungsvariable: <PREFIX_>HTTPS_PORT

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: preferHostingUrls
Typ: bool (true oder 1)
Standard: true
Umgebungsvariable: <PREFIX_>_PREFERHOSTINGURLS

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: preventHostingStartup
Typ: bool (true oder 1)
Standard: false
Umgebungsvariable: <PREFIX_>_PREVENTHOSTINGSTARTUP

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: startupAssembly
Typ: string
Standard: Die Assembly der App
Umgebungsvariable: <PREFIX_>STARTUPASSEMBLY

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

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: urls
Typ: string
Standard: http://localhost:5000 und https://localhost:5001
Umgebungsvariable: <PREFIX_>URLS

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 Kestrel 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: webroot
Typ: string
Standard: Der Standardwert ist wwwroot. Der Pfad zu {Inhaltsstammverzeichnis}/wwwroot muss vorhanden sein.
Umgebungsvariable: <PREFIX_>WEBROOT

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 STRG+C/SIGINT 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. Dies kann verwendet werden, um den Start zu verzögern, bis dieser durch ein externes Ereignis initiiert wird.

StopAsync

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

WaitForShutdown

WaitForShutdown blockiert den aufrufenden Thread, bis das Herunterfahren durch den IHostLifetime, z. B. über STRG+C/SIGINT 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));
        }
    }
}

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.

In diesem Artikel wird der generische ASP.NET Core-Host (HostBuilder) erläutert, der für das Hosten von Apps verwendet wird, die keine HTTP-Anforderungen verarbeiten.

Das Ziel des generischen Hosts besteht darin, die HTTP-Pipeline von der Webhost-API zu entkoppeln, um mehr Hostszenarios zu ermöglichen. Messaging, Hintergrundtasks und andere Nicht-HTTP-Workloads, die auf dem generischen Host basieren, profitieren von übergreifenden Funktionen wie der Konfiguration, Dependency Injection (DI) und der Protokollerstellung.

Der generische Host ist neu in ASP.NET Core 2.1 und ist nicht für Webhostingszenarios geeignet. Verwenden Sie den Webhost für Webhostingszenarios. Der generische Host wird den Webhost in einem zukünftigen Release ersetzen und als primäre Host-API in HTTP- und Nicht-HTTP-Szenarios fungieren.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Wenn Sie die Beispiel-App in Visual Studio Code ausführen, verwenden Sie ein externes oder integriertes Terminal. Führen Sie das Beispiel nicht in internalConsole aus.

So legen Sie die Konsole in Visual Studio Code fest:

  1. Öffnen Sie die Datei .vscode/launch.json.
  2. Suchen Sie in der Konfiguration .NET Core-Start (Konsole) den Eintrag Konsole. Legen Sie den Wert auf externalTerminal oder integratedTerminal fest.

Einführung

Die generische Hostbibliothek ist im Namespace Microsoft.Extensions.Hosting verfügbar und wird vom Paket Microsoft.Extensions.Hosting bereitgestellt. Das Paket Microsoft.Extensions.Hosting ist im Metapaket Microsoft.AspNetCore.App (ASP.NET Core 2.1 oder höher) enthalten.

IHostedService ist der Einstiegspunkt für die Ausführung des Codes. Jede Implementierung von IHostedService wird in der Reihenfolge der Dienstregistrierung in ConfigureServices ausgeführt. StartAsync wird in jeder IHostedService-Schnittstelle aufgerufen, wenn der Host gestartet wird, und StopAsync wird in umgekehrter Registrierungsreihenfolge aufgerufen, wenn der Host ordnungsgemäß heruntergefahren wird.

Einrichten eines Hosts

IHostBuilder ist die Hauptkomponente, die Bibliotheken und Apps für die Initialisierung, Erstellung und Ausführung des Hosts verwenden:

public static async Task Main(string[] args)
{
    var host = new HostBuilder()
        .Build();

    await host.RunAsync();
}

Optionen

HostOptions-Konfigurationsoptionen für IHost.

Timeout beim Herunterfahren

ShutdownTimeout legt den Timeout für StopAsync fest. Der Standardwert beträgt fünf Sekunden.

Die folgende Optionskonfiguration in Program.Main erhöht den standardmäßigen Timeout beim Herunterfahren von 5 Sekunden auf 20 Sekunden:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    })
    .Build();

Standarddienste

Die folgenden Dienste werden bei der Hostinitialisierung registriert:

Konfiguration des Hosts

Die Konfiguration des Hosts wird durch Folgendes erstellt:

Erweiterungsmethoden

Anwendungsschlüssel (Name)

Die Eigenschaft IHostingEnvironment.ApplicationName wird von der Hostkonfiguration während der Hostkonstruktion festgelegt. Um den Wert explizit festzulegen, verwenden Sie den HostDefaults.ApplicationKey:

Schlüssel: applicationName
Typ: string
Standard: Der Name der Assembly, die den Einstiegspunkt der App enthält.
Festlegen mit: HostBuilderContext.HostingEnvironment.ApplicationName
Umgebungsvariable: <PREFIX_>APPLICATIONNAME (<PREFIX_> ist optional und benutzerdefiniert)

Inhaltsstammverzeichnis

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

Schlüssel: contentRoot
Typ: string
Standard: Entspricht standardmäßig dem Ordner, in dem die App-Assembly gespeichert ist.
Festlegen mit: UseContentRoot
Umgebungsvariable: <PREFIX_>CONTENTROOT (<PREFIX_> ist optional und benutzerdefiniert)

Wenn der Pfad nicht vorhanden ist, kann der Host nicht gestartet werden.

var host = new HostBuilder()
    .UseContentRoot("c:\\<content-root>")

Weitere Informationen finden Sie unter Grundlagen: Inhaltsstammverzeichnis.

Umgebung

Legt die Umgebung der App fest.

Schlüssel: environment
Typ: string
Standard: Production
Festlegen mit: UseEnvironment
Umgebungsvariable: <PREFIX_>ENVIRONMENT (<PREFIX_> ist optional und benutzerdefiniert)

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.

var host = new HostBuilder()
    .UseEnvironment(EnvironmentName.Development)

ConfigureHostConfiguration

ConfigureHostConfiguration verwendet einen IConfigurationBuilder, um eine IConfiguration für den Host zu erstellen. Die Hostkonfiguration dient zum Initialisieren der IHostingEnvironment für die Verwendung im App-Buildprozesses.

ConfigureHostConfiguration kann mehrfach mit additiven Ergebnissen aufgerufen werden. Der Host verwendet die Option, die zuletzt einen Wert für einen bestimmten Schlüssel festlegt.

Standardmäßig sind keine Anbieter enthalten. Sie müssen explizit angeben, welche Konfigurationsanbieter die App in ConfigureHostConfiguration erfordert, einschließlich Folgendes:

  • Dateikonfiguration (z.B. von einer Datei namens hostsettings.json)
  • Konfiguration von Umgebungsvariablen
  • Konfiguration von Befehlszeilenargumenten
  • Alle anderen erforderlichen Konfigurationsanbieter

Die Dateikonfiguration des Hosts erfolgt durch Angabe des App-Basispfads mit SetBasePath gefolgt von einem Aufruf eines der Dateikonfigurationsanbieter. Die Beispiel-App verwendet die JSON-Datei hostsettings.json und ruft AddJsonFile auf, um die Hostkonfigurationseinstellungen der Datei zu nutzen.

Um die Umgebungsvariablenkonfiguration des Hosts hinzuzufügen, rufen Sie AddEnvironmentVariables im Host-Generator auf. AddEnvironmentVariables akzeptiert ein optionales benutzerdefiniertes Präfix. Die Beispiel-App verwendet das Präfix PREFIX_. Das Präfix wird entfernt, wenn die Umgebungsvariablen gelesen werden. Wenn der Host der Beispiel-App konfiguriert wird, wird der Wert der Umgebungsvariable für PREFIX_ENVIRONMENT der Hostkonfigurationswert für den environment-Schlüssel.

Wenn Sie Visual Studio oder eine App mit dotnet run während der Entwicklung verwenden, können Umgebungsvariablen in der Datei Properties/launchSettings.json festgelegt werden. In Visual Studio Code können Umgebungsvariablen während der Entwicklung in der Datei .vscode/launch.json festgelegt werden. Weitere Informationen finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.

Die Befehlszeilenkonfiguration wird durch Aufrufen von AddCommandLine hinzugefügt. Die Befehlszeilenkonfiguration wird zuletzt hinzugefügt, damit Befehlszeilenargumente die Konfiguration überschreiben können, die von früheren Konfigurationsanbietern bereitgestellt wurden.

hostsettings.json:

{
  "environment": "Development"
}

Weitere Konfigurationen können durch die Schlüssel applicationName und contentRoot bereitgestellt werden.

Beispielkonfiguration für HostBuilder mithilfe von ConfigureHostConfiguration:

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

ConfigureAppConfiguration

Die App-Konfiguration wird durch Aufrufen von ConfigureAppConfiguration in der IHostBuilder-Implementierung erstellt. ConfigureAppConfiguration verwendet einen IConfigurationBuilder, um eine IConfiguration für die App zu erstellen. 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 ist unter HostBuilderContext.Configuration verfügbar und kann für nachfolgende Vorgänge und in Services verwendet werden.

Auf die App-Konfiguration wird automatisch die Hostkonfiguration angewendet, die von ConfigureHostConfiguration bereitgestellt wird.

Beispielkonfiguration für die App mithilfe von ConfigureAppConfiguration:

var host = new HostBuilder()
    .ConfigureAppConfiguration((hostContext, configApp) =>
    {
        configApp.SetBasePath(Directory.GetCurrentDirectory());
        configApp.AddJsonFile("appsettings.json", optional: true);
        configApp.AddJsonFile(
            $"appsettings.{hostContext.HostingEnvironment.EnvironmentName}.json", 
            optional: true);
        configApp.AddEnvironmentVariables(prefix: "PREFIX_");
        configApp.AddCommandLine(args);
    })

appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

appsettings.Production.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Error",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

Um Einstellungsdateien in das Ausgabeverzeichnis zu verschieben, geben Sie die Einstellungsdateien als MSBuild-Projektelemente in der Projektdatei an. Die Beispiel-App verschiebt ihre JSON-App-Einstellungsdateien und hostsettings.json mit dem folgenden <Content>-Element:

<ItemGroup>
  <Content Include="**\*.json" Exclude="bin\**\*;obj\**\*" 
      CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Hinweis

Konfigurationserweiterungsmethoden wie AddJsonFile und AddEnvironmentVariables erfordern zusätzliche NuGet-Pakete, z.B. Microsoft.Extensions.Configuration.Json und Microsoft.Extensions.Configuration.EnvironmentVariables. Wenn die App nicht das Microsoft.AspNetCore.App-Metapaket verwendet, müssen diese Pakete dem Projekt zusätzlich zum Microsoft.Extensions.Configuration-Kernpaket hinzugefügt werden. Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.

ConfigureServices

Mithilfe von ConfigureServices werden Dienste zum Container Abhängigkeitsinjektion der App hinzugefügt. ConfigureServices kann mehrfach mit additiven Ergebnissen aufgerufen werden.

Ein gehosteter Dienst ist eine Klasse mit Logik für Hintergrundaufgaben, die die Schnittstelle IHostedService implementiert. Weitere Informationen finden Sie unter Hintergrundtasks mit gehosteten Diensten in ASP.NET Core.

Die Beispiel-App verwendet die Erweiterungsmethode AddHostedService, um einen Dienst für Lebensdauerereignisse (LifetimeEventsHostedService) und einen zeitgesteuerten Hintergrundtask (TimedHostedService) zur App hinzuzufügen:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        if (hostContext.HostingEnvironment.IsDevelopment())
        {
            // Development service configuration
        }
        else
        {
            // Non-development service configuration
        }

        services.AddHostedService<LifetimeEventsHostedService>();
        services.AddHostedService<TimedHostedService>();
    })

ConfigureLogging

ConfigureLogging fügt einen Delegaten für die Konfiguration des bereitgestellten ILoggingBuilder hinzu. ConfigureLogging kann mehrfach mit additiven Ergebnissen aufgerufen werden.

var host = new HostBuilder()
    .ConfigureLogging((hostContext, configLogging) =>
    {
        configLogging.AddConsole();
        configLogging.AddDebug();
    })

UseConsoleLifetime

UseConsoleLifetime lauscht auf STRG+C/SIGINT oder SIGTERM und ruft StopApplication auf, um das Herunterfahren zu beginnen. UseConsoleLifetime hebt die Blockierung von Erweiterungen wie RunAsync und WaitForShutdownAsync auf. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime ist vorab als Standardimplementierung für die Lebensdauer registriert. Die letzte registrierte Lebensdauer wird verwendet.

var host = new HostBuilder()
    .UseConsoleLifetime()

Containerkonfiguration

Der Host kann eine IServiceProviderFactory<TContainerBuilder>-Schnittstelle verwenden, um die Integration in andere Container zu unterstützten. Das Bereitstellen einer Factory ist kein Teil der DI-Containerregistrierung, sondern ein Host, der systemintern verwendet wird, um den entsprechenden DI-Container zu erstellen. UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) überschreibt die Standardfactory, die zum Erstellen des Dienstanbieters der App verwendet wurde.

Die benutzerdefinierte Containerkonfiguration wird von der Methode ConfigureContainer verwaltet. ConfigureContainer stellt eine stark typisierte Möglichkeit für das Konfigurieren des Containers auf Basis der zugrunde liegenden Host-API bereit. ConfigureContainer kann mehrfach mit additiven Ergebnissen aufgerufen werden.

Erstellen eines Dienstcontainers für die App:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

Bereitstellen einer Factory für den Dienstcontainer:

using System;
using Microsoft.Extensions.DependencyInjection;

namespace GenericHostSample
{
    internal class ServiceContainerFactory : 
        IServiceProviderFactory<ServiceContainer>
    {
        public ServiceContainer CreateBuilder(
            IServiceCollection services)
        {
            return new ServiceContainer();
        }

        public IServiceProvider CreateServiceProvider(
            ServiceContainer containerBuilder)
        {
            throw new NotImplementedException();
        }
    }
}

Verwenden Sie die Factory, und konfigurieren Sie den benutzerdefinierten Dienstcontainer für die App:

var host = new HostBuilder()
    .UseServiceProviderFactory<ServiceContainer>(new ServiceContainerFactory())
    .ConfigureContainer<ServiceContainer>((hostContext, container) =>
    {
    })

Erweiterungen

Die Erweiterung des Hosts wird mit der Erweiterungsmethode in IHostBuilder durchgeführt. Im folgenden Beispiel wird dargestellt, wie eine Erweiterungsmethode eine IHostBuilder-Implementierung mit dem TimedHostedService-Beispiel erweitert, das in Hintergrundtasks mit gehosteten Diensten in ASP.NET Core gezeigt wird.

var host = new HostBuilder()
    .UseHostedService<TimedHostedService>()
    .Build();

await host.StartAsync();

Eine App richtet die UseHostedService-Erweiterungsmethode zum Registrieren des in T übergebenen gehosteten Diensts ein:

using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class Extensions
{
    public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
        where T : class, IHostedService, IDisposable
    {
        return hostBuilder.ConfigureServices(services =>
            services.AddHostedService<T>());
    }
}

Verwalten des Hosts

Die Implementierung von IHost ist für das Starten und Beenden der Implementierungen von IHostedService verantwortlich, die im Dienstcontainer registriert sind.

Run

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

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        host.Run();
    }
}

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:

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        await host.RunAsync();
    }
}

RunConsoleAsync

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

public class Program
{
    public static async Task Main(string[] args)
    {
        var hostBuilder = new HostBuilder();

        await hostBuilder.RunConsoleAsync();
    }
}

Start und StopAsync

Start startet den Host synchron.

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

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            await host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

StartAsync und StopAsync

StartAsync startet die App.

StopAsync hält die App an.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.StopAsync();
        }
    }
}

WaitForShutdown

WaitForShutdown wird über die IHostLifetime ausgelöst, z. B. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (lauscht auf STRG+C/SIGINT oder SIGTERM). WaitForShutdown ruft StopAsync auf.

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

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.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.WaitForShutdownAsync();
        }

    }
}

Externe Steuerung

Die externe Steuerung des Hosts kann mithilfe von Methoden durchgeführt werden, die extern aufgerufen werden können:

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

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

IHostingEnvironment-Schnittstelle

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

public class MyClass
{
    private readonly IHostingEnvironment _env;

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

    public void DoSomething()
    {
        var environmentName = _env.EnvironmentName;
    }
}

Weitere Informationen finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.

IApplicationLifetime-Schnittstelle

IApplicationLifetime ermöglicht Aktivitäten nach dem Starten und beim Herunterfahren (einschließlich Anforderungen für ordnungsgemäßes 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.

Fügen Sie den IApplicationLifetime-Dienst über einen Konstruktor in eine beliebige Klasse ein. Die Beispiel-App verwendet die Konstruktorinjektion für eine LifetimeEventsHostedService-Klasse (eine IHostedService-Implementierung), um die Ereignisse zu registrieren.

LifetimeEventsHostedService.cs:

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

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IApplicationLifetime 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
    }
}

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 IApplicationLifetime _appLifetime;

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

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

Zusätzliche Ressourcen

  • Hintergrundtasks mit gehosteten Diensten in ASP.NET Core
  • GitHub-Link zu Generischer Hostquelle

    Hinweis

    Dokumentationslinks zur ASP.NET Core-Verweisquelle laden den main-Branch des Repositorys, der die aktuelle Entwicklung der Produkteinheit für das nächste Release von ASP.NET Core darstellt. Um den Branch für ein anderes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Wählen Sie z. B. den release/5.0-Branch für das ASP.NET Core 5.0-Release aus.