ASP.NET Core 中的应用启动

作者:Rick AndersonTom DykstraSteve Smith

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 类。 通常,通过在主机生成器上调用 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 和整个应用中使用。

使用泛型主机 (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 配置中间件提供静态文件

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

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

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

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

若要配置服务和请求处理管道,而不使用 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 中使用承载启动程序集

其他资源

Startup 类

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

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

public class Startup
{
    // Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    // Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app)
    {
        ...
    }
}

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

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

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

Startup 类中注入依赖关系的常见用途为注入:

public class Startup
{
    private readonly IHostingEnvironment _env;
    private readonly IConfiguration _config;
    private readonly ILoggerFactory _loggerFactory;

    public Startup(IHostingEnvironment env, IConfiguration config, 
        ILoggerFactory loggerFactory)
    {
        _env = env;
        _config = config;
        _loggerFactory = loggerFactory;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var logger = _loggerFactory.CreateLogger<Startup>();

        if (_env.IsDevelopment())
        {
            // Development service configuration

            logger.LogInformation("Development environment");
        }
        else
        {
            // Non-development service configuration

            logger.LogInformation("Environment: {EnvironmentName}", _env.EnvironmentName);
        }

        // Configuration is available during startup.
        // Examples:
        //   _config["key"]
        //   _config["subsection:suboption1"]
    }
}

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

多启动

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

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

ConfigureServices 方法

ConfigureServices 方法:

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

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

对于需要大量设置的功能,IServiceCollection 上有 Add{Service} 扩展方法。 例如,AddDbContext、AddDefaultIdentity、AddEntityFrameworkStores 和 AddRazorPages :

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(
            Configuration.GetConnectionString("DefaultConnection")));
    services.AddDefaultIdentity<IdentityUser>()
        .AddDefaultUI(UIFramework.Bootstrap4)
        .AddEntityFrameworkStores<ApplicationDbContext>();


    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

    // Add application services.
    services.AddTransient<IEmailSender, AuthMessageSender>();
    services.AddTransient<ISmsSender, AuthMessageSender>();
}

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

若要详细了解 SetCompatibilityVersion,请参阅 SetCompatibilityVersion

Configure 方法

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

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

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

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

    app.UseMvc();
}

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

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

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

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

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

若要配置服务和请求处理管道,而不使用 Startup 类,请在主机生成器上调用 ConfigureServicesConfigure 便捷方法。 多次调用 ConfigureServices 将追加到另一个。 如果存在多个 Configure 方法调用,则使用最后一个 Configure 调用。

public class Program
{
    public static IHostingEnvironment HostingEnvironment { get; set; }
    public static IConfiguration Configuration { get; set; }

    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .ConfigureAppConfiguration((hostingContext, config) =>
            {
            })
            .ConfigureServices(services =>
            {
                ...
            })
            .Configure(app =>
            {
                var loggerFactory = app.ApplicationServices
                    .GetRequiredService<ILoggerFactory>();
                var logger = loggerFactory.CreateLogger<Program>();
                var env = app.ApplicationServices.GetRequiredService<IHostingEnvironment>();
                var config = app.ApplicationServices.GetRequiredService<IConfiguration>();

                logger.LogInformation("Logged in Configure");

                if (env.IsDevelopment())
                {
                    ...
                }
                else
                {
                    ...
                }

                var configValue = config["subsection:suboption1"];

                ...
            });
}

使用 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;
    private IOptions<AppOptions> _injectedOptions;

    public RequestSetOptionsMiddleware(
        RequestDelegate next, IOptions<AppOptions> injectedOptions)
    {
        _next = next;
        _injectedOptions = injectedOptions;
    }

    public async Task Invoke(HttpContext httpContext)
    {
        Console.WriteLine("RequestSetOptionsMiddleware.Invoke");

        var option = httpContext.Request.Query["option"];

        if (!string.IsNullOrWhiteSpace(option))
        {
            _injectedOptions.Value.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

WebHost.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddTransient<IStartupFilter, 
            RequestSetOptionsStartupFilter>();
    })
    .UseStartup<Startup>()
    .Build();

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

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

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

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

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

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

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

其他资源