Azure App Service 和 IIS 上的 ASP.NET Core 疑难解答Troubleshoot ASP.NET Core on Azure App Service and IIS

作者: Luke LathamJustin KotalikBy Luke Latham and Justin Kotalik

本文提供了有关常见应用启动错误的信息, 以及在将应用部署到 Azure App Service 或 IIS 时如何诊断错误的说明:This article provides information on common app startup errors and instructions on how to diagnose errors when an app is deployed to Azure App Service or IIS:

应用启动错误App startup errors
介绍常见的启动 HTTP 状态代码方案。Explains common startup HTTP status code scenarios.

Azure App Service 疑难解答Troubleshoot on Azure App Service
为部署到 Azure App Service 的应用提供故障排除建议。Provides troubleshooting advice for apps deployed to Azure App Service.

IIS 疑难解答Troubleshoot on IIS
为部署到 IIS 或本地运行 IIS Express 的应用程序提供故障排除建议。Provides troubleshooting advice for apps deployed to IIS or running on IIS Express locally. 本指南适用于 Windows Server 和 Windows 桌面部署。The guidance applies to both Windows Server and Windows desktop deployments.

清除包缓存Clear package caches
说明当一致包在执行重大升级或更改包版本时中断应用时应执行的操作。Explains what to do when incoherent packages break an app when performing major upgrades or changing package versions.

其他资源Additional resources
列出其他故障排除主题。Lists additional troubleshooting topics.

应用启动错误App startup errors

在 Visual Studio 中,ASP.NET Core 项目默认为在调试期间进行 IIS Express 托管。In Visual Studio, an ASP.NET Core project defaults to IIS Express hosting during debugging. 在本地调试时, 可以使用本主题中的建议来诊断 " 502.5-进程故障" 或 " 500.30-启动" 故障A 502.5 - Process Failure or a 500.30 - Start Failure that occurs when debugging locally can be diagnosed using the advice in this topic.

在 Visual Studio 中,ASP.NET Core 项目默认为在调试期间进行 IIS Express 托管。In Visual Studio, an ASP.NET Core project defaults to IIS Express hosting during debugging. 使用本主题中的建议可以诊断本地调试时发生的502.5 进程故障A 502.5 Process Failure that occurs when debugging locally can be diagnosed using the advice in this topic.

403.14 禁止403.14 Forbidden

应用启动失败。The app fails to start. 记录以下错误:The following error is logged:

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

此错误通常是由托管系统上的部署中断引起的,其中包括以下任何方案:The error is usually caused by a broken deployment on the hosting system, which includes any of the following scenarios:

  • 该应用程序部署到托管系统上的错误文件夹中。The app is deployed to the wrong folder on the hosting system.
  • 部署过程未能将所有应用的文件和文件夹移到托管系统上的部署文件夹中。The deployment process failed to move all of the app's files and folders to the deployment folder on the hosting system.
  • 部署中缺少web.config文件,或web.config 文件内容的格式不正确。The web.config file is missing from the deployment, or the web.config file contents are malformed.

执行以下步骤:Perform the following steps:

  1. 删除宿主系统上的部署文件夹中的所有文件和文件夹。Delete all of the files and folders from the deployment folder on the hosting system.
  2. 使用常规部署方法(如 Visual Studio、PowerShell 或手动部署)将应用程序的 "发布" 文件夹的内容重新部署到宿主系统:Redeploy the contents of the app's publish folder to the hosting system using your normal method of deployment, such as Visual Studio, PowerShell, or manual deployment:
    • 确认部署中存在web.config文件且其内容正确。Confirm that the web.config file is present in the deployment and that its contents are correct.
    • 在 Azure App Service 上承载时,确认该应用程序已部署到D:\home\site\wwwroot该文件夹。When hosting on Azure App Service, confirm that the app is deployed to the D:\home\site\wwwroot folder.
    • 当应用程序由 IIS 承载时,确认该应用程序部署到 iis管理器的 "基本设置" 中显示的 iis物理路径When the app is hosted by IIS, confirm that the app is deployed to the IIS Physical path shown in IIS Manager's Basic Settings.
  3. 通过将主机系统上的部署与项目的 "发布" 文件夹的内容进行比较,确认应用的所有文件和文件夹都已部署。Confirm that all of the app's files and folders are deployed by comparing the deployment on the hosting system to the contents of the project's publish folder.

有关已发布 ASP.NET Core 应用布局的详细信息,请参阅ASP.NET Core 目录结构For more information on the layout of a published ASP.NET Core app, see ASP.NET Core 目录结构. 有关web.config文件的详细信息,请参阅ASP.NET Core 模块For more information on the web.config file, see ASP.NET Core 模块.

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

应用启动,但某个错误阻止了服务器完成请求。The app starts, but an error prevents the server from fulfilling the request.

在启动期间或在创建响应时,应用的代码内出现此错误。This error occurs within the app's code during startup or while creating a response. 响应可能不包含任何内容,或响应可能会在浏览器中显示为“500 内部服务器错误”。The response may contain no content, or the response may appear as a 500 Internal Server Error in the browser. 应用程序事件日志通常表明应用正常启动。The Application Event Log usually states that the app started normally. 从服务器的角度来看,这是正确的。From the server's perspective, that's correct. 应用已启动,但无法生成有效的响应。The app did start, but it can't generate a valid response. 在服务器上的命令提示符处运行应用程序, 或启用 ASP.NET Core Module stdout 日志来解决该问题。Run the app at a command prompt on the server or enable the ASP.NET Core Module stdout log to troubleshoot the problem.

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

工作进程失败。The worker process fails. 应用不启动。The app doesn't start.

