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

作者：Justin Kotalik

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

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

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

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

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

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

应用启动错误

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

403.14 禁止

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

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

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

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

执行以下步骤：

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

有关已发布 ASP.NET Core 应用布局的详细信息，请参阅 ASP.NET Core 目录结构。 有关“web.config”文件的详细信息，请参阅适用于 IIS 的 ASP.NET Core 模块 (ANCM)。

500 内部服务器错误

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

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

当 .NET Core 托管捆绑包未安装或已损坏时，也可能发生此错误。 安装或修复 .NET Core 托管捆绑包（对于 IIS）或 Visual Studio（对于 IIS Express）可以解决此问题。

500.0 进程内处理程序加载失败

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

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

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

500.30 进程内启动失败

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

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 找不到本机依赖项

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

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 无法加载 dll

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

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

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

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

500.33 ANCM 请求处理程序加载失败

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

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

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

500.34 ANCM 混合托管模型不受支持

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

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

500.35 ANCM 同一进程内有多个进程内应用程序

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

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

500.36 ANCM 进程外处理程序加载失败

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

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

500.37 ANCM 无法在启动时间限制内启动

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

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

500.38 ANCM 找不到应用程序 DLL

ANCM 找不到应用程序 ANCM，该内容应显示在可执行文件的旁边。

在使用进程内托管模型托管打包为单文件可执行程序的应用。 该进程内模型要求 ANCM 将 .NET Core 应用加载到现有 IIS 进程中。 单文件部署模型不支持此方案。 请在应用的项目文件中使用下述方法之一来修复此错误：

1. 通过将 PublishSingleFile MSBuild 属性设置为 false 来禁用单文件发布。
2. 通过将 AspNetCoreHostingModel MSBuild 属性设置为 OutOfProcess 来切换到进程外托管模型。

502.5 进程失败

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

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

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

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

未能启动应用程序（错误代码“0x800700c1”）

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

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

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

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

1. 在 IIS 管理器的“应用程序池”中选择应用池。
2. 在“操作”面板中的“编辑应用程序池”下选择“高级设置”。
3. 设置“启用 32 位应用程序”：
   • 如果部署 32 位 (x86) 应用，则将值设置为 True。
   • 如果部署 64 位 (x64) 应用，则将值设置为 False。

确认项目文件中的 <Platform> MSBuild 属性与应用的已发布位数之间没有冲突。

未能启动应用程序（错误代码“0x800701b1”）

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

由于 Windows 服务加载失败，应用未能启动。

需要启用的一个常见服务是“null”服务。 以下命令启用 null Windows 服务：

sc.exe start null

连接重置

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

默认启动限制

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

排查 Azure 应用服务中的问题

重要

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

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

Azure 应用服务日志流

Azure 应用服务日志流记录发生的信息。 查看流式处理日志：

1. 在 Azure 门户中打开“应用服务”中的应用。
2. 在左侧窗格中，导航至“监视”>“应用服务日志”。
3. 对于“Web 服务器日志记录”，选择“文件系统”。 可选择启用“应用程序日志记录”。
4. 在左侧窗格中，导航至“监视”>“日志流”，然后选择“应用程序日志”或“Web 服务器日志”。

下图显示了应用程序日志输出：

流式处理日志存在一些延迟，可能不会立即显示。

应用程序事件日志（Azure 应用服务）

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

1. 在 Azure 门户中打开“应用服务”中的应用。
2. 选择“诊断并解决问题”。
3. 选择“诊断工具”标题。
4. 在“支持工具”下，选择“应用程序事件”按钮 。
5. 检查“源”列中由 IIS AspNetCoreModule 或 IIS AspNetCoreModule V2条目提供的最新错误 。

使用“诊断并解决问题”边栏选项卡的替代方法是直接使用 Kudu 检查应用程序事件日志文件：

1. 打开“开发工具”区域中的“高级工具” 。 选择“转到→”按钮。 此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
2. 使用页面顶部的导航栏，打开“调试控制台”并选择“CMD”。
3. 打开 LogFiles 文件夹。
4. 选择 eventlog.xml 文件旁边的铅笔图标。
5. 检查日志。 滚动到日志底部以查看最新事件。

