对 Azure 应用服务和 IIS 上的 ASP.NET Core 进行故障排除Troubleshoot ASP.NET Core on Azure App Service and IIS

本文内容

作者：Justin Kotalik

本文提供了有关常见应用启动错误的信息，以及在将应用部署到 Azure 应用服务或 IIS 时如何诊断错误的说明：

应用启动错误介绍常见的启动 HTTP 状态代码方案。

排查 Azure 应用服务中的问题为部署到 Azure 应用服务的应用提供疑难解答建议。

IIS 疑难解答为部署到 IIS 或在本地 IIS Express 上运行的应用提供疑难解答建议。本指南适用于 Windows Server 和 Windows 桌面部署。

清除包缓存说明当执行重大升级或更改包版本时，不一致的包中断应用时应如何处理。

其他资源列出其他疑难解答主题。

应用启动错误App startup errors

在 Visual Studio 中，ASP.NET Core 项目默认为在调试期间进行 IIS Express 托管。本地调试时出现的“502.5 - 进程失败”或“500.30 - 启动失败”可以使用本主题中的建议进行诊断 。

403.14 禁止403.14 Forbidden

应用无法启动。记录以下错误：

The Web server is configured to not list the contents of this directory.

此错误通常是由于托管系统上的部署中断引起的，包括以下任何情况：

• 该应用部署到托管系统上的错误文件夹。
• 部署过程未能将所有应用的文件和文件夹移到托管系统上的部署文件夹中。
• 部署中缺少 web.config 文件，或者 web.config 文件内容格式不正确 。

执行以下步骤：

• 从托管系统上的部署文件夹中删除所有文件和文件夹。
• 使用常规部署方法（如 Visual Studio、PowerShell 或手动部署）将应用“发布”文件夹的内容重新部署到托管系统 ：
  • 确认部署中存在 web.config 文件，并且其内容正确 。
  • 在 Azure 应用服务上托管时，请确认该应用已部署到 D:\home\site\wwwroot 文件夹。
  • 当应用由 IIS 托管时，请确认应用已部署到“IIS 管理器”的“基本设置”中显示的 IIS 物理路径 。
• 通过将托管系统上的部署与项目“发布”文件夹的内容进行比较，确认已部署应用的所有文件和文件夹 。
  有关已发布 ASP.NET Core 应用布局的详细信息，请参阅 ASP.NET Core 目录结构。有关 web.config 文件的详细信息，请参阅 ASP.NET Core 模块 。

500 内部服务器错误500 Internal Server Error

应用启动，但某个错误阻止了服务器完成请求。

在启动期间或在创建响应时，应用的代码内出现此错误。响应可能不包含任何内容，或响应可能会在浏览器中显示为“500 内部服务器错误” 。应用程序事件日志通常表明应用正常启动。从服务器的角度来看，这是正确的。应用已启动，但无法生成有效的响应。在服务器上的命令提示符下运行应用，或启用 ASP.NET Core 模块 stdout 日志来解决问题。

500.0 进程内处理程序加载失败500.0 In-Process Handler Load Failure

工作进程失败。应用不启动。

加载 ASP.NET Core 模块组件时出现未知错误。请执行以下一项操作：

• 联系 Microsoft 支持部门（依次选择“开发人员工具”和“ASP.NET Core”） 。
• 在 Stack Overflow 上提出问题。
• 在 GitHub 存储库中提出问题。

500.30 进程内启动失败500.30 In-Process Startup Failure

工作进程失败。应用不启动。

ASP.NET Core 模块尝试进程内启动 .NET Core CLR，但启动失败。进程启动失败的原因通常可通过“应用程序事件日志”和“ASP.NET Core 模块 stdout 日志”中的条目进行确定。

常见失败情况：

• 由于目标 ASP.NET Core 共享框架版本不存在，因此应用配置错误。检查目标计算机上安装的 ASP.NET Core 共享框架版本。
• 使用 Azure Key Vault 时，缺少对 Key Vault 的权限。检查目标 Key Vault 中的访问策略，确保授予了正确的权限。

500.31 ANCM 找不到本机依赖项500.31 ANCM Failed to Find Native Dependencies

工作进程失败。应用不启动。

ASP.NET Core 模块尝试进程内启动 .NET Core 运行时，但启动失败。此类启动失败的最常见原因是未安装 Microsoft.NETCore.App 或 Microsoft.AspNetCore.App运行时。如果将应用部署为面向 ASP.NET Core 3.0，并且计算机上不存在该版本，则会发生此错误。示例错误消息如下所示：

The specified framework 'Microsoft.NETCore.App', version '3.0.0' was not found.
  - The following frameworks were found:
      2.2.1 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
      3.0.0-preview5-27626-15 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
      3.0.0-preview6-27713-13 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
      3.0.0-preview6-27714-15 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]
      3.0.0-preview6-27723-08 at [C:\Program Files\dotnet\x64\shared\Microsoft.NETCore.App]

错误消息列出了所有已安装的 .NET Core 版本以及应用请求的版本。请通过以下一种方法修复此错误：

• 在计算机上安装适当版本的 .NET Core。
• 更改应用，使其面向计算机上已存在的 .NET Core 版本。
• 将应用作为独立部署进行发布。

在开发过程（ASPNETCORE_ENVIRONMENT 环境变量设置为 Development）中运行时，HTTP 响应中会写入特定的错误。进程启动失败的原因也可在“应用程序事件日志”中找到。

500.32 ANCM 无法加载 dll500.32 ANCM Failed to Load dll

工作进程失败。应用不启动。

此错误的最常见原因是针对不兼容的处理器体系结构发布了应用。如果工作进程作为 32 位应用运行，而将应用发布为面向 64 位，则会发生此错误。

请通过以下一种方法修复此错误：

• 针对同一处理器体系结构将应用作为工作进程进行重新发布。
• 将应用作为依赖框架的部署进行发布。

500.33 ANCM 请求处理程序加载失败500.33 ANCM Request Handler Load Failure

工作进程失败。应用不启动。

应用未引用 Microsoft.AspNetCore.App 框架。ASP.NET Core 模块只能托管面向 Microsoft.AspNetCore.App 框架的应用。

要修复此错误，请确保应用面向 Microsoft.AspNetCore.App 框架。检查 .runtimeconfig.json 以验证该应用所面向的框架。

500.34 ANCM 混合托管模型不受支持500.34 ANCM Mixed Hosting Models Not Supported

工作进程不能在同一进程中同时运行进程内应用和进程外应用。

要修复此错误，请在单独的 IIS 应用程序池中运行应用。

500.35 ANCM 同一进程内有多个进程内应用程序500.35 ANCM Multiple In-Process Applications in same Process

工作进程不能在同一进程中运行多个进程内应用。

要修复此错误，请在单独的 IIS 应用程序池中运行应用。

500.36 ANCM 进程外处理程序加载失败500.36 ANCM Out-Of-Process Handler Load Failure

进程外请求处理程序 aspnetcorev2_outofprocess.dll 未与 aspnetcorev2.dll 文件相邻 。这表示 ASP.NET Core 模块的安装已损坏。

要修复此错误，请修复 .NET Core 托管捆绑包（对于 IIS）或 Visual Studio（对于 IIS Express）的安装。

500.37 ANCM 无法在启动时间限制内启动500.37 ANCM Failed to Start Within Startup Time Limit

ANCM 无法在提供的启动时间限制内启动。默认情况下，超时时间为 120 秒。

在同一台计算机上启动大量应用时，则可能发生此错误。在启动期间检查服务器上的 CPU/内存使用峰值。可能需要交错执行多个应用程序的启动进程。

502.5 进程失败502.5 Process Failure

工作进程失败。应用不启动。

ASP.NET Core 模块尝试启动工作进程，但启动失败。进程启动失败的原因通常可通过“应用程序事件日志”和“ASP.NET Core 模块 stdout 日志”中的条目进行确定。

常见的失败情况是，由于目标 ASP.NET Core 共享框架版本不存在，因此应用配置错误。检查目标计算机上安装的 ASP.NET Core 共享框架版本。 共享框架是安装在计算机上并由 Microsoft.AspNetCore.App 等元包引用的一组程序集（.dll 文件）。元包引用可以指定所需的最低版本。有关详细信息，请参阅共享框架。

托管或应用配置错误导致工作进程失败时，将返回“502.5 进程失败” 错误页面：

未能启动应用程序（错误代码“0x800700c1”）Failed to start application (ErrorCode '0x800700c1')

EventID: 1010
Source: IIS AspNetCore Module V2
Failed to start application '/LM/W3SVC/6/ROOT/', ErrorCode '0x800700c1'.

应用未能启动，因为应用的程序集 (.dll ) 无法加载。

当已发布的应用与 w3wp/iisexpress 进程之间的位数不匹配时，会出现此错误。

确认应用池的 32 位设置正确：

