你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Snapshot Debugger 调试 .NET 应用程序中的异常

  • 项目

使用 Snapshot Debugger，可以在实时 .NET 应用程序中发生异常时自动收集调试快照。 收集的调试快照显示引发异常时源代码和变量的状态。

Application Insights 中的 Snapshot Debugger：

  • 监视 Web 应用中系统生成的日志。
  • 收集最常引发的异常的快照。
  • 提供诊断生产问题所需的信息。

详细了解 Snapshot Debugger 和 Snapshot Uploader 进程。

支持的应用程序和环境

本部分列出了受支持的应用程序和环境。

应用程序

快照集合可用于：

环境

支持以下环境：

注意

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

使用 Snapshot Debugger 的先决条件

包和配置

权限

Snapshot Debugger 的工作原理

Snapshot Debugger 将以 Application Insights 遥测处理器的形式实现。 在应用程序运行时，会将 Snapshot Debugger 遥测处理器添加到应用程序的系统生成的日志管道中。

重要

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

Snapshot Debugger 进程

Snapshot Debugger 进程以 TrackException 方法开始和结束。 进程快照是正在运行的进程的挂起克隆，因此用户几乎不会遇到任何中断。

  1. 应用程序引发 TrackException。

  2. Snapshot Debugger 通过订阅 AppDomain.CurrentDomain.FirstChanceException 事件来监视引发的异常。

  3. 针对问题 ID 递增计数器。

    • 当计数器达到 ThresholdForSnapshotting 值时，问题 ID 将添加到收集计划。

    注意

    ThresholdForSnapshotting 默认最小值为 1。 使用此值，在创建快照之前，应用必须触发相同的异常两次。

  4. 将计算异常事件的问题 ID，并将其与收集计划中的问题 ID 进行比较。

  5. 如果问题 ID 匹配，则将创建正在运行的进程的快照。

    • 将为快照分配一个唯一标识符，并使用该标识符标记异常。

    注意

    快照创建速率受 SnapshotsPerTenMinutesLimit 设置的限制。 默认情况下，限制为 10 分钟一个快照。

  6. FirstChanceException 处理程序返回后，将按正常方式处理引发的异常。

  7. 异常会再次到达 TrackException 方法，该方法会将异常与快照标识符一起报告给 Application Insights。

注意

如果想要在 Visual Studio 中进行调试时生成快照，请将 IsEnabledInDeveloperMode 设置为 true。

Snapshot Uploader 进程

当 Snapshot Debugger 进程继续运行并在几乎没有中断的情况下为用户提供流量时，快照将移交给 Snapshot Uploader 进程。 Snapshot Uploader：

  1. 创建小型转储。

  2. 将小型转储和任何相关的符号 (.pdb) 文件一起上传到 Application Insights。

注意

每天可以上传不超过 50 个快照。

如果已启用 Snapshot Debugger 但未看到快照，请参阅故障排除指南。

限制

本部分将讨论适用于 Snapshot Debugger 的限制。

  • 数据保留

    调试快照将存储 15 天。 默认数据保留策略基于每个应用程序进行设置。 如果需要，可以在 Azure 门户中打开支持案例，以请求增加此值。 对于每个 Application Insights 实例，每天允许的最大快照数为 50。

  • 发布符号

    Snapshot Debugger 需要生产服务器上的符号文件才能：

    • 解码变量
    • 在 Visual Studio 中提供调试体验

    默认情况下，在发布到应用服务时，Visual Studio 2017 版本 15.2+ 会发布适用于发行版本的符号。

    在以前的版本中，必须将以下行添加到发布配置文件 .pubxml 文件中，以便在发布模式下发布符号：

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    对于 Azure Compute 和其他类型，请确保符号文件：

    • 位于主应用程序 .dll 所在的同一文件夹中（通常为 wwwroot/bin），或
    • 在当前路径上可用。

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

  • 优化的内部版本

    在某些情况下，由于 JIT 编译器应用的优化，无法在发布版本中查看局部变量。

    但在应用服务中，Snapshot Debugger 可以取消对属于其收集计划的引发方法的优化。

    提示

    在应用服务实例中安装 Application Insights 站点扩展，以获取关于取消优化的支持。

后续步骤

为你的应用程序启用 Application Insights Snapshot Debugger：

Microsoft.ApplicationInsights.SnapshotCollector 发行说明

本部分包含适用于 .NET 应用程序的 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包（由 Application Insights Snapshot Debugger 使用）的发行说明。

详细了解适用于 .NET 应用程序的 Application Insights Snapshot Debugger。

要报告 Bug 和提交反馈，请在 GitHub 上提出问题。

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。 检测密钥引入功能将会继续工作，但我们将不再为该功能提供更新或支持。 转换为连接字符串，以利用新功能。