在 Kudu 控制台中运行应用

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

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

测试 32 位 (x86) 应用

当前版本

1. cd d:\home\site\wwwroot
2. 运行应用：

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

     dotnet .\{ASSEMBLY NAME}.dll
     

   • 如果应用是独立部署：

     {ASSEMBLY NAME}.exe
     

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

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

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

1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32（{X.Y} 是运行时版本）
2. 运行应用：dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll

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

测试 64 位 (x64) 应用

当前版本

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

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

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

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

1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64（{X.Y} 是运行时版本）
2. 运行应用：dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll

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

ASP.NET Core 模块 stdout 日志（Azure 应用服务）

警告

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

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

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

1. 在 Azure 门户中，导航到 Web 应用。
2. 在“应用服务”边栏选项卡中，在搜索框中输入 kudu 。
3. 选择“高级工具”>“转到”。
4. 选择“调试控制台”>“CMD”。
5. 导航到 site/wwwroot
6. 选择铅笔图标以编辑 web.config 文件。
7. 在 <aspNetCore /> 元素中，设置 stdoutLogEnabled="true" 并选择“保存”。

故障排除完成后，通过设置 stdoutLogEnabled="false" 来禁用 stdout 日志记录。

有关详细信息，请参阅适用于 IIS 的 ASP.NET Core 模块 (ANCM)。

ASP.NET Core 模块调试日志（Azure 应用服务）

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

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

故障排除完成后，禁用调试日志记录：

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

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

有关详细信息，请参阅 ASP.NET Core 模块的日志创建和重定向。

警告

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

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

应用缓慢或挂起（Azure 应用服务）

当应用响应缓慢或挂起请求时，请参阅解决 Azure 应用服务中 Web 应用性能缓慢的问题。

监视边栏选项卡

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

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

1. 在“开发工具”边栏选项卡部分中，选择“扩展”边栏选项卡。
2. “ASP.NET Core 扩展”应显示在列表中。
3. 如果未安装扩展，请选择“添加”按钮。
4. 从列表中选择“ASP.NET Core 扩展”。
5. 选择“确定”以接受法律条款。
6. 选择“添加扩展”边栏选项卡上的“确定”。
7. 信息性弹出消息指示成功安装扩展的时间。

如果未启用 stdout 日志记录，请执行以下步骤：

1. 在 Azure 门户中，选择“开发工具”区域中的“高级工具”边栏选项卡。 选择“转到→”按钮。 此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。
2. 使用页面顶部的导航栏，打开“调试控制台”并选择“CMD”。
3. 打开路径“site>wwwroot”下的文件夹，然后向下滚动以显示列表底部的 web.config 文件。
4. 单击“web.config”文件旁边的铅笔图标。
5. 将“stdoutLogEnabled”设置为 true，并将“stdoutLogFile”路径更改为 \\?\%home%\LogFiles\stdout。
6. 选择“保存”以保存已更新的 web.config 文件。

继续激活诊断日志记录：

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

故障排除完成后，请务必禁用 stdout 日志记录。

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

1. 在 Azure 门户中导航到“诊断并解决问题”边栏选项卡。
2. 从侧栏的“支持工具”区域中选择“失败请求跟踪日志”。

有关详细信息，请参阅“在 Azure 应用服务中启用 Web 应用的诊断日志记录”主题的“失败请求跟踪”部分和 Azure 中的 Web 应用的应用程序性能常见问题：如何打开失败请求跟踪？。

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

警告

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

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

IIS 疑难解答

应用程序事件日志 (IIS)

访问应用程序事件日志：

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

在命令提示符处运行应用

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

依赖框架的部署

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

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

独立部署

如果应用是独立部署：

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

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

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

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

故障排除完成后，禁用 stdout 日志记录：

1. 编辑 web.config 文件。
2. 将“stdoutLogEnabled”设置为 false。
3. 保存文件。