• 在 IIS 管理器的“应用程序池” 中选择应用池。
• 在“操作” 面板中的“编辑应用程序池” 下选择“高级设置” 。
• 设置“启用 32 位应用程序” ：
  • 如果部署 32 位 (x86) 应用，则将值设置为 True。
  • 如果部署 64 位 (x64) 应用，则将值设置为 False。
    确认项目文件中的 <Platform> MSBuild 属性与应用的已发布位数之间没有冲突。

连接重置Connection reset

如果在发送标头后出现错误，则服务器在出现错误时发送“500 内部服务器错误” 已经太晚了。通常在序列化响应的复杂对象期间出现错误时发生这种情况。此类型的错误在客户端上显示为“连接重置” 错误。应用程序日志记录可以帮助解决这些类型的错误。

默认启动限制Default startup limits

ASP.NET Core 模块的默认“startupTimeLimit”配置为 120 秒 。保留默认值时，在模块记录进程故障之前，可能最多需要两分钟来启动应用。有关配置模块的信息，请参阅 aspNetCore 元素的属性。

排查 Azure 应用服务中的问题Troubleshoot on Azure App Service

重要

Azure 应用服务中的 ASP.NET Core 预览版

默认情况下不会将 ASP.NET Core 预览版部署到 Azure 应用服务。要托管使用 ASP.NET Core 预览版的应用，请参阅将 ASP.NET Core 预览版部署到 Azure 应用服务。

应用程序事件日志（Azure 应用服务）Application Event Log (Azure App Service)

若要访问应用程序事件日志，请在 Azure 门户中使用“诊断并解决问题”边栏选项卡 ：

• 在 Azure 门户中打开“应用服务”中的应用 。
• 选择“诊断并解决问题” 。
• 选择“诊断工具”标题 。
• 在“支持工具”下，选择“应用程序事件”按钮 。

• 检查“源”列中由 IIS AspNetCoreModule 或 IIS AspNetCoreModule V2条目提供的最新错误 。
  使用“诊断并解决问题” 边栏选项卡的替代方法是直接使用 Kudu 检查应用程序事件日志文件：

• 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。

• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 打开 LogFiles 文件夹。
• 选择 eventlog.xml 文件旁边的铅笔图标。
• 检查日志。滚动到日志底部以查看最新事件。

在 Kudu 控制台中运行应用Run the app in the Kudu console

许多启动错误未在应用程序事件日志中生成有用信息。可以在 Kudu 远程执行控制台中运行应用以发现错误：

• 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。

测试 32 位 (x86) 应用Test a 32-bit (x86) app

当前版本

• cd d:\home\site\wwwroot
• 运行应用：
  • 如果应用是依赖框架的部署：

dotnet .\{ASSEMBLY NAME}.dll

• 如果应用是独立部署：

{ASSEMBLY NAME}.exe

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

在预览版上运行的依赖框架的部署

必须安装 ASP.NET Core {VERSION} (x86) 运行时站点扩展。

• cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32（{X.Y} 是运行时版本）
• 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
  来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

测试 64 位 (x64) 应用Test a 64-bit (x64) app

当前版本

• 如果应用是 64 位 (x64) 依赖框架的部署：
  • cd D:\Program Files\dotnet
  • 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
• 如果应用是独立部署：
  • cd D:\home\site\wwwroot
  • 运行应用：{ASSEMBLY NAME}.exe

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

在预览版上运行的依赖框架的部署

必须安装 ASP.NET Core {VERSION} (x64) 运行时站点扩展。

• cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64（{X.Y} 是运行时版本）
• 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
  来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

ASP.NET Core 模块 stdout 日志（Azure 应用服务）ASP.NET Core Module stdout log (Azure App Service)

ASP.NET Core 模块 stdout 日志通常记录应用程序事件日志中找不到的有用错误消息。若要启用和查看 stdout 日志，请执行以下操作：

• 在 Azure 门户中导航到“诊断并解决问题” 边栏选项卡。
• 在“选择问题类别” 下，选择“Web 应用关闭” 按钮。
• 在“建议的解决方案”>“启用 Stdout 日志重定向”下，选择“打开 Kudu 控制台以编辑 Web.Config”对应的按钮 。
• 在 Kudu 诊断控制台 中，打开路径“站点 > wwwroot ”下的文件夹。向下滚动以在列表底部显示“web.config” 文件。
• 单击“web.config” 文件旁边的铅笔图标。
• 将“stdoutLogEnabled” 设置为 true，并将“stdoutLogFile” 路径更改为 \?\%home%\LogFiles\stdout。
• 选择“保存” 以保存已更新的 web.config 文件。
• 向应用发出请求。
• 返回到 Azure 门户。选择“开发工具” 区域中的“高级工具” 边栏选项卡。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 选择“LogFiles” 文件夹。
• 检查“已修改” 列并选择铅笔图标以编辑具有最新修改日期的 stdout 日志。

• 打开日志文件后，将显示错误。
  故障排除完成后，禁用 stdout 日志记录：

• 在 Kudu 诊断控制台 中，返回到路径“site > wwwroot ”以显示 web.config 文件。通过选择铅笔图标再次打开 web.config 文件。

• 将“stdoutLogEnabled” 设置为 false。
• 选择“保存” 以保存文件。
  有关详细信息，请参阅 ASP.NET Core 模块。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。仅使用 stdout 日志记录来解决应用启动问题。

对于在 ASP.NET Core 应用启动后生成的常规日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

ASP.NET Core 模块调试日志（Azure 应用服务）ASP.NET Core Module debug log (Azure App Service)

ASP.NET Core 模块调试日志从 ASP.NET Core 模块提供了更多、更详细的日志记录。若要启用和查看 stdout 日志，请执行以下操作：

• 要启用增强的诊断日志，请执行以下任一操作：
  • 按照增强的诊断日志中的说明配置应用以获取增强的诊断日志记录。重新部署应用。
  • 使用 Kudu 控制台将增强的诊断日志中显示的 <handlerSettings> 添加到动态应用的 web.config 文件中 ：
    • 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
    • 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
    • 打开路径“site > wwwroot ”下的文件夹。通过选择铅笔按钮编辑 web.config 文件 。添加 <handlerSettings> 部分（如增强的诊断日志中所示）。选择“保存”按钮 。
• 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 打开路径“site > wwwroot ”下的文件夹。如果没有为 aspnetcore-debug.log 文件提供路径，则该文件将显示在列表中 。如果提供了路径，请导航到日志文件的位置。
• 使用文件名旁边的铅笔按钮打开日志文件。
  故障排除完成后，禁用调试日志记录：

要禁用增强的调试日志，请执行以下任一操作：

• 从本地删除 web.config 文件中的 <handlerSettings> 并重新部署该应用 。
• 使用 Kudu 控制台编辑 web.config 文件并删除 <handlerSettings> 部分 。保存该文件。

有关详细信息，请参阅 ASP.NET Core 模块。

警告

无法禁用调试日志可能会导致应用或服务器出现故障。日志文件大小没有任何限制。仅使用调试日志记录来解决应用启动问题。

对于在 ASP.NET Core 应用启动后生成的常规日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

应用缓慢或挂起（Azure 应用服务）Slow or hanging app (Azure App Service)

如果应用程序响应缓慢或在有请求时挂起，请参阅以下文章：

• 解决 Azure 应用服务中 Web 应用性能缓慢的问题
• 使用故障诊断程序站点扩展来捕获 Azure Web 应用程序上间歇性异常问题或性能问题的转储

监视边栏选项卡Monitoring blades

监视边栏选项卡提供了本主题前面所述的方法的替代故障排除体验。这些边栏选项卡可用于诊断 500 系列错误。

确认是否已安装 ASP.NET Core 扩展。如果未安装扩展，请手动进行安装：

• 在“开发工具” 边栏选项卡部分中，选择“扩展” 边栏选项卡。
• “ASP.NET Core 扩展” 应显示在列表中。
• 如果未安装扩展，请选择“添加” 按钮。
• 从列表中选择“ASP.NET Core 扩展” 。
• 选择“确定” 以接受法律条款。
• 选择“添加扩展” 边栏选项卡上的“确定” 。

• 信息性弹出消息指示成功安装扩展的时间。
  如果未启用 stdout 日志记录，请执行以下步骤：

• 在 Azure 门户中，选择“开发工具” 区域中的“高级工具” 边栏选项卡。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。

• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 打开路径“site>wwwroot”下的文件夹，然后向下滚动以显示列表底部的 web.config 文件 。
• 单击“web.config” 文件旁边的铅笔图标。
• 将“stdoutLogEnabled” 设置为 true，并将“stdoutLogFile” 路径更改为 \?\%home%\LogFiles\stdout。

• 选择“保存” 以保存已更新的 web.config 文件。
  继续激活诊断日志记录：

• 在 Azure 门户中，选择“诊断日志” 边栏选项卡。

• 选择“应用程序日志记录(文件系统)” 和“详细错误消息” 的“开” 开关。选择边栏选项卡顶部的“保存” 按钮。
• 若要包含失败请求跟踪（也称为失败请求事件缓冲 (FREB) 日志记录），请选择“失败请求跟踪” 的“开” 开关。
• 选择“日志流” 边栏选项卡，将在门户中的“诊断日志” 边栏选项卡下立即列出。
• 向应用发出请求。
• 在日志流数据中，指示了错误的原因。
  故障排除完成后，请务必禁用 stdout 日志记录。