ASP.NET Core 模块未能找到 .NET Core CLR 并找不到进程内请求处理程序(aspnetcorev2_inprocess)。The ASP.NET Core Module fails to find the .NET Core CLR and find the in-process request handler (aspnetcorev2_inprocess.dll). 检查:Check that:

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

工作进程失败。The worker process fails. 应用不启动。The app doesn't start.

ASP.NET Core 模块未能找到进程外宿主请求处理程序。The ASP.NET Core Module fails to find the out-of-process hosting request handler. 请确保 aspnetcorev2.dll 旁边的子文件夹中存在 aspnetcorev2_outofprocess.dll。Make sure the aspnetcorev2_outofprocess.dll is present in a subfolder next to aspnetcorev2.dll.

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

工作进程失败。The worker process fails. 应用不启动。The app doesn't start.

加载ASP.NET Core 模块组件时出现未知错误。An unknown error occurred loading ASP.NET Core Module components. 请执行以下一项操作:Take one of the following actions:

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

工作进程失败。The worker process fails. 应用不启动。The app doesn't start.

ASP.NET Core 模块尝试在进程中启动 .NET Core CLR, 但无法启动。The ASP.NET Core Module attempts to start the .NET Core CLR in-process, but it fails to start. 通常, 可以根据应用程序事件日志中的条目和 ASP.NET Core 模块 stdout 日志中的条目来确定进程启动失败的原因。The cause of a process startup failure can usually be determined from entries in the Application Event Log and the ASP.NET Core Module stdout log.

常见的失败情况是,由于目标 ASP.NET Core 共享框架版本不存在,因此应用配置错误。A common failure condition is the app is misconfigured due to targeting a version of the ASP.NET Core shared framework that isn't present. 检查目标计算机上安装的 ASP.NET Core 共享框架版本。Check which versions of the ASP.NET Core shared framework are installed on the target machine.

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

工作进程失败。The worker process fails. 应用不启动。The app doesn't start.

ASP.NET Core 模块尝试在进程内启动 .net Core 运行时, 但无法启动。The ASP.NET Core Module attempts to start the .NET Core runtime in-process, but it fails to start. 此类启动失败的最常见原因是未安装 Microsoft.NETCore.AppMicrosoft.AspNetCore.App运行时。The most common cause of this startup failure is when the Microsoft.NETCore.App or Microsoft.AspNetCore.App runtime isn't installed. 如果将应用部署为面向 ASP.NET Core 3.0,并且计算机上不存在该版本,则会发生此错误。If the app is deployed to target ASP.NET Core 3.0 and that version doesn't exist on the machine, this error occurs. 示例错误消息如下所示:An example error message follows:

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 版本以及应用请求的版本。The error message lists all the installed .NET Core versions and the version requested by the app. 请通过以下一种方法修复此错误:To fix this error, either:

  • 在计算机上安装适当版本的 .NET Core。Install the appropriate version of .NET Core on the machine.
  • 更改应用,使其面向计算机上已存在的 .NET Core 版本。Change the app to target a version of .NET Core that's present on the machine.
  • 将应用作为独立部署进行发布。Publish the app as a self-contained deployment.

在开发过程(ASPNETCORE_ENVIRONMENT 环境变量设置为 Development)中运行时,HTTP 响应中会写入特定的错误。When running in development (the ASPNETCORE_ENVIRONMENT environment variable is set to Development), the specific error is written to the HTTP response. 在应用程序事件日志中也可以找到进程启动失败的原因。The cause of a process startup failure is also found in the Application Event Log.

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

工作进程失败。The worker process fails. 应用不启动。The app doesn't start.

此错误的最常见原因是针对不兼容的处理器体系结构发布了应用。The most common cause for this error is that the app is published for an incompatible processor architecture. 如果工作进程作为 32 位应用运行,而将应用发布为面向 64 位,则会发生此错误。If the worker process is running as a 32-bit app and the app was published to target 64-bit, this error occurs.

请通过以下一种方法修复此错误:To fix this error, either:

  • 针对同一处理器体系结构将应用作为工作进程进行重新发布。Republish the app for the same processor architecture as the worker process.
  • 将应用作为依赖框架的部署进行发布。Publish the app as a framework-dependent deployment.

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

工作进程失败。The worker process fails. 应用不启动。The app doesn't start.

应用未引用 Microsoft.AspNetCore.App 框架。The app didn't reference the Microsoft.AspNetCore.App framework. 只有面向该框架Microsoft.AspNetCore.App的应用才能由ASP.NET Core 模块承载。Only apps targeting the Microsoft.AspNetCore.App framework can be hosted by the ASP.NET Core Module.

要修复此错误,请确保应用面向 Microsoft.AspNetCore.App 框架。To fix this error, confirm that the app is targeting the Microsoft.AspNetCore.App framework. 检查 .runtimeconfig.json 以验证该应用所面向的框架。Check the .runtimeconfig.json to verify the framework targeted by the app.

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

工作进程不能在同一进程中同时运行进程内应用和进程外应用。The worker process can't run both an in-process app and an out-of-process app in the same process.

要修复此错误,请在单独的 IIS 应用程序池中运行应用。To fix this error, run apps in separate IIS application pools.

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

工作进程不能在同一进程中同时运行进程内应用和进程外应用。The worker process can't run both an in-process app and an out-of-process app in the same process.

要修复此错误,请在单独的 IIS 应用程序池中运行应用。To fix this error, run apps in separate IIS application pools.

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