有关详细信息，请参阅适用于 IIS 的 ASP.NET Core 模块 (ANCM)。

警告

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

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

ASP.NET Core 模块调试日志 (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 模块的日志创建和重定向。

启用开发人员异常页面

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 子元素。

从应用中获取数据

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

应用缓慢或挂起 (IIS)

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

应用崩溃或引发异常

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

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

2. 运行 EnableDumps PowerShell 脚本：

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

     .\EnableDumps w3wp.exe c:\dumps
     

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

     .\EnableDumps dotnet.exe c:\dumps
     

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

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

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

     .\DisableDumps w3wp.exe
     

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

     .\DisableDumps dotnet.exe
     

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

警告

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

应用挂起、在启动期间失败或正常运行

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

分析转储

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

清除包缓存

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

1. 删除 bin 和 obj 文件夹。

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

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

3. 还原并重新生成项目。

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

收集状态代码和日志条目

当在 IIS 上运行的 ASP.NET Core 应用遇到错误时，请收集信息以帮助诊断问题。 以下信息可用于故障排除，请收集以下信息：

• 浏览器行为，例如状态代码和错误消息。
• 应用程序事件日志条目
  • Azure 应用服务：请参阅对 Azure 应用服务和 IIS 上的 ASP.NET Core 进行故障排除。
  • IIS
    1. 选择 Windows 菜单中的“开始”，键入“事件查看器”，然后按 Enter 。
    2. 打开“事件查看器”后，展开侧栏中的“Windows 日志”>“应用程序”。
• ASP.NET Core 模块 stdout 和 debug日志条目
  • Azure 应用服务：请参阅对 Azure 应用服务和 IIS 上的 ASP.NET Core 进行故障排除。
  • IIS：按照 ASP.NET Core 模块主题的日志创建和重定向和增强的诊断日志部分中的说明进行操作。

将错误信息与以下常见错误进行比较。 如果找到匹配项，请按照故障排除建议进行操作。

本主题中的错误列表并未包含所有错误。 如果遇到此处未列出的错误，请使用本主题底部的“内容反馈”按钮打开一个新问题，并提供有关如何重现错误的详细说明。

重要

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

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

OS 升级删除了 32 位 ASP.NET Core 模块

应用程序日志： 未能加载模块 DLL C:\WINDOWS\system32\inetsrv\aspnetcore.dll。 该数据是个错误。

疑难解答：

OS 升级期间不会保留 C:\Windows\SysWOW64\inetsrv 目录中的非 OS 文件。 如果在 OS 升级前已安装 ASP.NET Core 模块，且随后在 OS 升级后在 32 位模式下运行任何应用池，则会遇到此问题。 在 OS 升级后修复 ASP.NET Core 模块。 请参阅安装 .NET Core 托管捆绑包。 运行安装程序时，选择“修复”。

缺少站点扩展、安装了 32 位 (x86) 和 64 位 (x64) 站点扩展，或设置了错误的进程位数

适用于 Azure 应用服务托管的应用。

• 浏览器： HTTP 错误 500.0 - ANCM 进程内处理程序加载失败

• 应用程序日志： 调用 hostfxr 以查找进程内请求处理程序失败，未找到任何本机依赖项。 找不到进程内请求处理程序。 调用 hostfxr 捕获的输出：无法找到任何兼容的框架版本。 找不到指定的框架“Microsoft.AspNetCore.App”、版本“{VERSION}-preview-*”。 未能启动应用程序“/LM/W3SVC/1416782824/ROOT”，ErrorCode“0x8000ffff”。

• ASP.NET Core 模块 stdout 日志： 无法找到任何兼容的框架版本。 找不到指定的框架“Microsoft.AspNetCore.App”、版本“{VERSION}-preview-*”。

• ASP.NET Core 模块调试日志： 调用 hostfxr 以查找进程内请求处理程序失败，未找到任何本机依赖项。 这很可能意味着应用配置错误，请检查 Microsoft.NetCore.App 和 Microsoft.AspNetCore.App 版本是否针对该应用程序并安装在计算机上。 返回失败的 HRESULT：0x8000ffff。 找不到进程内请求处理程序。 无法找到任何兼容的框架版本。 找不到指定的框架“Microsoft.AspNetCore.App”、版本“{VERSION}-preview-*”。

疑难解答：

• 如果在预览运行时运行该应用，请安装 32 位 (x86) 或 64位 (x64) 站点扩展，以匹配应用的位数和应用的运行时版本。 请勿同时安装扩展或扩展的多个运行时版本。

  • ASP.NET Core {RUNTIME VERSION} (x86) 运行时
  • ASP.NET Core {RUNTIME VERSION} (x64) 运行时

  重新启动应用。 等待几秒钟，以便应用重新启动。

• 如果在预览运行时运行应用，且同时安装了 32 位 (x86) 和 64 位 (x64) 站点扩展，请卸载与应用的位数不匹配的站点扩展。 删除站点扩展之后，重新启动应用。 等待几秒钟，以便应用重新启动。

• 如果在预览运行时运行该应用，并且站点扩展的位数匹配应用的位数，请确认预览站点扩展的运行时版本匹配应用的运行时版本。

• 确认“应用程序设置”中的应用“平台”与应用的位数匹配。

有关详细信息，请参阅将 ASP.NET Core 应用部署到 Azure 应用服务。

已部署 x86 应用，但 32 位应用未启用应用池

• 浏览器： HTTP 错误 500.30 - ANCM 进程内启动失败

• 应用程序日志： 物理根路径为 '{PATH}' 的应用程序 '/LM/W3SVC/5/ROOT' 遇到意外的托管异常，异常代码= '0xe0434352'。 请检查 stderr 日志以获取详细信息。 物理根路径为 '{PATH}' 的应用程序 '/LM/W3SVC/5/ROOT' 未能加载 clr 和托管应用程序。 CLR 工作线程提前退出

• ASP.NET Core 模块 stdout 日志： 日志文件已创建，但为空。

• ASP.NET Core 模块调试日志： 返回失败的 HRESULT：0x8007023e

发布自包含应用时，SDK 会捕获此方案。 如果 RID 与平台目标（例如，win10-x64 RID 与项目文件中的 <PlatformTarget>x86</PlatformTarget>）不匹配，则 SDK 会产生错误。

疑难解答：

对于依赖 x86 框架的部署 (<PlatformTarget>x86</PlatformTarget>)，请为 32 位应用启用 IIS 应用池。 在 IIS 管理器中，打开应用池的“高级设置”并将“启用 32 位应用程序”设置为 True 。

平台与 RID 冲突

• 浏览器： HTTP 错误 502.5 - 进程失败

• 应用程序日志：物理根路径为 'C:{PATH}' 的应用程序 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY}' 未能通过 '"C:{PATH}{ASSEMBLY}.{exe|dll}" ' 命令行启动进程，ErrorCode = '0x80004005 : ff。