1.4.6

可解决使用 .NET 8 应用程序时的回归问题的点发布。

缺陷修复

  • 未正确跟踪 .NET 8 中动态生成的方法（例如已编译的表达式树）引发的异常。 固定。

1.4.5

用于解决用户报告的 bug 的单点版本。

Bug 修复

  • 修复了在读取某些 PDB 时出现的 AccessViolationException。

更改

  • 向 NuGet 包添加了自述文件。
  • 更新了 msdia140.dll。

1.4.4

用于解决用户报告的 bug 的单点版本。

Bug 修复

更改

  • 已将 PDB 扫描失败消息从“错误”降低到“警告”。
  • 更新了 msdia140.dll。
  • 如果通过站点扩展设置禁用了调试器，请避免建立服务连接。

1.4.3

用于解决用户报告的 bug 的单点版本。

Bug 修复

1.4.2

用于解决用户报告的 bug 的单点版本。

Bug 修复

修复了 ArgumentException：委托必须属于同一类型。

1.4.1

用于还原 1.4.0 中引入的中断性变更的单点版本。

Bug 修复

修复了在 WebJobs 中找不到方法。

1.4.0

做出了多项改进，并添加了对 Application Insights 引入进行 Microsoft Entra 身份验证的支持。

更改

  • 将 Snapshot Collector 包大小减小了 60%（从 10.34 MB 减少到 4.11 MB）。
  • Snapshot Collector 中仅针对 netstandard2.0。
  • 将 Application Insights SDK 依赖项升级到 2.15.0。
  • 在写入转储时重新添加了 MinidumpWithThreadInfo。
  • 添加了 CompatibilityVersion，以改进中断性变更时 Snapshot Collector 代理和快照上传程序之间的同步。
  • 更改了 SnapshotUploader LogFile 命名算法，以避免应用服务中文件 I/O 过多。
  • 向上传的 Blob 元数据添加了 pid、role name 和 process start time。
  • 在 Snapshot Collector 和快照上传程序中使用了 System.Diagnostics.Process。

新功能

已将 Microsoft Entra 身份验证添加到 SnapshotCollector。 若要详细了解 Application Insights 中的 Microsoft Entra 身份验证，请参阅 Application Insights 的 Microsoft Entra 身份验证。

1.3.7.5

用于从 1.4.0-pre 版本向后移植修补程序的若干修正发布。

Bug 修复

修复了关闭时的 ObjectDisposedException。

1.3.7.4

用于解决在测试 Azure 应用服务无代码附加方案时发现的问题的修正发布。

更改

netcoreapp3.0 目标现在依赖于 Microsoft.ApplicationInsights.AspNetCore>=2.1.1（以前 >=2.1.2）。

1.3.7.3

用于解决几个具有重大影响的问题的若干修正发布。

Bug 修复

  • 修复了 wwwroot/bin 文件夹中的 PDB 发现，此发现在 1.3.6 中更改符号搜索算法时损坏。
  • 修复了遥测数据中的干扰性 ExtractWasCalledMultipleTimesException。

1.3.7

更改

SnapshotCollector 的 netcoreapp2.0 目标依赖于 Microsoft.ApplicationInsights.AspNetCore>=2.1.1（再次）。 此更改会将行为还原为 1.3.5 之前的行为。 我们已尝试在 1.3.6 中对其进行升级，但它破坏了某些应用服务方案。

新增功能

Snapshot Collector 可从 APPLICATIONINSIGHTS_CONNECTION_STRING 环境变量或 TelemetryConfiguration 读取和分析 ConnectionString。 它主要用于设置用于连接到快照服务的终结点。 有关详细信息，请参阅连接字符串文档。

Bug 修复

已切换为将 HttpClient 用于除 net45 以外的所有目标，因为 WebRequest 在一些环境中由于不兼容的 SecurityProtocol 而失败（需要使用 TLS 1.2）。

1.3.6

更改

  • SnapshotCollector 现在依赖于 Microsoft.ApplicationInsights>=2.5.1（适用于所有目标框架）。 如果应用程序依赖较早版本的 Microsoft.ApplicationInsights SDK，此要求可能是中断性变更。
  • 移除了快照上传程序中对 TLS 1.0 和 1.1 的支持。
  • 现在，PDB 扫描时间默认为 24 小时，而不是 15 分钟。 可通过 PdbRescanInterval 上的 SnapshotCollectorConfiguration 进行配置。
  • PDB 扫描仅搜索顶级文件夹，而不执行递归搜索。 如果符号位于二进制文件文件夹的子文件夹中，则此更改可能是中断性变更。