若要查看失败请求跟踪日志（FREB 日志），请执行以下操作：

• 在 Azure 门户中导航到“诊断并解决问题” 边栏选项卡。
• 从侧栏的“支持工具” 区域中选择“失败请求跟踪日志” 。
  有关详细信息，请参阅“在 Azure 应用服务中启用 Web 应用的诊断日志记录”主题的“失败请求跟踪”部分和 Azure 中的 Web 应用的应用程序性能常见问题：如何打开失败请求跟踪？。

有关详细信息，请参阅在 Azure 应用服务中启用 Web 应用的诊断日志记录。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。

对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

IIS 疑难解答Troubleshoot on IIS

应用程序事件日志 (IIS)Application Event Log (IIS)

访问应用程序事件日志：

• 打开“开始”菜单，搜索“事件查看器” ，然后选择“事件查看器” 应用。
• 在“事件查看器” 中，打开“Windows 日志” 节点。
• 选择“应用程序” 以打开应用程序事件日志。
• 搜索与失败应用相关联的错误。错误具有“源” 列中“IIS AspNetCore 模块” 或“IIS Express AspNetCore 模块” 的值。

在命令提示符处运行应用Run the app at a command prompt

许多启动错误未在应用程序事件日志中生成有用信息。可以通过在托管系统上在命令提示符处运行应用来找到某些错误的原因。

依赖框架的部署Framework-dependent deployment

如果应用是依赖框架的部署：

• 在命令提示符处，导航到部署文件夹并通过使用 dotnet.exe 执行应用的程序集来运行应用。在以下命令中，替换 的应用程序集的名称：dotnet .\<assembly_name>.dll。
• 来自应用且显示任何错误的控制台输出将写入控制台窗口。
• 如果向应用发出请求时出现错误，请向 Kestrel 侦听所在的主机和端口发出请求。如果使用默认主机和端口，请向 http://localhost:5000/ 发出请求。如果应用在 Kestrel 终结点地址处正常响应，则问题更可能与承载配置相关，而不太可能在于应用。

独立部署Self-contained deployment

如果应用是独立部署：

• 在命令提示符处，导航到部署文件夹并运行应用的可执行文件。在以下命令中，替换 的应用程序集的名称：<assembly_name>.exe。
• 来自应用且显示任何错误的控制台输出将写入控制台窗口。
• 如果向应用发出请求时出现错误，请向 Kestrel 侦听所在的主机和端口发出请求。如果使用默认主机和端口，请向 http://localhost:5000/ 发出请求。如果应用在 Kestrel 终结点地址处正常响应，则问题更可能与承载配置相关，而不太可能在于应用。

ASP.NET Core 模块 stdout 日志 (IIS)ASP.NET Core Module stdout log (IIS)

若要启用和查看 stdout 日志，请执行以下操作：

• 在托管系统上导航到站点的部署文件夹。
• 如果 logs 文件夹不存在，请创建该文件夹。有关如何启用 MSBuild 以在部署中自动创建 logs 文件夹的说明，请参阅目录结构主题。
• 编辑 web.config 文件。将“stdoutLogEnabled” 设置为 true 并更改“stdoutLogFile” 路径以指向 logs 文件夹（例如，.\logs\stdout）。路径中的 stdout 是日志文件名的前缀。创建日志时，将自动添加时间戳、进程 ID 和文件扩展名。如果将 stdout 用作文件名的前缀，典型的日志文件将命名为“stdout_20180205184032_5412.log” 。
• 请确保应用程序池的标识具有对日志文件夹的写入权限 。
• 保存已更新的 web.config 文件。
• 向应用发出请求。
• 导航到 logs 文件夹。查找并打开最新的 stdout 日志。

• 研究日志以查找错误。
  故障排除完成后，禁用 stdout 日志记录：

• 编辑 web.config 文件。

• 将“stdoutLogEnabled” 设置为 false。
• 保存该文件。
  有关详细信息，请参阅 ASP.NET Core 模块。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。

对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

ASP.NET Core 模块调试日志 (IIS)ASP.NET Core Module debug log (IIS)

将以下处理程序设置添加到应用的 web.config 文件以启用 ASP.NET Core 模块调试日志 ：

<aspNetCore ...>
  <handlerSettings>
    <handlerSetting name="debugLevel" value="file" />
    <handlerSetting name="debugFile" value="c:\temp\ancm.log" />
  </handlerSettings>
</aspNetCore>

确认为日志指定的路径存在，并且应用池的标识具有该位置的写入权限。

有关详细信息，请参阅 ASP.NET Core 模块。

启用开发人员异常页面Enable the Developer Exception Page

ASPNETCORE_ENVIRONMENT 环境变量可以添加到 web.config 以在开发环境中运行应用。只要在应用启动时环境不被主机生成器上的 UseEnvironment 重写，设置环境变量就会在运行应用时显示“开发人员异常页面”。

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="InProcess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
  </environmentVariables>
</aspNetCore>

仅建议在未向 Internet 公开的暂存服务器和测试服务器上设置 ASPNETCORE_ENVIRONMENT 的环境变量。在故障排除后从 web.config 文件中删除环境变量。有关设置 web.config 中的环境变量的信息，请参阅 aspNetCore 的 environmentVariables 子元素。

从应用中获取数据Obtain data from an app

如果应用能够响应请求，则使用终端内联中间件从应用中获取请求、连接和其他数据。有关详细信息和示例代码，请参阅ASP.NET Core 项目故障排除和调试。

应用缓慢或挂起 (IIS)Slow or hanging app (IIS)

故障转储是系统内存的一个快照，可帮助确定应用崩溃、启动故障或应用速度缓慢等状况的原因 。

应用崩溃或引发异常App crashes or encounters an exception

从 Windows 错误报告 (WER) 中获取转储并进行分析：

• 创建文件夹，将崩溃转储文件保存在 c:\dumps。应用池必须对该文件夹具有写权限。

• 运行 EnableDumps PowerShell 脚本：

  • 如果应用使用进程内托管模型，则请为 w3wp.exe 运行脚本 ：

.\EnableDumps w3wp.exe c:\dumps

• 如果应用使用进程外托管模型，则请为 dotnet.exe 运行脚本 ：

.\EnableDumps dotnet.exe c:\dumps

• 在造成崩溃的条件下运行应用。

• 出现崩溃后，运行 DisableDumps PowerShell 脚本：

  • 如果应用使用进程内托管模型，则请为 w3wp.exe 运行脚本 ：

.\DisableDumps w3wp.exe

• 如果应用使用进程外托管模型，则请为 dotnet.exe 运行脚本 ：

.\DisableDumps dotnet.exe

在应用崩溃并完成转储收集后，即可正常终止应用。PowerShell 脚本会 WER 来按应用收集转储（最多收集 5 个）。

警告

崩溃转储可能会占用大量磁盘空间（每个最多占用数 GB）。

应用挂起、在启动期间失败或正常运行App hangs, fails during startup, or runs normally

如果应用挂起（停止响应但不崩溃）、在启动期间失败或者正常运行hangs，请参阅用户模式转储文件：选择最佳工具，以选择适合用于生成转储的工具。

分析转储Analyze the dump

可采用几种方法来分析转储。有关详细信息，请参阅分析用户模式转储文件。

清除包缓存Clear package caches

正常运行的应用在开发计算机上升级 .NET Core SDK 或在应用内更改包版本后可能会立即出现故障。在某些情况下，不同的包可能在执行主要升级时中断应用。可以按照以下说明来修复其中大部分问题：

• 删除 bin 和 obj 文件夹。

• 通过从命令行界面执行 dotnet nuget locals all —clear 清除包缓存。

清除包缓存还可通过使用 nuget.exe 工具并执行命令 nuget locals all -clear 来完成。nuget.exe 不是与 Windows 桌面操作系统的捆绑安装，必须从 NuGet 网站中单独获取。

• 还原并重新生成项目。

• 在重新部署应用前，在服务器上删除部署文件夹中的所有文件。

其他资源Additional resources

• ASP.NET Core 项目故障排除和调试
• Azure 应用服务和 IIS 上 ASP.NET Core 的常见错误参考
• 处理 ASP.NET Core 中的错误
• ASP.NET Core 模块

Azure 文档Azure documentation

• 用于 ASP.NET Core 的 Application Insights
• “使用 Visual Studio 对 Azure 应用服务中的 Web 应用进行故障排除”的“远程调试 Web 应用”一节
• Azure 应用服务诊断概述
• 如何：在 Azure 应用服务中监视应用
• 使用 Visual Studio 对 Azure 应用服务中的 Web 应用进行故障排除
• 解决 Azure Web 应用中的“502 错误的网关”和“503 服务不可用”HTTP 错误
• 解决 Azure 应用服务中 Web 应用性能缓慢的问题
• Azure 中的 Web 应用的应用程序性能常见问题
• Azure Web 应用沙盒（应用服务运行时执行限制）
• Azure Friday：Azure 应用服务诊断和疑难解答体验（12 分钟视频）

