在 Visual Studio 中调试 ASP.NET 或 ASP.NET Core 应用

可以在 Visual Studio 中调试 ASP.NET 和 ASP.NET Core 应用。 无论是在 IIS Express 还是在本地 IIS 服务器上运行,ASP.NET 和 ASP.NET Core 的调试过程都不同。

注意

以下步骤和设置仅适用于在本地服务器上调试应用。 在远程 IIS 服务器上调试应用使用“附加到进程”,并忽略这些设置。 有关在 IIS 上远程调试 ASP.NET 应用的详细信息和说明,请参阅在 IIS 计算机上远程调试 ASP.NET在远程 IIS 计算机上远程调试 ASP.NET Core

Visual Studio 中内置了 Kestrel 和 IIS Express 服务器。 Kestrel 是 ASP.NET Core 项目的默认调试服务器,并且是预先配置的。 IIS Express 是 ASP.NET 的默认调试服务器。

Visual Studio 中内置了 IIS Express 服务器。 IIS Express 是 ASP.NET 和 ASP.NET Core 项目的默认调试服务器,并且是预先配置的。 这是最简单的调试方法,也是初始调试和测试的理想选择。

对于 ASP.NET Core,还可以在 Kestrel Web 服务器上进行调试。

本地 IIS 服务器的先决条件

你还可以在配置为运行该应用的本地 IIS 服务器(8.0 或更高版本)上调试 ASP.NET 或 ASP.NET Core 应用。 要在本地 IIS 上调试,必须满足以下要求:

  • 如果未安装,请安装“ASP.NET 和 Web 开发”工作负载。 (重新运行 Visual Studio 安装程序,选择“修改”,然后添加此工作负载。)

  • 以管理员身份运行 Visual Studio。

  • 使用适当版本的 ASP.NET 和/或 ASP.NET Core 安装并正确配置 IIS。 若要详细了解如何结合使用 IIS 和 ASP.NET Core,请参阅使用 IIS 在 Windows 上托管 ASP.NET Core。 有关 ASP.NET,请参阅安装 IIS 和 ASP.NET 模块

  • 请确保应用在 IIS 上运行且未出现错误。

调试 ASP.NET Core 应用

可能存在基于 https 的默认配置文件或基于项目名称的默认配置文件,该配置文件是为 Kestrel Web 服务器配置的。 如果要在本地 IIS 上进行调试,请确保满足本地 IIS 调试的先决条件

  1. 在 Visual Studio“解决方案资源管理器”中,选择 ASP.NET Core 项目,然后单击“属性”图标,或按 Alt+Enter,或右键单击并选择“属性”。

  2. 选择“调试”选项卡,然后单击链接以打开“打开调试启动配置文件 UI”。

    显示的 UI 对应于项目的 launchSettings.json 文件中的设置。 有关此文件的详细信息,请参阅在 ASP.NET Core 中使用多个环境中的“开发”和 launchSettings.json 部分。

  3. 选择要配置的配置文件进行调试。

    • 对于 Kestrel,请选择 https 配置文件或以项目命名的配置文件。
    • 对于 IIS Express,请从下拉列表中选择 IIS Express。
    • 对于本地 IIS,请选择“新建”并创建新的 IIS 配置文件。
  4. 确保选中“启动浏览器”。

  5. 确保“URL”、“应用 URL” 和“应用 SSL URL”正确。

    “URL”指定 .NET 或 .NET Core 的主机 URL 的位置。 对于根据项目命名的配置文件(即 launchSettings.json 中的 commandName 属性为 Project),Kestrel 服务器侦听指定的端口。 对于 IIS 配置文件,此值通常与“应用 URL”相同。 有关详细信息,请参阅配置项目下的 IIS 启动配置文件部分。

    “应用 URL”和“应用 SSL URL”指定应用程序 URL。 对于根据项目命名的配置文件,此属性指定 Kestrel 服务器 URL,通常为 https://localhost:5001http://localhost:5000。 对于 IIS Express,“应用 SSL URL”通常为 http://localhost:44334

  6. 在“环境变量”下,确保 ASPNETCORE_ENVIRONMENT 显示了值“开发” 。 否则,请添加变量。

    ASP.NET Core 调试器设置

    有关环境变量的详细信息,请参阅环境

  7. 要调试应用,请在项目中的某些代码上设置断点。 在 Visual Studio 工具栏中,确保将配置设置为“调试”。

  8. 若要开始调试,请在工具栏中选择配置文件名称(如https、IIS Express 或 <>工具栏中的 IIS 配置文件名称,),从“调试”菜单中选择“开始调试”,或按 F5。 调试器在断点处暂停。 如果调试器无法命中断点,请参阅调试疑难解答

调试 ASP.NET Core 应用

IIS Express 是默认选择,并且是预先配置的。 如果要在本地 IIS 上调试,请确保满足本地 IIS 调试的要求

  1. 在 Visual Studio“解决方案资源管理器”中,选择 ASP.NET Core 项目,然后单击“属性”图标,或按 Alt+Enter,或右键单击并选择“属性”。

  2. 选择“调试”选项卡。

  3. 在“属性”窗格中的“配置文件”旁边 ,

    • 对于 IIS Express,请从下拉列表中选择 IIS Express。
    • 对于本地 IIS,请从下拉列表中选择应用名称,或选择“新建”,创建新的配置文件名称,然后选择“确定” 。
  4. 在“启动”旁边,从下拉列表中选择 IIS Express 或 IIS 。

  5. 确保选中“启动浏览器”。

  6. 在“环境变量”下,确保 ASPNETCORE_ENVIRONMENT 显示了值“开发” 。 否则,请选择“添加”进行添加。

    ASP.NET Core 调试器设置

  7. 使用“文件”>“保存选定项”或 Ctrl+S 来保存更改 。

  8. 要调试应用,请在项目中的某些代码上设置断点。 在 Visual Studio 工具栏中,确保将配置设置为“调试”,且 IIS Express 或新的 IIS 配置文件名称显示在模拟器字段中 。

  9. 若要开始调试,请在工具栏中选择“IIS Express”或“<IIS 配置文件名称>”,从“调试”菜单中选择“开始调试”,或按 F5。 调试器在断点处暂停。 如果调试器无法命中断点,请参阅调试疑难解答

