AppBuildOptions 配置指南

AppBuildOptions/DefaultMvcApplicationOptions 是宿主应用最重要的配置对象。本文按属性分类说明常见场景。

基础属性

属性	说明
`BoostrapLogPath`	自定义启动日志输出目录，默认写入 `app_data/bootlog`。
`AspNetWebApplicationOptions`	透传给 `WebApplication.CreateBuilder` 的选项，如 `ApplicationName`、`Args`。
`BootstrapLoggerConfiguration`	追加 Serilog 配置，用于启动阶段（Host/DI 建立之前）。
`BootstrapLoggingLevelControl`	`LoggingLevelSwitch`，可在运行时动态调整启动日志级别。
`ActivityConfiguration`	Activity Id、Listener 配置。

构建阶段 Hook

Hook	触发时机	典型用途
`ConfigureWebApplicationBuilder` / `ConfigureWebApplicationBuilderAsync`	`WebApplicationBuilder` 创建后	注册自定义配置源、Serilog、Kestrel 端口等。
`ConfigureHostBuilder`	`HostBuilder` 阶段	替换容器（Autofac）、配置 Host 默认服务。
`ConfigureWebHostBuilder`	`webApplicationBuilder.WebHost`	配置 `UseUrls`、`UseKestrel`、`ConfigureAppConfiguration`。
`ConfigureServices`	Host `ConfigureServices` 阶段	注册业务服务、IHostedService、第三方库。
`ConfigureMvcOptions` / `ConfigureMvcBuilder`	MVC 构建过程中	调整 `MvcOptions`、添加过滤器/格式化器、开启 RazorRuntimeCompilation。
`ConfigureLoggingBuilder`	ASP.NET Core Logging Builder	扩展日志 Provider。
`ConfigureStartupInitServiceFunc` / `ConfigureStartupInitServiceAsync`	`ConfigureWebApplication` 中	启动后执行一次的初始化逻辑。

启动阶段配置顺序

启动阶段按源码顺序大致如下：

StartApplicationAsync 创建 AppBuildOptions，进入 AppBootstrapper.SafeStartAsync。
CreateHostPrepare 配置 Activity 默认行为。
CreateHostAsync 初始化 AppBuildContext，创建 WebApplicationBuilder。
执行 ConfigureWebApplicationBuilder / ConfigureWebApplicationBuilderAsync。
执行 ConfigureHostBuilder，其中包含 Autofac、Host、Logging、ConfigureServices 和自动发现服务注册。
执行 ConfigureWebHostBuilder，再调用 Build() 构建容器。
ConfigureWebApplication 初始化 RootServiceProvider、执行启动初始化服务、装配请求管道。
RunAsync 进入 ASP.NET Core 主循环。

配置放置建议：

要做什么	推荐位置
增加配置源、读取外部配置、调整 `WebApplicationBuilder`	`ConfigureWebApplicationBuilder`
配置 Host 默认服务、FeatureSwitch、容器替换	`ConfigureHostBuilder`
配置 Kestrel、监听地址、WebHost 行为	`ConfigureWebHostBuilder`
注册业务服务、第三方客户端、HostedService	`ConfigureServices`
调整 ASP.NET Core Logging Provider	`ConfigureLoggingBuilder`
调整 MVC 过滤器、Json、应用部件	`ConfigureMvcOptions` / `ConfigureMvcBuilder`
启动后预热缓存、初始化数据、启动一次性任务	`ConfigureStartupInitServiceFunc` / `ConfigureStartupInitServiceAsync`

启动失败或日志异常时，先按排查启动、日志与诊断问题的顺序定位。

自动发现与过滤

AutoDiscoverServiceRegisterTypeFilter：筛选实现 IServiceRegister、IAdvancedServiceRegister、ISingleton/IScoped/ITransient 的类型。
PipelineRegisterTypeFilter：控制 IRequestPiplineRegister 的加载范围。
EndpointRegisterTypeFilter：控制 IEndpointConfig 的加载范围。

过滤器通常用于多租户或插件场景，确保只有指定程序集参与自动注册。

FeatureSwitch

AppBuildContext.FeatureSwitch 用于控制框架底层能力开关，例如 ASP.NET Core 认证授权集成、Autofac 未注册类型解析、高级服务注册链等。它不是业务功能开关，不建议放项目自己的业务开关。

常见写法：

options.ConfigureHostBuilder += (IHostBuilder hostBuilder, AppBuildContext context) =>
{
    context.FeatureSwitch.IsIntegrateAspNetAuthentication = true;
};

完整清单与风险边界见应用功能开关。

线程池与容器

UseThreadPoolOptimization：启用后，会调用 ThreadPool.SetMinThreads(WorkThreadCount, CompletionPortThreadCount)。
UseAutofacContainer：默认 true，意味着框架会使用 AppServcieProviderFactory 替换默认容器。
UseSerilogProvider：默认为 true，可关闭以使用其他日志框架。

MVC Builder 创建

默认 DefaultMvcApplicationOptions 中：

MvcBuilderCreateFunc ??= (serviceCollection, action) => serviceCollection.AddControllers(action);

你可以在应用选项中覆盖该委托，例如：

public class IdsAppOptions : DefaultMvcApplicationOptions
{
    public IdsAppOptions()
    {
        MvcBuilderCreateFunc = (services, mvcOptions) => services.AddControllersWithViews(mvcOptions);
    }
}

启动服务与缓存

services.RegisterCache(appContext.Configuration);：默认注册 Redis/MemoryCache。
services.AddMemoryCache：设置 ExpirationScanFrequency 与 SizeLimit。

常见模式

多环境日志：通过 configure 参数或 LOG_MINI_LEVEL 环境变量调整输出。
按需启用 Hangfire：配合 JobControl.IsDisableJobs，在测试环境关闭后台任务。
自定义请求管道：使用 RequestPiplineCollection.Register 在 BeforeRouting / BeforeEndpointConfig 阶段插入中间件。

相关阅读：