Visual Studio 文档Visual Studio documentation

• 在 Azure 中的 IIS 上的 Visual Studio 2017 中远程调试 ASP.NET Core
• 在远程 IIS 计算机的 Visual Studio 2017 中远程调试 ASP.NET Core
• 了解如何使用 Visual Studio 进行调试

Visual Studio Code 文档Visual Studio Code documentation

• 使用 Visual Studio Code 进行调试

本文提供了有关常见应用启动错误的信息，以及在将应用部署到 Azure 应用服务或 IIS 时如何诊断错误的说明：

应用启动错误介绍常见的启动 HTTP 状态代码方案。

排查 Azure 应用服务中的问题为部署到 Azure 应用服务的应用提供疑难解答建议。

IIS 疑难解答为部署到 IIS 或在本地 IIS Express 上运行的应用提供疑难解答建议。本指南适用于 Windows Server 和 Windows 桌面部署。

清除包缓存说明当执行重大升级或更改包版本时，不一致的包中断应用时应如何处理。

其他资源列出其他疑难解答主题。

应用启动错误App startup errors

在 Visual Studio 中，ASP.NET Core 项目默认为在调试期间进行 IIS Express 托管。本地调试时出现的“502.5 - 进程失败”或“500.30 - 启动失败”可以使用本主题中的建议进行诊断 。

403.14 禁止403.14 Forbidden

应用无法启动。记录以下错误：

The Web server is configured to not list the contents of this directory.

此错误通常是由于托管系统上的部署中断引起的，包括以下任何情况：

• 该应用部署到托管系统上的错误文件夹。
• 部署过程未能将所有应用的文件和文件夹移到托管系统上的部署文件夹中。
• 部署中缺少 web.config 文件，或者 web.config 文件内容格式不正确 。

执行以下步骤：

• 从托管系统上的部署文件夹中删除所有文件和文件夹。
• 使用常规部署方法（如 Visual Studio、PowerShell 或手动部署）将应用“发布”文件夹的内容重新部署到托管系统 ：
  • 确认部署中存在 web.config 文件，并且其内容正确 。
  • 在 Azure 应用服务上托管时，请确认该应用已部署到 D:\home\site\wwwroot 文件夹。
  • 当应用由 IIS 托管时，请确认应用已部署到“IIS 管理器”的“基本设置”中显示的 IIS 物理路径 。
• 通过将托管系统上的部署与项目“发布”文件夹的内容进行比较，确认已部署应用的所有文件和文件夹 。
  有关已发布 ASP.NET Core 应用布局的详细信息，请参阅 ASP.NET Core 目录结构。有关 web.config 文件的详细信息，请参阅 ASP.NET Core 模块 。

500 内部服务器错误500 Internal Server Error

应用启动，但某个错误阻止了服务器完成请求。

在启动期间或在创建响应时，应用的代码内出现此错误。响应可能不包含任何内容，或响应可能会在浏览器中显示为“500 内部服务器错误” 。应用程序事件日志通常表明应用正常启动。从服务器的角度来看，这是正确的。应用已启动，但无法生成有效的响应。在服务器上的命令提示符下运行应用，或启用 ASP.NET Core 模块 stdout 日志来解决问题。

500.0 进程内处理程序加载失败500.0 In-Process Handler Load Failure

工作进程失败。应用不启动。

ASP.NET Core 模块无法找到 .NET Core CLR 和进程内请求处理程序 (aspnetcorev2_inprocess.dll) 。检查：

• 该应用针对 Microsoft.AspNetCore.Server.IIS NuGet 包或 Microsoft.AspNetCore.App 元包。
• 目标计算机上安装了该应用所针对的 ASP.NET Core 共享框架版本。

500.0 进程外处理程序加载失败500.0 Out-Of-Process Handler Load Failure

工作进程失败。应用不启动。

ASP.NET Core 模块无法找到进程外托管请求处理程序。请确保 aspnetcorev2.dll 旁边的子文件夹中存在 aspnetcorev2_outofprocess.dll 。

502.5 进程失败502.5 Process Failure

工作进程失败。应用不启动。

ASP.NET Core 模块尝试启动工作进程，但启动失败。进程启动失败的原因通常可通过“应用程序事件日志”和“ASP.NET Core 模块 stdout 日志”中的条目进行确定。

常见的失败情况是，由于目标 ASP.NET Core 共享框架版本不存在，因此应用配置错误。检查目标计算机上安装的 ASP.NET Core 共享框架版本。 共享框架是安装在计算机上并由 Microsoft.AspNetCore.App 等元包引用的一组程序集（.dll 文件）。元包引用可以指定所需的最低版本。有关详细信息，请参阅共享框架。

托管或应用配置错误导致工作进程失败时，将返回“502.5 进程失败” 错误页面：

未能启动应用程序（错误代码“0x800700c1”）Failed to start application (ErrorCode '0x800700c1')

EventID: 1010
Source: IIS AspNetCore Module V2
Failed to start application '/LM/W3SVC/6/ROOT/', ErrorCode '0x800700c1'.

应用未能启动，因为应用的程序集 (.dll ) 无法加载。

当已发布的应用与 w3wp/iisexpress 进程之间的位数不匹配时，会出现此错误。

确认应用池的 32 位设置正确：

• 在 IIS 管理器的“应用程序池” 中选择应用池。
• 在“操作” 面板中的“编辑应用程序池” 下选择“高级设置” 。
• 设置“启用 32 位应用程序” ：
  • 如果部署 32 位 (x86) 应用，则将值设置为 True。
  • 如果部署 64 位 (x64) 应用，则将值设置为 False。
    确认项目文件中的 <Platform> MSBuild 属性与应用的已发布位数之间没有冲突。

连接重置Connection reset

如果在发送标头后出现错误，则服务器在出现错误时发送“500 内部服务器错误” 已经太晚了。通常在序列化响应的复杂对象期间出现错误时发生这种情况。此类型的错误在客户端上显示为“连接重置” 错误。应用程序日志记录可以帮助解决这些类型的错误。

默认启动限制Default startup limits

ASP.NET Core 模块的默认“startupTimeLimit”配置为 120 秒 。保留默认值时，在模块记录进程故障之前，可能最多需要两分钟来启动应用。有关配置模块的信息，请参阅 aspNetCore 元素的属性。

排查 Azure 应用服务中的问题Troubleshoot on Azure App Service

重要

Azure 应用服务中的 ASP.NET Core 预览版

默认情况下不会将 ASP.NET Core 预览版部署到 Azure 应用服务。要托管使用 ASP.NET Core 预览版的应用，请参阅将 ASP.NET Core 预览版部署到 Azure 应用服务。

应用程序事件日志（Azure 应用服务）Application Event Log (Azure App Service)

若要访问应用程序事件日志，请在 Azure 门户中使用“诊断并解决问题”边栏选项卡 ：

• 在 Azure 门户中打开“应用服务”中的应用 。
• 选择“诊断并解决问题” 。
• 选择“诊断工具”标题 。
• 在“支持工具”下，选择“应用程序事件”按钮 。

• 检查“源”列中由 IIS AspNetCoreModule 或 IIS AspNetCoreModule V2条目提供的最新错误 。
  使用“诊断并解决问题” 边栏选项卡的替代方法是直接使用 Kudu 检查应用程序事件日志文件：

• 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。

• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 打开 LogFiles 文件夹。
• 选择 eventlog.xml 文件旁边的铅笔图标。
• 检查日志。滚动到日志底部以查看最新事件。

在 Kudu 控制台中运行应用Run the app in the Kudu console

许多启动错误未在应用程序事件日志中生成有用信息。可以在 Kudu 远程执行控制台中运行应用以发现错误：

• 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。

测试 32 位 (x86) 应用Test a 32-bit (x86) app

当前版本

• cd d:\home\site\wwwroot
• 运行应用：
  • 如果应用是依赖框架的部署：

dotnet .\{ASSEMBLY NAME}.dll

• 如果应用是独立部署：

{ASSEMBLY NAME}.exe

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

在预览版上运行的依赖框架的部署

必须安装 ASP.NET Core {VERSION} (x86) 运行时站点扩展。

• cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32（{X.Y} 是运行时版本）
• 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
  来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

测试 64 位 (x64) 应用Test a 64-bit (x64) app

当前版本

• 如果应用是 64 位 (x64) 依赖框架的部署：
  • cd D:\Program Files\dotnet
  • 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
• 如果应用是独立部署：
  • cd D:\home\site\wwwroot
  • 运行应用：{ASSEMBLY NAME}.exe

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

在预览版上运行的依赖框架的部署

必须安装 ASP.NET Core {VERSION} (x64) 运行时站点扩展。

• cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64（{X.Y} 是运行时版本）
• 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
  来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

ASP.NET Core 模块 stdout 日志（Azure 应用服务）ASP.NET Core Module stdout log (Azure App Service)