• ASP.NET Core 模块 stdout 日志： 未经处理的异常：System.BadImageFormatException：无法加载文件或程序集 '{ASSEMBLY}.dll'。 试图加载的程序的格式不正确。

疑难解答：

• 确认应用在 Kestrel 上本地运行。 进程失败可能是由应用的内部问题导致的。 有关详细信息，请参阅对 Azure 应用服务和 IIS 上的 ASP.NET Core 进行故障排除。

• 如果在升级应用和部署更新的程序集时，Azure 应用部署出现此异常，请从先前的部署中手动删除所有文件。 部署升级的应用时，延迟的不兼容程序集可能造成 System.BadImageFormatException 异常。

URI 终结点错误或网站已停止

• 浏览器： ERR_CONNECTION_REFUSED --或者-- 无法连接

• 应用程序日志： 没有条目

• ASP.NET Core 模块 stdout 日志： 未创建日志文件。

• ASP.NET Core 模块调试日志： 未创建日志文件。

疑难解答：

• 确认正在使用的应用的 URI 端点是否正确。 检查绑定。

• 确认 IIS 网站未处于“已停止”状态。

已禁用 CoreWebEngine 或 W3SVC 服务器功能

OS 异常： 必须安装 IIS 7.0 CoreWebEngine 和 W3SVC 功能才能使用 ASP.NET Core 模块。

