Anwendungsstart in ASP.NET Core

Note

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 10-Version dieses Artikels.

Warning

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Die aktuelle Version finden Sie in der .NET 10-Version dieses Artikels.

In diesem Artikel wird beschrieben, wie ASP.NET Core Apps gestartet werden und wie Dienste und die Anforderungspipeline der App konfiguriert werden.

Anleitungen zum Blazor-Start, die die Anleitungen in diesem Artikel ergänzen oder ersetzen, finden Sie unter ASP.NET Core-Blazor-Start.

Die Program-Datei.

ASP.NET Core Apps initialisieren und konfigurieren den Start in der App-Datei Program (Program.cs).

Der erste Teil der Program Datei konzentriert sich auf das Erstellen der App. In dieser Phase wird WebApplication.CreateBuilder verwendet, um vor dem Start der App eine neue Instanz der Klasse WebApplicationBuilder mit vorkonfigurierten Standardwerten zu initialisieren. Die ASP.NET Core-Projektvorlagen weisen den Webanwendungs-Builder einer Variable mit dem Namen builder zu:

var builder = WebApplication.CreateBuilder(args);

Zu den Eigenschaften des Webanwendungs-Generators gehören:

Die App wird durch Aufrufen von WebApplicationBuilder.Build erstellt, das das erstellte WebApplication zurückgibt. Die ASP.NET-Core-Projektvorlagen weisen die erstellte Webanwendung einer Variablen namens app zu:

var app = builder.Build();

Der nächste Teil der Program Datei konzentriert sich auf die Einrichtung der HTTP-Anforderungsverarbeitungspipeline als eine Reihe von Middleware-Komponenten. Jede Middleware führt Operationen an einer HttpContext aus und ruft entweder die nächste Middleware in der Pipeline auf oder beendet die Anfrage. Standardmäßig werden Middleware-Komponenten zur Pipeline hinzugefügt, indem eine Erweiterungsmethode aufgerufen wird, die mit "Use" beginnt. Weitere Informationen finden Sie unter ASP.NET Core Middleware.

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

app.Run();

Wenn Run zur Ausführung kommt, geht die App in einen aktiven, laufenden Prozess über:

  1. Gehostete Dienste werden gestartet.

    Der Host durchläuft alle registrierten gehosteten Dienste (IHostedService Instanzen) und ruft ihre StartAsync Methoden auf. Sofern sich die App nicht für den gleichzeitigen Start des gehosteten Diensts (.NET 8 oder höher) entscheidet, beginnen gehostete Dienste sequenziell in der Reihenfolge ihrer DI-Containerregistrierungen. Weitere Informationen finden Sie unter Hintergrundaufgaben mit gehosteten Diensten in ASP.NET Core.

  2. Die Middleware-Pipeline ist erstellt.

    Wenn builder.Build aufgerufen wird, werden Abhängigkeiten aufgelöst, die eigentliche Verarbeitungspipeline ist jedoch nicht vollständig eingerichtet. Wenn app.Run ausgeführt wird, finalisiert das Framework die HTTP-Middleware-Pipeline. Die deklarierten Middlewaremethoden und Endpunktzuordnungen werden in einer einzelnen, leistungsstarken Ausführungsdelegatsequenz kompiliert. Weitere Informationen finden Sie unter ASP.NET Core Middleware.

  3. Der Webserver (Kestrel standardmäßig) wird gestartet.

    Der Host sucht innerhalb des Abhängigkeitscontainers, sucht die registrierte Serverimplementierung (in der Regel Kestrel) und löst den Startzyklus aus. Kestrel dann:

    • Sucht die definierten Hosting-URLs und Ports aus Konfigurations-, Umgebungsvariablen oder Befehlszeilenargumenten.
    • Öffnet und weist physische Netzwerksockets zu.
    • Bindet Ports und beginnt mit der Überwachung auf eingehenden Datenverkehr.

    Weitere Informationen finden Sie unter .NET Generic Host in ASP.NET Core, Webserverimplementierungen in ASP.NET Core und Kestrel Webservern in ASP.NET Core.

  4. Beim Starten der Anwendung werden Lebenszyklusereignisse ausgelöst.

    Der IHostApplicationLifetime Dienst löst sein ApplicationStarted-Token aus, wodurch die für das Token registrierten Callbacks aufgerufen werden. Alle Callbacks, Datenbank-Seeder oder anderen benutzerdefinierten Ereignis-Listener, die so eingerichtet sind, dass sie darauf warten, dass das Token ausgelöst wird, werden aktiviert und beginnen mit der Verarbeitung.

  5. Der Hauptausführungsthread wird blockiert, während die App ausgeführt wird.

    Run (app.Run()) wartet synchron darauf, bis das System heruntergefahren wird.

  6. Die App ist bereit, Anfragen zu verarbeiten.

    An diesem Punkt protokolliert die Befehlsshell die Hostingdiagnose:

    info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7123
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5123
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