调试 ASP.NET 应用

IIS Express 是默认选择,并且是预先配置的。 如果要在本地 IIS 上调试,请确保满足本地 IIS 调试的要求

  1. 在 Visual Studio“解决方案资源管理器”中,选择 ASP.NET 项目,然后单击“属性”图标,或按 Alt+Enter,或右键单击并选择“属性”。

  2. 选择 Web 选项卡。

    如果没有看到“Web”选项卡,请参阅调试 ASP.NET Core 应用。 “Web”选项卡仅在 ASP.NET Framework 中显示。

  3. 在“属性”窗格中的“服务器”下 ,

    • 对于 Kestrel,请从下拉列表中选择 https
    • 对于 IIS Express,请从下拉列表中选择 IIS Express。
    • 对于本地 IIS,
      1. 请从下拉列表中选择“本地 IIS”。
      2. 如果尚未在 IIS 中设置应用,请在“项目 URL”字段旁边选择“创建虚拟目录” 。
  4. 在“调试器”下,选择 ASP.NET 。

    显示 ASP.NET 调试器设置的屏幕截图。

  5. 依次选择“文件”>“保存选定项”(或按 Ctrl+S),以保存所有更改。

  6. 要调试应用,请在项目中的某些代码上设置断点。 在 Visual Studio 工具栏中,确保将配置设置为“调试”,所需的浏览器将出现在模拟器字段中的“IIS Express (<浏览器名称>)”或“本地 IIS (<浏览器名称>)”中。

  7. 若要开始调试,请在工具栏中选择“IIS Express (<浏览器名称>)”或“本地 IIS (<浏览器名称>)”,从“调试”菜单中选择“开始调试”,或按 F5。 调试器在断点处暂停。 如果调试器无法命中断点,请参阅调试疑难解答

调试疑难解答

如果本地 IIS 调试无法进行到断点,请按照以下步骤进行故障排除。

  1. 从 IIS 启动 Web 应用,并确保其正常运行。 使 Web 应用保持运行状态。

  2. 在 Visual Studio 中,选择“调试”>“附加到进程”或按 Ctrl+Alt+P,并连接到 ASP.NET 或 ASP.NET Core 进程(通常为 w3wp.exe 或 dotnet.exe)。 有关详细信息,请参阅附加到进程如何查找 ASP.NET 进程名称

如果可以通过使用“附加到进程”来连接和命中断点,但不能通过使用“调试”>“启动调试”或 F5 来连接和命中断点,则项目属性中的设置可能不正确 。 如果使用 HOSTS 文件,请确保其配置正确。

在 web.config 文件中配置调试

ASP.NET 项目默认有 web.config 文件,其中包含应用配置、启动信息和调试设置。 必须正确配置 web.config 文件才能进行调试。 可通过前面部分的“属性”设置来更新 web.config 文件,但也可手动配置。

注意

ASP.NET Core 项目最初没有 web.config 文件,但使用 appsettings.jsonlaunchSettings.json 文件来提供应用配置和启动信息。 部署应用会在项目中创建一个或多个 web.config 文件,但这些文件通常不包含调试信息。

提示

部署进程可能会更新 web.config 设置,因此,在尝试调试之前,请确保已将 web.config 配置为用于调试。

要手动配置 web.config 文件以进行调试,请执行以下操作:

  1. 在 Visual Studio 中,打开 ASP.NET 项目的 web.config 文件。

  2. Web.config 是一个 XML 文件,嵌套部分用标记标识。 找到 configuration/system.web/compilation 部分。 (如果 compilation 元素不存在,请创建一个。)

  3. 确保 compilation 元素中的 debug 属性设置为 true。 (如果 compilation 元素不包含 debug 属性,请添加该元素并将其设置为 true。)

    如果使用本地 IIS 而不是默认 IIS Express 服务器,请确保 compilation 元素中的 targetFramework 属性值与 IIS 服务器上的框架一致。

    web.config 文件的 compilation 元素应类似于下面的示例:

    注意

    此示例仅展示部分 web.config 文件。 configurationsystem.web 元素中通常还有其他 XML 部分,compilation 元素也可能包含其他属性和元素。

    <configuration>
       ...
       <system.web>
           <compilation  debug="true"  targetFramework="4.6.1" ... >
              ...
           </compilation>
       </system.web>
    </configuration>
    

ASP.NET 会自动检测对 web.config 文件的任何更改,并应用新的配置设置。 更改立即生效,不必重启计算机或 IIS 服务器。

一个网站可包含多个虚拟目录和子目录,其中每个目录中都有 web.config 文件。 ASP.NET 应用从 URL 路径中更高级别的 web.config 文件继承配置设置。 分层 web.config 文件设置应用于层次结构中的所有下级 ASP.NET 应用。 在层次结构下较低级别的 web.config 文件中设置其他配置将覆盖较高级别文件中的设置。

例如,如果在 www\.microsoft.com/aaa/web.config 中指定 debug="true",则 aaa 文件夹或 aaa 任何子文件夹中的任何应用都将继承该设置,除非其中一个应用使用自己的 web.config 文件覆盖设置。

重要

调试模式会极大地降低应用的性能。 在部署生产应用或执行性能度量时,请在 web.config 中设置 debug="false",并指定发布版本。