Inicialização de aplicativo no ASP.NET Core

O arquivo Program

Os aplicativos ASP.NET Core inicializam e configuram a inicialização no arquivo Program do aplicativo (Program.cs).

A primeira parte do Program arquivo se concentra na criação do aplicativo. Essa fase utiliza WebApplication.CreateBuilder para inicializar uma nova instância da WebApplicationBuilder classe com padrões pré-configurados antes de o aplicativo ser iniciado. Os modelos de projeto ASP.NET Core atribuem o construtor de aplicativos Web a uma variável chamadabuilder:

var builder = WebApplication.CreateBuilder(args);

As propriedades do construtor de aplicativos Web incluem:

• builder.Configuration é um IConfigurationBuilder e IConfigurationRoot para gerenciar fontes e provedores de configuração. Para obter mais informações, consulte Configuração no ASP.NET Core.
• builder.Environment é um IWebHostEnvironment que fornece informações sobre o ambiente de hospedagem web do aplicativo. Para obter mais informações, consulte ambientes de runtime do ASP.NET Core.
• builder.Host é um IHostBuilder para configurar propriedades específicas do host. Para saber mais, confira Host Genérico .NET no ASP.NET Core.
• builder.Logging é um ILoggingBuilder com métodos de extensão que adicionam e gerenciam provedores de log. Para obter mais informações, consulte Logging no .NET e ASP.NET Core.
• builder.Metrics(.NET 8 ou posterior) permite habilitar métricas e direcionar sua saída. Para saber mais, confira Métricas do ASP.NET Core
• builder.Services é uma coleção de serviços de injeção de dependência (DI) (IServiceCollection) para o aplicativo compor para Inversão de Controle (IoC). Para obter mais informações, consulte Injeção de dependência no ASP.NET Core.
• builder.WebHost é um IWebHostBuilder para configurar propriedades específicas do servidor.

O aplicativo é compilado chamando WebApplicationBuilder.Build, que retorna o WebApplication compilado. Os modelos de projeto ASP.NET Core atribuem o aplicativo Web compilado a uma variável chamadaapp:

var app = builder.Build();

A próxima parte do arquivo Program se concentra em definir o pipeline de processamento de solicitações HTTP como uma série de componentes de middleware. Cada middleware executa operações em um HttpContext e ou chama o próximo middleware no pipeline ou encerra a solicitação. Por convenção, os componentes de middleware são adicionados ao pipeline invocando um método de extensão que começa com "Use." Para obter mais informações, consulte ASP.NET Core middleware.

O Run método inicia o aplicativo e bloqueia o thread de chamada até que o host seja desligado:

app.Run();

Quando Run executado, o aplicativo faz a transição para um processo ativo e em execução:

1. Os serviços hospedados iniciam.

   O host percorre todos os serviços hospedados registrados (instâncias de IHostedService) e chama os métodos StartAsync. A menos que o aplicativo opte pela inicialização simultânea do serviço hospedado (.NET 8 ou posterior), os serviços hospedados começam sequencialmente na ordem de seus registros de contêiner de DI. Para obter mais informações, consulte tarefas em segundo plano com serviços hospedados no ASP.NET Core.

2. O pipeline de middleware foi criado.

   Quando builder.Build é chamado, as dependências são resolvidas, mas o pipeline de processamento real não está completamente definido. Quando app.Run é executado, o framework finaliza o pipeline de middleware HTTP. Os métodos de middleware declarados e os mapeamentos de endpoint são compilados em uma única sequência de delegados de execução de alto desempenho. Para obter mais informações, consulte ASP.NET Core middleware.

3. O servidor Web (Kestrel por padrão) é iniciado.

   O host procura em seu contêiner de dependências, localiza a implementação de servidor registrada (geralmente Kestrel) e inicia seu ciclo de inicialização. Kestrel em seguida:

   • Pesquisa as URLs de hospedagem definidas e as portas de configuração, variáveis de ambiente ou argumentos de linha de comando.
   • Abre e aloca soquetes de rede física.
   • Vincula portas e passa a escutar o tráfego de entrada.

   Para obter mais informações, consulte .NET Host Genérico em ASP.NET Core, implementações de servidor Web em ASP.NET Core e Kestrel servidor Web em ASP.NET Core.