ASP.NET Core 模块 stdout 日志通常记录应用程序事件日志中找不到的有用错误消息。若要启用和查看 stdout 日志，请执行以下操作：

• 在 Azure 门户中导航到“诊断并解决问题” 边栏选项卡。
• 在“选择问题类别” 下，选择“Web 应用关闭” 按钮。
• 在“建议的解决方案”>“启用 Stdout 日志重定向”下，选择“打开 Kudu 控制台以编辑 Web.Config”对应的按钮 。
• 在 Kudu 诊断控制台 中，打开路径“站点 > wwwroot ”下的文件夹。向下滚动以在列表底部显示“web.config” 文件。
• 单击“web.config” 文件旁边的铅笔图标。
• 将“stdoutLogEnabled” 设置为 true，并将“stdoutLogFile” 路径更改为 \?\%home%\LogFiles\stdout。
• 选择“保存” 以保存已更新的 web.config 文件。
• 向应用发出请求。
• 返回到 Azure 门户。选择“开发工具” 区域中的“高级工具” 边栏选项卡。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 选择“LogFiles” 文件夹。
• 检查“已修改” 列并选择铅笔图标以编辑具有最新修改日期的 stdout 日志。

• 打开日志文件后，将显示错误。
  故障排除完成后，禁用 stdout 日志记录：

• 在 Kudu 诊断控制台 中，返回到路径“site > wwwroot ”以显示 web.config 文件。通过选择铅笔图标再次打开 web.config 文件。

• 将“stdoutLogEnabled” 设置为 false。
• 选择“保存” 以保存文件。
  有关详细信息，请参阅 ASP.NET Core 模块。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。仅使用 stdout 日志记录来解决应用启动问题。

对于在 ASP.NET Core 应用启动后生成的常规日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

ASP.NET Core 模块调试日志（Azure 应用服务）ASP.NET Core Module debug log (Azure App Service)

ASP.NET Core 模块调试日志从 ASP.NET Core 模块提供了更多、更详细的日志记录。若要启用和查看 stdout 日志，请执行以下操作：

• 要启用增强的诊断日志，请执行以下任一操作：
  • 按照增强的诊断日志中的说明配置应用以获取增强的诊断日志记录。重新部署应用。
  • 使用 Kudu 控制台将增强的诊断日志中显示的 <handlerSettings> 添加到动态应用的 web.config 文件中 ：
    • 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
    • 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
    • 打开路径“site > wwwroot ”下的文件夹。通过选择铅笔按钮编辑 web.config 文件 。添加 <handlerSettings> 部分（如增强的诊断日志中所示）。选择“保存”按钮 。
• 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 打开路径“site > wwwroot ”下的文件夹。如果没有为 aspnetcore-debug.log 文件提供路径，则该文件将显示在列表中 。如果提供了路径，请导航到日志文件的位置。
• 使用文件名旁边的铅笔按钮打开日志文件。
  故障排除完成后，禁用调试日志记录：

要禁用增强的调试日志，请执行以下任一操作：

• 从本地删除 web.config 文件中的 <handlerSettings> 并重新部署该应用 。
• 使用 Kudu 控制台编辑 web.config 文件并删除 <handlerSettings> 部分 。保存该文件。

有关详细信息，请参阅 ASP.NET Core 模块。

警告

无法禁用调试日志可能会导致应用或服务器出现故障。日志文件大小没有任何限制。仅使用调试日志记录来解决应用启动问题。

对于在 ASP.NET Core 应用启动后生成的常规日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

应用缓慢或挂起（Azure 应用服务）Slow or hanging app (Azure App Service)

如果应用程序响应缓慢或在有请求时挂起，请参阅以下文章：

• 解决 Azure 应用服务中 Web 应用性能缓慢的问题
• 使用故障诊断程序站点扩展来捕获 Azure Web 应用程序上间歇性异常问题或性能问题的转储

监视边栏选项卡Monitoring blades

监视边栏选项卡提供了本主题前面所述的方法的替代故障排除体验。这些边栏选项卡可用于诊断 500 系列错误。

确认是否已安装 ASP.NET Core 扩展。如果未安装扩展，请手动进行安装：

• 在“开发工具” 边栏选项卡部分中，选择“扩展” 边栏选项卡。
• “ASP.NET Core 扩展” 应显示在列表中。
• 如果未安装扩展，请选择“添加” 按钮。
• 从列表中选择“ASP.NET Core 扩展” 。
• 选择“确定” 以接受法律条款。
• 选择“添加扩展” 边栏选项卡上的“确定” 。

• 信息性弹出消息指示成功安装扩展的时间。
  如果未启用 stdout 日志记录，请执行以下步骤：

• 在 Azure 门户中，选择“开发工具” 区域中的“高级工具” 边栏选项卡。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。

• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 打开路径“site>wwwroot”下的文件夹，然后向下滚动以显示列表底部的 web.config 文件 。
• 单击“web.config” 文件旁边的铅笔图标。
• 将“stdoutLogEnabled” 设置为 true，并将“stdoutLogFile” 路径更改为 \?\%home%\LogFiles\stdout。

• 选择“保存” 以保存已更新的 web.config 文件。
  继续激活诊断日志记录：

• 在 Azure 门户中，选择“诊断日志” 边栏选项卡。

• 选择“应用程序日志记录(文件系统)” 和“详细错误消息” 的“开” 开关。选择边栏选项卡顶部的“保存” 按钮。
• 若要包含失败请求跟踪（也称为失败请求事件缓冲 (FREB) 日志记录），请选择“失败请求跟踪” 的“开” 开关。
• 选择“日志流” 边栏选项卡，将在门户中的“诊断日志” 边栏选项卡下立即列出。
• 向应用发出请求。
• 在日志流数据中，指示了错误的原因。
  故障排除完成后，请务必禁用 stdout 日志记录。

若要查看失败请求跟踪日志（FREB 日志），请执行以下操作：

• 在 Azure 门户中导航到“诊断并解决问题” 边栏选项卡。
• 从侧栏的“支持工具” 区域中选择“失败请求跟踪日志” 。
  有关详细信息，请参阅“在 Azure 应用服务中启用 Web 应用的诊断日志记录”主题的“失败请求跟踪”部分和 Azure 中的 Web 应用的应用程序性能常见问题：如何打开失败请求跟踪？。

有关详细信息，请参阅在 Azure 应用服务中启用 Web 应用的诊断日志记录。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。

对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

IIS 疑难解答Troubleshoot on IIS

应用程序事件日志 (IIS)Application Event Log (IIS)

访问应用程序事件日志：

• 打开“开始”菜单，搜索“事件查看器” ，然后选择“事件查看器” 应用。
• 在“事件查看器” 中，打开“Windows 日志” 节点。
• 选择“应用程序” 以打开应用程序事件日志。
• 搜索与失败应用相关联的错误。错误具有“源” 列中“IIS AspNetCore 模块” 或“IIS Express AspNetCore 模块” 的值。

在命令提示符处运行应用Run the app at a command prompt

许多启动错误未在应用程序事件日志中生成有用信息。可以通过在托管系统上在命令提示符处运行应用来找到某些错误的原因。

依赖框架的部署Framework-dependent deployment

如果应用是依赖框架的部署：

• 在命令提示符处，导航到部署文件夹并通过使用 dotnet.exe 执行应用的程序集来运行应用。在以下命令中，替换 的应用程序集的名称：dotnet .\<assembly_name>.dll。
• 来自应用且显示任何错误的控制台输出将写入控制台窗口。
• 如果向应用发出请求时出现错误，请向 Kestrel 侦听所在的主机和端口发出请求。如果使用默认主机和端口，请向 http://localhost:5000/ 发出请求。如果应用在 Kestrel 终结点地址处正常响应，则问题更可能与承载配置相关，而不太可能在于应用。

独立部署Self-contained deployment

如果应用是独立部署：

• 在命令提示符处，导航到部署文件夹并运行应用的可执行文件。在以下命令中，替换 的应用程序集的名称：<assembly_name>.exe。
• 来自应用且显示任何错误的控制台输出将写入控制台窗口。
• 如果向应用发出请求时出现错误，请向 Kestrel 侦听所在的主机和端口发出请求。如果使用默认主机和端口，请向 http://localhost:5000/ 发出请求。如果应用在 Kestrel 终结点地址处正常响应，则问题更可能与承载配置相关，而不太可能在于应用。

ASP.NET Core 模块 stdout 日志 (IIS)ASP.NET Core Module stdout log (IIS)

若要启用和查看 stdout 日志，请执行以下操作：

• 在托管系统上导航到站点的部署文件夹。
• 如果 logs 文件夹不存在，请创建该文件夹。有关如何启用 MSBuild 以在部署中自动创建 logs 文件夹的说明，请参阅目录结构主题。
• 编辑 web.config 文件。将“stdoutLogEnabled” 设置为 true 并更改“stdoutLogFile” 路径以指向 logs 文件夹（例如，.\logs\stdout）。路径中的 stdout 是日志文件名的前缀。创建日志时，将自动添加时间戳、进程 ID 和文件扩展名。如果将 stdout 用作文件名的前缀，典型的日志文件将命名为“stdout_20180205184032_5412.log” 。
• 请确保应用程序池的标识具有对日志文件夹的写入权限 。
• 保存已更新的 web.config 文件。
• 向应用发出请求。
• 导航到 logs 文件夹。查找并打开最新的 stdout 日志。

