Partilhar via

Inicialização do aplicativo no ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 9 deste artigo.

Advertência

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

Importante

Estas informações referem-se a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui.

Para a versão atual, consulte a versão .NET 9 deste artigo.

Por Rick Anderson

ASP.NET Os aplicativos principais criados com os modelos da Web contêm o código de inicialização do aplicativo no arquivo Program.cs.

Para obter Blazor orientação de inicialização, que adiciona ou substitui a orientação neste artigo, consulte ASP.NET Core Blazor startup.

O código de inicialização do aplicativo a seguir oferece suporte a vários tipos de aplicativos:

using WebAll.Components;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.UseAntiforgery();

app.Run();

Os aplicativos que usam EventSource podem medir o tempo de inicialização para entender e otimizar o desempenho da inicialização. O evento ServerReady em Microsoft.AspNetCore.Hosting representa o ponto em que o servidor está pronto para responder às solicitações.

Estenda a inicialização com filtros de inicialização

Use IStartupFilter:

  • Para configurar o middleware no início ou no final do pipeline de middleware de uma aplicação sem uma chamada explícita para Use{Middleware}. Use IStartupFilter para adicionar padrões ao início do pipeline sem registrar explicitamente o middleware padrão. IStartupFilter permite que um componente diferente chame Use{Middleware} em nome do autor do aplicativo.
  • Para criar um pipeline de métodos Configure. IStartupFilter.Configure pode definir um middleware para ser executado antes ou depois do middleware adicionado pelas bibliotecas.

Uma implementação IStartupFilter executa Configure, que recebe e retorna um Action<IApplicationBuilder>. Um IApplicationBuilder define uma classe para configurar o pipeline de solicitação de um aplicativo. Para obter mais informações, consulte Criar um pipeline de middleware com IApplicationBuilder.

Cada implementação IStartupFilter pode adicionar um ou mais middlewares no pipeline de solicitação. Os filtros são invocados na ordem em que foram adicionados ao contêiner de serviço. Os filtros podem adicionar middleware antes ou depois de passar o controle para o próximo filtro, portanto, eles acrescentam ao início ou ao fim do pipeline do aplicativo.

O exemplo a seguir demonstra como registrar um middleware com IStartupFilter. O middleware RequestSetOptionsMiddleware define um valor de opções a partir de um parâmetro de cadeia de caracteres de consulta:

public class RequestSetOptionsMiddleware
{
    private readonly RequestDelegate _next;

    public RequestSetOptionsMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    // Test with https://localhost:5001/Privacy/?option=Hello
    public async Task Invoke(HttpContext httpContext)
    {
        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            httpContext.Items["option"] = WebUtility.HtmlEncode(option);
        }

        await _next(httpContext);
    }
}

O RequestSetOptionsMiddleware é configurado na classe RequestSetOptionsStartupFilter:

public class RequestSetOptionsStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            builder.UseMiddleware<RequestSetOptionsMiddleware>();
            next(builder);
        };
    }
}

A implementação IStartupFilter está registada em Program.cs:

using WebStartup.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddTransient<IStartupFilter,
                      RequestSetOptionsStartupFilter>();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Quando um parâmetro de cadeia de caracteres de consulta para option é fornecido, o middleware processa a atribuição de valor antes que o middleware ASP.NET Core renderize a resposta:

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p> Append query string ?option=hello</p>
Option String: @HttpContext.Items["option"];

A ordem de execução do middleware é definida pela ordem dos registos IStartupFilter:

  • Várias implementações de IStartupFilter podem interagir com os mesmos objetos. Se o pedido for importante, solicite que seus registros de serviço IStartupFilter correspondam à ordem que seus middlewares devem executar.

  • As bibliotecas podem adicionar middleware com uma ou mais implementações IStartupFilter que são executadas antes ou depois de outro middleware da aplicação registado com IStartupFilter. Para invocar um middleware IStartupFilter antes de um middleware adicionado pelo IStartupFilterde uma biblioteca:

    • Posicione o registro de serviço antes que a biblioteca seja adicionada ao contêiner de serviço.
    • Para invocar depois, posicione o registro de serviço depois que a biblioteca for adicionada.

