通过

.NET 应用中发生异常时的调试快照

  • 项目

发生异常时，可自动从实时 Web 应用程序收集调试快照。 快照显示发生异常时源代码和变量的状态。 Azure Application Insights 中的 Snapshot Debugger 可以监视来自 Web 应用的异常遥测。 它可收集常出现的异常的调试快照，为诊断生产中的问题提供所需信息。 请将快照收集器 NuGet 包添加到应用程序，并按需在 ApplicationInsights.config 中配置收集参数。快照显示在 Application Insights 门户中的异常区域中。

可在门户中查看调试快照，查看调用堆栈并检查每个调用堆栈帧中的变量。 若要获取更强大的调试体验与源代码，请在 Visual Studio 2019 Enterprise 中打开快照。 在 Visual Studio 中，还可以将快照设置为以交互方式拍摄快照，而无需等待异常。

调试快照将存储 15 天。 此保留策略是逐个应用程序进行设置。 如果需要，可以在 Azure 门户中打开支持案例，以请求增加此值。

为你的应用程序启用 Application Insights 快照调试器

快照集合可用于：

  • .NET Framework 和运行 .NET Framework LTS 或更高版本的 ASP.NET 应用程序。
  • .NET Core 和在 Windows 上运行 NET Core LTS 的 ASP.NET Core 应用程序。
  • Windows 上的 .NET LTS 应用程序。

不建议使用早于 LTS 的 .NET Core 版本，因为它们不受支持。

支持以下环境：

注意

不支持客户端应用程序（例如，WPF、Windows 窗体或 UWP）。

如果已启用快照调试器但未看到快照，请查看故障排除指南。

授予权限

对快照的访问受 Azure 基于角色的访问控制 (Azure RBAC) 的保护。 若要检查快照，必须先由订阅所有者将你添加到必需的角色。

注意

所有者和参与者不会自动具有此角色。 如果他们想要查看快照，他们必须将自己添加到此角色。

订阅所有者应将 Application Insights Snapshot Debugger 角色分配给要检查快照的用户。 订阅所有者可将该角色分配给目标 Application Insights 资源或其资源组或订阅的各个用户或组。

  1. 将调试器角色分配给应用程序见解快照。

    有关详细步骤，请参阅使用 Azure 门户分配 Azure 角色。

重要

请注意，快照可能在变量值和参数值中包含个人数据或其他敏感信息。 快照数据与 App Insights 资源存储在同一区域中。

在门户中查看快照

在应用程序中发生异常并创建快照后，你应当会有可查看的快照。 从发生异常到快照准备就绪并可从门户查看可能需要花费 5 到 10 分钟时间。 若要查看快照，在“失败” 窗格中，在查看“操作” 选项卡时选择“操作” 按钮，或者在查看“异常” 选项卡时选择“异常” 按钮：

Failures Page

在右侧窗格中选择一个操作或异常以打开“端到端事务详细信息” 窗格，然后选择异常事件。 如果有某个快照可用于给定的异常，则包含该异常的详细信息的右窗格上会显示一个“打开调试快照”按钮 。

Open Debug Snapshot button on exception

在“调试快照”视图中，可以看到调用堆栈和变量窗格。 当在调用堆栈窗格中选择调用堆栈帧时，可在变量窗格中查看该函数调用的局部变量和参数。

View Debug Snapshot in the portal

快照可能包含敏感信息，默认情况下不可查看。 要查看快照，必须获取 Application Insights Snapshot Debugger 角色。

