practical-aspnetcore 实战:使用 WebApplication 响应应用生命周期事件(Application Lifetime Events)

原创2026-10-14 19:26:441,817 阅读
文章标签:示例工程

practical-aspnetcore 实战:使用 WebApplication 响应应用生命周期事件(Application Lifetime Events)

本文基于 practical-aspnetcore 仓库中的 web-application-lifetime-events 示例,讲解如何使用全新的 WebApplication 极简托管类响应 ASP.NET Core 的应用程序生命周期事件。读完本文,你将掌握 ApplicationStarted、ApplicationStopping、ApplicationStopped 三个事件的含义与注册方式,学会借助 app.Lifetime 与 app.Logger 在应用启动与关闭时执行初始化、清理和日志记录,并了解这些事件在经典 Host 模型中的等价用法。

一、示例定位:Minimal Hosting 家族中的生命周期事件

在 practical-aspnetcore 仓库中,projects/minimal-hosting 目录收录了 25 个极简托管(Minimal Hosting)相关示例,而本示例 web-application-lifetime-events 属于其中的「WebApplication」示例组。该组的特点是在不引入 WebApplication.CreateBuilder() 的前提下,直接使用 WebApplication.Create() 的默认配置完成常见任务——除了生命周期事件,还包括欢迎页、默认日志、中间件、中间件管道、URL 与端口配置等,详见 minimal-hosting 总览。

本示例的核心意图非常明确:学习如何响应 WebApplication 提供的应用生命周期事件。当应用启动、正在停止、已停止时,分别触发对应的回调,从而让开发者有机会在正确的时机挂载自己的逻辑。

二、原理解析:IHostApplicationLifetime 与三个生命周期事件

ASP.NET Core 应用的托管模型建立在通用主机(Generic Host)之上,而生命周期能力由 IHostApplicationLifetime 接口提供。该接口暴露了三个 CancellationToken 与三个对应的事件注册方法:

事件 触发时机 典型用途
ApplicationStarted 应用完成启动、开始处理请求时触发 初始化数据库连接、预热缓存、启动后台任务
ApplicationStopping 应用正在关闭、开始优雅停机时触发 停止接收新请求、等待进行中的请求完成、释放资源
ApplicationStopped 应用已完全停止后触发 输出最终清理日志、收尾工作

在经典的 WebApplicationBuilder/HostBuilder 模型中,通常通过依赖注入获取 IHostApplicationLifetime 并调用 Register() 注册回调;而在本示例使用的 WebApplication 极简托管类中,app.Lifetime 属性直接暴露了 IHostApplicationLifetime,无需任何额外配置即可使用。

注:原文档给出了 WebApplication 与 WebApplicationBuilder 的实现源码链接(位于 dotnet/aspnetcore 仓库的 src/DefaultBuilder 目录)。由于仓库为只读镜像,读者可在本地通过 git clone 该仓库后自行查阅相关实现,或直接依据本文示例代码理解其行为。

三、核心代码逐行解读

本示例的完整代码位于 Program.cs,整个文件仅 27 行,展示了极简托管模型的全部关键点:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

var app = WebApplication.Create();
app.Run(async (context) =>
{
    await context.Response.WriteAsync("Check the log to see when the log messages displayed in response to application lifetime event");
});

app.Lifetime.ApplicationStarted.Register(() =>
{
    app.Logger.LogWarning("Application started");
});

app.Lifetime.ApplicationStopping.Register(() =>
{
    app.Logger.LogWarning("Application stopping");
});


app.Lifetime.ApplicationStopped.Register(() =>
{
    app.Logger.LogWarning("Application stopped");
});

await app.RunAsync();

3.1 WebApplication.Create():免配置的极简入口

WebApplication.Create() 是 WebApplication 类的静态工厂方法,与 WebApplication.CreateBuilder() 的区别在于:它直接返回一个已经配置好默认行为的 WebApplication 实例,不需要经过 Builder 构建阶段。官方文档与仓库中的其他示例(如 web-application-logging、web-application-server-default-urls)都展示了这一模式——适合在默认配置足够、无需自定义服务注册时使用。