进程外请求处理程序 aspnetcorev2_outofprocess.dll 未与 aspnetcorev2.dll 文件相邻。The out-of-process request handler, aspnetcorev2_outofprocess.dll, isn't next to the aspnetcorev2.dll file. 这表示安装的ASP.NET Core 模块已损坏。This indicates a corrupted installation of the ASP.NET Core Module.

要修复此错误,请修复 .NET Core 托管捆绑包(对于 IIS)或 Visual Studio(对于 IIS Express)的安装。To fix this error, repair the installation of the .NET Core Hosting Bundle (for IIS) or Visual Studio (for IIS Express).

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

ANCM 无法在提供的启动时间限制内启动。ANCM failed to start within the provied startup time limit. 默认情况下,超时时间为 120 秒。By default, the timeout is 120 seconds.

在同一台计算机上启动大量应用时,则可能发生此错误。This error can occur when starting a large number of apps on the same machine. 在启动期间检查服务器上的 CPU/内存使用峰值。Check for CPU/Memory usage spikes on the server during startup. 可能需要交错执行多个应用程序的启动进程。You may need to stagger the startup process of multiple apps.

502.5 进程失败502.5 Process Failure

工作进程失败。The worker process fails. 应用不启动。The app doesn't start.

ASP.NET Core 模块尝试启动工作进程,但启动失败。The ASP.NET Core Module attempts to start the worker process but it fails to start. 通常, 可以根据应用程序事件日志中的条目和 ASP.NET Core 模块 stdout 日志中的条目来确定进程启动失败的原因。The cause of a process startup failure can usually be determined from entries in the Application Event Log and the ASP.NET Core Module stdout log.

常见的失败情况是,由于目标 ASP.NET Core 共享框架版本不存在,因此应用配置错误。A common failure condition is the app is misconfigured due to targeting a version of the ASP.NET Core shared framework that isn't present. 检查目标计算机上安装的 ASP.NET Core 共享框架版本。Check which versions of the ASP.NET Core shared framework are installed on the target machine. 共享框架是安装在计算机上并由 Microsoft.AspNetCore.App 等元包引用的一组程序集(.dll 文件)。The shared framework is the set of assemblies (.dll files) that are installed on the machine and referenced by a metapackage such as Microsoft.AspNetCore.App. 元包引用可以指定所需的最低版本。The metapackage reference can specify a minimum required version. 有关详细信息,请参阅共享框架For more information, see The shared framework.

托管或应用配置错误导致工作进程失败时,将返回“502.5 进程失败”错误页面:The 502.5 Process Failure error page is returned when a hosting or app misconfiguration causes the worker process to fail:

未能启动应用程序(错误代码“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) 无法加载。The app failed to start because the app's assembly (.dll) couldn't be loaded.

当已发布的应用与 w3wp/iisexpress 进程之间的位数不匹配时,会出现此错误。This error occurs when there's a bitness mismatch between the published app and the w3wp/iisexpress process.

确认应用池的 32 位设置正确:Confirm that the app pool's 32-bit setting is correct:

  1. 在 IIS 管理器的“应用程序池”中选择应用池。Select the app pool in IIS Manager's Application Pools.
  2. 在“操作”面板中的“编辑应用程序池”下选择“高级设置”。Select Advanced Settings under Edit Application Pool in the Actions panel.
  3. 设置“启用 32 位应用程序”:Set Enable 32-Bit Applications:
    • 如果部署 32 位 (x86) 应用,则将值设置为 TrueIf deploying a 32-bit (x86) app, set the value to True.
    • 如果部署 64 位 (x64) 应用,则将值设置为 FalseIf deploying a 64-bit (x64) app, set the value to False.

确认项目文件中的<Platform> MSBuild 属性和应用的已发布位之间没有冲突。Confirm that there isn't a conflict between a <Platform> MSBuild property in the project file and the published bitness of the app.

连接重置Connection reset

如果在发送标头后出现错误,则服务器在出现错误时发送“500 内部服务器错误”已经太晚了。If an error occurs after the headers are sent, it's too late for the server to send a 500 Internal Server Error when an error occurs. 通常在序列化响应的复杂对象期间出现错误时发生这种情况。This often happens when an error occurs during the serialization of complex objects for a response. 此类型的错误在客户端上显示为“连接重置”错误。This type of error appears as a connection reset error on the client. 应用程序日志记录可以帮助解决这些类型的错误。Application logging can help troubleshoot these types of errors.

默认启动限制Default startup limits

ASP.NET Core 模块配置了默认startupTimeLimit为120秒。The ASP.NET Core Module is configured with a default startupTimeLimit of 120 seconds. 保留默认值时,在模块记录进程故障之前,可能最多需要两分钟来启动应用。When left at the default value, an app may take up to two minutes to start before the module logs a process failure. 有关配置模块的信息,请参阅 aspNetCore 元素的属性For information on configuring the module, see Attributes of the aspNetCore element.

Azure App Service 疑难解答Troubleshoot on Azure App Service

重要

Azure 应用服务中的 ASP.NET Core 预览版ASP.NET Core preview releases with Azure App Service

默认情况下不会将 ASP.NET Core 预览版部署到 Azure 应用服务。ASP.NET Core preview releases aren't deployed to Azure App Service by default. 要托管使用 ASP.NET Core 预览版的应用,请参阅将 ASP.NET Core 预览版部署到 Azure 应用服务To host an app that uses an ASP.NET Core preview release, see Deploy ASP.NET Core preview release to Azure App Service.

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