4. Os eventos de inicialização do aplicativo são acionados.

   O serviço IHostApplicationLifetime aciona seu token ApplicationStarted, que invoca as funções de callback registradas nesse token. Quaisquer callbacks, seeders de banco de dados ou outros ouvintes de eventos personalizados que estejam configurados para aguardar o disparo do token são acionados para iniciar o processamento.

5. O thread de execução principal é bloqueado enquanto o aplicativo é executado.

   Run (app.Run()) espera de forma síncrona até o desligamento.

6. O aplicativo está pronto para processar solicitações.

   Neste ponto, o interpretador de comandos registra diagnósticos de hospedagem:

   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.
   

O aplicativo permanece nesse estado indefinidamente, encaminhando o tráfego web recebido pelo pipeline de middleware e enviando respostas.

Quando o desligamento é sinalizado, por exemplo, quando Ctrl+c é detectado no shell de comando que executa o aplicativo ou uma ferramenta de orquestração de contêiner envia um evento SIGTERM, Run desbloqueia e as seguintes ações ocorrem:

1. ApplicationStopping os tokens são disparados, o que permite que o aplicativo execute a lógica antes do início do processo de desligamento.

2. O Kestrel servidor é desligado, o que desabilita novas conexões. O servidor aguarda a conclusão de solicitações em conexões existentes pelo tempo que o tempo limite de desligamento permitir. O servidor envia o cabeçalho de fechamento de conexão para novas solicitações em conexões existentes.

3. O host desliga os serviços hospedados registrados. A menos que o aplicativo opte por interromper serviços hospedados simultaneamente (.NET 8 ou posterior), os serviços hospedados param sequencialmente na ordem inversa de seus registros de contêiner de DI. Para obter mais informações, consulte tarefas em segundo plano com serviços hospedados no ASP.NET Core.

4. ApplicationStopped os manipuladores de eventos são disparados, o que permite que o aplicativo execute a lógica depois que o aplicativo for desligado.

5. A execução do console termina normalmente com um código de saída 0.

A classe Startup configura serviços e o pipeline de solicitação do aplicativo.

A classe Startup

ASP.NET Core aplicativos usam uma classe de inicialização, que é nomeada Startup por convenção. A classe Startup:

• Opcionalmente, inclua um método ConfigureServices para configurar os serviços do aplicativo. Um serviço é um componente reutilizável que fornece a funcionalidade do aplicativo. Os serviços estão registrados em ConfigureServices e consumidos no aplicativo por meio da DI (injeção de dependência) ou ApplicationServices.
• Inclui um método Configure para criar o pipeline de processamento de solicitações do aplicativo.

ConfigureServices e Configure são chamados pelo runtime do ASP.NET Core quando o aplicativo é iniciado:

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

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

A classe Startup é especificada quando o host do aplicativo é criado. A Startup classe normalmente é especificada chamando WebHostBuilderExtensions.UseStartup o construtor de 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>();
            });
}

O host fornece serviços que estão disponíveis para o construtor de classe Startup. O aplicativo adiciona serviços adicionais por meio de ConfigureServices. Os serviços de aplicativos e o host ficam disponíveis em Configure e em todo o aplicativo.

Somente os seguintes serviços podem ser injetados no construtor Startup ao usar o Host Genérico (IHostBuilder):

• IWebHostEnvironment
• IHostEnvironment
• IConfiguration

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

A maioria dos serviços não está disponível até que o Configure método seja chamado.

Várias Startup classes

