.NET 应用中发生异常时的调试快照Debug snapshots on exceptions in .NET apps

发生异常时,可自动从实时 Web 应用程序收集调试快照。When an exception occurs, you can automatically collect a debug snapshot from your live web application. 快照显示发生异常时源代码和变量的状态。The snapshot shows the state of source code and variables at the moment the exception was thrown. Azure Application Insights 中的 Snapshot Debugger 可以监视来自 Web 应用的异常遥测。The Snapshot Debugger in Azure Application Insights monitors exception telemetry from your web app. 它可收集常出现的异常的调试快照,为诊断生产中的问题提供所需信息。It collects snapshots on your top-throwing exceptions so that you have the information you need to diagnose issues in production. 请将快照收集器 NuGet 包添加到应用程序,并按需在 ApplicationInsights.config 中配置收集参数。快照显示在 Application Insights 门户中的异常区域中。Include the Snapshot collector NuGet package in your application, and optionally configure collection parameters in ApplicationInsights.config. Snapshots appear on exceptions in the Application Insights portal.

可在门户中查看调试快照,查看调用堆栈并检查每个调用堆栈帧中的变量。You can view debug snapshots in the portal to see the call stack and inspect variables at each call stack frame. 若要获取更强大的调试体验与源代码,请在 Visual Studio 2019 Enterprise 中打开快照。To get a more powerful debugging experience with source code, open snapshots with Visual Studio 2019 Enterprise. 在 Visual Studio 中,还可以将快照设置为以交互方式拍摄快照,而无需等待异常。In Visual Studio, you can also set Snappoints to interactively take snapshots without waiting for an exception.

调试快照将存储 15 天。Debug snapshots are stored for 15 days. 此保留策略是逐个应用程序进行设置。This retention policy is set on a per-application basis. 如果需要,可以在 Azure 门户中打开支持案例,以请求增加此值。If you need to increase this value, you can request an increase by opening a support case in the Azure portal.

为你的应用程序启用 Application Insights 快照调试器Enable Application Insights Snapshot Debugger for your application

快照集合可用于:Snapshot collection is available for:

  • 运行 .NET Framework 4.5 或更高版本的 .NET Framework 和 ASP.NET 应用程序。.NET Framework and ASP.NET applications running .NET Framework 4.5 or later.
  • 在 Windows 上运行的 .NET Core 2.0 和 ASP.NET Core 2.0 应用程序。.NET Core 2.0 and ASP.NET Core 2.0 applications running on Windows.

支持以下环境:The following environments are supported:

备注

不支持客户端应用程序(例如,WPF、Windows 窗体或 UWP)。Client applications (for example, WPF, Windows Forms or UWP) are not supported.

如果已启用快照调试器但未看到快照,请查看故障排除指南If you've enabled Snapshot Debugger but aren't seeing snapshots, check our Troubleshooting guide.

授予权限Grant permissions

对快照的访问受基于角色的访问控制 (RBAC) 的保护。Access to snapshots is protected by role-based access control (RBAC). 若要检查快照,必须先由订阅所有者将你添加到必需的角色。To inspect a snapshot, you must first be added to the necessary role by a subscription owner.

备注

所有者和参与者不会自动具有此角色。Owners and contributors do not automatically have this role. 如果他们想要查看快照,他们必须将自己添加到此角色。If they want to view snapshots, they must add themselves to the role.

订阅所有者应将 Application Insights Snapshot Debugger 角色分配给要检查快照的用户。Subscription owners should assign the Application Insights Snapshot Debugger role to users who will inspect snapshots. 订阅所有者可将该角色分配给目标 Application Insights 资源或其资源组或订阅的各个用户或组。This role can be assigned to individual users or groups by subscription owners for the target Application Insights resource or its resource group or subscription.

  1. 在 Azure 门户中导航到 Application Insights 资源。Navigate to the Application Insights resource in the Azure portal.
  2. 单击“访问控制(IAM)” 。Click Access control (IAM).
  3. 单击“+添加角色分配”按钮 。Click the +Add role assignment button.
  4. 从“角色”下拉列表中,选择“Application Insights 快照调试程序” 。Select Application Insights Snapshot Debugger from the Roles drop-down list.
  5. 搜索并输入要添加的用户的名称。Search for and enter a name for the user to add.
  6. 单击“保存”按钮将用户添加到角色 。Click the Save button to add the user to the role.

重要

快照的变量和参数值中可能包含个人信息和其他敏感信息。Snapshots can potentially contain personal and other sensitive information in variable and parameter values.

在门户中查看快照View Snapshots in the Portal