Não é possível estender o aplicativo ASP.NET Core quando você substitui Configure. Para obter mais informações, consulte este problema do GitHub.

Adicionar configuração na inicialização a partir de um componente externo

Uma implementação IHostingStartup permite adicionar aprimoramentos a um aplicativo na inicialização a partir de um assembly externo fora do arquivo Program.cs do aplicativo. Para obter mais informações, consulte Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Inicialização, ConfigureServices e Configuração

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

ASP.NET Os aplicativos principais criados com os modelos da Web contêm o código de inicialização do aplicativo no arquivo Program.cs.

O seguinte código de inicialização do aplicativo suporta:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Para obter mais informações sobre a inicialização do aplicativo, consulte ASP.NET Visão geral dos fundamentos principais.

Prolongue a inicialização utilizando filtros de arranque

Utilize o IStartupFilter:

  • Para configurar o middleware no início ou no final do pipeline de middleware de uma aplicação sem uma chamada explícita ao Use{Middleware}. Use IStartupFilter para adicionar padrões ao início do pipeline sem registrar explicitamente o middleware padrão. IStartupFilter permite que um componente diferente chame Use{Middleware} em nome do autor do aplicativo.
  • Para criar um pipeline de métodos Configure. IStartupFilter.Configure pode definir um middleware para ser executado antes ou depois do middleware adicionado pelas bibliotecas.

IStartupFilter implementa Configure, que recebe e retorna um Action<IApplicationBuilder>. Um IApplicationBuilder define uma classe para configurar o pipeline de solicitação de um aplicativo. Para obter mais informações, consulte Criar um pipeline de middleware com IApplicationBuilder.

Cada IStartupFilter pode adicionar um ou mais middleware na pipeline de solicitação. Os filtros são invocados na ordem em que foram adicionados ao contêiner de serviço. Os filtros podem adicionar middleware antes ou depois de passar o controle para o próximo filtro, portanto, eles acrescentam ao início ou ao fim do pipeline do aplicativo.

O exemplo a seguir demonstra como registrar um middleware com IStartupFilter. O middleware RequestSetOptionsMiddleware define um valor de opções a partir de um parâmetro de cadeia de caracteres de consulta:

public class RequestSetOptionsMiddleware
{
    private readonly RequestDelegate _next;

    public RequestSetOptionsMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    // Test with https://localhost:5001/Privacy/?option=Hello
    public async Task Invoke(HttpContext httpContext)
    {
        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            httpContext.Items["option"] = WebUtility.HtmlEncode(option);
        }

        await _next(httpContext);
    }
}

O RequestSetOptionsMiddleware é configurado na classe RequestSetOptionsStartupFilter:

namespace WebStartup.Middleware;
// <snippet1>
public class RequestSetOptionsStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            builder.UseMiddleware<RequestSetOptionsMiddleware>();
            next(builder);
        };
    }
}
// </snippet1>

O IStartupFilter está registado em Program.cs:

using WebStartup.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddTransient<IStartupFilter,
                      RequestSetOptionsStartupFilter>();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Quando um parâmetro de cadeia de caracteres de consulta para option é fornecido, o middleware processa a atribuição de valor antes que o middleware ASP.NET Core renderize a resposta:

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p> Append query string ?option=hello</p>
Option String: @HttpContext.Items["option"];

A ordem de execução do middleware é definida pela ordem dos registos IStartupFilter:

  • Várias implementações de IStartupFilter podem interagir com os mesmos objetos. Se o pedido for importante, solicite que seus registros de serviço IStartupFilter correspondam à ordem que seus middlewares devem executar.

  • As bibliotecas podem adicionar middleware com uma ou mais implementações IStartupFilter executadas antes ou depois de outro middleware de aplicação registrado com IStartupFilter. Para invocar um middleware IStartupFilter antes de um middleware adicionado pelo IStartupFilterde uma biblioteca:

    • Posicione o registro de serviço antes que a biblioteca seja adicionada ao contêiner de serviço.
    • Para invocar depois, coloque o registo de serviço depois que a biblioteca seja adicionada.

