Avvio dell'app in ASP.NET Core

Note

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 10 di questo articolo.

Warning

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere i criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 10 di questo articolo.

Questo articolo descrive come si avviano le applicazioni ASP.NET Core e come configurare i servizi e la pipeline delle richieste dell'app.

Per Blazor indicazioni sull'avvio, che aggiunge o sostituisce le linee guida in questo articolo, vedere ASP.NET Core Blazor startup.

Il Program file

Le app ASP.NET Core inizializzano e configurano l'avvio nel file Program dell'app (Program.cs).

La prima parte del Program file è incentrata sulla compilazione dell'app. Questa fase usa WebApplication.CreateBuilder per inizializzare una nuova istanza della WebApplicationBuilder classe con impostazioni predefinite preconfigurate prima dell'avvio dell'app. I modelli di progetto ASP.NET Core assegnano il generatore di applicazioni Web a una variabile denominata builder:

var builder = WebApplication.CreateBuilder(args);

Le proprietà del generatore di applicazioni Web includono:

L'app viene creata invocando WebApplicationBuilder.Build, che restituisce l'istanza WebApplication creata. I modelli di progetto ASP.NET Core assegnano l'applicazione Web compilata a una variabile denominata app:

var app = builder.Build();

La parte successiva del Program file è incentrata sulla definizione della pipeline di gestione delle richieste HTTP come una serie di componenti middleware. Ogni middleware esegue operazioni su un HttpContext oggetto e richiama il middleware successivo nella pipeline o termina la richiesta. Per convenzione, i componenti middleware vengono aggiunti alla pipeline richiamando un metodo di estensione che inizia con "Use". Per altre informazioni, vedere ASP.NET Core middleware.

Il Run metodo avvia l'app e blocca il thread chiamante fino all'arresto dell'host:

app.Run();

Quando Run viene eseguita, l'app passa a un processo attivo ed in esecuzione:

  1. Avvio dei servizi ospitati.

    L'host scorre tutti i servizi ospitati registrati (IHostedService istanze) e chiama i metodi StartAsync. A meno che l'app non abiliti l'avvio simultaneo dei servizi ospitati (.NET 8 o versioni successive), i servizi ospitati vengono avviati in sequenza nell'ordine delle registrazioni nel contenitore DI. Per altre informazioni, vedere Attività in background con servizi ospitati in ASP.NET Core.

  2. Viene costruita la pipeline del middleware.

    Quando builder.Build viene chiamato , le dipendenze vengono risolte, ma la pipeline di elaborazione effettiva non è completamente impostata. Quando app.Run viene eseguito, il framework finalizza la pipeline del middleware HTTP. I metodi dichiarati del middleware e le mappature dichiarate degli endpoint vengono compilati in un'unica sequenza di delegati di esecuzione ad alte prestazioni. Per altre informazioni, vedere ASP.NET Core middleware.

  3. Il server Web (Kestrel per impostazione predefinita) viene avviato.

    L'host cerca all'interno del contenitore di dipendenze, individua l'implementazione del server registrata (in genere Kestrel) e attiva il ciclo di avvio. Kestrel quindi:

    • Cerca gli URL e le porte di hosting definiti da configurazioni, variabili di ambiente o argomenti della riga di comando.
    • Apre e alloca i socket di rete fisici.
    • Associa le porte e inizia l'ascolto del traffico in ingresso.

    Per altre informazioni, vedere .NET host generico in ASP.NET Core, implementazioni del server Web in ASP.NET Core e Kestrel server Web in ASP.NET Core.

  4. Vengono attivati gli eventi del ciclo di vita all'avvio dell'applicazione.

    Il servizio IHostApplicationLifetime attiva il proprio token ApplicationStarted, che invoca le funzioni di callback registrate sul token. Tutti i callback, i seeder del database e gli altri listener di eventi personalizzati configurati per restare in attesa che il token si attivi vengono attivati per avviare l'elaborazione.

  5. Il thread di esecuzione principale viene bloccato durante l'esecuzione dell'app.

    Run (app.Run()) attende in modo sincrono fino all'arresto.

  6. L'app è pronta per elaborare le richieste.

    A questo punto, l'interprete dei comandi registra i log di diagnostica dell'hosting:

    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.

L'app rimane in questo stato a tempo indeterminato, passando il traffico Web in ingresso verso il basso nella pipeline middleware e inviando risposte.

Quando viene segnalato l'arresto, ad esempio quando viene rilevato CTRL+C nella shell dei comandi che esegue l'app o uno strumento di orchestrazione del contenitore invia un evento SIGTERM, Run sblocca e vengono eseguite le azioni seguenti:

  1. ApplicationStopping i token vengono attivati, il che consente all'app di eseguire operazioni prima che inizi il processo di arresto.

  2. Il server Kestrel è arrestato, il che disabilita nuove connessioni. Il server attende che le richieste sulle connessioni esistenti vengano completate per il tempo consentito dal timeout di arresto. Il server invia l'intestazione di chiusura della connessione per ulteriori richieste sulle connessioni esistenti.

  3. L'host arresta i servizi ospitati registrati. A meno che l'app non sia configurata esplicitamente per arrestare i servizi ospitati contemporaneamente (.NET 8 o versioni successive), i servizi ospitati vengono arrestati in modo sequenziale nell'ordine inverso delle registrazioni nel contenitore DI. Per altre informazioni, vedere Attività in background con servizi ospitati in ASP.NET Core.

  4. ApplicationStopped i gestori eventi vengono attivati, che consente all'app di eseguire la logica dopo l'arresto dell'app.

  5. L'esecuzione della console viene chiusa normalmente con un codice di uscita pari a 0.