在应用程序中发生异常并创建快照后,你应当会有可查看的快照。After an exception has occurred in your application and a snapshot has been created, you should have snapshots to view. 从发生异常到快照准备就绪并可从门户查看可能需要花费 5 到 10 分钟时间。It can take 5 to 10 minutes from an exception occurring to a snapshot ready and viewable from the portal. 若要查看快照,在“失败” 窗格中,在查看“操作” 选项卡时选择“操作” 按钮,或者在查看“异常” 选项卡时选择“异常” 按钮:To view snapshots, in the Failure pane, select the Operations button when viewing the Operations tab, or select the Exceptions button when viewing the Exceptions tab:

“失败”页面

在右侧窗格中选择一个操作或异常以打开“端到端事务详细信息” 窗格,然后选择异常事件。Select an operation or exception in the right pane to open the End-to-End Transaction Details pane, then select the exception event. 如果有某个快照可用于给定的异常,则包含该异常的详细信息的右窗格上会显示一个“打开调试快照”按钮 。If a snapshot is available for the given exception, an Open Debug Snapshot button appears on the right pane with details for the exception.

异常区域中的“打开调试快照”按钮

在“调试快照”视图中,可以看到调用堆栈和变量窗格。In the Debug Snapshot view, you see a call stack and a variables pane. 当在调用堆栈窗格中选择调用堆栈帧时,可在变量窗格中查看该函数调用的局部变量和参数。When you select frames of the call stack in the call stack pane, you can view local variables and parameters for that function call in the variables pane.

在门户中查看调试快照

快照可能包含敏感信息,默认情况下不可查看。Snapshots might include sensitive information, and by default they aren't viewable. 要查看快照,必须获取 Application Insights Snapshot Debugger 角色。To view snapshots, you must have the Application Insights Snapshot Debugger role assigned to you.

在 Visual Studio 2017 Enterprise 或更高版本中查看快照View Snapshots in Visual Studio 2017 Enterprise or above

  1. 单击“下载快照” 按钮以下载一个 .diagsession 文件,可在 Visual Studio 2017 Enterprise 中打开该文件。Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio Enterprise.

  2. 若要打开 .diagsession 文件,需要安装 Visual Studio Snapshot Debugger 组件。To open the .diagsession file, you need to have the Snapshot Debugger Visual Studio component installed. Snapshot Debugger 组件是 Visual Studio 中 ASP.net 工作负载的必需组件,可以从 Visual Studio 安装程序中的单独组件列表中选择。The Snapshot Debugger component is a required component of the ASP.net workload in Visual Studio and can be selected from the Individual Component list in the Visual Studio installer. 如果你使用的是 Visual Studio 2017 版本 15.5 之前的 Visual Studio 版本,则需要从 Visual Studio Marketplace 安装扩展。If you are using a version of Visual Studio prior to Visual Studio 2017 version 15.5, you will need to install the extension from the Visual Studio Marketplace.

  3. 打开快照文件后,将出现 Visual Studio 中的“小型转储调试”页面。After you open the snapshot file, the Minidump Debugging page in Visual Studio appears. 单击“调试托管代码”开始调试快照 。Click Debug Managed Code to start debugging the snapshot. 快照将打开到引发异常的代码行,以便可以调试进程的当前状态。The snapshot opens to the line of code where the exception was thrown so that you can debug the current state of the process.

    在 Visual Studio 中查看调试快照

下载的快照中包含在 Web 应用程序服务器上找到的所有符号文件。The downloaded snapshot includes any symbol files that were found on your web application server. 需要使用这些符号文件将快照数据与源代码相关联。These symbol files are required to associate snapshot data with source code. 对于应用服务应用,请确保在发布 Web 应用时启用符号部署。For App Service apps, make sure to enable symbol deployment when you publish your web apps.

快照的工作原理How snapshots work

快照收集器以 Application Insights 遥测处理器的形式实现。The Snapshot Collector is implemented as an Application Insights Telemetry Processor. 应用程序运行时,会将快照收集器遥测处理器添加到应用程序的遥测管道中。When your application runs, the Snapshot Collector Telemetry Processor is added to your application's telemetry pipeline. 每次应用程序调用 TrackException 时,快照收集器都会根据引发的异常类型和引发方法计算问题 ID。Each time your application calls TrackException, the Snapshot Collector computes a Problem ID from the type of exception being thrown and the throwing method. 每次应用程序调用 TrackException 时,计数器都会递增以获得相应的问题 ID。Each time your application calls TrackException, a counter is incremented for the appropriate Problem ID. 当计数器达到 ThresholdForSnapshotting 值时,问题 ID 将添加到收集计划。When the counter reaches the ThresholdForSnapshotting value, the Problem ID is added to a Collection Plan.

