agilelabs-fx-docs main fundamentals/agilelabs-application/overview.md

AgileLabApplication 运行原理

AgileLabApplication 是框架的宿主入口，它封装了 ASP.NET Core WebApplicationBuilder / HostBuilder 的创建、配置与运行逻辑。理解该流程是掌握 AgileLabs Framework 的关键。

启动流程

using AgileLabs.WebApp;
using AgileLabs.WebApp.Hosting;

await AgileLabApplication.StartApplicationAsync<DefaultMvcApplicationOptions>(options =>
{
    options.MvcBuilderCreateFunc = (services, mvcOptions) => services.AddControllersWithViews(mvcOptions);
});

流程拆解：

  1. StartApplicationAsync：实例化 TAppOptions（默认 AppBuildOptions），执行调用者提供的委托。
  2. SafeStartAsync：AppBootstrapper 创建引导日志（Bootstrap Logger），并在 Activity 中记录“Application Booting...”。
  3. CreateHostPrepare：根据 ActivityConfiguration 配置默认 Activity Listener，可在分布式调用链中观测到 TraceId/SpanId。
  4. CreateHostAsync：
    • 初始化 AppBuildContext，持有 BootstrapLogger、TypeFinder、HostEnvironment。
    • 调用 ConfigureWebApplicationBuilder / ConfigureWebHostBuilder 注入自定义逻辑。
    • 构建 WebApplication，随后调用 ConfigureWebApplication 注册请求管道与启动服务。
  5. RunAsync：进入 ASP.NET Core 主循环，直至服务被终止。

AppBuildContext 与 Singleton 组件

  • Singleton<AppBuildOptions>.Instance：全局保存当前应用配置，供框架其他组件（例如自动注册器）读取。
  • Singleton<AppBuildContext>.Instance：存储宿主环境、配置、TypeFinder、BootstrapLogger 等对象。
  • AgileLabContexts.CreateAppContext(...)：初始化全局 AgileLabContext，后续 WorkContext、Scope 管理均依赖该实例。

由于 Singleton<T> 是线程安全的全局容器，建议仅在框架内部使用。业务代码应通过 DI 获取所需服务。

AgileLabContext.ConfigureRequestPipeline

AppBuildOptions 允许定义 PipelineRegisterTypeFilter、EndpointRegisterTypeFilter。框架会自动扫描实现 IRequestPiplineRegister / IEndpointConfig 的类型并执行：

  1. 按 RequestPipelineStage 排序：BeginOfPipeline → BeforeRouting → BeforeEndpointConfig → AfterEndpointConfig。
  2. 执行注册顺序：RequestPiplineCollection.Register 支持自定义名称与阶段内顺序（stageOrder）。
  3. Endpoint 注册：IEndpointConfig.ConfigureEndpoints 中调用 endpoints.MapControllers()、MapHangfireDashboard() 等。

CallStartupInitServiceAsync

在 ConfigureWebApplication 中，框架会创建一个带 WorkContext 的 IServiceScope，按顺序执行：

  1. 框架级 StartupInit Service（调用 AgileLabContext.CallFrameworkStartupInitServiceAsync）。
  2. 应用注入的 ConfigureStartupInitServiceFunc / ConfigureStartupInitServiceAsync。

该阶段适合进行一次性初始化，例如预热缓存、执行数据迁移、注册后台任务等。

日志与 Activity

  • AppBootstrapper.Logger：在宿主启动期间输出关键信息（应用名称、环境、ContentRoot、WebRoot）。
  • LoggingLevelControl.LevelSwitch：通过 AppBuildOptions.BootstrapLoggingLevelControl 控制启动阶段日志级别。
  • ActivityConfiguration：默认使用 W3C IdFormat，并可通过正则筛选需要监听的 Activity Source。配合 ActivitySource.AddActivityListener 可以把事件输出到 OpenTelemetry、APM 等系统。

下一步：