ASP.NET Core 中的应用启动

注意

此版本不是本文的最新版本。 对于当前版本,请参阅此文的 .NET 8 版本

警告

此版本的 ASP.NET Core 不再受支持。 有关详细信息,请参阅 .NET 和 .NET Core 支持策略。 对于当前版本,请参阅此文的 .NET 8 版本

重要

此信息与预发布产品相关,相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

对于当前版本,请参阅此文的 .NET 8 版本

作者:Rick Anderson

使用 Web 模板创建的 ASP.NET Core 应用包含 Program.cs 文件中的应用程序启动代码。

有关 Blazor 启动指南(补充或取代本文中的指南),请参阅 ASP.NET Core Blazor 启动

以下应用启动代码支持:

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

使用 EventSource 的应用可以度量启动时间,以了解和优化启动性能。 Microsoft.AspNetCore.Hosting 中的 ServerReady 事件表示服务器已准备好响应请求的点。

有关应用程序启动的详细信息,请参阅 ASP.NET Core 基础知识概述

使用 Startup 筛选器扩展 Startup

使用 IStartupFilter

  • 在应用的中间件管道的开头或末尾配置中间件,而无需显式调用 Use{Middleware}。 使用 IStartupFilter 在不显式注册默认中间件的情况下将默认值添加到管道的开头。 IStartupFilter 允许代表应用作者使用不同的组件调用 Use{Middleware}
  • 创建 Configure 方法的管道。 IStartupFilter.Configure 可以将中间件设置为在库添加的中间件之前或之后运行。

IStartupFilter 实现 Configure,即接收并返回 Action<IApplicationBuilder>IApplicationBuilder 定义用于配置应用请求管道的类。 有关详细信息,请参阅使用 IApplicationBuilder 创建中间件管道

每个 IStartupFilter 可以在请求管道中添加一个或多个中间件。 筛选器按照添加到服务容器的顺序调用。 筛选器可在将控件传递给下一个筛选器之前或之后添加中间件,从而附加到应用管道的开头或末尾。

下面的示例演示如何使用 IStartupFilter 注册中间件。 RequestSetOptionsMiddleware 中间件从查询字符串参数中设置选项值:

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

RequestSetOptionsStartupFilter 类中配置 RequestSetOptionsMiddleware

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

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

当提供 option 的查询字符串参数时,中间件在 ASP.NET Core 中间件呈现响应之前处理分配值:

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

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

中间件执行顺序由 IStartupFilter 注册顺序设置:

  • 多个 IStartupFilter 实现可能与相同的对象进行交互。 如果顺序很重要,请将它们的 IStartupFilter 服务注册进行排序,以匹配其中间件应有的运行顺序。

  • 库可能添加包含一个或多个 IStartupFilter 实现的中间件,这些实现在向 IStartupFilter 注册的其他应用中间件之前或之后运行。 若要在库的 IStartupFilter 添加的中间件之前调用 IStartupFilter 中间件,请执行以下操作:

    • 在库添加到服务容器之前定位服务注册。
    • 要在此后调用,请在添加库之后定位服务注册。

注意:重写 Configure 时,无法扩展 ASP.NET Core 应用。 有关详细信息,请参阅此 GitHub 问题

在启动时从外部程序集添加配置

通过 IHostingStartup 实现,可在启动时从应用的 Program.cs 文件之外的外部程序集向应用添加增强功能。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集

Startup、ConfigureServices 和 Configure

有关将 ConfigureServicesConfigure 方法与最小托管模型结合使用的信息,请参阅:

使用 Web 模板创建的 ASP.NET Core 应用包含 Program.cs 文件中的应用程序启动代码。

以下应用启动代码支持:

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

有关应用程序启动的详细信息,请参阅 ASP.NET Core 基础知识概述

使用 Startup 筛选器扩展 Startup