若要访问应用程序事件日志,请在 Azure 门户中使用“诊断并解决问题”边栏选项卡:To access the Application Event Log, use the Diagnose and solve problems blade in the Azure portal:

  1. 在 Azure 门户中打开“应用服务”中的应用。In the Azure portal, open the app in App Services.
  2. 选择“诊断并解决问题”。Select Diagnose and solve problems.
  3. 选择“诊断工具”标题。Select the Diagnostic Tools heading.
  4. 在“支持工具”下,选择“应用程序事件”按钮。Under Support Tools, select the Application Events button.
  5. 检查“源”列中由 IIS AspNetCoreModule 或 IIS AspNetCoreModule V2 条目提供的最新错误。Examine the latest error provided by the IIS AspNetCoreModule or IIS AspNetCoreModule V2 entry in the Source column.

使用“诊断并解决问题”边栏选项卡的替代方法是直接使用 Kudu 检查应用程序事件日志文件:An alternative to using the Diagnose and solve problems blade is to examine the Application Event Log file directly using Kudu:

  1. 打开“开发工具”区域中的“高级工具”。Open Advanced Tools in the Development Tools area. 选择“转到→”按钮。Select the Go→ button. 此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。The Kudu console opens in a new browser tab or window.
  2. 使用页面顶部的导航栏,打开“调试控制台”并选择“CMD”。Using the navigation bar at the top of the page, open Debug console and select CMD.
  3. 打开 LogFiles 文件夹。Open the LogFiles folder.
  4. 选择 eventlog.xml 文件旁边的铅笔图标。Select the pencil icon next to the eventlog.xml file.
  5. 检查日志。Examine the log. 滚动到日志底部以查看最新事件。Scroll to the bottom of the log to see the most recent events.

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

许多启动错误未在应用程序事件日志中生成有用信息。Many startup errors don't produce useful information in the Application Event Log. 可以在 Kudu 远程执行控制台中运行应用以发现错误:You can run the app in the Kudu Remote Execution Console to discover the error:

  1. 打开“开发工具”区域中的“高级工具”。Open Advanced Tools in the Development Tools area. 选择“转到→”按钮。Select the Go→ button. 此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。The Kudu console opens in a new browser tab or window.
  2. 使用页面顶部的导航栏,打开“调试控制台”并选择“CMD”。Using the navigation bar at the top of the page, open Debug console and select CMD.

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

当前版本Current release

  1. cd d:\home\site\wwwroot
  2. 运行应用:Run the app:

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。The console output from the app, showing any errors, is piped to the Kudu console.

在预览版本中运行的依赖框架的部署Framework-dependent deployment running on a preview release

必须安装 ASP.NET Core {VERSION} (x86) 运行时站点扩展。Requires installing the ASP.NET Core {VERSION} (x86) Runtime site extension.

  1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32{X.Y} 是运行时版本)cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x32 ({X.Y} is the runtime version)
  2. 运行应用:dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dllRun the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。The console output from the app, showing any errors, is piped to the Kudu console.

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

当前版本Current release

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。The console output from the app, showing any errors, is piped to the Kudu console.

在预览版本中运行的依赖框架的部署Framework-dependent deployment running on a preview release

必须安装 ASP.NET Core {VERSION} (x64) 运行时站点扩展。Requires installing the ASP.NET Core {VERSION} (x64) Runtime site extension.

  1. cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64{X.Y} 是运行时版本)cd D:\home\SiteExtensions\AspNetCoreRuntime.{X.Y}.x64 ({X.Y} is the runtime version)
  2. 运行应用:dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dllRun the app: dotnet \home\site\wwwroot\{ASSEMBLY NAME}.dll

来自应用且显示任何错误的控制台输出将传送到 Kudu 控制台。The console output from the app, showing any errors, is piped to the Kudu console.

ASP.NET Core 模块 stdout 日志 (Azure App Service)ASP.NET Core Module stdout log (Azure App Service)

ASP.NET Core 模块 stdout 日志通常记录应用程序事件日志中找不到的有用错误消息。The ASP.NET Core Module stdout log often records useful error messages not found in the Application Event Log. 若要启用和查看 stdout 日志,请执行以下操作:To enable and view stdout logs:

  1. 在 Azure 门户中导航到“诊断并解决问题”边栏选项卡。Navigate to the Diagnose and solve problems blade in the Azure portal.
  2. 在“选择问题类别”下,选择“Web 应用关闭”按钮。Under SELECT PROBLEM CATEGORY, select the Web App Down button.
  3. 在“建议的解决方案” > “启用 Stdout 日志重定向”下,选择“打开 Kudu 控制台以编辑 Web.Config”对应的按钮。Under Suggested Solutions > Enable Stdout Log Redirection, select the button to Open Kudu Console to edit Web.Config.
  4. 在 Kudu 诊断控制台中,打开路径“站点 > wwwroot”下的文件夹。In the Kudu Diagnostic Console, open the folders to the path site > wwwroot. 向下滚动以在列表底部显示“web.config”文件。Scroll down to reveal the web.config file at the bottom of the list.
  5. 单击“web.config”文件旁边的铅笔图标。Click the pencil icon next to the web.config file.
  6. 将“stdoutLogEnabled”设置为 true,并将“stdoutLogFile”路径更改为 \\?\%home%\LogFiles\stdoutSet stdoutLogEnabled to true and change the stdoutLogFile path to: \\?\%home%\LogFiles\stdout.
  7. 选择“保存”以保存已更新的 web.config 文件。Select Save to save the updated web.config file.
  8. 向应用发出请求。Make a request to the app.
  9. 返回到 Azure 门户。Return to the Azure portal. 选择“开发工具”区域中的“高级工具”边栏选项卡。Select the Advanced Tools blade in the DEVELOPMENT TOOLS area. 选择“转到→”按钮。Select the Go→ button. 此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。The Kudu console opens in a new browser tab or window.
  10. 使用页面顶部的导航栏,打开“调试控制台”并选择“CMD”。Using the navigation bar at the top of the page, open Debug console and select CMD.
  11. 选择“LogFiles”文件夹。Select the LogFiles folder.
  12. 检查“已修改”列并选择铅笔图标以编辑具有最新修改日期的 stdout 日志。Inspect the Modified column and select the pencil icon to edit the stdout log with the latest modification date.
  13. 打开日志文件后,将显示错误。When the log file opens, the error is displayed.