在 Visual Studio 2017 Enterprise 或更高版本中查看快照

  1. 单击“下载快照” 按钮以下载一个 .diagsession 文件，可在 Visual Studio 2017 Enterprise 中打开该文件。

  2. 若要打开 .diagsession 文件，需要安装 Visual Studio Snapshot Debugger 组件。 Snapshot Debugger 组件是 Visual Studio 中 ASP.NET 工作负载的必需组件，可以从 Visual Studio 安装程序中的单独组件列表中选择。 如果使用的是 Visual Studio 2017 版本 15.5 之前的 Visual Studio 版本，则需要从 Visual Studio Marketplace 安装扩展。

  3. 打开快照文件后，将出现 Visual Studio 中的“小型转储调试”页面。 单击“调试托管代码”开始调试快照 。 快照将打开到引发异常的代码行，以便可以调试进程的当前状态。

    View debug snapshot in Visual Studio

下载的快照中包含在 Web 应用程序服务器上找到的所有符号文件。 需要使用这些符号文件将快照数据与源代码相关联。 对于应用服务应用，请确保在发布 Web 应用时启用符号部署。

快照的工作原理

快照收集器以 Application Insights 遥测处理器的形式实现。 应用程序运行时，会将快照收集器遥测处理器添加到应用程序的遥测管道中。 每次应用程序调用 TrackException 时，快照收集器都会根据引发的异常类型和引发方法计算问题 ID。 每次应用程序调用 TrackException 时，计数器都会递增以获得相应的问题 ID。 当计数器达到 ThresholdForSnapshotting 值时，问题 ID 将添加到收集计划。

快照收集器还通过订阅 AppDomain.CurrentDomain.FirstChanceException 事件来监视引发的异常。 当该事件触发时，将计算异常的问题 ID 并将其与收集计划中的问题 ID 进行比较。 如果匹配，则将创建正在运行的进程的快照。 将为快照分配一个唯一标识符，并使用该标识符标记异常。 FirstChanceException 处理程序返回后，将按正常方式处理引发的异常。 最终，异常会再次到达 TrackException 方法，该方法将异常与快照标识符一起报告给 Application Insights。

主进程会继续运行并向用户提供流量，几乎没有中断。 同时，快照将传递给快照上传程序进程。 快照上传程序会创建一个小型转储并将其连同任何相关的符号 (.pdb) 文件一起上传到 Application Insights。

提示

  • 进程快照是正在运行的进程的暂停克隆。
  • 创建快照大约需要 10 到 20 毫秒。
  • ThresholdForSnapshotting 的默认值为 1。 这也是最小值。 因此，在创建快照之前，应用程序必须触发相同的异常两次。
  • 如果想要在 Visual Studio 中调试时生成快照，请将 IsEnabledInDeveloperMode 设置为 true。
  • 快照创建速率受 SnapshotsPerTenMinutesLimit 设置的限制。 默认情况下，限制为每十分钟一个快照。
  • 每天不超过 50 张的快照可以上传。

限制

默认数据保留期为 15 天。 对于每个 Application Insights 实例，每天允许的最大快照数为 50。

发布符号

快照调试程序要求符号文件位于生产服务器上，这样它才能在 Visual Studio 中解码变量并提供调试体验。 默认情况下，在发布到应用服务时，Visual Studio 2017 版本 15.2（或更高版本）会发布适用于发行版本的符号。 在以前的版本中，需要将以下代码行添加到发布配置文件 .pubxml，以便在发布模式下发布符号：

    <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

对于 Azure 计算和其他类型，请确保符号文件位于主应用程序 .dll 所在的同一文件夹（通常为 wwwroot/bin）中，或者可通过当前路径访问。

注意

有关可用的不同符号选项的详细信息，请参阅 Visual Studio 文档。 为了获得最佳结果，建议使用“完整”、“可移植”或“嵌入”。

优化的内部版本

在某些情况下，由于 JIT 编译器应用了优化，无法在发布版本中查看局部变量。 但是，在 Azure 应用服务中，快照收集器可以对属于其收集计划的引发方法取消优化。

提示

在应用服务中安装 Application Insights 站点扩展可获得取消优化支持。

后续步骤

为你的应用程序启用 Application Insights 快照调试器：

Application Insights 快照调试器之外的功能：