• 研究日志以查找错误。
  故障排除完成后，禁用 stdout 日志记录：

• 编辑 web.config 文件。

• 将“stdoutLogEnabled” 设置为 false。
• 保存该文件。
  有关详细信息，请参阅 ASP.NET Core 模块。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。

对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

ASP.NET Core 模块调试日志 (IIS)ASP.NET Core Module debug log (IIS)

将以下处理程序设置添加到应用的 web.config 文件以启用 ASP.NET Core 模块调试日志 ：

<aspNetCore ...>
  <handlerSettings>
    <handlerSetting name="debugLevel" value="file" />
    <handlerSetting name="debugFile" value="c:\temp\ancm.log" />
  </handlerSettings>
</aspNetCore>

确认为日志指定的路径存在，并且应用池的标识具有该位置的写入权限。

有关详细信息，请参阅 ASP.NET Core 模块。

启用开发人员异常页面Enable the Developer Exception Page

ASPNETCORE_ENVIRONMENT 环境变量可以添加到 web.config 以在开发环境中运行应用。只要在应用启动时环境不被主机生成器上的 UseEnvironment 重写，设置环境变量就会在运行应用时显示“开发人员异常页面”。

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="InProcess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
  </environmentVariables>
</aspNetCore>

仅建议在未向 Internet 公开的暂存服务器和测试服务器上设置 ASPNETCORE_ENVIRONMENT 的环境变量。在故障排除后从 web.config 文件中删除环境变量。有关设置 web.config 中的环境变量的信息，请参阅 aspNetCore 的 environmentVariables 子元素。

从应用中获取数据Obtain data from an app

如果应用能够响应请求，则使用终端内联中间件从应用中获取请求、连接和其他数据。有关详细信息和示例代码，请参阅ASP.NET Core 项目故障排除和调试。

应用缓慢或挂起 (IIS)Slow or hanging app (IIS)

故障转储是系统内存的一个快照，可帮助确定应用崩溃、启动故障或应用速度缓慢等状况的原因 。

应用崩溃或引发异常App crashes or encounters an exception

从 Windows 错误报告 (WER) 中获取转储并进行分析：

• 创建文件夹，将崩溃转储文件保存在 c:\dumps。应用池必须对该文件夹具有写权限。

• 运行 EnableDumps PowerShell 脚本：

  • 如果应用使用进程内托管模型，则请为 w3wp.exe 运行脚本 ：

.\EnableDumps w3wp.exe c:\dumps

• 如果应用使用进程外托管模型，则请为 dotnet.exe 运行脚本 ：

.\EnableDumps dotnet.exe c:\dumps

• 在造成崩溃的条件下运行应用。

• 出现崩溃后，运行 DisableDumps PowerShell 脚本：

  • 如果应用使用进程内托管模型，则请为 w3wp.exe 运行脚本 ：

.\DisableDumps w3wp.exe

• 如果应用使用进程外托管模型，则请为 dotnet.exe 运行脚本 ：

.\DisableDumps dotnet.exe

在应用崩溃并完成转储收集后，即可正常终止应用。PowerShell 脚本会 WER 来按应用收集转储（最多收集 5 个）。

警告

崩溃转储可能会占用大量磁盘空间（每个最多占用数 GB）。

应用挂起、在启动期间失败或正常运行App hangs, fails during startup, or runs normally

如果应用挂起（停止响应但不崩溃）、在启动期间失败或者正常运行hangs，请参阅用户模式转储文件：选择最佳工具，以选择适合用于生成转储的工具。

分析转储Analyze the dump

可采用几种方法来分析转储。有关详细信息，请参阅分析用户模式转储文件。

清除包缓存Clear package caches

正常运行的应用在开发计算机上升级 .NET Core SDK 或在应用内更改包版本后可能会立即出现故障。在某些情况下，不同的包可能在执行主要升级时中断应用。可以按照以下说明来修复其中大部分问题：

• 删除 bin 和 obj 文件夹。

• 通过从命令行界面执行 dotnet nuget locals all —clear 清除包缓存。

清除包缓存还可通过使用 nuget.exe 工具并执行命令 nuget locals all -clear 来完成。nuget.exe 不是与 Windows 桌面操作系统的捆绑安装，必须从 NuGet 网站中单独获取。

• 还原并重新生成项目。

• 在重新部署应用前，在服务器上删除部署文件夹中的所有文件。

其他资源Additional resources

• ASP.NET Core 项目故障排除和调试
• Azure 应用服务和 IIS 上 ASP.NET Core 的常见错误参考
• 处理 ASP.NET Core 中的错误
• ASP.NET Core 模块

Azure 文档Azure documentation

• 用于 ASP.NET Core 的 Application Insights
• “使用 Visual Studio 对 Azure 应用服务中的 Web 应用进行故障排除”的“远程调试 Web 应用”一节
• Azure 应用服务诊断概述
• 如何：在 Azure 应用服务中监视应用
• 使用 Visual Studio 对 Azure 应用服务中的 Web 应用进行故障排除
• 解决 Azure Web 应用中的“502 错误的网关”和“503 服务不可用”HTTP 错误
• 解决 Azure 应用服务中 Web 应用性能缓慢的问题
• Azure 中的 Web 应用的应用程序性能常见问题
• Azure Web 应用沙盒（应用服务运行时执行限制）
• Azure Friday：Azure 应用服务诊断和疑难解答体验（12 分钟视频）

Visual Studio 文档Visual Studio documentation

• 在 Azure 中的 IIS 上的 Visual Studio 2017 中远程调试 ASP.NET Core
• 在远程 IIS 计算机的 Visual Studio 2017 中远程调试 ASP.NET Core
• 了解如何使用 Visual Studio 进行调试

Visual Studio Code 文档Visual Studio Code documentation

• 使用 Visual Studio Code 进行调试

本文提供了有关常见应用启动错误的信息，以及在将应用部署到 Azure 应用服务或 IIS 时如何诊断错误的说明：

应用启动错误介绍常见的启动 HTTP 状态代码方案。

排查 Azure 应用服务中的问题为部署到 Azure 应用服务的应用提供疑难解答建议。

IIS 疑难解答为部署到 IIS 或在本地 IIS Express 上运行的应用提供疑难解答建议。本指南适用于 Windows Server 和 Windows 桌面部署。

清除包缓存说明当执行重大升级或更改包版本时，不一致的包中断应用时应如何处理。

其他资源列出其他疑难解答主题。

应用启动错误App startup errors

在 Visual Studio 中，ASP.NET Core 项目默认为在调试期间进行 IIS Express 托管。本地调试时出现的“502.5 - 进程失败”可以使用本主题中的建议进行诊断 。

403.14 禁止403.14 Forbidden

应用无法启动。记录以下错误：

The Web server is configured to not list the contents of this directory.

此错误通常是由于托管系统上的部署中断引起的，包括以下任何情况：

• 该应用部署到托管系统上的错误文件夹。
• 部署过程未能将所有应用的文件和文件夹移到托管系统上的部署文件夹中。
• 部署中缺少 web.config 文件，或者 web.config 文件内容格式不正确 。

执行以下步骤：

• 从托管系统上的部署文件夹中删除所有文件和文件夹。
• 使用常规部署方法（如 Visual Studio、PowerShell 或手动部署）将应用“发布”文件夹的内容重新部署到托管系统 ：
  • 确认部署中存在 web.config 文件，并且其内容正确 。
  • 在 Azure 应用服务上托管时，请确认该应用已部署到 D:\home\site\wwwroot 文件夹。
  • 当应用由 IIS 托管时，请确认应用已部署到“IIS 管理器”的“基本设置”中显示的 IIS 物理路径 。
• 通过将托管系统上的部署与项目“发布”文件夹的内容进行比较，确认已部署应用的所有文件和文件夹 。
  有关已发布 ASP.NET Core 应用布局的详细信息，请参阅 ASP.NET Core 目录结构。有关 web.config 文件的详细信息，请参阅 ASP.NET Core 模块 。

500 内部服务器错误500 Internal Server Error

应用启动，但某个错误阻止了服务器完成请求。

在启动期间或在创建响应时，应用的代码内出现此错误。响应可能不包含任何内容，或响应可能会在浏览器中显示为“500 内部服务器错误” 。应用程序事件日志通常表明应用正常启动。从服务器的角度来看，这是正确的。应用已启动，但无法生成有效的响应。在服务器上的命令提示符下运行应用，或启用 ASP.NET Core 模块 stdout 日志来解决问题。

502.5 进程失败502.5 Process Failure

工作进程失败。应用不启动。

ASP.NET Core 模块尝试启动工作进程，但启动失败。进程启动失败的原因通常可通过“应用程序事件日志”和“ASP.NET Core 模块 stdout 日志”中的条目进行确定。