Quando o aplicativo define classes Startup separadas para ambientes diferentes (por exemplo, StartupDevelopment), a classe Startup apropriada é selecionada no runtime. A classe cujo sufixo do nome corresponde ao ambiente atual é priorizada. Se o aplicativo for executado no ambiente Development e incluir tanto uma classe Startup quanto uma classe StartupDevelopment, a classe StartupDevelopment será usada. Para obter mais informações, veja Usar vários ambientes.

O método ConfigureServices

O método opcional ConfigureServices é:

• Chamado pelo host antes do método Configure para configurar os serviços do aplicativo.
• Quando as opções de configuração são definidas por convenção.

O host pode configurar alguns serviços antes que métodos Startup sejam chamados. Para obter mais informações, consulte Visão geral dos conceitos básicos do ASP.NET Core.

Para recursos que exigem configuração substancial, existem métodos de extensão Add{Service} em IServiceCollection, como:

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

Adicionar serviços ao contêiner de serviços os torna disponíveis dentro do aplicativo e no método Configure. Os serviços são resolvidos por meio da injeção de dependência ou de ApplicationServices.

O método Configure

O método Configure é usado para especificar como o aplicativo responde às solicitações HTTP. O pipeline de solicitação é configurado adicionando componentes de middleware a uma instância de IApplicationBuilder. IApplicationBuilder está disponível para o método Configure, mas não é registrado no contêiner de serviço. A hospedagem cria um IApplicationBuilder e o passa diretamente para Configure.

Os modelos do ASP.NET Core configuram o pipeline com suporte para:

• Página de exceção do desenvolvedor
• Manipulador de exceção
• Segurança de Transporte Estrita de HTTP (HSTS)
• Redirecionamento HTTPS
• Arquivos estáticos
• MVC do ASP.NET Core e RazorRazor Pages

O exemplo a seguir demonstra o middleware para um aplicativo típico Razor 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();
        });
    }
}

O exemplo anterior é para RazorPages; a versão MVC é semelhante.

Cada método de extensão Use adiciona um ou mais componentes de middleware ao pipeline de solicitação. Por exemplo, UseStaticFiles configura o middleware para atender arquivos estáticos.

Cada componente de middleware na cadeia de solicitação é responsável por invocar o próximo componente na cadeia ou interromper a cadeia, se apropriado.

Serviços adicionais, como IWebHostEnvironment, ILoggerFactory ou qualquer coisa definida em ConfigureServices, podem ser especificados na assinatura do método Configure. Esses serviços serão injetados se estiverem disponíveis.

Para obter mais informações sobre como usar IApplicationBuilder e a ordem do processamento de middleware, consulte ASP.NET Core middleware.

Configurar serviços sem uma Startup classe

Para configurar serviços e o pipeline de processamento de solicitação sem usar uma classe Startup, chame os métodos de conveniência ConfigureServices e Configure no construtor do host. Diversas chamadas para ConfigureServices são acrescentadas umas às outras. Se houver várias chamadas de método Configure, a última chamada de Configure será usada.

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

A implementação do filtro de inicialização é registrada no Program arquivo:

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

A implementação do filtro de inicialização está registrada em Startup.ConfigureServices:

services.AddTransient<IStartupFilter, CustomResponseHeaderFilter>();

A classe Startup (métodos ConfigureServices e Configure)

Embora tenha suporte em aplicativos ASP.NET Core que visam .NET 6 ou posteriores, não é recomendável usar uma Startup classe. Para obter mais informações, consulte Migrar do ASP.NET Core no .NET 5 para o .NET 6.

Para obter informações sobre como usar os métodos ConfigureServices e Configure com o modelo de hospedagem mínima, consulte o seguinte:

• Usar uma Startup classe com o modelo de hospedagem mínimo
• A Startup classe (versão .NET 5 deste artigo)

Medir o desempenho de inicialização

A hospedagem do ASP.NET Core EventSource emite o ServerReady evento, que representa o ponto em que o servidor está pronto para responder a requisições e pode ser usado para medir o tempo de inicialização. Para obter mais informações, consulte Logging no .NET e ASP.NET Core.