3.2 app.Run(...):注册请求处理管道

app.Run(async (context) =>
{
    await context.Response.WriteAsync("Check the log to see when the log messages displayed in response to application lifetime event");
});

这里注册了一个简单的请求处理终端,任何请求都会返回一段提示文字,引导读者去查看控制台日志来确认生命周期事件的输出。注意:这段响应正文本身就是验证手段——它提示你「去查看日志,看看生命周期事件触发的日志消息」。

3.3 app.Lifetime:直接访问生命周期事件

app.Lifetime 是 WebApplication 暴露的 IHostApplicationLifetime 属性。三个事件分别通过 Register() 方法挂载回调:

  • ApplicationStarted.Register(() => { ... }) —— 应用启动完成后执行;
  • ApplicationStopping.Register(() => { ... }) —— 应用开始关闭时执行;
  • ApplicationStopped.Register(() => { ... }) —— 应用完全停止后执行。

Register() 接收一个 Action 委托,示例中传入的是 lambda 表达式。多个回调可以重复注册,它们会按注册顺序依次执行,因此你可以在不同位置、不同模块中分别注册自己的初始化与清理逻辑。

3.4 app.Logger:立即可用的默认日志器

回调内部统一使用 app.Logger.LogWarning(...) 输出日志。WebApplication.Logger 是 ILogger 实例,无需任何额外配置即可直接使用——这一点在配套示例 web-application-logging 中有明确说明:默认 logger 立即可用,但注意它默认并不通过 DI 容器提供(app.Services.GetService<ILogger>() 会返回 null,见该示例的 Program.cs)。

示例选择 LogWarning 级别而非 LogInformation,是为了让生命周期消息在默认日志配置下更醒目——默认配置通常只显示 Information 及以上级别,而 Warning 级别会明确突出启动/停止的关键节点。

3.5 await app.RunAsync():启动并等待关闭

RunAsync() 是 WebApplication 的启动方法:它启动 Kestrel 服务器、触发 ApplicationStarted,然后阻塞等待应用被关闭(如收到 Ctrl+C、SIGTERM 或调用 StopAsync),关闭过程中依次触发 ApplicationStopping 与 ApplicationStopped。

四、运行与验证

4.1 工程配置

项目文件 web-application-lifetime-events.csproj 极为精简:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>
</Project>

采用 Microsoft.NET.Sdk.Web SDK,目标框架为 net10.0,并启用了 ImplicitUsings(因此 Microsoft.AspNetCore.Builder、Microsoft.Extensions.Logging 等命名空间可自动引入,不过示例仍显式写出了 using 以便阅读)。仓库根目录的 global.json 指定了 .NET SDK 10.0.0(rollForward: major、允许预发布版),运行前请确保本机安装有匹配的 SDK。

4.2 运行步骤

# 在项目目录下执行
dotnet run