故障排除完成后,禁用 stdout 日志记录:Disable stdout logging when troubleshooting is complete:

  1. 在 Kudu 诊断控制台中,返回到路径“site > wwwroot”以显示 web.config 文件。In the Kudu Diagnostic Console, return to the path site > wwwroot to reveal the web.config file. 通过选择铅笔图标再次打开 web.config 文件。Open the web.config file again by selecting the pencil icon.
  2. 将“stdoutLogEnabled”设置为 falseSet stdoutLogEnabled to false.
  3. 选择“保存”以保存文件。Select Save to save the file.

有关详细信息,请参阅 ASP.NET Core 模块For more information, see ASP.NET Core 模块.

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。Failure to disable the stdout log can lead to app or server failure. 日志文件大小或创建的日志文件数没有限制。There's no limit on log file size or the number of log files created. 仅使用 stdout 日志记录来解决应用启动问题。Only use stdout logging to troubleshoot app startup problems.

对于在 ASP.NET Core 应用启动后生成的常规日志记录,使用限制日志文件大小和旋转日志的日志记录库。For general logging in an ASP.NET Core app after startup, use a logging library that limits log file size and rotates logs. 有关详细信息,请参阅第三方日志记录提供程序For more information, see third-party logging providers.

ASP.NET Core 模块调试日志 (Azure App Service)ASP.NET Core Module debug log (Azure App Service)

ASP.NET Core 模块调试日志从 ASP.NET Core 模块提供了更多、更详细的日志记录。The ASP.NET Core Module debug log provides additional, deeper logging from the ASP.NET Core Module. 若要启用和查看 stdout 日志,请执行以下操作:To enable and view stdout logs:

  1. 要启用增强的诊断日志,请执行以下任一操作:To enable the enhanced diagnostic log, perform either of the following:
    • 按照增强的诊断日志中的说明配置应用以获取增强的诊断日志记录。Follow the instructions in Enhanced diagnostic logs to configure the app for an enhanced diagnostic logging. 重新部署应用。Redeploy the app.
    • 使用 Kudu 控制台将增强的诊断日志中显示的 <handlerSettings> 添加到动态应用的 web.config 文件中:Add the <handlerSettings> shown in Enhanced diagnostic logs to the live app's web.config file using the Kudu console:
      1. 打开“开发工具”区域中的“高级工具”。Open Advanced Tools in the Development Tools area. 选择“转到→”按钮。Select the Go→ button. 此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。The Kudu console opens in a new browser tab or window.
      2. 使用页面顶部的导航栏,打开“调试控制台”并选择“CMD”。Using the navigation bar at the top of the page, open Debug console and select CMD.
      3. 打开路径“site > wwwroot”下的文件夹。Open the folders to the path site > wwwroot. 通过选择铅笔按钮编辑 web.config 文件。Edit the web.config file by selecting the pencil button. 添加 <handlerSettings> 部分(如增强的诊断日志中所示)。Add the <handlerSettings> section as shown in Enhanced diagnostic logs. 选择“保存”按钮。Select the Save button.
  2. 打开“开发工具”区域中的“高级工具”。Open Advanced Tools in the Development Tools area. 选择“转到→”按钮。Select the Go→ button. 此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。The Kudu console opens in a new browser tab or window.
  3. 使用页面顶部的导航栏,打开“调试控制台”并选择“CMD”。Using the navigation bar at the top of the page, open Debug console and select CMD.
  4. 打开路径“site > wwwroot”下的文件夹。Open the folders to the path site > wwwroot. 如果没有为 aspnetcore-debug.log 文件提供路径,则该文件将显示在列表中。If you didn't supply a path for the aspnetcore-debug.log file, the file appears in the list. 如果提供了路径,请导航到日志文件的位置。If you supplied a path, navigate to the location of the log file.
  5. 使用文件名旁边的铅笔按钮打开日志文件。Open the log file with the pencil button next to the file name.

故障排除完成后,禁用调试日志记录:Disable debug logging when troubleshooting is complete:

要禁用增强的调试日志,请执行以下任一操作:To disable the enhanced debug log, perform either of the following:

  • 从本地删除 web.config 文件中的 <handlerSettings> 并重新部署该应用。Remove the <handlerSettings> from the web.config file locally and redeploy the app.
  • 使用 Kudu 控制台编辑 web.config 文件并删除 <handlerSettings> 部分。Use the Kudu console to edit the web.config file and remove the <handlerSettings> section. 保存该文件。Save the file.

有关详细信息,请参阅 ASP.NET Core 模块For more information, see ASP.NET Core 模块.

警告

无法禁用调试日志可能会导致应用或服务器出现故障。Failure to disable the debug log can lead to app or server failure. 日志文件大小没有任何限制。There's no limit on log file size. 仅使用调试日志记录来解决应用启动问题。Only use debug logging to troubleshoot app startup problems.

对于在 ASP.NET Core 应用启动后生成的常规日志记录,使用限制日志文件大小和旋转日志的日志记录库。For general logging in an ASP.NET Core app after startup, use a logging library that limits log file size and rotates logs. 有关详细信息,请参阅第三方日志记录提供程序For more information, see third-party logging providers.