Die App verbleibt unbestimmt in diesem Zustand und übergibt eingehenden Webdatenverkehr an die Middlewarepipeline und sendet Antworten.

Wenn das Herunterfahren signalisiert wird, z. B. wenn Strg+c in der Befehlszeile erkannt wird, in der die App ausgeführt wird, oder wenn ein Container-Orchestrierungstool ein SIGTERM-Ereignis sendet, wird die Blockierung von Run aufgehoben, und die folgenden Aktionen finden statt:

  1. ApplicationStopping Token werden ausgelöst, wodurch die App Logik ausführen kann, bevor der Herunterfahrenvorgang beginnt.

  2. Der Kestrel Server wird heruntergefahren, wodurch neue Verbindungen deaktiviert werden. Der Server wartet, bis Anforderungen über bestehende Verbindungen abgeschlossen sind, solange es das Zeitlimit für das Herunterfahren zulässt. Der Server sendet bei weiteren Anforderungen für vorhandene Verbindungen den Header zur Verbindungstrennung.

  3. Der Host beendet registrierte gehostete Dienste. Sofern sich die App nicht dafür entscheidet, gehostete Dienste gleichzeitig (.NET 8 oder höher) zu beenden, werden gehostete Dienste sequenziell in der umgekehrten Reihenfolge ihrer DI-Containerregistrierungen beendet. Weitere Informationen finden Sie unter Hintergrundaufgaben mit gehosteten Diensten in ASP.NET Core.

  4. ApplicationStopped Ereignishandler werden ausgelöst, wodurch die App Logik ausführen kann, nachdem die App heruntergefahren wurde.

  5. Die Konsolenausführung wird ordnungsgemäß mit einem Exitcode von 0 beendet.

Die Startup-Klasse konfiguriert Dienste und die Anforderungspipeline einer App.

Die Startup-Klasse

ASP.NET Core Apps verwenden eine Startklasse, die nach Konvention benannt Startup wird. Die Startup-Klasse:

  • Optional kann eine ConfigureServices Methode enthalten, um die Dienste der App zu konfigurieren. Ein Dienst ist eine wiederverwendbare Komponente, die App-Funktionalität bereitstellt. Dienste werden in ConfigureServices und in der App über Dependency Injection (DI) oder ApplicationServices genutzt.
  • Enthält eine Configure-Methode, um die Anforderungsverarbeitungspipeline einer App zu erstellen.

ConfigureServices und Configure werden von der ASP.NET Core-Runtime aufgerufen, wenn die App gestartet wird:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
    }
}

Die Startup-Klasse wird angegeben, wenn der Host der App erstellt wird. Die Startup Klasse wird in der Regel durch Aufrufen WebHostBuilderExtensions.UseStartup des Host-Generators angegeben:

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 Host stellt Dienste für den Startup-Klassenkonstruktor bereit. Die App fügt über ConfigureServices zusätzliche Dienste hinzu. Sowohl die Host- als auch die App-Dienste sind in Configure und über die App verfügbar.

Beim Einsatz des Startup () können nur die folgenden Diensttypen in den IHostBuilder Konstruktor eingefügt werden:

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
        }
        else
        {
        }
    }
}

Die meisten Dienste sind erst verfügbar, wenn die Configure Methode aufgerufen wird.

Note

Das private Feld im vorherigen Beispiel IWebHostEnvironment wird mit einem Unterstrich (_env) benannt. Es ist auch zulässig, eine Codierungskonvention zu übernehmen, die denselben Namen wie das eingefügte IWebHostEnvironment (env) verwendet, wenn das private Feld das this Schlüsselwort verwendet (this.env = env im Konstruktor und env.IsDevelopment() in der ConfigureServices Methode).

Die ASP.NET Core Projektvorlagen vor .NET 8 und C# 12 übernehmen keine primären Konstruktoren, aber der vorangehende Code kann umgestaltet werden, um einen primären Konstruktor zu übernehmen, wenn Ihre Organisation ein .NET 8 oder höher-SDK verwendet und die App auf C# 12 oder höher ausgerichtet ist (z. B<LangVersion>12.0</LangVersion>. ). Weitere Informationen finden Sie unter Declare primary constructors for classes and structs (C# documentation tutorial) und Primary constructors (C# Guide).

Mehrere Startup Klassen