Observação: não é possível estender a aplicação ASP.NET Core ao substituir Configure. Para obter mais informações, consulte este problema do GitHub.

Adicionar configuração ao iniciar a partir de um assembly externo

Uma implementação IHostingStartup permite adicionar aprimoramentos a um aplicativo na inicialização a partir de um assembly externo fora do arquivo Program.cs do aplicativo. Para obter mais informações, consulte Utilização de assemblies de arranque de hospedagem no ASP.NET Core.

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

A classe Startup

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

  • Opcionalmente, inclui um método ConfigureServices para configurar os serviços de do aplicativo. Um serviço é um componente reutilizável que fornece funcionalidade de aplicativo. Os serviços são registados no ConfigureServices e consumidos em todo o aplicativo através de ou ApplicationServicespela injeção de dependência (DI).
  • Inclui um método Configure para criar o pipeline de processamento de solicitações do aplicativo.

ConfigureServices e Configure são chamados pelo tempo de execução do ASP.NET Core quando o aplicativo é iniciado:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

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

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

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

A classe Startup é especificada quando o host do aplicativo é criado. A classe Startup é normalmente especificada chamando o método WebHostBuilderExtensions.UseStartup/<TStartup> no 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. A aplicação adiciona serviços adicionais via ConfigureServices. Os serviços de host e aplicativo estão disponíveis em Configure e em todo o aplicativo.

Somente os seguintes tipos de serviço podem ser injetados no construtor Startup ao usar o Generic Host (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
        {
        }
    }
}

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

Inicialização múltipla

Quando o aplicativo define classes Startup separadas para ambientes diferentes (por exemplo, StartupDevelopment), a classe Startup apropriada é selecionada em tempo de execução. A classe cujo sufixo de nome corresponde ao ambiente atual é priorizada. Se o aplicativo for executado no ambiente de desenvolvimento e incluir uma classe Startup e uma classe StartupDevelopment, a classe StartupDevelopment será usada. Para obter mais informações, consulte Usar vários ambientes.

Consulte O anfitrião para obter mais informações sobre o anfitrião. Para obter informações sobre como manipular erros durante a inicialização, consulte Startup exception handling.

O método ConfigureServices

O método ConfigureServices é:

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

O host pode configurar alguns serviços antes que Startup métodos sejam chamados. Para obter mais informações, consulte O anfitrião.

Para funcionalidades que exigem uma configuração substancial, há Add{Service} métodos de extensão no IServiceCollection. Por exemplo, AdicionarDbContext, AdicionarDefaultIdentity, AdicionarEntityFrameworkStores e AdicionarRazorPages:

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ço os torna disponíveis no aplicativo e no método Configure. Os serviços são resolvidos por injeção de dependência através de ou a partir de ApplicationServices.

O método Configure

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

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

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

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

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

O exemplo anterior é para Razor Pages; 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 servir arquivos estáticos .

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

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

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

Configurar serviços sem inicialização

Para configurar serviços e o pipeline de processamento de solicitações sem usar uma classe Startup, chame os métodos de conveniência ConfigureServices e Configure no host builder. Várias chamadas para ConfigureServices se somam umas às outras. Se existirem várias chamadas de método Configure, a última chamada 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 =>
                {
                    services.AddControllersWithViews();
                })
                .Configure(app =>
                {
                    var loggerFactory = app.ApplicationServices
                        .GetRequiredService<ILoggerFactory>();
                    var logger = loggerFactory.CreateLogger<Program>();
                    var env = app.ApplicationServices.GetRequiredService<IWebHostEnvironment>();
                    var config = app.ApplicationServices.GetRequiredService<IConfiguration>();

                    logger.LogInformation("Logged in Configure");

                    if (env.IsDevelopment())
                    {
                        app.UseDeveloperExceptionPage();
                    }
                    else
                    {
                        app.UseExceptionHandler("/Home/Error");
                        app.UseHsts();
                    }

                    var configValue = config["MyConfigKey"];
                });
            });
        });
}