使用 IStartupFilter

  • 在应用的中间件管道的开头或末尾配置中间件,而无需显式调用 Use{Middleware}。 使用 IStartupFilter 在不显式注册默认中间件的情况下将默认值添加到管道的开头。 IStartupFilter 允许代表应用作者使用不同的组件调用 Use{Middleware}
  • 创建 Configure 方法的管道。 IStartupFilter.Configure 可以将中间件设置为在库添加的中间件之前或之后运行。

IStartupFilter 实现 Configure,即接收并返回 Action<IApplicationBuilder>IApplicationBuilder 定义用于配置应用请求管道的类。 有关详细信息,请参阅使用 IApplicationBuilder 创建中间件管道

每个 IStartupFilter 可以在请求管道中添加一个或多个中间件。 筛选器按照添加到服务容器的顺序调用。 筛选器可在将控件传递给下一个筛选器之前或之后添加中间件,从而附加到应用管道的开头或末尾。

下面的示例演示如何使用 IStartupFilter 注册中间件。 RequestSetOptionsMiddleware 中间件从查询字符串参数中设置选项值:

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

RequestSetOptionsStartupFilter 类中配置 RequestSetOptionsMiddleware

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

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

当提供 option 的查询字符串参数时,中间件在 ASP.NET Core 中间件呈现响应之前处理分配值:

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

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

中间件执行顺序由 IStartupFilter 注册顺序设置:

  • 多个 IStartupFilter 实现可能与相同的对象进行交互。 如果顺序很重要,请将它们的 IStartupFilter 服务注册进行排序,以匹配其中间件应有的运行顺序。

  • 库可能添加包含一个或多个 IStartupFilter 实现的中间件,这些实现在向 IStartupFilter 注册的其他应用中间件之前或之后运行。 若要在库的 IStartupFilter 添加的中间件之前调用 IStartupFilter 中间件,请执行以下操作:

    • 在库添加到服务容器之前定位服务注册。
    • 要在此后调用,请在添加库之后定位服务注册。

注意:重写 Configure 时,无法扩展 ASP.NET Core 应用。 有关详细信息,请参阅此 GitHub 问题

在启动时从外部程序集添加配置

通过 IHostingStartup 实现,可在启动时从应用的 Program.cs 文件之外的外部程序集向应用添加增强功能。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集

Startup 类配置服务和应用的请求管道。

Startup 类

ASP.NET Core 应用使用 Startup 类,按照约定命名为 StartupStartup 类:

在应用启动时,ASP.NET Core 运行时会调用 ConfigureServicesConfigure

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

前面的示例适用于 Razor Pages;MVC 版本类似。

在构建应用Startup时指定 Startup 类。 通常通过在主机生成器上调用 WebHostBuilderExtensions.UseStartup/<TStartup> 方法来指定 Startup 类:

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

主机提供 Startup 类构造函数可用的某些服务。 应用通过 ConfigureServices 添加其他服务。 主机和应用服务都可以在 Configure 和整个应用中使用。

使用Startup (IHostBuilder) 时,只能将以下服务类型注入 Startup 构造函数:

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

在调用 Configure 方法之前,大多数服务都不可用。

多启动

应用为不同的环境(例如,StartupDevelopment)单独定义 Startup 类时,相应的 Startup 类会在运行时被选中。 优先考虑名称后缀与当前环境相匹配的类。 如果应用在开发环境中运行并包含 Startup 类和 StartupDevelopment 类,则使用 StartupDevelopment 类。 有关详细信息,请参阅使用多个环境

请参阅主机,了解有关主机的详细信息。 有关在启动过程中处理错误的信息,请参阅启动异常处理

ConfigureServices 方法

ConfigureServices 方法:

  • 可选。
  • Configure 方法配置应用服务之前,由主机调用。
  • 其中按常规设置配置选项

主机可能会在调用 Startup 方法之前配置某些服务。 有关详细信息,请参阅主机

对于需要大量设置的功能,IServiceCollection 上有 Add{Service} 扩展方法。 例如,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();
    }

