使用快照偵錯工具對 .NET 應用程式中的例外狀況進行偵錯

  • 發行項

透過快照偵錯工具，您可以自動地在即時 .NET 應用程式中發生例外狀況時收集偵錯快照集。 所收集的偵錯快照集會顯示系統擲回例外狀況當下，原始程式碼和變數的狀態。

Application Insights 中的快照偵錯工具：

  • 從 Web 應用程式監視系統產生的記錄。
  • 對最常擲回的例外狀況收集快照集。
  • 提供診斷生產環境中的問題所需的資訊。

深入了解快照偵錯工具和 Snapshot Uploader 的程序。

支援的應用程式和環境

本節列出支援的應用程式和環境。

應用程式

快照集集合適用於：

環境

支援下列環境：

注意

不支援用戶端應用程式 (例如，WPF、Windows Forms 或 UWP)。

使用快照偵錯工具的必要條件

套件和組態

權限

快照偵錯工具的運作方式

Snapshot Collector 會實作為 Application Insights 遙測處理器。 當您的應用程式執行時，Snapshot Collector 遙測處理器會新增至應用程式的系統產生的記錄管線。

重要

快照集可能包含變數和參數值中的個人資料或其他敏感性資訊。 快照集資料會儲存在與 Application Insights 資源相同的區域中。

快照偵錯工具程序

快照偵錯工具程序會以 TrackException 方法開始和結束。 程序快照集是執行中程序的暫止複製品，因此您的使用者幾乎不會遇到中斷。

  1. 您的應用程式擲回 TrackException。

  2. 快照偵錯工具藉由訂閱 AppDomain.CurrentDomain.FirstChanceException 事件來監視擲回的例外狀況。

  3. 問題識別碼的計數器遞增。

    • 當計數器達到 ThresholdForSnapshotting 值時，問題識別碼就會新增至收集計畫。

    注意

    ThresholdForSnapshotting 的預設最小值為 1。 使用此值時，您的應用程式必須觸發相同的例外狀況兩次，才會建立快照集。

  4. 計算例外狀況事件的問題識別碼，並與收集計畫中的問題識別碼進行比較。

  5. 如果兩者的問題識別碼相符，便會建立執行中程序的快照集。

    • 快照集獲指派一個唯一的識別碼，而例外狀況則標有該識別碼的戳記。

    注意

    快照集建立速率受限於 SnapshotsPerTenMinutesLimit 設定。 根據預設，限制為每隔 10 分鐘建立一個快照集。

  6. FirstChanceException 處理常式傳回後，擲回的例外狀況就會正常處理。

  7. 例外狀況再次到達 TrackException 方法，並與快照集識別碼一起回報給 Application Insights。

注意

如果您想要在 Visual Studio 中進行偵錯時產生快照集，請將 IsEnabledInDeveloperMode 設定為 true。

Snapshot Uploader 程序

在快照偵錯工具的程序繼續執行並提供流量給使用者，但偶而會中斷的情況下，快照集會移交給 Snapshot Uploader 程序。 Snapshot Uploader 會：

  1. 建立小型傾印。

  2. 將小型傾印連同任何相關的符號 (.pdb) 檔案上傳至 Application Insights。

注意

每日可上傳的快照集不可超過 50 個。

如果您已啟用快照偵錯工具，但未看到快照集，請參閱疑難排解指南。

限制