快照收集器还通过订阅 AppDomain.CurrentDomain.FirstChanceException 事件来监视引发的异常。The Snapshot Collector also monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event. 当该事件触发时,将计算异常的问题 ID 并将其与收集计划中的问题 ID 进行比较。When that event fires, the Problem ID of the exception is computed and compared against the Problem IDs in the Collection Plan. 如果匹配,则将创建正在运行的进程的快照。If there's a match, then a snapshot of the running process is created. 将为快照分配一个唯一标识符,并使用该标识符标记异常。The snapshot is assigned a unique identifier and the exception is stamped with that identifier. FirstChanceException 处理程序返回后,将按正常方式处理引发的异常。After the FirstChanceException handler returns, the thrown exception is processed as normal. 最终,异常会再次到达 TrackException 方法,该方法将异常与快照标识符一起报告给 Application Insights。Eventually, the exception reaches the TrackException method again where it, along with the snapshot identifier, is reported to Application Insights.

主进程会继续运行并向用户提供流量,几乎没有中断。The main process continues to run and serve traffic to users with little interruption. 同时,快照将传递给快照上传程序进程。Meanwhile, the snapshot is handed off to the Snapshot Uploader process. 快照上传程序会创建一个小型转储并将其连同任何相关的符号 (.pdb) 文件一起上传到 Application Insights。The Snapshot Uploader creates a minidump and uploads it to Application Insights along with any relevant symbol (.pdb) files.

提示

  • 进程快照是正在运行的进程的暂停克隆。A process snapshot is a suspended clone of the running process.
  • 创建快照大约需要 10 到 20 毫秒。Creating the snapshot takes about 10 to 20 milliseconds.
  • ThresholdForSnapshotting 的默认值为 1。The default value for ThresholdForSnapshotting is 1. 这也是最小值。This is also the minimum value. 因此,在创建快照之前,应用程序必须触发相同的异常两次Therefore, your app has to trigger the same exception twice before a snapshot is created.
  • 如果想要在 Visual Studio 中调试时生成快照,请将 IsEnabledInDeveloperMode 设置为 true。Set IsEnabledInDeveloperMode to true if you want to generate snapshots while debugging in Visual Studio.
  • 快照创建速率受 SnapshotsPerTenMinutesLimit 设置的限制。The snapshot creation rate is limited by the SnapshotsPerTenMinutesLimit setting. 默认情况下,限制为每十分钟一个快照。By default, the limit is one snapshot every ten minutes.
  • 每天不超过 50 张的快照可以上传。No more than 50 snapshots per day may be uploaded.

限制Limitations

默认数据保留期为 15 天。The default data retention period is 15 days. 对于每个 Application Insights 实例,每天最多允许 50 个快照。For each Application Insights instance, a maximum number of 50 snapshots is allowed per day.

发布符号Publish symbols

快照调试程序要求符号文件位于生产服务器上,这样它才能在 Visual Studio 中解码变量并提供调试体验。The Snapshot Debugger requires symbol files on the production server to decode variables and to provide a debugging experience in Visual Studio. 默认情况下,在发布到应用服务时,Visual Studio 2017 版本 15.2(或更高版本)会发布适用于发行版本的符号。Version 15.2 (or above) of Visual Studio 2017 publishes symbols for release builds by default when it publishes to App Service. 在以前的版本中,需要将以下代码行添加到发布配置文件 .pubxml,以便在发布模式下发布符号:In prior versions, you need to add the following line to your publish profile .pubxml file so that symbols are published in release mode:

    <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

对于 Azure 计算和其他类型,请确保符号文件位于主应用程序 .dll 所在的同一文件夹(通常为 wwwroot/bin)中,或者可通过当前路径访问。For Azure Compute and other types, make sure that the symbol files are in the same folder of the main application .dll (typically, wwwroot/bin) or are available on the current path.

优化的内部版本Optimized builds

在某些情况下,由于 JIT 编译器应用了优化,无法在发布版本中查看局部变量。In some cases, local variables can't be viewed in release builds because of optimizations that are applied by the JIT compiler. 但是,在 Azure 应用服务中,快照收集器可以对属于其收集计划的引发方法取消优化。However, in Azure App Services, the Snapshot Collector can deoptimize throwing methods that are part of its Collection Plan.

提示

在应用服务中安装 Application Insights 站点扩展可获得取消优化支持。Install the Application Insights Site Extension in your App Service to get deoptimization support.

后续步骤Next steps

为你的应用程序启用 Application Insights 快照调试器:Enable Application Insights Snapshot Debugger for your application:

Application Insights 快照调试器之外的功能:Beyond Application Insights Snapshot Debugger: