Uruchamianie aplikacji na platformie ASP.NET Core

Note

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z aktualną wersją, zobacz artykuł w wersji .NET 10.

Warning

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z aktualną wersją, zobacz artykuł w wersji .NET 10.

W tym artykule opisano sposób uruchamiania aplikacji ASP.NET Core oraz sposobu konfigurowania usług i potoku żądań aplikacji.

Aby uzyskać Blazor wskazówki dotyczące uruchamiania, które dodają lub zastępują wskazówki zawarte w tym artykule, zobacz ASP.NET Core Blazor startup.

Program Plik

Aplikacje ASP.NET Core inicjalizują i konfigurują uruchamianie w pliku Program aplikacji (Program.cs).

Pierwsza część Program pliku koncentruje się na tworzeniu aplikacji. Ta faza wykorzystuje WebApplication.CreateBuilder do zainicjowania nowej instancji klasy WebApplicationBuilder z prekonfigurowanymi ustawieniami domyślnymi przed uruchomieniem aplikacji. Szablony projektów ASP.NET Core przypisują konstruktora aplikacji internetowych do zmiennej o nazwie builder:

var builder = WebApplication.CreateBuilder(args);

Właściwości konstruktora aplikacji internetowej obejmują:

Aplikacja jest tworzona przez wywołanie WebApplicationBuilder.Build, które zwraca utworzony obiekt WebApplication. Szablony projektów ASP.NET Core przypisują skompilowana aplikację internetową do zmiennej o nazwie app:

var app = builder.Build();

Kolejna część Program pliku skupia się na skonfigurowaniu potoku przetwarzania żądań HTTP jako serii komponentów pośredniczących. Każdy składnik pośredniczący wykonuje operacje na obiekcie HttpContext i albo wywołuje następny składnik pośredniczący w potoku przetwarzania, albo kończy przetwarzanie żądania. Zgodnie z konwencją składniki middleware są dodawane do potoku przez wywołanie metody rozszerzającej, której nazwa zaczyna się od „Use”. Aby uzyskać więcej informacji, zobacz middleware platformy ASP.NET Core.

Metoda Run uruchamia aplikację i blokuje wątek wywołujący do momentu zamknięcia hosta:

app.Run();

Po Run wykonaniu aplikacja przechodzi do aktywnego, uruchomionego procesu:

  1. Uruchamianie hostowanych usług.

    Host przechodzi przez wszystkie zarejestrowane usługi hostowane (wystąpienia IHostedService) i wywołuje ich metody StartAsync. Jeśli aplikacja nie zdecyduje się na współbieżne uruchamianie usługi hostowanej (.NET 8 lub nowszej), hostowane usługi są uruchamiane sekwencyjnie w kolejności rejestracji kontenera di. Aby uzyskać więcej informacji, zobacz Zadania w tle z hostowanymi usługami w ASP.NET Core.

  2. Potok oprogramowania pośredniczącego został zbudowany.

    Gdy wywoływane jest builder.Build, zależności są ustalane, ale rzeczywisty potok przetwarzania nie jest jeszcze w pełni skonfigurowany. Gdy wykonywane jest app.Run, framework zamyka potok middleware HTTP. Zadeklarowane metody oprogramowania pośredniczącego i mapowania punktów końcowych są kompilowane w jedną sekwencję delegatów wykonywania o wysokiej wydajności. Aby uzyskać więcej informacji, zobacz ASP.NET Core oprogramowanie pośredniczące.

  3. Serwer internetowy (Kestrel domyślnie) jest uruchamiany.

    Host szuka wewnątrz kontenera zależności, lokalizuje zarejestrowaną implementację serwera (zazwyczaj Kestrel) i wyzwala cykl uruchamiania. Kestrel następnie:

    • Wyszukuje zdefiniowane adresy URL i porty hostingu z konfiguracji, zmiennych środowiskowych lub argumentów wiersza polecenia.
    • Otwiera i przydziela fizyczne gniazda sieciowe.
    • Tworzy powiązania portów i rozpoczyna nasłuchiwanie ruchu przychodzącego.

    Aby uzyskać więcej informacji, zobacz host ogólny .NET w ASP.NET Core, implementacje serwera sieci Web w ASP.NET Core i Kestrel serwerze internetowym w ASP.NET Core.

  4. Wywoływane są zdarzenia cyklu życia związane z uruchomieniem aplikacji.

    Usługa IHostApplicationLifetime uruchamia token ApplicationStarted , który wywołuje wywołania zwrotne zarejestrowane w tokenie. Wszystkie wywołania zwrotne, inicjatory bazy danych lub inne niestandardowe odbiorniki zdarzeń, które są podłączone do oczekiwania na uruchomienie tokenu, są wyzwalane w celu rozpoczęcia przetwarzania.

  5. Główny wątek wykonywania jest blokowany podczas działania aplikacji.

    Run (app.Run()) synchronicznie czeka na zamknięcie.

  6. Aplikacja jest gotowa do przetwarzania żądań.

    W tym momencie powłoka poleceń rejestruje informacje diagnostyczne hostowania:

    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.

Aplikacja pozostaje w tym stanie na czas nieokreślony, przekazując przychodzący ruch internetowy w dół potoku oprogramowania pośredniczącego i wysyłając odpowiedzi.

Gdy zostanie zasygnalizowane zamknięcie, na przykład po wykryciu naciśnięcia Ctrl+c w powłoce poleceń, w której uruchomiono aplikację, lub gdy narzędzie do orkiestracji kontenerów wysyła sygnał SIGTERM, Run zostaje odblokowany i następują poniższe działania:

  1. ApplicationStopping tokeny są wyzwalane, co umożliwia aplikacji uruchamianie logiki przed rozpoczęciem procesu zamykania.

  2. Serwer Kestrel jest zamykany, co wyłącza nowe połączenia. Serwer czeka, aż żądania dotyczące istniejących połączeń zakończą się tak długo, jak zezwala limit czasu zamknięcia. Serwer wysyła nagłówek zamknięcia połączenia dla dalszych żądań dotyczących istniejących połączeń.

  3. Host zamyka zarejestrowane usługi hostowane. Jeśli aplikacja nie włączy równoczesnego zatrzymywania hostowanych usług (.NET 8 lub nowszy), hostowane usługi są zatrzymywane sekwencyjnie w odwrotnej kolejności względem ich rejestracji w kontenerze DI. Aby uzyskać więcej informacji, zobacz Zadania w tle z hostowanymi usługami w ASP.NET Core.

  4. ApplicationStopped Programy obsługi zdarzeń są wyzwalane, co umożliwia aplikacji uruchamianie logiki po zamknięciu aplikacji.

  5. Wykonanie w konsoli kończy się poprawnie z kodem zakończenia 0.

Klasa Startup konfiguruje usługi i potok żądania aplikacji.

Klasa Startup

ASP.NET Core aplikacje używają klasy startowej, która jest nazwana Startup zgodnie z konwencją. Klasa Startup:

  • Opcjonalnie zawiera metodę ConfigureServices konfigurowania usług aplikacji. Usługa to składnik wielokrotnego użytku, który zapewnia funkcjonalność aplikacji. Usługi są rejestrowane w ConfigureServices aplikacji i wykorzystywane poprzez wstrzykiwanie zależności (DI) lub ApplicationServices.
  • Zawiera metodę Configure do tworzenia potoku przetwarzania żądań aplikacji.

ConfigureServices i Configure są wywoływane przez środowisko uruchomieniowe ASP.NET Core po uruchomieniu aplikacji:

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

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

Klasa Startup jest określana podczas kompilowania hosta aplikacji. Klasa Startup jest zwykle określana przez wywołanie WebHostBuilderExtensions.UseStartup w konstruktorze hosta:

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

Host udostępnia usługi dostępne dla konstruktora Startup klasy. Aplikacja dodaje dodatkowe usługi za pośrednictwem ConfigureServices. Zarówno usługi hosta, jak i aplikacji są dostępne w Configure i w całej aplikacji.

Tylko następujące typy usług można wstrzyknąć do konstruktora Startup podczas korzystania z Hosta Ogólnego (IHostBuilder):

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

Większość usług nie jest dostępna, dopóki Configure metoda nie zostanie wywołana.

Note

Prywatne pole elementu IWebHostEnvironment w poprzednim przykładzie ma nazwę rozpoczynającą się od znaku podkreślenia (_env). Dopuszczalne jest również przyjęcie konwencji kodowania, która używa tej samej nazwy co wstrzykiwany IWebHostEnvironment (env), gdy pole prywatne jest deklarowane przy użyciu this słowa kluczowego (this.env = env w konstruktorze i env.IsDevelopment() w metodzie ConfigureServices).

Szablony projektów ASP.NET Core przed .NET 8 i C# 12 nie przyjmują konstruktorów podstawowych, ale powyższy kod można refaktoryzować w celu wdrożenia podstawowego konstruktora, jeśli organizacja używa .NET 8 lub nowszego zestawu SDK, a aplikacja jest przeznaczona dla języka C# 12 lub nowszego (na przykład <LangVersion>12.0</LangVersion>). Aby uzyskać więcej informacji, zobacz Deklarowanie konstruktorów podstawowych dla klas i struktur (samouczek dokumentacji języka C#) i Konstruktory podstawowe (Przewodnik języka C#).

Wiele Startup klas

Gdy aplikacja definiuje oddzielne Startup klasy dla różnych środowisk (na przykład StartupDevelopment), odpowiednia Startup klasa jest wybierana w czasie wykonywania. Klasa, której sufiks nazwy pasuje do bieżącego środowiska, ma priorytet. Jeśli aplikacja jest uruchamiana w Development środowisku i zawiera zarówno klasę Startup, jak i klasę StartupDevelopment, klasa StartupDevelopment jest używana. Aby uzyskać więcej informacji, zobacz Używanie wielu środowisk.

Metoda ConfigureServices

Opcjonalna ConfigureServices metoda to:

  • Wywoływana przez hosta przed Configure metodą konfigurowania usług aplikacji.
  • Gdzie opcje konfiguracji są ustawiane zgodnie z konwencją.

Niektóre usługi mogą być skonfigurowane przez hosta, zanim metody Startup zostaną wywołane. Aby uzyskać więcej informacji, zobacz omówienie podstaw platformy ASP.NET Core.

W przypadku funkcji wymagających rozbudowanej konfiguracji są dostępne Add{Service} metody rozszerzające dla IServiceCollection, takie jak:

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

Dodanie usług do kontenera usług umożliwia ich dostęp w aplikacji i w metodzie Configure. Usługi są rozwiązywane za pomocą iniekcji zależności lub z ApplicationServices.

Metoda Configure

Metoda Configure służy do określania sposobu, w jaki aplikacja odpowiada na żądania HTTP. Potok żądania jest konfigurowany przez dodanie składników oprogramowania pośredniczącego IApplicationBuilder do wystąpienia. IApplicationBuilder jest dostępna dla Configure metody, ale nie jest zarejestrowana w kontenerze usługi. Hosting tworzy obiekt IApplicationBuilder i przekazuje go bezpośrednio do elementu Configure.

Szablony ASP.NET Core konfigurują potok z obsługą następujących elementów:

W poniższym przykładzie pokazano oprogramowanie pośredniczące dla typowej Razor aplikacji Pages:

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

Powyższy przykład dotyczy stron Razor; wersja MVC jest podobna.

Każda Use metoda rozszerzenia dodaje do potoku żądania jeden lub więcej składników middleware. Na przykład UseStaticFiles konfiguruje middleware do obsługi statycznych plików.

Każdy element middleware w potoku żądań jest odpowiedzialny za wywoływanie następnego elementu w potoku lub pominięcie niektórych kroków, jeśli jest to konieczne.

W sygnaturze metody IWebHostEnvironment można określić dodatkowe usługi, takie jak ILoggerFactory, ConfigureServices, lub dowolne elementy zdefiniowane w Configure. Te usługi są wstrzykiwane, jeśli są dostępne.

Aby uzyskać więcej informacji na temat sposobu używania IApplicationBuilder i kolejności przetwarzania oprogramowania pośredniczącego, zobacz ASP.NET Core oprogramowanie pośredniczące.

Konfigurowanie usług bez Startup klasy

Aby skonfigurować usługi i potok przetwarzania żądań bez użycia klasy Startup, wywołaj metody ConfigureServices i Configure na budowniczym hosta. Wiele wywołań ConfigureServices łączy się ze sobą. Jeśli istnieje wiele Configure wywołań metody, zostanie użyte ostatnie Configure wywołanie.

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 =>
                {
                    ...
                });
        });
}

Filtry startowe

Chociaż aplikacja zazwyczaj tworzy jawny potok wykonywania oprogramowania pośredniczącego, filtr uruchamiania (IStartupFilter) jest przydatny w następujących sytuacjach:

  • Tworzenie udostępnionej biblioteki/pakietu NuGet, który automatycznie ładuje niestandardowe oprogramowanie pośredniczące bez konieczności jawnego wywoływania metody "Use" oprogramowania pośredniczącego. Na przykład użytkownik biblioteki nie musi wykonywać wywołania app.UseImageProcessingMiddleware dla oprogramowania pośredniczącego do przetwarzania obrazów w potoku przetwarzania żądań aplikacji.
  • Zapewnienie, że oprogramowanie pośrednie zostanie wykonane przed innym oprogramowaniem pośrednim lub po nim, niezależnie od tego, jak deweloper modyfikuje potok przetwarzania żądań aplikacji.

Implementacja filtru uruchamiania udostępnia metodę IStartupFilter.Configure , która odbiera i zwraca element Action<IApplicationBuilder>. Interfejs IApplicationBuilder służy do konfigurowania potoku żądania aplikacji. Aby uzyskać więcej informacji, zobacz Tworzenie potoku oprogramowania pośredniczącego za pomocą polecenia IApplicationBuilder.

Każda implementacja filtru startowego może dodawać jeden lub więcej składników pośredniczących do potoku przetwarzania żądań. Filtry są wywoływane w kolejności dodawania ich do kontenera usługi. Filtry mogą dodawać oprogramowanie pośredniczące przed przekazaniem sterowania do następnego filtru lub po nim, a zatem są dodawane na początku lub na końcu potoku przetwarzania.

W poniższym przykładzie pokazano, jak zarejestrować oprogramowanie pośredniczące w programie IStartupFilter. Filtr uruchamiania CustomResponseHeaderFilter używa oprogramowania pośredniczącego do dołączania nagłówka niestandardowego (X-Custom-Header) do wszystkich odpowiedzi aplikacji przed wykonaniem innych oprogramowania pośredniczącego.

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

Implementacja filtru startowego jest zarejestrowana w pliku Program:

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

Implementacja filtru uruchamiania jest zarejestrowana w pliku Startup.ConfigureServices:

services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

Kolejność wykonywania oprogramowania pośredniczącego jest ustawiana według kolejności rejestracji filtru uruchamiania:

  • Wiele implementacji może współdziałać z tymi samymi obiektami. Jeśli kolejność ma znaczenie, uporządkuj rejestracje usług tak, aby odpowiadały kolejności, w jakiej powinno być uruchamiane oprogramowanie pośredniczące.
  • Biblioteki mogą dodawać oprogramowanie pośrednie z co najmniej jedną implementacją, która jest uruchamiana przed lub po innym oprogramowaniu pośrednim aplikacji zarejestrowanym za pomocą IStartupFilter. Aby wywołać oprogramowanie pośredniczące filtru uruchamiania przed oprogramowaniem pośredniczącym dodanym przez filtr uruchamiania biblioteki:
    • Umieść rejestrację usługi filtru uruchamiania przed dodaniem biblioteki do kontenera usług.
    • Aby wywołać później, umieść rejestrację usługi po dodaniu biblioteki.

Note

Nie można rozszerzyć aplikacji ASP.NET Core za pomocą filtrów uruchamiania, gdy przesłonisz delegat Configure. Aby uzyskać więcej informacji, zobacz WebApplicationFactory Client zwraca NotFound dla wszystkich żądań z zastępowaniem metody Configure (dotnet/aspnetcore #45372).

Dodawanie konfiguracji podczas uruchamiania z zestawu zewnętrznego

Implementacja IHostingStartup umożliwia dodawanie rozszerzeń do aplikacji przy uruchamianiu z zewnętrznego zestawu, poza plikiem Startup lub klasą Program aplikacji. Więcej informacji można znaleźć w temacie Korzystanie z hostowania zestawów startowych na platformie ASP.NET Core.

Klasa Startup (ConfigureServices i Configure metody)

Mimo że jest obsługiwana w aplikacjach ASP.NET Core przeznaczonych dla .NET 6 lub nowszych, używanie Startup klasy nie jest zalecane. Aby uzyskać więcej informacji, zobacz Migrowanie z platformy ASP.NET Core na platformie .NET 5 do platformy .NET 6.

Aby uzyskać informacje na temat używania metod ConfigureServices i Configure w minimalnym modelu hostingu, zobacz:

Mierzenie wydajności uruchamiania

Hostowanie ASP.NET Core EventSource emituje zdarzenie ServerReady, które oznacza moment, w którym serwer jest gotowy do obsługi żądań i może być używane do pomiaru czasu uruchamiania. Aby uzyskać więcej informacji, zobacz Rejestrowanie na platformie .NET i ASP.NET Core.

Dodatkowe zasoby

  • Last updated on