缓慢或悬挂式应用 (Azure App Service)Slow or hanging app (Azure App Service)

如果应用程序响应缓慢或在有请求时挂起,请参阅以下文章:When an app responds slowly or hangs on a request, see the following articles:

监视边栏选项卡Monitoring blades

监视边栏选项卡提供了本主题前面所述的方法的替代故障排除体验。Monitoring blades provide an alternative troubleshooting experience to the methods described earlier in the topic. 这些边栏选项卡可用于诊断 500 系列错误。These blades can be used to diagnose 500-series errors.

确认是否已安装 ASP.NET Core 扩展。Confirm that the ASP.NET Core Extensions are installed. 如果未安装扩展,请手动进行安装:If the extensions aren't installed, install them manually:

  1. 在“开发工具”边栏选项卡部分中,选择“扩展”边栏选项卡。In the DEVELOPMENT TOOLS blade section, select the Extensions blade.
  2. “ASP.NET Core 扩展”应显示在列表中。The ASP.NET Core Extensions should appear in the list.
  3. 如果未安装扩展,请选择“添加”按钮。If the extensions aren't installed, select the Add button.
  4. 从列表中选择“ASP.NET Core 扩展”。Choose the ASP.NET Core Extensions from the list.
  5. 选择“确定”以接受法律条款。Select OK to accept the legal terms.
  6. 选择“添加扩展”边栏选项卡上的“确定”。Select OK on the Add extension blade.
  7. 信息性弹出消息指示成功安装扩展的时间。An informational pop-up message indicates when the extensions are successfully installed.

如果未启用 stdout 日志记录,请执行以下步骤:If stdout logging isn't enabled, follow these steps:

  1. 在 Azure 门户中,选择“开发工具”区域中的“高级工具”边栏选项卡。In the Azure portal, select the Advanced Tools blade in the DEVELOPMENT TOOLS area. 选择“转到→”按钮。Select the Go→ button. 此时将在新的浏览器选项卡或窗口中打开 Kudu 控制台。The Kudu console opens in a new browser tab or window.
  2. 使用页面顶部的导航栏,打开“调试控制台”并选择“CMD”。Using the navigation bar at the top of the page, open Debug console and select CMD.
  3. 打开路径“site > wwwroot”下的文件夹,然后向下滚动以显示列表底部的 web.config 文件。Open the folders to the path site > wwwroot and scroll down to reveal the web.config file at the bottom of the list.
  4. 单击“web.config”文件旁边的铅笔图标。Click the pencil icon next to the web.config file.
  5. 将“stdoutLogEnabled”设置为 true,并将“stdoutLogFile”路径更改为 \\?\%home%\LogFiles\stdoutSet stdoutLogEnabled to true and change the stdoutLogFile path to: \\?\%home%\LogFiles\stdout.
  6. 选择“保存”以保存已更新的 web.config 文件。Select Save to save the updated web.config file.

继续激活诊断日志记录:Proceed to activate diagnostic logging:

  1. 在 Azure 门户中,选择“诊断日志”边栏选项卡。In the Azure portal, select the Diagnostics logs blade.
  2. 选择“应用程序日志记录(文件系统)”和“详细错误消息”的“开”开关。Select the On switch for Application Logging (Filesystem) and Detailed error messages. 选择边栏选项卡顶部的“保存”按钮。Select the Save button at the top of the blade.
  3. 若要包含失败请求跟踪(也称为失败请求事件缓冲 (FREB) 日志记录),请选择“失败请求跟踪”的“开”开关。To include failed request tracing, also known as Failed Request Event Buffering (FREB) logging, select the On switch for Failed request tracing.
  4. 选择“日志流”边栏选项卡,将在门户中的“诊断日志”边栏选项卡下立即列出。Select the Log stream blade, which is listed immediately under the Diagnostics logs blade in the portal.
  5. 向应用发出请求。Make a request to the app.
  6. 在日志流数据中,指示了错误的原因。Within the log stream data, the cause of the error is indicated.

故障排除完成后,请务必禁用 stdout 日志记录。Be sure to disable stdout logging when troubleshooting is complete.

若要查看失败请求跟踪日志(FREB 日志),请执行以下操作:To view the failed request tracing logs (FREB logs):

  1. 在 Azure 门户中导航到“诊断并解决问题”边栏选项卡。Navigate to the Diagnose and solve problems blade in the Azure portal.
  2. 从侧栏的“支持工具”区域中选择“失败请求跟踪日志”。Select Failed Request Tracing Logs from the SUPPORT TOOLS area of the sidebar.

有关详细信息,请参阅“在 Azure 应用服务中启用 Web 应用的诊断日志记录”主题的“失败请求跟踪”部分Azure 中的 Web 应用的应用程序性能常见问题:如何打开失败请求跟踪?See Failed request traces section of the Enable diagnostics logging for web apps in Azure App Service topic and the Application performance FAQs for Web Apps in Azure: How do I turn on failed request tracing? for more information.

有关详细信息,请参阅在 Azure 应用服务中启用 Web 应用的诊断日志记录For more information, see Enable diagnostics logging for web apps in Azure App Service.

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。Failure to disable the stdout log can lead to app or server failure. 日志文件大小或创建的日志文件数没有限制。There's no limit on log file size or the number of log files created.

对于 ASP.NET Core 应用中的例程日志记录,使用限制日志文件大小和旋转日志的日志记录库。For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. 有关详细信息,请参阅第三方日志记录提供程序For more information, see third-party logging providers.

IIS 故障排除Troubleshoot on IIS

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

