如何排查ASP.NET Core应用抛出的未处理异常

以下日志是Kestrel检测到应用层抛出未捕获异常、请求连接异常终止时输出的通用提示，默认不携带具体异常堆栈和请求上下文：

Microsoft.AspNetCore.Server.Kestrel | Connection id "XXXXX", Request id "YYYY:0000": An unhandled exception was thrown by the application.

可通过以下方式定位根因：

一、直接定位异常根因的常用手段 #

• 开发环境使用开发者异常页：将部署环境变量ASPNETCORE_ENVIRONMENT设置为Development，并在HTTP管道最靠前的位置注册中间件app.UseDeveloperExceptionPage();，触发异常时会直接返回包含完整异常堆栈、路由信息、请求参数、Cookie和请求头的详细错误页，是本地复现场景下最快的定位方式。注意该配置绝对不能在生产环境开启，会泄露敏感业务信息和服务配置。
• 注册全局异常捕获中间件：生产环境可在HTTP管道最外层添加自定义异常拦截中间件，统一捕获所有请求管道内的未处理异常，同时记录异常对应的请求路径、方法、参数、用户标识等上下文信息，核心实现参考：

// 注意要放在所有其他中间件注册之前
app.Use(async (context, next) =>
{
    try
    {
        await next();
    }
    catch (Exception ex)
    {
        // 替换为项目实际使用的日志组件写入逻辑
        logger.LogError(ex, "请求处理异常，路径：{RequestPath}，方法：{RequestMethod}", 
            context.Request.Path, context.Request.Method);
        context.Response.StatusCode = StatusCodes.Status500InternalServerError;
        // 按项目接口规范返回错误响应
        await context.Response.WriteAsJsonAsync(new { code = 500, message = "服务内部错误" });
    }
});

• 调试器附加捕获：本地复现问题时，用Visual Studio/Rider附加到运行的dotnet进程，开启CLR异常"抛出时中断"配置（无需勾选"仅我的代码"），触发异常时调试器会直接定位到异常抛出的代码行，可实时查看调用栈、局部变量值等上下文。
• 生产环境Dump分析：生产环境无法直接调试时，在异常复现的时间点用dotnet-dump collect或者任务管理器抓取对应dotnet进程的完整内存转储，导入dotnet-dump、Visual Studio或WinDbg即可提取异常对象的完整堆栈和内存上下文。
• 游离异常补充捕获：如果异常来自未await的异步任务、后台执行的线程逻辑，不会经过HTTP请求管道，需要额外注册两个全局事件捕获这类游离异常：

// 捕获未被观察的Task异常
TaskScheduler.UnobservedTaskException += (sender, e) =>
{
    logger.LogError(e.Exception, "未捕获Task异常");
    e.SetObserved();
};
// 捕获应用域级别的未处理异常
AppDomain.CurrentDomain.UnhandledException += (sender, e) =>
{
    logger.LogError(e.ExceptionObject as Exception, "应用域未处理异常");
};

二、辅助排查的日志配置调整 #

• 提升框架日志输出级别：默认配置下ASP.NET Core框架日志级别为Warning，部分异常细节不会输出，可在appsettings.json中调整日志配置，开启框架层的Debug级别日志：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Debug",
      "Microsoft.AspNetCore.Server.Kestrel": "Debug",
      "Microsoft.Extensions.Hosting": "Information"
    }
  }
}

• 开启宿主基础日志：Windows部署场景（IIS/Windows Service）可查看系统事件查看器的应用程序日志，.NET Runtime会默认记录所有未处理异常的完整堆栈；Linux部署场景可开启服务的stdout/stderr重定向，未被日志组件捕获的异常默认会输出到标准错误流。
• IIS部署开启失败请求跟踪：IIS托管场景可开启Failed Request Tracing（失败请求跟踪）模块，针对500状态码的请求生成全流程跟踪日志，可定位请求在IIS模块、托管管道中的异常位置。

内容的提问来源于stack exchange，提问作者Steve