常见的失败情况是，由于目标 ASP.NET Core 共享框架版本不存在，因此应用配置错误。检查目标计算机上安装的 ASP.NET Core 共享框架版本。 共享框架是安装在计算机上并由 Microsoft.AspNetCore.App 等元包引用的一组程序集（.dll 文件）。元包引用可以指定所需的最低版本。有关详细信息，请参阅共享框架。

托管或应用配置错误导致工作进程失败时，将返回“502.5 进程失败” 错误页面：

未能启动应用程序（错误代码“0x800700c1”）Failed to start application (ErrorCode '0x800700c1')

EventID: 1010
Source: IIS AspNetCore Module V2
Failed to start application '/LM/W3SVC/6/ROOT/', ErrorCode '0x800700c1'.

应用未能启动，因为应用的程序集 (.dll ) 无法加载。

当已发布的应用与 w3wp/iisexpress 进程之间的位数不匹配时，会出现此错误。

确认应用池的 32 位设置正确：

• 在 IIS 管理器的“应用程序池” 中选择应用池。
• 在“操作” 面板中的“编辑应用程序池” 下选择“高级设置” 。
• 设置“启用 32 位应用程序” ：
  • 如果部署 32 位 (x86) 应用，则将值设置为 True。
  • 如果部署 64 位 (x64) 应用，则将值设置为 False。
    确认项目文件中的 <Platform> MSBuild 属性与应用的已发布位数之间没有冲突。

连接重置Connection reset

如果在发送标头后出现错误，则服务器在出现错误时发送“500 内部服务器错误” 已经太晚了。通常在序列化响应的复杂对象期间出现错误时发生这种情况。此类型的错误在客户端上显示为“连接重置” 错误。应用程序日志记录可以帮助解决这些类型的错误。

默认启动限制Default startup limits

ASP.NET Core 模块的默认“startupTimeLimit”配置为 120 秒 。保留默认值时，在模块记录进程故障之前，可能最多需要两分钟来启动应用。有关配置模块的信息，请参阅 aspNetCore 元素的属性。

排查 Azure 应用服务中的问题Troubleshoot on Azure App Service

重要

Azure 应用服务中的 ASP.NET Core 预览版

默认情况下不会将 ASP.NET Core 预览版部署到 Azure 应用服务。要托管使用 ASP.NET Core 预览版的应用，请参阅将 ASP.NET Core 预览版部署到 Azure 应用服务。

应用程序事件日志（Azure 应用服务）Application Event Log (Azure App Service)

若要访问应用程序事件日志，请在 Azure 门户中使用“诊断并解决问题”边栏选项卡 ：

• 在 Azure 门户中打开“应用服务”中的应用 。
• 选择“诊断并解决问题” 。
• 选择“诊断工具”标题 。
• 在“支持工具”下，选择“应用程序事件”按钮 。

• 检查“源”列中由 IIS AspNetCoreModule 或 IIS AspNetCoreModule V2条目提供的最新错误 。
  使用“诊断并解决问题” 边栏选项卡的替代方法是直接使用 Kudu 检查应用程序事件日志文件：

• 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。

• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 打开 LogFiles 文件夹。
• 选择 eventlog.xml 文件旁边的铅笔图标。
• 检查日志。滚动到日志底部以查看最新事件。

在 Kudu 控制台中运行应用Run the app in the Kudu console

许多启动错误未在应用程序事件日志中生成有用信息。可以在 Kudu 远程执行控制台中运行应用以发现错误：

• 打开“开发工具”区域中的“高级工具” 。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。

测试 32 位 (x86) 应用Test a 32-bit (x86) app

当前版本

• cd d:\home\site\wwwroot
• 运行应用：
  • 如果应用是依赖框架的部署：

dotnet .\{ASSEMBLY NAME}.dll

• 如果应用是独立部署：

{ASSEMBLY NAME}.exe

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

在预览版上运行的依赖框架的部署

必须安装 ASP.NET Core {VERSION} (x86) 运行时站点扩展。

• cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32（{X.Y} 是运行时版本）
• 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
  来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

测试 64 位 (x64) 应用Test a 64-bit (x64) app

当前版本

• 如果应用是 64 位 (x64) 依赖框架的部署：
  • cd D:\Program Files\dotnet
  • 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
• 如果应用是独立部署：
  • cd D:\home\site\wwwroot
  • 运行应用：{ASSEMBLY NAME}.exe

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

在预览版上运行的依赖框架的部署

必须安装 ASP.NET Core {VERSION} (x64) 运行时站点扩展。

• cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64（{X.Y} 是运行时版本）
• 运行应用：dotnet \home\site\wwwroot{ASSEMBLY NAME}.dll
  来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。

ASP.NET Core 模块 stdout 日志（Azure 应用服务）ASP.NET Core Module stdout log (Azure App Service)

ASP.NET Core 模块 stdout 日志通常记录应用程序事件日志中找不到的有用错误消息。若要启用和查看 stdout 日志，请执行以下操作：

• 在 Azure 门户中导航到“诊断并解决问题” 边栏选项卡。
• 在“选择问题类别” 下，选择“Web 应用关闭” 按钮。
• 在“建议的解决方案”>“启用 Stdout 日志重定向”下，选择“打开 Kudu 控制台以编辑 Web.Config”对应的按钮 。
• 在 Kudu 诊断控制台 中，打开路径“站点 > wwwroot ”下的文件夹。向下滚动以在列表底部显示“web.config” 文件。
• 单击“web.config” 文件旁边的铅笔图标。
• 将“stdoutLogEnabled” 设置为 true，并将“stdoutLogFile” 路径更改为 \?\%home%\LogFiles\stdout。
• 选择“保存” 以保存已更新的 web.config 文件。
• 向应用发出请求。
• 返回到 Azure 门户。选择“开发工具” 区域中的“高级工具” 边栏选项卡。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 选择“LogFiles” 文件夹。
• 检查“已修改” 列并选择铅笔图标以编辑具有最新修改日期的 stdout 日志。

• 打开日志文件后，将显示错误。
  故障排除完成后，禁用 stdout 日志记录：

• 在 Kudu 诊断控制台 中，返回到路径“site > wwwroot ”以显示 web.config 文件。通过选择铅笔图标再次打开 web.config 文件。

• 将“stdoutLogEnabled” 设置为 false。
• 选择“保存” 以保存文件。
  有关详细信息，请参阅 ASP.NET Core 模块。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。仅使用 stdout 日志记录来解决应用启动问题。

对于在 ASP.NET Core 应用启动后生成的常规日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

应用缓慢或挂起（Azure 应用服务）Slow or hanging app (Azure App Service)

如果应用程序响应缓慢或在有请求时挂起，请参阅以下文章：

• 解决 Azure 应用服务中 Web 应用性能缓慢的问题
• 使用故障诊断程序站点扩展来捕获 Azure Web 应用程序上间歇性异常问题或性能问题的转储

监视边栏选项卡Monitoring blades

监视边栏选项卡提供了本主题前面所述的方法的替代故障排除体验。这些边栏选项卡可用于诊断 500 系列错误。

确认是否已安装 ASP.NET Core 扩展。如果未安装扩展，请手动进行安装：

• 在“开发工具” 边栏选项卡部分中，选择“扩展” 边栏选项卡。
• “ASP.NET Core 扩展” 应显示在列表中。
• 如果未安装扩展，请选择“添加” 按钮。
• 从列表中选择“ASP.NET Core 扩展” 。
• 选择“确定” 以接受法律条款。
• 选择“添加扩展” 边栏选项卡上的“确定” 。

• 信息性弹出消息指示成功安装扩展的时间。
  如果未启用 stdout 日志记录，请执行以下步骤：

• 在 Azure 门户中，选择“开发工具” 区域中的“高级工具” 边栏选项卡。选择“转到→” 按钮。此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。

• 使用页面顶部的导航栏，打开“调试控制台” 并选择“CMD” 。
• 打开路径“site>wwwroot”下的文件夹，然后向下滚动以显示列表底部的 web.config 文件 。
• 单击“web.config” 文件旁边的铅笔图标。
• 将“stdoutLogEnabled” 设置为 true，并将“stdoutLogFile” 路径更改为 \?\%home%\LogFiles\stdout。

• 选择“保存” 以保存已更新的 web.config 文件。
  继续激活诊断日志记录：

• 在 Azure 门户中，选择“诊断日志” 边栏选项卡。

• 选择“应用程序日志记录(文件系统)” 和“详细错误消息” 的“开” 开关。选择边栏选项卡顶部的“保存” 按钮。
• 若要包含失败请求跟踪（也称为失败请求事件缓冲 (FREB) 日志记录），请选择“失败请求跟踪” 的“开” 开关。
• 选择“日志流” 边栏选项卡，将在门户中的“诊断日志” 边栏选项卡下立即列出。
• 向应用发出请求。
• 在日志流数据中，指示了错误的原因。
  故障排除完成后，请务必禁用 stdout 日志记录。