将服务添加到服务容器,使其在应用和 Configure 方法中可用。 服务通过依赖关系注入ApplicationServices 进行解析。

Configure 方法

Configure 方法用于指定应用响应 HTTP 请求的方式。 可通过将中间件组件添加到 IApplicationBuilder 实例来配置请求管道。 Configure 方法可使用 IApplicationBuilder,但未在服务容器中注册。 托管创建 IApplicationBuilder 并将其直接传递到 Configure

ASP.NET Core 模板配置的管道支持:

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

前面的示例适用于 Razor Pages;MVC 版本类似。

每个 Use 扩展方法将一个或多个中间件组件添加到请求管道。 例如,UseStaticFiles 配置UseStaticFiles提供静态文件

请求管道中的每个中间件组件负责调用管道中的下一个组件,或在适当情况下使链发生短路。

可以在 Configure 方法签名中指定其他服务,如 IWebHostEnvironmentILoggerFactoryConfigureServices 中定义的任何内容。 如果这些服务可用,则会被注入。

有关如何使用 IApplicationBuilder 和中间件处理顺序的详细信息,请参阅 IApplicationBuilder

在不启动的情况下配置服务

若要配置服务和请求处理管道,而不使用 Startup 类,请在主机生成器上调用 ConfigureServicesConfigure 便捷方法。 多次调用 ConfigureServices 将追加到另一个。 如果存在多个 Configure 方法调用,则使用最后一个 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 =>
                {
                    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"];
                });
            });
        });
}

使用 Startup 筛选器扩展 Startup

使用 IStartupFilter

  • 在应用的 Configure 中间件管道的开头或末尾配置中间件,而无需显式调用 Use{Middleware}IStartupFilter 由 ASP.NET Core 用于将默认值添加到管道的开头,而无需使应用作者显式注册默认中间件。 IStartupFilter 允许代表应用作者使用不同的组件调用 Use{Middleware}
  • 创建 Configure 方法的管道。 IStartupFilter.Configure 可以将中间件设置为在库添加的中间件之前或之后运行。

IStartupFilter 实现 Configure,即接收并返回 Action<IApplicationBuilder>IApplicationBuilder 定义用于配置应用请求管道的类。 有关详细信息,请参阅使用 IApplicationBuilder 创建中间件管道

每个 IStartupFilter 可以在请求管道中添加一个或多个中间件。 筛选器按照添加到服务容器的顺序调用。 筛选器可在将控件传递给下一个筛选器之前或之后添加中间件,从而附加到应用管道的开头或末尾。

下面的示例演示如何使用 IStartupFilter 注册中间件。 RequestSetOptionsMiddleware 中间件从查询字符串参数中设置选项值:

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

RequestSetOptionsStartupFilter 类中配置 RequestSetOptionsMiddleware

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

ConfigureServices 中的服务容器中注册 IStartupFilter

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

当提供 option 的查询字符串参数时,中间件在 ASP.NET Core 中间件呈现响应之前处理分配值。

中间件执行顺序由 IStartupFilter 注册顺序设置:

  • 多个 IStartupFilter 实现可能与相同的对象进行交互。 如果顺序很重要,请将它们的 IStartupFilter 服务注册进行排序,以匹配其中间件应有的运行顺序。

  • 库可能添加包含一个或多个 IStartupFilter 实现的中间件,这些实现在向 IStartupFilter 注册的其他应用中间件之前或之后运行。 若要在库的 IStartupFilter 添加的中间件之前调用 IStartupFilter 中间件,请执行以下操作:

    • 在库添加到服务容器之前定位服务注册。
    • 要在此后调用,请在添加库之后定位服务注册。

在启动时从外部程序集添加配置

通过 IHostingStartup 实现,可在启动时从应用 Startup 类之外的外部程序集向应用添加增强功能。 有关详细信息,请参阅在 ASP.NET Core 中使用托管启动程序集

其他资源