新增功能

  • SnapshotUploader 中的日志轮换，用于避免使用旧文件填充日志文件夹。
  • .NET Core 3.0 应用程序的 Deoptimization 支持（通过 ReJIT 进行附加）。
  • 向 NuGet 包添加了符号。
  • 在上传小型转储时设置了更多元数据。
  • 向 SnapshotCollectorTelemetryProcessor 添加了属性 Initialized。 它是一个 CancellationToken，当 Snapshot Collector 初始化并连接到服务终结点时，会将其取消。
  • 现在可以为动态生成的方法中的异常捕获快照。 例如，由实体框架查询生成的已编译表达式树。

Bug 修复

  • 由于状态监视器出现的加载 Snapshot Collector 的 AmbiguousMatchException。
  • GetSnapshotCollector 扩展方法现在会搜索所有 TelemetrySinks。
  • 请勿在不受支持的平台上启动 Snapshot Uploader。
  • 在取消优化动态方法（例如实体框架）时处理 InvalidOperationException。

1.3.5

  • 添加了对主权云的支持（较旧的版本不适用于主权云）。
  • 使用 AddSnapshotCollector() 可以更轻松地添加 Snapshot Collector。 有关详细信息，请参阅在 Azure 应用服务中为 .NET 应用启用 Snapshot Debugger。
  • 使用 FISMA MD5 设置来验证 Blob 块。 此设置可避免使用默认的 .NET MD5 加密算法，当 OS 设置为符合 FIPS 的模式时，该算法不可用。
  • 取消优化函数调用时忽略 .NET Framework 框架。 使用 DeoptimizeIgnoredModules 配置设置控制此行为。
  • 添加了 DeoptimizeMethodCount 配置设置，该设置支持取消优化多个函数调用。

1.3.4

  • 允许了结构化检测密钥。
  • 提高了快照上传程序的可靠性。 即使无法移动旧的上传程序日志，也能继续启动。
  • 当 SnapshotUploader.exe 立即退出时，重新启用了报告其他遥测（已在 1.3.3 中禁用）。
  • 简化了内部遥测。
  • 试验性功能：快照收集计划：添加 snapshotOnFirstOccurence。 有关详细信息，请参阅此 GitHub 文章。

1.3.3

修复了导致 SnapshotUploader.exe 停止响应且不上传 .NET Core 应用快照的 Bug。

1.3.2

  • 试验性功能：快照收集计划。 有关详细信息，请参阅此 GitHub 文章。
  • 当运行时上传从中加载 SnapshotCollector 的 AppDomain 时，SnapshotUploader.exe 将会退出，而不是等待进程退出。 此操作可改善收集器托管在 IIS 中时的可靠性。
  • 添加了配置，以允许使用相同检测密钥的多个 SnapshotCollector 实例共享同一 SnapshotUploader 进程：ShareUploaderProcess（默认为 true）。
  • 当 SnapshotUploader.exe 立即退出时，报告了更多遥测数据。
  • 减少了 SnapshotUploader.exe 写入磁盘所需的支持文件数量。

1.3.1

  • 移除了对通过 RtlCloneUserProcess API 收集快照的支持，且仅支持 PssCaptureSnapshots API。
  • 提高了在 10 分钟内可以捕获的快照数量的默认上限（从 1 增加到 3）。
  • 允许 SnapshotUploader.exe 协商 TLS 1.1 和 1.2。
  • 在 SnapshotUploader 记录警告或错误时报告了更多遥测数据。
  • 当后端服务报告达到每日配额（每天 50 个快照）时停止拍摄快照。
  • 在 SnapshotUploader.exe 中添加了额外的检查，以禁止同时运行两个实例。

1.3.0

更改

  • 对于面向 .NET Framework 的应用程序，Snapshot Collector 现在依赖于 Microsoft.ApplicationInsights 版本 2.3.0 或更高版本。 它过去是 2.2.0 或更高版本。 我们认为此更改对于大多数应用程序不会出现问题。 如果此更改阻止你使用最新的 Snapshot Collector，请告知我们。
  • 重试失败的上传时，在 Snapshot Uploader 中使用指数回退延迟。
  • 使用 ServerTelemetryChannel（如果可用）来更可靠地报告遥测数据。
  • 在与 Snapshot Debugger 服务的初始连接上使用 SdkInternalOperationsMonitor，以便依赖项跟踪可将其忽略。
  • 改进了与 Snapshot Debugger 的初始连接相关的遥测。
  • 报告以下项的更多遥测数据：
    • 应用服务版本。
    • Azure 计算实例。
    • 容器。
    • Azure Functions 应用。

Bug 修复

  • 如果问题计数器重置间隔设置为 24 天，则将其理解为 24 小时。
  • 修复了以下 bug：在处置快照时，如果出现异常，Snapshot Uploader 将停止处理新的快照。