疑难解答：

确认启用了适当的角色和功能。 请参阅 IIS 配置。

网站物理路径不正确或缺少应用

• 浏览器： 403 禁止访问 - 访问被拒绝 --或者-- 403.14 禁止访问 - Web 服务器被配置为不列出此目录的内容。

• 应用程序日志： 没有条目

• ASP.NET Core 模块 stdout 日志： 未创建日志文件。

• ASP.NET Core 模块调试日志： 未创建日志文件。

疑难解答：

检查 IIS 网站的“基本设置”和物理应用文件夹。 确认应用所在的文件夹位于 IIS 网站的物理路径中。

角色不正确、未安装 ASP.NET Core 模块或权限不正确

• 浏览器： 500.19 内部服务器错误 - 无法访问请求的页面，因为该页面的相关配置数据无效。 --或者-- 无法显示此页面

• 应用程序日志： 没有条目

• ASP.NET Core 模块 stdout 日志： 未创建日志文件。

• ASP.NET Core 模块调试日志： 未创建日志文件。

疑难解答：

• 确认启用了适当的角色。 请参阅 IIS 配置。

• 打开“程序和功能”或“应用和功能”，然后确认是否安装了 Windows Server Hosting。 如果已安装的程序列表中没有 Windows Server Hosting，请下载并安装 .NET Core 托管捆绑包。

  当前 .NET Core 托管捆绑包安装程序（直接下载）

  有关详细信息，请参阅安装 .NET Core 托管捆绑包。

• 请确保将“应用程序池”“进程模型”“Identity”设置为“ApplicationPoolIdentity”，或确保自定义标识具有访问应用部署文件夹的相应权限。

• 如果卸载了 ASP.NET Core 托管捆绑包并已安装了一个早期版本的托管捆绑包，则 applicationHost.config 文件将不包含 ASP.NET Core 模块分区。 可打开 %windir%/System32/inetsrv/config 处的 applicationHost.config 文件并找到 分区组。 如果分区组中缺少 ASP.NET Core 模块分区，请添加以下分区元素：

  <section name="aspNetCore" overrideModeDefault="Allow" />
  

  或者，安装最新版本的 ASP.NET Core 托管捆绑包。 最新版本与受支持的 ASP.NET Core 应用向后兼容。

processPath 不正确、缺少 PATH 变量、未安装托管捆绑包、未重启系统/IIS、未安装 VC++ Redistributable 或 dotnet.exe 访问冲突

• 浏览器： HTTP 错误 500.0 - ANCM 进程内处理程序加载失败

• 应用程序日志：物理根路径为 'C:{PATH}' 的应用程序 'MACHINE/WEBROOT/APPHOST/{ASSEMBLY}' 未能通过 '"{...}" ' 命令行启动进程，ErrorCode = '0x80070002 : 0。 应用程序 '{PATH}' 无法启动。 '{PATH}' 中未找到可执行文件。 未能启动应用程序 '/LM/W3SVC/2/ROOT'，ErrorCode '0x8007023e'。

• ASP.NET Core 模块 stdout 日志： 未创建日志文件。

• ASP.NET Core 模块调试日志： 事件日志：应用程序 '{PATH}' 无法启动。 '{PATH}' 中未找到可执行文件。 返回失败的 HRESULT：0x8007023e

疑难解答：

• 确认应用在 Kestrel 上本地运行。 进程失败可能是由应用的内部问题导致的。 有关详细信息，请参阅对 Azure 应用服务和 IIS 上的 ASP.NET Core 进行故障排除。

• 检查 web.config 中 元素的 processPath 属性，对于依赖框架的部署 (FDD)，确保它为 ，对于.\{ASSEMBLY}.exe，确保它为 .\{ASSEMBLY}.exe。

• 对于 FDD，可能无法通过路径设置访问 dotnet.exe。 确认“系统路径”设置中存在“C:\Program Files\dotnet\”。

• 对于 FDD，应用池的用户标识可能无法访问 dotnet.exe。 确认应用池用户标识具有访问 C:\Program Files\dotnet 目录的权限。 确认没有为应用池用户标识配置针对 C:\Program Files\dotnet 和应用目录的拒绝规则。

• 可能已部署 FDD 并安装了 .NET Core，但未重启 IIS。 重启服务器，或通过从命令提示符依次执行 net stop was /y 和 net start w3svc 来重启 IIS 。

• 可能已部署 FDD，但未在托管系统上安装 .NET Core 运行时。 如果尚未安装 .NET Core 运行时，则运行系统上的 .NET Core 托管捆绑包安装程序。

  当前 .NET Core 托管捆绑包安装程序（直接下载）

  有关详细信息，请参阅安装 .NET Core 托管捆绑包。

  如果需要特定的运行时，请从 .NET 下载页下载运行时并将其安装在系统上。 重启系统，或通过从命令提示符依次执行 net stop was /y 和 net start w3svc 来重启 IIS，完成安装 。

<aspNetCore> 元素的参数不正确

• 浏览器： HTTP 错误 500.0 - ANCM 进程内处理程序加载失败

• 应用程序日志： 调用 hostfxr 以查找进程内请求处理程序失败，未找到任何本机依赖项。 这很可能意味着应用配置错误，请检查 Microsoft.NetCore.App 和 Microsoft.AspNetCore.App 版本是否针对该应用程序并安装在计算机上。 找不到进程内请求处理程序。 调用 hostfxr 捕获的输出：是否希望运行 dotnet SDK 命令？ 请从以下位置安装 dotnet SDK：https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409 未能启动应用程序“/LM/W3SVC/3/ROOT”，ErrorCode“0x8000ffff”。

• ASP.NET Core 模块 stdout 日志： 是否希望运行 dotnet SDK 命令？ 请从以下位置安装 dotnet SDK：https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409

• ASP.NET Core 模块调试日志： 调用 hostfxr 以查找进程内请求处理程序失败，未找到任何本机依赖项。 这很可能意味着应用配置错误，请检查 Microsoft.NetCore.App 和 Microsoft.AspNetCore.App 版本是否针对该应用程序并安装在计算机上。 返回失败的 HRESULT：0x8000ffff 找不到进程内请求处理程序。 调用 hostfxr 捕获的输出：是否希望运行 dotnet SDK 命令？ 请从以下位置安装 dotnet SDK：https://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409 HRESULT 失败 返回：0x8000ffff

疑难解答：

• 确认应用在 Kestrel 上本地运行。 进程失败可能是由应用的内部问题导致的。 有关详细信息，请参阅对 Azure 应用服务和 IIS 上的 ASP.NET Core 进行故障排除。

• 检查 web.config 中 元素的 arguments 属性，确认该属性：(a) 对于依赖框架的部署 (FDD) 为 ；或 (b) 对于独立部署 (SCD)，则为不存在、为空字符串 (arguments="")，或为应用参数列表 (arguments="{ARGUMENT_1}, {ARGUMENT_2}, ... {ARGUMENT_X}")。

缺少 .NET Core 共享框架

• 浏览器： HTTP 错误 500.0 - ANCM 进程内处理程序加载失败

• 应用程序日志： 调用 hostfxr 以查找进程内请求处理程序失败，未找到任何本机依赖项。 这很可能意味着应用配置错误，请检查 Microsoft.NetCore.App 和 Microsoft.AspNetCore.App 版本是否针对该应用程序并安装在计算机上。 找不到进程内请求处理程序。 调用 hostfxr 捕获的输出：无法找到任何兼容的框架版本。 找不到指定的框架 'Microsoft.AspNetCore.App'、版本 '{VERSION}'。

未能启动应用程序 '/LM/W3SVC/5/ROOT'，ErrorCode '0x8000ffff'。