访问应用程序事件日志:Access the Application Event Log:

  1. 打开“开始”菜单,搜索“事件查看器”,然后选择“事件查看器”应用。Open the Start menu, search for Event Viewer, and then select the Event Viewer app.
  2. 在“事件查看器”中,打开“Windows 日志”节点。In Event Viewer, open the Windows Logs node.
  3. 选择“应用程序”以打开应用程序事件日志。Select Application to open the Application Event Log.
  4. 搜索与失败应用相关联的错误。Search for errors associated with the failing app. 错误具有“源”列中“IIS AspNetCore 模块”或“IIS Express AspNetCore 模块”的值。Errors have a value of IIS AspNetCore Module or IIS Express AspNetCore Module in the Source column.

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

许多启动错误未在应用程序事件日志中生成有用信息。Many startup errors don't produce useful information in the Application Event Log. 可以通过在托管系统上在命令提示符处运行应用来找到某些错误的原因。You can find the cause of some errors by running the app at a command prompt on the hosting system.

依赖框架的部署Framework-dependent deployment

如果应用是依赖框架的部署If the app is a framework-dependent deployment:

  1. 在命令提示符处,导航到部署文件夹并通过使用 dotnet.exe 执行应用的程序集来运行应用。At a command prompt, navigate to the deployment folder and run the app by executing the app's assembly with dotnet.exe. 在以下命令中,替换 <assembly_name> 的应用程序集的名称:dotnet .\<assembly_name>.dllIn the following command, substitute the name of the app's assembly for <assembly_name>: dotnet .\<assembly_name>.dll.
  2. 来自应用且显示任何错误的控制台输出将写入控制台窗口。The console output from the app, showing any errors, is written to the console window.
  3. 如果向应用发出请求时出现错误,请向 Kestrel 侦听所在的主机和端口发出请求。If the errors occur when making a request to the app, make a request to the host and port where Kestrel listens. 如果使用默认主机和端口,请向 http://localhost:5000/ 发出请求。Using the default host and post, make a request to http://localhost:5000/. 如果应用在 Kestrel 终结点地址处正常响应,则问题更可能与承载配置相关,而不太可能在于应用。If the app responds normally at the Kestrel endpoint address, the problem is more likely related to the hosting configuration and less likely within the app.

独立部署Self-contained deployment

如果应用是独立部署If the app is a self-contained deployment:

  1. 在命令提示符处,导航到部署文件夹并运行应用的可执行文件。At a command prompt, navigate to the deployment folder and run the app's executable. 在以下命令中,替换 <assembly_name> 的应用程序集的名称:<assembly_name>.exeIn the following command, substitute the name of the app's assembly for <assembly_name>: <assembly_name>.exe.
  2. 来自应用且显示任何错误的控制台输出将写入控制台窗口。The console output from the app, showing any errors, is written to the console window.
  3. 如果向应用发出请求时出现错误,请向 Kestrel 侦听所在的主机和端口发出请求。If the errors occur when making a request to the app, make a request to the host and port where Kestrel listens. 如果使用默认主机和端口,请向 http://localhost:5000/ 发出请求。Using the default host and post, make a request to http://localhost:5000/. 如果应用在 Kestrel 终结点地址处正常响应,则问题更可能与承载配置相关,而不太可能在于应用。If the app responds normally at the Kestrel endpoint address, the problem is more likely related to the hosting configuration and less likely within the app.

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

若要启用和查看 stdout 日志,请执行以下操作:To enable and view stdout logs:

  1. 在托管系统上导航到站点的部署文件夹。Navigate to the site's deployment folder on the hosting system.
  2. 如果 logs 文件夹不存在,请创建该文件夹。If the logs folder isn't present, create the folder. 有关如何启用 MSBuild 以在部署中自动创建 logs 文件夹的说明,请参阅目录结构主题。For instructions on how to enable MSBuild to create the logs folder in the deployment automatically, see the Directory structure topic.
  3. 编辑 web.config 文件。Edit the web.config file. 将“stdoutLogEnabled”设置为 true 并更改“stdoutLogFile”路径以指向 logs 文件夹(例如,.\logs\stdout)。Set stdoutLogEnabled to true and change the stdoutLogFile path to point to the logs folder (for example, .\logs\stdout). 路径中的 stdout 是日志文件名的前缀。stdout in the path is the log file name prefix. 创建日志时,将自动添加时间戳、进程 ID 和文件扩展名。A timestamp, process id, and file extension are added automatically when the log is created. 如果将 stdout 用作文件名的前缀,典型的日志文件将命名为“stdout_20180205184032_5412.log”。Using stdout as the file name prefix, a typical log file is named stdout_20180205184032_5412.log.
  4. 请确保应用程序池的标识具有对日志文件夹的写入权限。Ensure your application pool's identity has write permissions to the logs folder.
  5. 保存已更新的 web.config 文件。Save the updated web.config file.
  6. 向应用发出请求。Make a request to the app.
  7. 导航到 logs 文件夹。Navigate to the logs folder. 查找并打开最新的 stdout 日志。Find and open the most recent stdout log.
  8. 研究日志以查找错误。Study the log for errors.

故障排除完成后,禁用 stdout 日志记录:Disable stdout logging when troubleshooting is complete:

  1. 编辑 web.config 文件。Edit the web.config file.
  2. 将“stdoutLogEnabled”设置为 falseSet stdoutLogEnabled to false.
  3. 保存该文件。Save the file.

有关详细信息,请参阅 ASP.NET Core 模块For more information, see ASP.NET Core 模块.

警告

无法禁用 stdout 日志可能会导致应用或服务器出现故障。Failure to disable the stdout log can lead to app or server failure. 日志文件大小或创建的日志文件数没有限制。There's no limit on log file size or the number of log files created.