Wenn die App unterschiedliche Startup-Klassen für unterschiedliche Umgebungen definiert (z.B. StartupDevelopment), wird zur Laufzeit die entsprechende Startup-Klasse ausgewählt. Die Klasse, deren Namenssuffix mit der aktuellen Umgebung übereinstimmt, wird priorisiert. Wenn die App in der Development Umgebung ausgeführt wird und sowohl eine Startup Klasse als auch eine StartupDevelopment Klasse enthält, wird die StartupDevelopment Klasse verwendet. Weitere Informationen finden Sie unter Verwenden mehrerer Umgebungen.

Die ConfigureServices -Methode

Die optionale ConfigureServices Methode lautet:

  • wird vor der Configure-Methode vom Host aufgerufen, um die App-Dienste zu konfigurieren.
  • Über diese Methode werden standardmäßig Konfigurationsoptionen festgelegt.

Es kann sein, dass der Host einige Dienste konfiguriert, bevor die Startup-Methoden aufgerufen werden. Weitere Informationen finden Sie unter ASP.NET Core Fundamentals Overview.

Für Funktionen, die einen erheblichen Einrichtungsaufwand erfordern, gibt es Add{Service}Erweiterungsmethoden für IServiceCollection, z. B.:

  • AddDbContext
  • AddDefaultIdentity
  • AddEntityFrameworkStores
  • AddRazorPages
public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {

        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                Configuration.GetConnectionString("DefaultConnection")));
        services.AddDefaultIdentity<IdentityUser>(
            options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<ApplicationDbContext>();

        services.AddRazorPages();
    }
}

Wenn Sie Dienste zum Dienstcontainer hinzufügen, können Sie auch über die App und die Configure-Methode auf diese zugreifen. Die Dienste werden über die Dependency Injection oder über ApplicationServices aufgelöst.

Die Configure -Methode

Die Configure-Methode wird verwendet, um festzulegen, wie die App auf HTTP-Anforderungen reagiert. Die Anforderungspipeline wird konfiguriert, indem Middlewarekomponenten zu einer IApplicationBuilder-Instanz hinzugefügt werden. IApplicationBuilder steht für die Configure-Methode zur Verfügung, ist aber nicht im Dienstcontainer registriert. Über das Hosting wird ein IApplicationBuilder erstellt, der direkt an Configure übergeben wird.

Die ASP.NET Core-Vorlagen konfigurieren die Pipeline mit Unterstützung für:

Das folgende Beispiel veranschaulicht Middleware für eine typische Razor Pages-App:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Das Beispiel oben bezieht sich auf Razor Pages. Die MVC-Version ist aber ähnlich.

Jede Use-Erweiterungsmethode fügt mindestens eine Middlewarekomponente zu der Anforderungspipeline hinzu. Beispielsweise konfiguriert UseStaticFilesMiddleware um statische Dateien bereitzustellen.

Jede Middlewarekomponente in der Anforderungspipeline ist für das Aufrufen der jeweils nächsten Komponente in der Pipeline oder, wenn nötig, für das Kurzschließen der Kette zuständig.

In der IWebHostEnvironment-Methodensignatur können außerdem auch zusätzliche Dienste wie ILoggerFactory, ConfigureServices oder in Configure definierte Dienste angegeben werden. Diese Dienste werden eingefügt, wenn Sie verfügbar sind.

Weitere Informationen zur Verwendung IApplicationBuilder und Reihenfolge der Middlewareverarbeitung finden Sie unter ASP.NET Core Middleware.

Konfigurieren von Diensten ohne Klasse Startup

Rufen Sie die Hilfsmethoden Startup und ConfigureServices im Hostgenerator auf, um Dienste und die Anforderungsverarbeitungspipeline ohne die Configure-Klasse zu konfigurieren. Wenn ConfigureServices mehrmals aufgerufen wird, werden diese Aufrufe einander angefügt. Wenn es mehrere Aufrufe der Methode Configure gibt, wird der letzte Configure-Aufruf verwendet.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.ConfigureServices(services =>
                {
                    ...
                })
                .Configure(app =>
                {
                    ...
                });
        });
}

Startfilter

Während eine App in der Regel eine explizite Middleware-Ausführungspipeline erstellt, ist ein Startfilter (IStartupFilter) nützlich für:

  • Erstellen eines freigegebenen Bibliotheks-/NuGet-Pakets, das automatisch benutzerdefinierte Middleware lädt, ohne dass die App die "Use"-Methode der Middleware explizit aufrufen muss. Beispielsweise muss der Nutzer der Bibliothek in der Anforderungsverarbeitungs-Pipeline der App keinen app.UseImageProcessingMiddleware-Aufruf für eine Middleware zur Bildverarbeitung ausführen.
  • Sicherstellen, dass eine Middleware-Komponente vor oder nach anderer Middleware ausgeführt wird, unabhängig davon, wie ein Entwickler die Pipeline der Anforderungsverarbeitung der App ändert.