本節討論快照偵錯工具的限制。

  • 資料保留

    偵錯快照集會儲存 15 天。 預設資料保留原則會就個別的應用程式進行設定。 如果您需要增加此值，您可以在 Azure 入口網站中建立支援案例，以提出增加的要求。 針對每個 Application Insights 執行個體，每天最多允許 50 個快照集。

  • 發佈符號

    快照偵錯工具需要生產伺服器上的符號檔案才能：

    • 將變數解碼
    • 在 Visual Studio 中提供偵錯體驗

    根據預設，Visual Studio 2017 15.2+ 版會在發佈至 App Service 時，發佈版本組建的符號。

    在舊版中，您必須將下列這一行新增至發佈設定檔 .pubxml 檔案，才會在發行模式中將符號發佈：

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    若為 Azure 計算和其他類型，請確定符號檔案：

    • 在主要應用程式 .dll 的相同資料夾中 (通常是 wwwroot/bin)，或者
    • 可在目前的路徑上取得。

    如需不同可用符號選項的詳細資訊，請參閱 Visual Studio 文件。 如需最佳結果，建議您使用「完整」、「可攜式」或「內嵌」。

  • 最佳化的組建

    在某些情況下，由於 JIT 編譯器所套用的最佳化，因此無法在版本組建中檢視本機變數。

    不過，在 App Service 中，快照偵錯工具可以將屬於其收集計畫一部分的擲回方法反最佳化。

    提示

    在 App Service 的執行個體中安裝 Application Insights 網站延伸模組，以取得反最佳化支援。

下一步

針對您的應用程式啟用 Application Insights 快照偵錯工具：

Microsoft.ApplicationInsights.SnapshotCollector 的版本資訊

本節包含適用於 .NET 應用程式的 Microsoft.ApplicationInsights.SnapshotCollector NuGet 套件發行備註，這是 Application Insights 快照偵錯工具所使用的套件。

深入了解適用於 .NET 應用程式的 Application Insights 快照偵錯工具。

若要回報錯誤和提供意見反應，請在 GitHub 上發佈議題。

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。 檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。 轉換至連接字串以利用新功能。

1.4.6

解決使用 .NET 8 應用程式時之迴歸的小數點版本。

錯誤修正

  • 未能正確追蹤 .NET 8 中從動態產生的方法擲回的例外狀況 (例如，已編譯的運算式樹狀架構)。 固定。

1.4.5

解決使用者回報錯誤的小數點版本。

錯誤修正

  • 已修正讀取某些 PDB 時的 AccessViolationException。

變更

  • 已在 NuGet 套件中新增讀我檔案。
  • 已更新 msdia140.dll。

1.4.4

對應使用者回報錯誤的小數點版本。

錯誤修正

變更

  • 將 PDB 掃描失敗訊息從「錯誤」降低為「警告」。
  • 已更新 msdia140.dll。
  • 避免在透過網站延伸模組設定停用偵錯工具時建立服務連線。

1.4.3

對應使用者回報錯誤的小數點版本。

錯誤修正

1.4.2

解決使用者回報錯誤的小數點版本。

錯誤修正

已修正 ArgumentException：委派的類型必須相同。

1.4.1

還原 1.4.0 中所述中斷性變更的小數點版本。

錯誤修正

已修正在 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 代理程式與 Snapshot Uploader 在中斷性變更之間的同步。
  • 已變更 SnapshotUploader LogFile 命名演算法，以避免 App Service 中的檔案 I/O 過多。
  • 已將 pid、role name 和 process start time 新增至所上傳的 Blob 中繼資料。
  • 已在 Snapshot Collector 和 Snapshot Uploader 中使用 System.Diagnostics.Process。

新功能

已將 Microsoft Entra 驗證新增至 SnapshotCollector。 若要深入了解 Application Insights 中的 Microsoft Entra 驗證，請參閱 Application Insights 的 Microsoft Entra 驗證。

1.3.7.5

從 1.4.0-pre 向後移植修正程式的小數點版本。

錯誤修正

已修正關機時的 ObjectDisposedException。

1.3.7.4

用來解決測試 App Service 無程式碼連結案例中所發現問題的小數點版本。

變更

netcoreapp3.0 目標現在相依於 Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (先前 >= 2.1.2)。

1.3.7.3

解決幾個高影響問題的小數點版本。

錯誤修正

  • 已修正 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 中將其升級，但這麼做會損壞部分 App Service 案例。

新功能

Snapshot Collector 會從 APPLICATIONINSIGHTS_CONNECTION_STRING 環境變數或 TelemetryConfiguration 讀取和剖析 ConnectionString。 其主要用途是設定用來連線到快照服務的端點。 如需詳細資訊，請參閱連接字串文件。

錯誤修正