• ASP.NET Core 模块 stdout 日志： 无法找到任何兼容的框架版本。 找不到指定的框架 'Microsoft.AspNetCore.App'、版本 '{VERSION}'。

• ASP.NET Core 模块调试日志： 返回失败的 HRESULT：0x8000ffff

疑难解答：

对于依赖框架的部署 (FDD)，确认已在系统上安装正确的运行时。

应用程序池已停止

• 浏览器： 503 服务不可用

• 应用程序日志： 没有条目

• ASP.NET Core 模块 stdout 日志： 未创建日志文件。

• ASP.NET Core 模块调试日志： 未创建日志文件。

疑难解答：

确认应用程序池未处于“已停止”状态。

子应用程序包括 <handlers> 部分

• 浏览器： HTTP 错误 500.19 - 内部服务器错误

• 应用程序日志： 没有条目

• ASP.NET Core 模块 stdout 日志： 创建根应用的日志文件并显示正常操作。 未创建子应用的日志文件。

• ASP.NET Core 模块调试日志： 创建根应用的日志文件并显示正常操作。 未创建子应用的日志文件。

疑难解答：

确认子应用的 web.config 文件不包含 部分，或者子应用未继承父级应用的处理程序。

父级应用的 web.config 的<system.webServer> 放在 <location> 元素内。 将 InheritInChildApplications 属性设置为 false，表示 InheritInChildApplications 元素中指定的设置不会由驻留在父级应用子目录中的应用继承。 有关详细信息，请参阅用于 IIS 的 ASP.NET Core 模块 (ANCM)。

stdout 日志路径不正确

• 浏览器： 应用正常响应。

• 应用程序日志： 无法在 C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll 中启动 stdout 重定向。 异常消息：在 {PATH}\aspnetcoremodulev2\commonlib\fileoutputmanager.cpp:84 返回了 HRESULT 0x80070005。 无法在 C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll 中停止 stdout 重定向。 异常消息：在 {PATH} 返回了 HRESULT 0x80070002。 无法在 {PATH}\aspnetcorev2_inprocess.dll 中启动 stdout 重定向。

• ASP.NET Core 模块 stdout 日志： 未创建日志文件。

• ASP.NET Core 模块调试日志： 无法在 C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll 中启动 stdout 重定向。 异常消息：在 {PATH}\aspnetcoremodulev2\commonlib\fileoutputmanager.cpp:84 返回了 HRESULT 0x80070005。 无法在 C:\Program Files\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll 中停止 stdout 重定向。 异常消息：在 {PATH} 返回了 HRESULT 0x80070002。 无法在 {PATH}\aspnetcorev2_inprocess.dll 中启动 stdout 重定向。

疑难解答：

• web.config 的 <aspNetCore> 元素中指定的 stdoutLogFile 路径不存在。 有关详细信息，请参阅 ASP.NET Core 模块：日志创建和重定向。

• 应用池用户没有 stdout 日志路径的写入权限。

应用程序配置常见问题

• 浏览器： HTTP 错误 500.0 - ANCM 进程内处理程序加载失败 --或者-- HTTP 错误 500.30 - ANCM 进程内启动失败

• 应用程序日志： 变量

• ASP.NET Core 模块 stdout 日志： 日志文件已创建，但为空或使用常规条目创建，直到应用失败。

• ASP.NET Core 模块调试日志： 变量

疑难解答：

此进程无法启动，这很可能是由应用配置或编程问题引起的。

有关详细信息，请参阅下列主题：

• 对 Azure 应用服务和 IIS 上的 ASP.NET Core 进行故障排除
• ASP.NET Core 项目故障排除和调试

其他资源

• 使用 Visual Studio 调试 .NET 和 ASP.NET Core 源代码
• ASP.NET Core 项目故障排除和调试
• 处理 ASP.NET Core 中的错误
• 用于 IIS 的 ASP.NET Core 模块 (ANCM)

Azure 文档

• 用于 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 应用沙盒（应用服务运行时执行限制）

Visual Studio 文档

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

Visual Studio Code 文档

• 使用 Visual Studio Code 进行调试