若要查看失败请求跟踪日志（FREB 日志），请执行以下操作：

• 在 Azure 门户中导航到“诊断并解决问题” 边栏选项卡。
• 从侧栏的“支持工具” 区域中选择“失败请求跟踪日志” 。
  有关详细信息，请参阅“在 Azure 应用服务中启用 Web 应用的诊断日志记录”主题的“失败请求跟踪”部分和 Azure 中的 Web 应用的应用程序性能常见问题：如何打开失败请求跟踪？。

有关详细信息，请参阅在 Azure 应用服务中启用 Web 应用的诊断日志记录。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。

对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

IIS 疑难解答Troubleshoot on IIS

应用程序事件日志 (IIS)Application Event Log (IIS)

访问应用程序事件日志：

• 打开“开始”菜单，搜索“事件查看器” ，然后选择“事件查看器” 应用。
• 在“事件查看器” 中，打开“Windows 日志” 节点。
• 选择“应用程序” 以打开应用程序事件日志。
• 搜索与失败应用相关联的错误。错误具有“源” 列中“IIS AspNetCore 模块” 或“IIS Express AspNetCore 模块” 的值。

在命令提示符处运行应用Run the app at a command prompt

许多启动错误未在应用程序事件日志中生成有用信息。可以通过在托管系统上在命令提示符处运行应用来找到某些错误的原因。

依赖框架的部署Framework-dependent deployment

如果应用是依赖框架的部署：

• 在命令提示符处，导航到部署文件夹并通过使用 dotnet.exe 执行应用的程序集来运行应用。在以下命令中，替换 的应用程序集的名称：dotnet .\<assembly_name>.dll。
• 来自应用且显示任何错误的控制台输出将写入控制台窗口。
• 如果向应用发出请求时出现错误，请向 Kestrel 侦听所在的主机和端口发出请求。如果使用默认主机和端口，请向 http://localhost:5000/ 发出请求。如果应用在 Kestrel 终结点地址处正常响应，则问题更可能与承载配置相关，而不太可能在于应用。

独立部署Self-contained deployment

如果应用是独立部署：

• 在命令提示符处，导航到部署文件夹并运行应用的可执行文件。在以下命令中，替换 的应用程序集的名称：<assembly_name>.exe。
• 来自应用且显示任何错误的控制台输出将写入控制台窗口。
• 如果向应用发出请求时出现错误，请向 Kestrel 侦听所在的主机和端口发出请求。如果使用默认主机和端口，请向 http://localhost:5000/ 发出请求。如果应用在 Kestrel 终结点地址处正常响应，则问题更可能与承载配置相关，而不太可能在于应用。

ASP.NET Core 模块 stdout 日志 (IIS)ASP.NET Core Module stdout log (IIS)

若要启用和查看 stdout 日志，请执行以下操作：

• 在托管系统上导航到站点的部署文件夹。
• 如果 logs 文件夹不存在，请创建该文件夹。有关如何启用 MSBuild 以在部署中自动创建 logs 文件夹的说明，请参阅目录结构主题。
• 编辑 web.config 文件。将“stdoutLogEnabled” 设置为 true 并更改“stdoutLogFile” 路径以指向 logs 文件夹（例如，.\logs\stdout）。路径中的 stdout 是日志文件名的前缀。创建日志时，将自动添加时间戳、进程 ID 和文件扩展名。如果将 stdout 用作文件名的前缀，典型的日志文件将命名为“stdout_20180205184032_5412.log” 。
• 请确保应用程序池的标识具有对日志文件夹的写入权限 。
• 保存已更新的 web.config 文件。
• 向应用发出请求。
• 导航到 logs 文件夹。查找并打开最新的 stdout 日志。

• 研究日志以查找错误。
  故障排除完成后，禁用 stdout 日志记录：

• 编辑 web.config 文件。

• 将“stdoutLogEnabled” 设置为 false。
• 保存该文件。
  有关详细信息，请参阅 ASP.NET Core 模块。

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。日志文件大小或创建的日志文件数没有限制。

对于 ASP.NET Core 应用中的例程日志记录，使用限制日志文件大小和旋转日志的日志记录库。有关详细信息，请参阅第三方日志记录提供程序。

启用开发人员异常页面Enable the Developer Exception Page

ASPNETCORE_ENVIRONMENT 环境变量可以添加到 web.config 以在开发环境中运行应用。只要在应用启动时环境不被主机生成器上的 UseEnvironment 重写，设置环境变量就会在运行应用时显示“开发人员异常页面”。

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
  </environmentVariables>
</aspNetCore>

仅建议在未向 Internet 公开的暂存服务器和测试服务器上设置 ASPNETCORE_ENVIRONMENT 的环境变量。在故障排除后从 web.config 文件中删除环境变量。有关设置 web.config 中的环境变量的信息，请参阅 aspNetCore 的 environmentVariables 子元素。

从应用中获取数据Obtain data from an app

如果应用能够响应请求，则使用终端内联中间件从应用中获取请求、连接和其他数据。有关详细信息和示例代码，请参阅ASP.NET Core 项目故障排除和调试。

应用缓慢或挂起 (IIS)Slow or hanging app (IIS)

故障转储是系统内存的一个快照，可帮助确定应用崩溃、启动故障或应用速度缓慢等状况的原因 。

应用崩溃或引发异常App crashes or encounters an exception

从 Windows 错误报告 (WER) 中获取转储并进行分析：

• 创建文件夹，将崩溃转储文件保存在 c:\dumps。应用池必须对该文件夹具有写权限。

• 运行 EnableDumps PowerShell 脚本：

  • 如果应用使用进程内托管模型，则请为 w3wp.exe 运行脚本 ：

.\EnableDumps w3wp.exe c:\dumps

• 如果应用使用进程外托管模型，则请为 dotnet.exe 运行脚本 ：

.\EnableDumps dotnet.exe c:\dumps

• 在造成崩溃的条件下运行应用。

• 出现崩溃后，运行 DisableDumps PowerShell 脚本：

  • 如果应用使用进程内托管模型，则请为 w3wp.exe 运行脚本 ：

.\DisableDumps w3wp.exe

• 如果应用使用进程外托管模型，则请为 dotnet.exe 运行脚本 ：

.\DisableDumps dotnet.exe

在应用崩溃并完成转储收集后，即可正常终止应用。PowerShell 脚本会 WER 来按应用收集转储（最多收集 5 个）。

警告

崩溃转储可能会占用大量磁盘空间（每个最多占用数 GB）。

应用挂起、在启动期间失败或正常运行App hangs, fails during startup, or runs normally

如果应用挂起（停止响应但不崩溃）、在启动期间失败或者正常运行hangs，请参阅用户模式转储文件：选择最佳工具，以选择适合用于生成转储的工具。

分析转储Analyze the dump

可采用几种方法来分析转储。有关详细信息，请参阅分析用户模式转储文件。

清除包缓存Clear package caches

正常运行的应用在开发计算机上升级 .NET Core SDK 或在应用内更改包版本后可能会立即出现故障。在某些情况下，不同的包可能在执行主要升级时中断应用。可以按照以下说明来修复其中大部分问题：

• 删除 bin 和 obj 文件夹。

• 通过从命令行界面执行 dotnet nuget locals all —clear 清除包缓存。

清除包缓存还可通过使用 nuget.exe 工具并执行命令 nuget locals all -clear 来完成。nuget.exe 不是与 Windows 桌面操作系统的捆绑安装，必须从 NuGet 网站中单独获取。

• 还原并重新生成项目。

• 在重新部署应用前，在服务器上删除部署文件夹中的所有文件。

其他资源Additional resources

• ASP.NET Core 项目故障排除和调试
• Azure 应用服务和 IIS 上 ASP.NET Core 的常见错误参考
• 处理 ASP.NET Core 中的错误
• ASP.NET Core 模块

Azure 文档Azure documentation

• 用于 ASP.NET Core 的 Application Insights
• “使用 Visual Studio 对 Azure 应用服务中的 Web 应用进行故障排除”的“远程调试 Web 应用”一节
• Azure 应用服务诊断概述
• 如何：在 Azure 应用服务中监视应用
• 使用 Visual Studio 对 Azure 应用服务中的 Web 应用进行故障排除
• 解决 Azure Web 应用中的“502 错误的网关”和“503 服务不可用”HTTP 错误
• 解决 Azure 应用服务中 Web 应用性能缓慢的问题
• Azure 中的 Web 应用的应用程序性能常见问题
• Azure Web 应用沙盒（应用服务运行时执行限制）
• Azure Friday：Azure 应用服务诊断和疑难解答体验（12 分钟视频）

Visual Studio 文档Visual Studio documentation

• 在 Azure 中的 IIS 上的 Visual Studio 2017 中远程调试 ASP.NET Core
• 在远程 IIS 计算机的 Visual Studio 2017 中远程调试 ASP.NET Core
• 了解如何使用 Visual Studio 进行调试

Visual Studio Code 文档Visual Studio Code documentation

• 使用 Visual Studio Code 进行调试