因為在某些環境中，WebRequest 會由於不相容的 SecurityProtocol (需要 TLS 1.2) 而失敗，因此所有目標 (net45 除外) 已切換為使用 HttpClient。

1.3.6

變更

  • 所有目標架構的 SnapshotCollector 現在相依於 Microsoft.ApplicationInsights>= 2.5.1。 如果您的應用程式相依於舊版的 Microsoft.ApplicationInsights SDK，此需求可能是中斷性變更。
  • 已在 Snapshot Uploader 中移除 TLS 1.0 和 1.1 的支援。
  • PDB 掃描的期間現在預設為 24 小時，而不是 15 分鐘。 可在 SnapshotCollectorConfiguration 上透過 PdbRescanInterval 來設定。
  • PDB 掃描只會搜尋最上層資料夾，而不是遞迴搜尋。 如果您的符號位於二進位資料夾的子資料夾中，此變更可能是中斷性變更。

新功能

  • SnapshotUploader 中的記錄輪替，可避免在記錄資料夾中填入舊檔案。
  • .NET Core 3.0 應用程式的反最佳化支援 (透過附加上的 ReJIT)。
  • 已將符號新增至 NuGet 套件。
  • 可在上傳小型傾印時設定更多中繼資料。
  • 已將 Initialized 屬性新增至 SnapshotCollectorTelemetryProcessor。 其為 CancellationToken，會在 Snapshot Collector 初始化並連線到服務端點時取消。
  • 快照集現在可以在動態產生的方法中擷取例外狀況。 範例是 Entity Framework 查詢所產生的已編譯運算式樹狀架構。

錯誤修正

  • AmbiguousMatchException 因為狀態監視器載入 Snapshot Collector。
  • GetSnapshotCollector 擴充方法現在會搜尋所有 TelemetrySinks。
  • 請勿在不支援的平台上啟動 Snapshot Uploader。
  • 處理將動態方法 (例如 Entity Framework) 反最佳化時的 InvalidOperationException。

1.3.5

  • 已新增對主權雲端的支援 (舊版無法在主權雲端中運作)。
  • 使用 AddSnapshotCollector() 來新增 Snapshot Collector 已變得更容易。 如需詳細資訊，請參閱在 Azure App Service 中啟用適用於 .NET 應用程式的快照偵錯工具。
  • 使用 FISMA MD5 設定來驗證 Blob 區塊。 此設定可避免使用預設的 .NET MD5 密碼編譯演算法，該演算法在 OS 設定為 FIPS 相容模式時無法使用。
  • 在反最佳化函式呼叫時忽略 .NET Framework 框架。 使用 DeoptimizeIgnoredModules 組態設定來控制此行為。
  • 已新增 DeoptimizeMethodCount 組態設定，以允許將多個函式呼叫反最佳化。

1.3.4

  • 已允許結構化檢測金鑰。
  • 已提高 Snapshot Uploader 穩健性。 即使無法移動舊的上傳程式記錄，仍繼續啟動。
  • 已重新啟用當 SnapshotUploader.exe 結束時，立即回報更多遙測 (在 1.3.3 中停用)。
  • 已簡化內部遙測。
  • 實驗性功能：快照點收集計畫：新增 snapshotOnFirstOccurence。 如需詳細資訊，請參閱此 GitHub 文章。

1.3.3

已修正造成 SnapshotUploader.exe 停止回應且未上傳 .NET Core 應用程式快照集的錯誤。

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 分鐘內可擷取的預設快照集數目限制從一個增加為三個。
  • 允許 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 獲得更可靠的遙測報告 (如果適用)。
  • 在快照偵錯工具服務的初始連線上使用 SdkInternalOperationsMonitor，使相依性追蹤忽略該連線。
  • 已改善關於快照偵錯工具初始連線的遙測。
  • 針對下列項目回報更多遙測：
    • App Service 版本。
    • Azure 計算執行個體。
    • 容器。
    • Azure Functions 應用程式。

錯誤修正

  • 當問題計數器重設間隔設定為 24 天時，將其解譯為 24 小時。
  • 已修正當快照集處置有例外狀況時，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 重新導向至環境變數時，請讓收集器保持在閒置狀態，直到設定好這些環境變數為止。
  • 對於透過 Proxy 伺服器連線到網際網路的應用程式，Snapshot Collector 現在會自動偵測任何 Proxy 設定，並將其傳遞至 SnapshotUploader.exe。
  • 降低 SnapshotUploader 程序的優先順序 (如果可能的話)。 您可以透過 IsLowPrioirtySnapshotUploader 選項覆寫此優先順序。
  • 已針對您想要以程式設計方式設定 Snapshot Collector 的案例，在 TelemetryConfiguration 上新增 GetSnapshotCollector 擴充方法。
  • 在客戶面向的遙測中設定 Application Insights SDK 版本 (而不是應用程式版本)。
  • 在兩分鐘後傳送第一個活動訊號事件。

錯誤修正

  • 已修正例外狀況有 Null 或不可變資料字典時的 NullReferenceException。
  • 在上傳程式中，收到共用違規時重試比對 PDB 多次。
  • 修正當啟動時多個執行緒呼叫遙測管線時的重複遙測。

1.2.1

變更

  • XML Doc 註解檔案現在包含在 NuGet 套件中。
  • 已針對您知道有雜訊例外狀況，並想要避免為其建立快照集的案例，在 System.Exception 上新增 ExcludeFromSnapshotting 擴充方法。
  • 已新增預設為 true 的 IsEnabledWhenProfiling 組態屬性。 這是來自舊版的變更，如果 Application Insights Profiler 正在執行詳細的收集，快照集建立就會暫時停用。 您可以將此屬性設定為 false，以復原舊的行為。

錯誤修正

  • 正確簽署 SnapshotUploader64.exe。
  • 防止遙測處理器的重複初始化。
  • 避免在具有多個管線的應用程式中重複記錄遙測。
  • 已修正收集計畫到期時間的錯誤，這可能會在 24 小時後禁止快照。

1.2.0

此版本最大的變更 (因此移至新的次要版本號碼) 是快照集建立和處理管線的重寫。 在舊版中，此功能是在機器碼中實作 (ProductionBreakpoints.dll* 和 SnapshotHolder.exe*)。 新的實作是搭配 P/Invokes 的完全受控程式碼。

針對使用新管線的第一個版本，我們尚未偏離原始行為。 新的實作可提供更好的錯誤報報，並有利於我們日後的改善。

此版本中的其他變更

  • MinidumpUploader.exe 已重新命名為 SnapshotUploader.exe (或 SnapshotUploader64.exe)。
  • 已將計時遙測新增至 DeOptimize/ReOptimize 要求。
  • 已新增用於小型傾印上傳的 gzip 壓縮。
  • 已修正 PDB 遭鎖定而無法升級站台的問題。
  • 執行陰影複製時，記錄原始資料夾名稱 (SnapshotCollectorFiles)。
  • 已調整 64 位元程序的記憶體限制，以防止因為 OOM 而重新啟動站台。
  • 已修正即使停用之後，仍會收集快照集的問題。
  • 將活動訊號事件記錄至客戶的 AI 資源。
  • 已從問題識別碼中移除「來源」以改善快照速度。

1.1.2

變更

  • 已增強使用量遙測。
  • 偵測並報告 .NET 版本和 OS。
  • 偵測並報告更多 Azure 環境 (Azure 雲端服務、Azure Service Fabric)。
  • 記錄並報告活動訊號遙測中的例外狀況計量 (第 1 次機會例外狀況的數目和 TrackException 呼叫的數目)。

錯誤修正

  • 正確處理 SqlException，其中不會擲回內部例外狀況 (Win32Exception)。
  • 已修剪符號資料夾的尾端空格，其導致 MinidumpUploader 的命令列引數剖析不正確。
  • 已防止對快照偵錯工具代理程式端點的失敗連線進行無限重試。

1.1.0

變更

  • 已新增主機記憶體保護。 這項功能可減少對主機機器記憶體的影響。
  • 已改善 Azure 入口網站的快照檢視體驗。