启动后,浏览器访问默认地址(通常是 http://localhost:5000 或 http://localhost:5001,取决于 HTTPS 重定向配置),页面会返回:

Check the log to see when the log messages displayed in response to application lifetime event

同时在控制台看到:

warn: ... Application started

此时在终端按 Ctrl+C(或向进程发送停止信号)触发优雅关闭,控制台会依次输出:

warn: ... Application stopping
warn: ... Application stopped

三条日志的输出顺序与事件触发顺序完全一致:started → stopping → stopped,读者可以据此直观验证事件的生命周期时序。

五、纵深对比:仓库中的两种等价实现

5.1 通过 DI 获取 IHostApplicationLifetime(极简托管版)

仓库中的另一个独立项目 i-application-lifetime 展示了在 WebApplication.Create() 模型下的第二种写法——不直接使用 app.Lifetime,而是从服务容器中取出 IHostApplicationLifetime:

var app = WebApplication.Create();

var lifetime = app.Services.GetService<IHostApplicationLifetime>();
lifetime.ApplicationStarted.Register(() => System.Console.WriteLine("===== Server is starting"));
lifetime.ApplicationStopping.Register(() => System.Console.WriteLine("===== Server is stopping"));
lifetime.ApplicationStopped.Register(() => System.Console.WriteLine("===== Server has stopped"));

app.Run(async context =>
{
    await context.Response.WriteAsync("Hello world");
});

app.Run();

这段代码与本示例形成互补:本示例用 app.Lifetime 直接访问并借助 app.Logger 写日志,而 i-application-lifetime 项目则演示了「从 DI 解析 IHostApplicationLifetime + 用 Console.WriteLine 输出」的等价路径。两者实现的效果一致,读者可以根据自己的习惯选择。

5.2 在 HostedService 中订阅生命周期(经典主机版)

如果你使用的是经典 HostBuilder 模型,则通常将生命周期订阅放在 IHostedService 内部,通过构造函数注入 IHostApplicationLifetime。仓库中的 generic-host-ihostapplicationlifetime 正是这种模式的代表:

await new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        services.AddHostedService<HelloWorldService>();
    })
    .ConfigureLogging(logging =>
    {
        logging.ClearProviders();
        logging.AddConsole();
        logging.AddFilter((provider, category, logLevel) =>
        {
            return !category.Contains("Microsoft");
        });
    })
    .Build().RunAsync();

其 HelloWorldService 在构造函数中接收 IHostApplicationLifetime lifetime 与 ILogger<HelloWorldService> logger,并在构造函数里完成三个事件的注册:

_lifetime.ApplicationStarted.Register(OnStarted);
_lifetime.ApplicationStopping.Register(OnStopping);
_lifetime.ApplicationStopped.Register(OnStopped);

对比可见:无论采用 WebApplication.Create()、WebApplicationBuilder 还是 HostBuilder,生命周期事件的机制完全一致,只是获取 IHostApplicationLifetime 的方式不同(属性直取 / DI 解析 / 构造函数注入)。WebApplication 的价值在于把这种能力以最少的样板代码暴露出来。

六、最佳实践与注意事项

结合仓库示例与事件语义,归纳出以下几点实践建议:

  1. 启动逻辑放 ApplicationStarted,而非 StartAsync 之前:ApplicationStarted 在应用真正可以对外服务时才触发,适合做数据库迁移、缓存预热、健康检查初始化等工作;过早执行可能导致请求到达时资源尚未就绪。
  2. 关闭逻辑放 ApplicationStopping:该事件在优雅停机开始时触发,此时应停止接收新任务、保存状态、释放非托管资源;ApplicationStopped 则适合做最终日志与收尾,此时服务器已完全停止。
  3. 回调应尽量短小、可重入:Register() 注册的回调在主机内部按顺序同步执行,阻塞或抛出未捕获异常会影响主机的启动/停止流程,建议把耗时操作移入后台任务并用 CancellationToken 配合。
  4. 日志级别选择:本示例用 LogWarning 突出关键节点;在实际项目中,常规运行信息可用 LogInformation,异常情况才用 LogWarning/LogError,保持日志可读性。
  5. WebApplication.Create() 的适用边界:它适合默认配置足够、无需自定义 DI 注册的场景(本示例即如此);一旦需要配置服务、中间件顺序或日志级别,应改用 WebApplication.CreateBuilder()——参见 minimal-hosting 总览 中 Builder 一组示例(如 web-application-builder-logging-set-minimum-level)。

七、小结

通过本示例可以确认:WebApplication 极简托管类将应用生命周期事件以 app.Lifetime 属性的形式开箱即用,配合立即可用的 app.Logger,短短几行代码即可完成启动/停止关键节点的日志与业务钩子。这套机制与经典 Host 模型中的 IHostApplicationLifetime 完全同源,掌握了它,就掌握了 ASP.NET Core 应用从启动到优雅关闭的完整生命周期脉络。

后续可以继续阅读 minimal-hosting 目录下的其他示例(欢迎页、默认日志、中间件管道、URL 配置等),或对照 generic-host 与 i-application-lifetime 两个项目,系统性地理解极简托管与经典托管两种模型下的应用生命周期管理。

登录后查看全文
practical-aspnetcore