La classe Startup configura i servizi e la pipeline delle richieste dell'app.

Classe Startup

ASP.NET Core le app usano una classe di avvio denominata Startup per convenzione. La classe Startup:

  • Include facoltativamente un metodo ConfigureServices per configurare i servizi dell'app. Un servizio è un componente riutilizzabile che fornisce la funzionalità delle app. I servizi vengono registrati in ConfigureServices e usati nell'app tramite iniezione delle dipendenze (DI) o ApplicationServices.
  • Include un metodo Configure per creare la pipeline di elaborazione delle richieste dell'app.

ConfigureServices e Configure sono chiamate dal runtime di ASP.NET Core all'avvio dell'app:

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

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

La classe Startup viene specificata al momento della compilazione dell'host dell'app. La Startup classe viene in genere specificata chiamando WebHostBuilderExtensions.UseStartup sul generatore host:

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

L'host fornisce i servizi disponibili al costruttore della classe Startup. L'app aggiunge servizi aggiuntivi tramite ConfigureServices. I servizi dell'host e dell'app sono disponibili in Configure e nel corso dell'app.

Solo i tipi di servizio seguenti possono essere inseriti nel Startup costruttore quando si usa l'host generico (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
        {
        }
    }
}

La maggior parte dei servizi non è disponibile finché non viene chiamato il Configure metodo .

Note

Il campo privato nell'esempio precedente per IWebHostEnvironment viene denominato con un carattere di sottolineatura (_env). È anche accettabile adottare una convenzione di codifica che usa lo stesso nome dell'inserimento IWebHostEnvironment (env) quando il campo privato usa la this parola chiave (this.env = env nel costruttore e env.IsDevelopment() nel ConfigureServices metodo ).

I modelli di progetto ASP.NET Core prima di .NET 8 e C# 12 non adottano costruttori primari, ma è possibile effettuare il refactoring del codice precedente per adottare un costruttore primario se l'organizzazione usa un SDK .NET 8 o versione successiva e l'app è destinata a C# 12 o versione successiva (ad esempio, <LangVersion>12.0</LangVersion>). Per altre informazioni, vedere Dichiara costruttori primari per classi e struct (esercitazione sulla documentazione di C#) e Costruttori primari (Guida di C#).

Più Startup classi

Quando l'app definisce classi Startup separate per i diversi ambienti (ad esempio StartupDevelopment), la classe Startup appropriata viene selezionata durante il runtime. La classe il cui suffisso di nome corrisponde all'ambiente corrente ha la priorità. Se l'app viene eseguita nell'ambiente Development e include sia una Startup classe che una StartupDevelopment classe , viene usata la StartupDevelopment classe . Per altre informazioni, vedere Usare più ambienti.

Metodo ConfigureServices

Il metodo facoltativo ConfigureServices è:

  • Chiamato dall'host prima del metodo Configure per configurare i servizi dell'app.
  • Dove le opzioni di configurazione sono impostate per convenzione.

L'host può configurare alcuni servizi prima che vengano chiamati i metodi Startup. Per altre informazioni, vedere ASP.NET Panoramica dei concetti fondamentali di base.

Per le funzionalità che richiedono una configurazione complessa, sono disponibili metodi di estensione Add{Service} su IServiceCollection, ad esempio:

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

L'aggiunta dei servizi al contenitore dei servizi li rende disponibili all'interno dell'app e nel metodo Configure. I servizi vengono risolti tramite dependency injection o da ApplicationServices.

Metodo Configure

Il metodo Configure viene usato per specificare come risponde l'app alle richieste HTTP. La pipeline delle richieste viene configurata aggiungendo i componenti middleware a un'istanza IApplicationBuilder. IApplicationBuilder è disponibile per il metodo Configure ma non viene registrato nel contenitore dei servizi. L'hosting crea IApplicationBuilder e lo passa direttamente a Configure.

I modelli ASP.NET Core configurano la pipeline con il supporto per:

L'esempio seguente illustra il middleware per un'app Pages tipica Razor :

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

L'esempio precedente riguarda Razor Pages. La versione MVC è simile.

Ogni metodo di estensione Use aggiunge uno o più componenti middleware alla pipeline delle richieste. Ad esempio, UseStaticFiles configura il middleware per fornire i file statici.

Ogni componente middleware nel pipeline di richieste è responsabile della chiamata del componente seguente nella pipeline o di interrompere la catena, se necessario.