Estenda a inicialização com filtros de inicialização

Use o código IStartupFilter:

  • Para configurar o middleware no início ou no final do de um aplicativo Configure pipeline de middleware sem uma chamada explícita para Use{Middleware}. IStartupFilter é usado pelo ASP.NET Core para adicionar padrões ao início do pipeline sem precisar fazer com que o autor do aplicativo registre explicitamente o middleware padrão. IStartupFilter permite que um componente diferente chame Use{Middleware} em nome do autor do aplicativo.
  • Para criar um pipeline de métodos Configure. IStartupFilter.Configure pode definir um middleware para ser executado antes ou depois do middleware adicionado pelas bibliotecas.

IStartupFilter implementa Configure, que recebe e retorna um Action<IApplicationBuilder>. Um IApplicationBuilder define uma classe para configurar o pipeline de solicitação de um aplicativo. Para obter mais informações, consulte Criar um pipeline de middleware com IApplicationBuilder.

Cada IStartupFilter pode adicionar um ou mais middlewares no pipeline de solicitação. Os filtros são invocados na ordem em que foram adicionados ao contêiner de serviço. Os filtros podem adicionar middleware antes ou depois de passar o controle para o próximo filtro, assim, eles são adicionados ao início ou ao fim do pipeline da aplicação.

O exemplo a seguir demonstra como registrar um middleware com IStartupFilter. O middleware RequestSetOptionsMiddleware define um valor de opções a partir de um parâmetro de cadeia de caracteres de consulta:

public class RequestSetOptionsMiddleware
{
    private readonly RequestDelegate _next;

    public RequestSetOptionsMiddleware( RequestDelegate next )
    {
        _next = next;
    }

    // Test with https://localhost:5001/Privacy/?option=Hello
    public async Task Invoke(HttpContext httpContext)
    {
        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            httpContext.Items["option"] = WebUtility.HtmlEncode(option);
        }

        await _next(httpContext);
    }
}

O RequestSetOptionsMiddleware é configurado na classe RequestSetOptionsStartupFilter:

public class RequestSetOptionsStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            builder.UseMiddleware<RequestSetOptionsMiddleware>();
            next(builder);
        };
    }
}

O IStartupFilter está registrado no contêiner de serviço em ConfigureServices.

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.UseStartup<Startup>();
         })
        .ConfigureServices(services =>
        {
            services.AddTransient<IStartupFilter,
                      RequestSetOptionsStartupFilter>();
        });
}

Quando um parâmetro de cadeia de caracteres de consulta para option é fornecido, o middleware processa a atribuição de valor antes que o middleware ASP.NET Core renderize a resposta.

A ordem de execução do middleware é definida pela ordem dos registos IStartupFilter:

  • Várias implementações de IStartupFilter podem interagir com os mesmos objetos. Se a ordem for importante, ordene os seus registos de serviço IStartupFilter para corresponder à ordem em que os seus middlewares devem funcionar.

  • As bibliotecas podem adicionar middleware com uma ou mais implementações IStartupFilter executadas antes ou depois de outro middleware de aplicativo registrado com IStartupFilter. Para invocar um middleware IStartupFilter antes de um middleware adicionado pelo IStartupFilterde uma biblioteca:

    • Posicione o registro de serviço antes que a biblioteca seja adicionada ao contêiner de serviço.
    • Para invocar depois, posicione o registro de serviço depois que a biblioteca for adicionada.

Adicionar configuração na inicialização de um conjunto externo

Uma implementação IHostingStartup permite adicionar aprimoramentos a um aplicativo na inicialização a partir de um assembly externo fora da classe Startup do aplicativo. Para obter mais informações, consulte Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Recursos adicionais