1.2.3

修复了 Snapshot Uploader 二进制文件的强名称签名。

1.2.2

更改

  • SnapshotUploader(64).exe 所需的文件现已作为资源嵌入到主 DLL 中。 这意味着将不会再创建 SnapshotCollectorFiles 文件夹，从而简化了生成和部署，并减少了解决方案资源管理器中的混乱。 请在升级时注意查看 .csproj 文件中的更改。 不再需要 Microsoft.ApplicationInsights.SnapshotCollector.targets 文件。
  • 即使将 ProvideAnonymousTelemetry 设置为 false，遥测数据也会记录到 Application Insights 资源。 通过此更改，可以在 Azure 门户中实现健康状况检查功能。 ProvideAnonymousTelemetry 仅影响发送到 Microsoft 用于产品支持和改进的遥测数据。
  • 如果将 TempFolder 或 ShadowCopyFolder 重定向到环境变量，请在设置这些环境变量之前，保持收集器处于空闲状态。
  • 对于通过代理服务器连接到 Internet 的应用程序，Snapshot Collector 现在会自动检测任何代理设置，并将其传递给 SnapshotUploader.exe。
  • 降低 SnapshotUploader 进程的优先级（如果可能）。 可通过 IsLowPrioirtySnapshotUploader 选项替代此优先级。
  • 在 TelemetryConfiguration 上添加了 GetSnapshotCollector 扩展方法，可用于想要以编程方式配置 Snapshot Collector 的方案。
  • 在面向客户的遥测中设置 Application Insights SDK 版本（而不是应用程序版本）。
  • 两分钟后发送首个检测信号事件。

Bug 修复

  • 修复了当异常具有 null 或不可变的数据字典时的 NullReferenceException。
  • 如果出现共享冲突，则在上传程序中重试 PDB 匹配几次。
  • 修复启动时多个线程调用到遥测管道时的重复遥测。

1.2.1

更改

  • XML 文档注释文件现在包含在 NuGet 包中。
  • 在 System.Exception 上添加了 ExcludeFromSnapshotting 扩展方法，可用于已知遇到干扰性异常并希望避免为其创建快照的情况。
  • 添加了默认为 true 的 IsEnabledWhenProfiling 配置属性。 这与以前的版本不同，在以前的版本中，如果 Application Insights Profiler 执行详细收集，则暂时禁用快照创建。 通过将此属性设置为 false，可以恢复旧的行为。

Bug 修复

  • 对 SnapshotUploader64.exe 正确签名。
  • 防止遥测处理器的双重初始化。
  • 防止在具有多个管道的应用中对遥测进行双重日志记录。
  • 修复了收集计划到期时间的 bug，这可能会在 24 小时后阻止快照。

1.2.0

此版本中的最大变化（因此更改为新的次要版本号）是重写快照创建和处理管道。 在以前的版本中，此功能是在本机代码中实现的（ProductionBreakpoints.dll* 和 SnapshotHolder.exe*）。 新实现是带有 P/Invoke 的完全托管代码。

对于这第一个使用新管道的版本，我们没有对原始行为进行太大的改动。 新的实现可提供更好的错误报告功能，使我们能够进一步改进。

此版本中的其他更改

  • 已将 MinidumpUploader.exe 重命名为 SnapshotUploader.exe（或 SnapshotUploader64.exe）。
  • 向 DeOptimize/ReOptimize 请求添加了计时遥测。
  • 添加了用于小型转储上传的 gzip 压缩。
  • 修复了阻止站点升级的 PDB 被锁定的问题。
  • 在进行卷影复制时记录原始文件夹名称（SnapshotCollectorFiles）。
  • 调整了 64 位进程的内存限制，以防止因 OOM 而重启站点。
  • 修复了即使禁用后仍会收集快照的问题。
  • 将检测信号事件记录到客户的 AI 资源。
  • 通过移除问题 ID 中的“源”提高了快照速度。

1.1.2

更改

  • 增强了使用情况遥测。
  • 检测和报告 .NET 版本和 OS。
  • 检测并报告更多 Azure 环境（Azure 云服务、Azure Service Fabric）。
  • 记录和报告检测信号遥测中的异常指标（第一次机会异常数量和 TrackException 调用次数）。

Bug 修复

  • 正确处理不会引发内部异常 (Win32Exception) 的 SqlException。
  • 剪裁了符号文件夹上的尾随空格，这会导致对 MinidumpUploader 的命令行参数分析不正确。
  • 阻止了无限次重试与 Snapshot Debugger 代理终结点的失败连接。

1.1.0

更改

  • 添加了主机内存保护。 此功能降低了对主机内存的影响。
  • 改进了 Azure 门户快照查看体验。