I servizi aggiuntivi, ad esempio IWebHostEnvironment, ILoggerFactory o qualsiasi elemento definito in ConfigureServices, possono essere specificati nella firma del metodo Configure. Questi servizi vengono iniettati se sono disponibili.

Per altre informazioni su come usare IApplicationBuilder e sull'ordine di elaborazione del middleware, vedere ASP.NET Core middleware.

Configurare i servizi senza una Startup classe

Per configurare i servizi e la pipeline di elaborazione delle richieste senza usare una classe Startup, chiamare i metodi pratici ConfigureServices e Configure sul generatore di host. Se vengono effettuate più chiamate a ConfigureServices, le chiamate vengono aggiunte l'una all'altra. In presenza di più chiamate del metodo Configure viene usata l'ultima chiamata di Configure.

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

Filtri di avvio

Mentre un'app crea in genere una pipeline di esecuzione del middleware esplicita, un filtro di avvio (IStartupFilter) è utile per:

  • Creazione di un pacchetto di libreria condivisa/NuGet che carica automaticamente il middleware personalizzato senza richiedere all'app di chiamare in modo esplicito il metodo "Use" del middleware. Ad esempio, il consumer della libreria non è tenuto a effettuare una chiamata a app.UseImageProcessingMiddleware per un middleware di elaborazione delle immagini nella pipeline di elaborazione delle richieste dell'app.
  • Garantire che un middleware venga eseguito prima o dopo altri middleware, indipendentemente dal modo in cui uno sviluppatore modifica la pipeline di elaborazione delle richieste dell'app.

Un'implementazione del filtro di avvio fornisce un IStartupFilter.Configure metodo che riceve e restituisce un oggetto Action<IApplicationBuilder>. L'interfaccia IApplicationBuilder viene usata per configurare la pipeline di richiesta dell'app. Per altre informazioni, vedere Creare una pipeline middleware con IApplicationBuilder.

Ogni implementazione del filtro di avvio può aggiungere uno o più middleware alla pipeline di richiesta. I filtri vengono richiamati nell'ordine in cui vengono aggiunti al contenitore del servizio. I filtri possono aggiungere middleware prima o dopo aver passato il controllo al filtro successivo, quindi aggiungono all'inizio o alla fine della pipeline.

L'esempio seguente dimostra come registrare un middleware con IStartupFilter. Il CustomResponseHeaderFilter filtro di avvio usa il middleware per aggiungere un'intestazione personalizzata (X-Custom-Header) a tutte le risposte dell'app prima dell'esecuzione di altri middleware.

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

L'implementazione del Program filtro di avvio viene registrata nel file :

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

L'implementazione del filtro di avvio è registrata in Startup.ConfigureServices:

services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

L'ordine di esecuzione del middleware viene impostato in base all'ordine delle registrazioni del filtro di avvio:

  • Più implementazioni potrebbero interagire con gli stessi oggetti. Se l'ordinamento è importante, ordinate le relative registrazioni dei servizi in modo che corrispondano all'ordine in cui i rispettivi middleware devono essere eseguiti.
  • Le librerie possono aggiungere middleware con una o più implementazioni che vengono eseguite prima o dopo gli altri middleware dell'app registrati con IStartupFilter. Per richiamare un middleware del filtro di avvio prima di un middleware aggiunto dal filtro di avvio di una libreria:
    • Posizionare la registrazione del servizio Startup Filter prima di aggiungere la libreria al contenitore dei servizi.
    • Per richiamarlo in un secondo momento, posizionare la registrazione dei servizi dopo l'aggiunta della libreria.

Note

Non è possibile estendere l'app ASP.NET Core con filtri di avvio quando si esegue l'override del delegato Configure. Per altre informazioni, vedere il client di WebApplicationFactory restituisce NotFound per tutte le richieste con l'override del metodo Configure (dotnet/aspnetcore #45372).

Aggiungere elementi di configurazione all'avvio da un assembly esterno

Un'implementazione IHostingStartup consente di aggiungere estensioni a un'app all'avvio da un assembly esterno, al di fuori del file Startup o della classe Program dell'app. Per ulteriori informazioni, fare riferimento a Utilizzare gli assembly di avvio per l'hosting in ASP.NET Core.

Classe Startup (ConfigureServices e Configure metodi)

Sebbene sia supportato nelle app ASP.NET Core destinate a .NET 6 o versioni successive, l'uso di una Startup classe non è consigliato. Per ulteriori informazioni, vedere Migrare da ASP.NET Core in .NET 5 a .NET 6.

Per informazioni sull'uso dei ConfigureServices metodi e Configure con il modello di hosting minimo, vedere quanto segue:

Misurare le prestazioni di avvio

L'hosting EventSource ASP.NET Core genera l'evento ServerReady , che rappresenta il punto in cui il server è pronto per rispondere alle richieste e può essere usato per misurare il tempo di avvio. Per altre informazioni, vedere Registrazione in .NET e ASP.NET Core.

Risorse aggiuntive

  • Last updated on