对于 ASP.NET Core 应用中的例程日志记录,使用限制日志文件大小和旋转日志的日志记录库。For routine logging in an ASP.NET Core app, use a logging library that limits log file size and rotates logs. 有关详细信息,请参阅第三方日志记录提供程序For more information, see third-party logging providers.

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

将以下处理程序设置添加到应用程序的web.config 文件, 以启用 ASP.NET Core 模块调试日志:Add the following handler settings to the app's web.config file to enable ASP.NET Core Module debug log:

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

确认为日志指定的路径存在,并且应用池的标识具有该位置的写入权限。Confirm that the path specified for the log exists and that the app pool's identity has write permissions to the location.

有关详细信息,请参阅 ASP.NET Core 模块For more information, see ASP.NET Core 模块.

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

ASPNETCORE_ENVIRONMENT 环境变量可以添加到 web.config 以在开发环境中运行应用。The ASPNETCORE_ENVIRONMENT environment variable can be added to web.config to run the app in the Development environment. 只要在应用启动时环境不被主机生成器上的 UseEnvironment 重写,设置环境变量就会在运行应用时显示“开发人员异常页面”。As long as the environment isn't overridden in app startup by UseEnvironment on the host builder, setting the environment variable allows the Developer Exception Page to appear when the app is run.

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

仅建议在未向 Internet 公开的暂存服务器和测试服务器上设置 ASPNETCORE_ENVIRONMENT 的环境变量。Setting the environment variable for ASPNETCORE_ENVIRONMENT is only recommended for use on staging and testing servers that aren't exposed to the Internet. 在故障排除后从 web.config 文件中删除环境变量。Remove the environment variable from the web.config file after troubleshooting. 有关设置 web.config 中的环境变量的信息,请参阅 aspNetCore 的 environmentVariables 子元素For information on setting environment variables in web.config, see environmentVariables child element of aspNetCore.

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

如果应用能够响应请求,则使用终端内联中间件从应用中获取请求、连接和其他数据。If an app is capable of responding to requests, obtain request, connection, and additional data from the app using terminal inline middleware. 有关详细信息和示例代码,请参阅解决 ASP.NET Core 项目For more information and sample code, see 解决 ASP.NET Core 项目.

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

故障转储是系统内存的快照, 可帮助确定应用崩溃、启动失败或应用速度缓慢的原因。A crash dump is a snapshot of the system's memory and can help determine the cause of an app crash, startup failure, or slow app.

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

Windows 错误报告 (WER) 中获取转储并进行分析:Obtain and analyze a dump from Windows Error Reporting (WER):

  1. 创建文件夹,将崩溃转储文件保存在 c:\dumpsCreate a folder to hold crash dump files at c:\dumps. 应用池必须对该文件夹具有写权限。The app pool must have write access to the folder.

  2. 运行 EnableDumps PowerShell 脚本Run the EnableDumps PowerShell script:

  3. 在造成崩溃的条件下运行应用。Run the app under the conditions that cause the crash to occur.

  4. 出现崩溃后,运行 DisableDumps PowerShell 脚本After the crash has occurred, run the DisableDumps PowerShell script:

在应用崩溃并完成转储收集后,即可正常终止应用。After an app crashes and dump collection is complete, the app is allowed to terminate normally. PowerShell 脚本会 WER 来按应用收集转储(最多收集 5 个)。The PowerShell script configures WER to collect up to five dumps per app.

警告

崩溃转储可能会占用大量磁盘空间(每个最多占用数 GB)。Crash dumps might take up a large amount of disk space (up to several gigabytes each).

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

如果应用挂起(停止响应但不崩溃)、在启动期间失败或者正常运行hangs,请参阅用户模式转储文件:选择最佳工具,以选择适合用于生成转储的工具。When an app hangs (stops responding but doesn't crash), fails during startup, or runs normally, see User-Mode Dump Files: Choosing the Best Tool to select an appropriate tool to produce the dump.

分析转储Analyze the dump

可采用几种方法来分析转储。A dump can be analyzed using several approaches. 有关详细信息,请参阅分析用户模式转储文件For more information, see Analyzing a User-Mode Dump File.

清除包缓存Clear package caches

有时, 在升级开发计算机上的 .NET Core SDK 或更改应用中的包版本后, 运行中的应用会立即失败。Sometimes a functioning app fails immediately after upgrading either the .NET Core SDK on the development machine or changing package versions within the app. 在某些情况下,不同的包可能在执行主要升级时中断应用。In some cases, incoherent packages may break an app when performing major upgrades. 可以按照以下说明来修复其中大部分问题:Most of these issues can be fixed by following these instructions:

  1. 删除 bin 和 obj 文件夹。Delete the bin and obj folders.

  2. 通过从命令行界面执行dotnet nuget locals all --clear来清除包缓存。Clear the package caches by executing dotnet nuget locals all --clear from a command shell.

    还可以通过nuget.exe工具和执行命令nuget locals all -clear来清除包缓存。Clearing package caches can also be accomplished with the nuget.exe tool and executing the command nuget locals all -clear. nuget.exe 不是与 Windows 桌面操作系统的捆绑安装,必须从 NuGet 网站中单独获取。nuget.exe isn't a bundled install with the Windows desktop operating system and must be obtained separately from the NuGet website.

  3. 还原并重新生成项目。Restore and rebuild the project.

  4. 重新部署应用之前, 请先删除服务器上部署文件夹中的所有文件。Delete all of the files in the deployment folder on the server prior to redeploying the app.

其他资源Additional resources

Azure 文档Azure documentation

Visual Studio 文档Visual Studio documentation

Visual Studio Code 文档Visual Studio Code documentation