ASP.NET Core 中的应用启动App startup in ASP.NET Core

本文内容

作者：Rick Anderson、Tom Dykstra 和 Steve Smith

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

Startup 类The Startup class

ASP.NET Core 应用使用 Startup 类，按照约定命名为 Startup。Startup 类：

• 可选择性地包括 ConfigureServices 方法以配置应用的服务 。服务是一个提供应用功能的可重用组件。在 ConfigureServices 中注册服务，并通过依赖关系注入 (DI) 或 ApplicationServices 在整个应用中使用服务 。
• 包括 Configure 方法以创建应用的请求处理管道。

在应用启动时，ASP.NET Core 运行时会调用 ConfigureServices 和 Configure：

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 构造函数：

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

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

多启动Multiple Startup

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

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

ConfigureServices 方法The ConfigureServices method

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 方法The Configure method

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

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

• 开发人员异常页
• 异常处理程序
• HTTP 严格传输安全性 (HSTS)
• HTTPS 重定向
• 静态文件
• ASP.NET Core MVC 和 Razor Pages

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 方法签名中指定其他服务，如 IWebHostEnvironment、ILoggerFactory 或 ConfigureServices 中定义的任何内容。如果这些服务可用，则会被注入。

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

在不启动的情况下配置服务Configure services without Startup

若要配置服务和请求处理管道，而不使用 Startup 类，请在主机生成器上调用 ConfigureServices 和 Configure 便捷方法。多次调用 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 筛选器扩展 StartupExtend Startup with startup filters

使用 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 中间件，请执行以下操作：

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

在启动时从外部程序集添加配置Add configuration at startup from an external assembly

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

其他资源Additional resources

• 主机
• 在 ASP.NET Core 中使用多个环境
• ASP.NET Core 中间件
• .NET Core 和 ASP.NET Core 中的日志记录
• ASP.NET Core 中的配置

Startup 类The Startup class

ASP.NET Core 应用使用 Startup 类，按照约定命名为 Startup。Startup 类：

• 可选择性地包括 ConfigureServices 方法以配置应用的服务 。服务是一个提供应用功能的可重用组件。在 ConfigureServices 中注册服务，并通过依赖关系注入 (DI) 或 ApplicationServices 在整个应用中使用服务 。
• 包括 Configure 方法以创建应用的请求处理管道。

在应用启动时，ASP.NET Core 运行时会调用 ConfigureServices 和 Configure：

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 类中注入依赖关系的常见用途为注入：

• IHostingEnvironment 按环境配置服务。
• IConfiguration 读取配置。
• ILoggerFactory 在记录器中创建 Startup.ConfigureServices。

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 方法之前，大多数服务都不可用。

多启动Multiple Startup

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

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

ConfigureServices 方法The ConfigureServices method

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 方法The Configure method

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

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

• 开发人员异常页
• 异常处理程序
• HTTP 严格传输安全性 (HSTS)
• HTTPS 重定向
• 静态文件
• ASP.NET Core MVC 和 Razor Pages
• 一般数据保护条例 (GDPR)

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 方法签名中指定其他服务，如 IHostingEnvironment 和 ILoggerFactory，或 ConfigureServices 中定义的任何内容。如果这些服务可用，则会被注入。

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

在不启动的情况下配置服务Configure services without Startup

若要配置服务和请求处理管道，而不使用 Startup 类，请在主机生成器上调用 ConfigureServices 和 Configure 便捷方法。多次调用 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 筛选器扩展 StartupExtend Startup with startup filters

使用 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 中间件，请执行以下操作：

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

在启动时从外部程序集添加配置Add configuration at startup from an external assembly

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

其他资源Additional resources

• 主机
• 在 ASP.NET Core 中使用多个环境
• ASP.NET Core 中间件
• .NET Core 和 ASP.NET Core 中的日志记录
• ASP.NET Core 中的配置