Eine Startupfilterimplementierung stellt eine IStartupFilter.Configure-Methode bereit, die ein Action<IApplicationBuilder> empfängt und zurückgibt. Die IApplicationBuilder Schnittstelle wird verwendet, um die Anforderungspipeline der App zu konfigurieren. Weitere Informationen finden Sie unter Erstellen einer Middleware-Pipeline mit IApplicationBuilder.

Jede Startfilterimplementierung kann der Anforderungspipeline mindestens eine Middleware hinzufügen. Die Filter werden in der Reihenfolge aufgerufen, in der sie dem Dienstcontainer hinzugefügt werden. Filter können Middleware hinzufügen, bevor oder nachdem dem nächsten Filter die Kontrolle erteilt wird. D.h., sie wird am Anfang oder am Ende der Pipeline hinzugefügt.

Im folgenden Beispiel wird veranschaulicht, wie Middleware bei IStartupFilter registriert wird. Der CustomResponseHeaderFilter Startfilter verwendet Middleware, um einen benutzerdefinierten Header (X-Custom-Header) an alle Antworten der App anzufügen, bevor andere Middlewares ausgeführt werden.

CustomResponseHeaderFilter.cs:

using System;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;

public class CustomResponseHeaderFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            // 1. Add middleware that runs BEFORE subsequent middlewares
            builder.Use(async (context, nextMiddleware) =>
            {
                context.Response.Headers.Append("X-Custom-Header", "VALUE");
                await nextMiddleware();
            });

            // 2. Call the rest of the application's configuration pipeline
            next(builder);

            // 3. (Optional) Add middleware that runs AFTER the rest of the pipeline
        };
    }
}

Die Startfilterimplementierung wird in der Program Datei registriert:

builder.Services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

Die Startfilterimplementierung ist registriert in Startup.ConfigureServices:

services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

Die Middleware-Ausführungsreihenfolge wird durch die Reihenfolge der Startfilterregistrierungen festgelegt:

  • Mehrere Implementierungen können mit denselben Objekten interagieren. Wenn die Reihenfolge für Sie wichtig ist, sollten Sie die Dienstregistrierungen der Implementierungen in der Reihenfolge anordnen, in der die Middleware ausgeführt werden soll.
  • Bibliotheken können Middleware mit einer oder mehreren Implementierungen hinzufügen, die vor oder nach anderer App-Middleware ausgeführt werden, die mit IStartupFilter registriert wurde. So rufen Sie eine Startfilter-Middleware auf, bevor eine Middleware durch den Startfilter einer Bibliothek hinzugefügt wird:
    • Positionieren Sie die Registrierung des Startfilterdiensts, bevor die Bibliothek dem Dienstcontainer hinzugefügt wird.
    • Wenn der Dienst danach aufgerufen werden soll, platzieren Sie die Dienstregistrierung, nachdem die Bibliothek hinzugefügt wurde.

Note

Sie können die ASP.NET Core-Anwendung nicht mit Startfiltern erweitern, wenn Sie den Configure Delegate überschreiben. Weitere Informationen finden Sie unter WebApplicationFactory-Client gibt bei allen Anfragen mit überschriebener Configure-Methode NotFound zurück (dotnet/aspnetcore #45372).

Hinzufügen von Konfigurationen aus einer externen Assembly beim Start

Eine IHostingStartup-Implementierung ermöglicht es, einer App beim Starten Erweiterungen aus einer externen Assembly hinzuzufügen, und zwar außerhalb der Startup-Datei oder Program-Klasse der App. Weitere Informationen finden Sie unter Verwenden von Hostingstartassemblys in ASP.NET Core.

Die Startup Klasse (ConfigureServices und Configure Methoden)

Obwohl dies in ASP.NET Core-Anwendungen unterstützt wird, die für .NET 6 oder höher vorgesehen sind, wird die Verwendung einer Startup-Klasse nicht empfohlen. Weitere Informationen finden Sie unter Migrieren von ASP.NET Core in .NET 5 zu .NET 6.

Informationen zur Verwendung der Methoden Configure und ConfigureServices mit dem minimalen Hostingmodell finden Sie hier:

Messen der Startleistung

Das ASP.NET Core Hosting EventSource gibt das ServerReady Ereignis aus, das den Punkt darstellt, an dem der Server bereit ist, auf Anforderungen zu reagieren und kann verwendet werden, um die Startzeit zu messen. Weitere Informationen finden Sie unter Protokollieren in .NET und ASP.NET Core.

Verwandte Inhalte

  • Zuletzt aktualisiert um