Debugowanie migawek wyjątków w aplikacjach .NETDebug snapshots on exceptions in .NET apps

Gdy wystąpi wyjątek, można automatycznie zebrać migawkę debugowania z działającej aplikacji sieci Web.When an exception occurs, you can automatically collect a debug snapshot from your live web application. Migawka pokazuje stan kodu źródłowego i zmienne w momencie, gdy wyjątek został zgłoszony.The snapshot shows the state of source code and variables at the moment the exception was thrown. Snapshot Debugger w usłudze Azure Application Insights monitoruje dane telemetryczne wyjątku z aplikacji sieci Web.The Snapshot Debugger in Azure Application Insights monitors exception telemetry from your web app. Zbiera migawki na najważniejszych wyjątkach, aby uzyskać informacje potrzebne do diagnozowania problemów w środowisku produkcyjnym.It collects snapshots on your top-throwing exceptions so that you have the information you need to diagnose issues in production. Dołącz pakiet NuGet modułu zbierającego migawki do aplikacji i opcjonalnie Skonfiguruj parametry kolekcji w ApplicationInsights.config. Migawki są wyświetlane na wyjątkach w portalu 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.

Migawki debugowania można wyświetlić w portalu, aby zobaczyć stos wywołań i sprawdzić zmienne w każdej ramce tego stosu.You can view debug snapshots in the portal to see the call stack and inspect variables at each call stack frame. Aby uzyskać bardziej zaawansowane środowisko debugowania z kodem źródłowym, Otwórz migawki w programie Visual Studio 2019 Enterprise.To get a more powerful debugging experience with source code, open snapshots with Visual Studio 2019 Enterprise. W programie Visual Studio można także ustawić punkty przyciągania, aby interaktywnie podejmować migawki bez oczekiwania na wyjątek.In Visual Studio, you can also set Snappoints to interactively take snapshots without waiting for an exception.

Migawki debugowania są przechowywane przez 15 dni.Debug snapshots are stored for 15 days. Te zasady przechowywania są ustawiane dla poszczególnych aplikacji.This retention policy is set on a per-application basis. Jeśli musisz zwiększyć tę wartość, możesz poprosić o zwiększenie, otwierając przypadek pomocy technicznej w Azure Portal.If you need to increase this value, you can request an increase by opening a support case in the Azure portal.

Włącz Snapshot Debugger Application Insights dla aplikacjiEnable Application Insights Snapshot Debugger for your application

Kolekcja migawek jest dostępna dla:Snapshot collection is available for:

  • .NET Framework i aplikacje ASP.NET z systemem .NET Framework 4,5 lub nowszym..NET Framework and ASP.NET applications running .NET Framework 4.5 or later.
  • Aplikacje .NET Core 2,0 i ASP.NET Core 2,0 działające w systemie Windows..NET Core 2.0 and ASP.NET Core 2.0 applications running on Windows.

Obsługiwane są następujące środowiska:The following environments are supported:

Uwaga

Aplikacje klienckie (na przykład WPF, Windows Forms lub platformy UWP) nie są obsługiwane.Client applications (for example, WPF, Windows Forms or UWP) are not supported.

Jeśli włączono Snapshot Debugger, ale nie widzisz migawek, zapoznaj się z naszym przewodnikiem rozwiązywania problemów.If you've enabled Snapshot Debugger but aren't seeing snapshots, check our Troubleshooting guide.

Udzielenie uprawnieńGrant permissions

Dostęp do migawek jest chroniony przez kontrolę dostępu opartą na rolach (Azure RBAC).Access to snapshots is protected by Azure role-based access control (Azure RBAC). Aby przeprowadzić inspekcję migawki, najpierw właściciel subskrypcji musi Cię dodać do niezbędnej roli.To inspect a snapshot, you must first be added to the necessary role by a subscription owner.

Uwaga

Właściciele i współautorzy nie mają tej roli automatycznie.Owners and contributors do not automatically have this role. Jeśli chcesz wyświetlić migawki, muszą dodać siebie do roli.If they want to view snapshots, they must add themselves to the role.

Właściciele subskrypcji powinni przypisać Application Insights Snapshot Debugger rolę do użytkowników, którzy będą przeprowadzali inspekcję migawek.Subscription owners should assign the Application Insights Snapshot Debugger role to users who will inspect snapshots. Tę rolę można przypisać do poszczególnych użytkowników lub grup według właścicieli subskrypcji dla docelowego zasobu Application Insights lub jego grupy zasobów lub subskrypcji.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. Przejdź do zasobu Application Insights w Azure Portal.Navigate to the Application Insights resource in the Azure portal.
  2. Kliknij pozycję Kontrola dostępu (IAM) .Click Access control (IAM).
  3. Kliknij przycisk + Dodaj przypisanie roli .Click the +Add role assignment button.
  4. Wybierz pozycję Application Insights Snapshot Debugger z listy rozwijanej role .Select Application Insights Snapshot Debugger from the Roles drop-down list.
  5. Wyszukaj i wprowadź nazwę użytkownika, który ma zostać dodany.Search for and enter a name for the user to add.
  6. Kliknij przycisk Zapisz , aby dodać użytkownika do roli.Click the Save button to add the user to the role.

Ważne

Migawki mogą potencjalnie zawierać informacje osobiste i inne poufne w wartościach zmiennych i parametrów.Snapshots can potentially contain personal and other sensitive information in variable and parameter values.

Wyświetlanie migawek w portaluView Snapshots in the Portal

Gdy w aplikacji wystąpił wyjątek, a migawka została utworzona, należy utworzyć migawki do wyświetlenia.After an exception has occurred in your application and a snapshot has been created, you should have snapshots to view. Wykonanie migawki w portalu może potrwać od 5 do 10 minut od wyjątku.It can take 5 to 10 minutes from an exception occurring to a snapshot ready and viewable from the portal. Aby wyświetlić migawki, w okienku awaria wybierz przycisk operacje podczas wyświetlania karty operacje lub wybierz przycisk wyjątki podczas wyświetlania karty wyjątki :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:

Strona błędów

Wybierz operację lub wyjątek w okienku po prawej stronie, aby otworzyć okienko szczegóły końca transakcji , a następnie wybierz zdarzenie wyjątku.Select an operation or exception in the right pane to open the End-to-End Transaction Details pane, then select the exception event. Jeśli dla danego wyjątku dostępna jest migawka, w okienku po prawej stronie zostanie wyświetlony przycisk Otwórz migawkę debugowania z szczegółowymi informacjami dotyczącymi wyjątku.If a snapshot is available for the given exception, an Open Debug Snapshot button appears on the right pane with details for the exception.

Przycisk otwierania migawki debugowania dla wyjątku

W widoku migawki debugowania zobaczysz stos wywołań i okienko zmiennych.In the Debug Snapshot view, you see a call stack and a variables pane. Po wybraniu ramek stosu wywołań w okienku stosu wywołań można wyświetlić zmienne lokalne i parametry dla tego wywołania funkcji w okienku zmienne.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.

Wyświetl migawkę debugowania w portalu

Migawki mogą zawierać informacje poufne i domyślnie nie są widoczne.Snapshots might include sensitive information, and by default they aren't viewable. Aby wyświetlić migawki, musisz mieć Application Insights Snapshot Debugger przypisaną rolę.To view snapshots, you must have the Application Insights Snapshot Debugger role assigned to you.

Wyświetlanie migawek w programie Visual Studio 2017 Enterprise lub nowszymView Snapshots in Visual Studio 2017 Enterprise or above

  1. Kliknij przycisk Pobierz migawkę , aby pobrać .diagsession plik, który może zostać otwarty przez Visual Studio Enterprise.Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio Enterprise.

  2. Aby otworzyć .diagsession plik, należy zainstalować składnik programu Snapshot Debugger Visual Studio.To open the .diagsession file, you need to have the Snapshot Debugger Visual Studio component installed. Składnik Snapshot Debugger jest wymaganym składnikiem obciążenia ASP.net w programie Visual Studio i można go wybrać z listy poszczególnych składników w Instalatorze programu 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. Jeśli używasz wersji programu Visual Studio starszej niż wersja 15,5 programu Visual 2017 Studio, musisz zainstalować rozszerzenie z 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. Po otwarciu pliku migawki zostanie wyświetlona strona debugowanie minizrzutu w programie Visual Studio.After you open the snapshot file, the Minidump Debugging page in Visual Studio appears. Kliknij pozycję Debuguj kod zarządzany , aby rozpocząć debugowanie migawki.Click Debug Managed Code to start debugging the snapshot. Migawka zostanie otwarta w wierszu kodu, w którym został zgłoszony wyjątek, aby można było debugować bieżący stan procesu.The snapshot opens to the line of code where the exception was thrown so that you can debug the current state of the process.

    Wyświetl migawkę debugowania w programie Visual Studio

Pobrana migawka zawiera pliki symboli, które zostały znalezione na serwerze aplikacji sieci Web.The downloaded snapshot includes any symbol files that were found on your web application server. Te pliki symboli są wymagane do skojarzenia danych migawki z kodem źródłowym.These symbol files are required to associate snapshot data with source code. W przypadku aplikacji App Service upewnij się, że włączono wdrażanie symboli podczas publikowania aplikacji sieci Web.For App Service apps, make sure to enable symbol deployment when you publish your web apps.

Jak działają migawkiHow snapshots work

Snapshot Collector jest implementowana jako procesor Telemetria usługi Application Insights.The Snapshot Collector is implemented as an Application Insights Telemetry Processor. Gdy aplikacja zostanie uruchomiona, procesor telemetrii Snapshot Collector zostanie dodany do potoku telemetrii aplikacji.When your application runs, the Snapshot Collector Telemetry Processor is added to your application's telemetry pipeline. Za każdym razem, gdy aplikacja wywołuje element trackexception, Snapshot Collector oblicza identyfikator problemu na podstawie typu zgłaszanego wyjątku i metody zgłaszania.Each time your application calls TrackException, the Snapshot Collector computes a Problem ID from the type of exception being thrown and the throwing method. Za każdym razem, gdy aplikacja wywołuje metodę Trackexception, licznik jest zwiększany dla odpowiedniego identyfikatora problemu.Each time your application calls TrackException, a counter is incremented for the appropriate Problem ID. Gdy licznik osiągnie ThresholdForSnapshotting wartość, identyfikator problemu zostanie dodany do planu kolekcji.When the counter reaches the ThresholdForSnapshotting value, the Problem ID is added to a Collection Plan.

Snapshot Collector również monitoruje wyjątki, ponieważ są zgłaszane przez zasubskrybowanie zdarzenia AppDomain. CurrentDomain —. FirstChanceException .The Snapshot Collector also monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event. Gdy zdarzenie zostanie wyzwolone, identyfikator problemu wyjątku jest obliczany i porównywany z identyfikatorami problemów w planie kolekcji.When that event fires, the Problem ID of the exception is computed and compared against the Problem IDs in the Collection Plan. Jeśli istnieje dopasowanie, tworzona jest migawka uruchomionego procesu.If there's a match, then a snapshot of the running process is created. Do migawki jest przypisany unikatowy identyfikator, a wyjątek jest sygnaturą tego identyfikatora.The snapshot is assigned a unique identifier and the exception is stamped with that identifier. Po powrocie procedury obsługi FirstChanceException, zgłoszony wyjątek jest przetwarzany jako normalny.After the FirstChanceException handler returns, the thrown exception is processed as normal. Ostatecznie wyjątek osiągnie metodę Trackexception, a wraz z identyfikatorem migawki jest raportowany do Application Insights.Eventually, the exception reaches the TrackException method again where it, along with the snapshot identifier, is reported to Application Insights.

Główny proces nadal działa i obsługuje ruch do użytkowników z małym zakłóceniem.The main process continues to run and serve traffic to users with little interruption. W tym czasie migawka jest przekazana do procesu obiektu przekazującego migawek.Meanwhile, the snapshot is handed off to the Snapshot Uploader process. Migawka obiektu przekazującego tworzy minizrzutu i przekazuje ją do Application Insights wraz z wszelkimi odpowiednimi plikami symboli (. pdb).The Snapshot Uploader creates a minidump and uploads it to Application Insights along with any relevant symbol (.pdb) files.

Porada

  • Migawka procesu jest zawieszonym klonem uruchomionego procesu.A process snapshot is a suspended clone of the running process.
  • Tworzenie migawki trwa od 10 do 20 milisekund.Creating the snapshot takes about 10 to 20 milliseconds.
  • Wartość domyślna dla ThresholdForSnapshotting wynosi 1.The default value for ThresholdForSnapshotting is 1. Jest to również wartość minimalna.This is also the minimum value. W związku z tym aplikacja musi wyzwolić ten sam wyjątek dwa razy przed utworzeniem migawki.Therefore, your app has to trigger the same exception twice before a snapshot is created.
  • Ustaw IsEnabledInDeveloperMode wartość true, jeśli chcesz generować migawki podczas debugowania w programie Visual Studio.Set IsEnabledInDeveloperMode to true if you want to generate snapshots while debugging in Visual Studio.
  • Szybkość tworzenia migawek jest ograniczona przez SnapshotsPerTenMinutesLimit ustawienie.The snapshot creation rate is limited by the SnapshotsPerTenMinutesLimit setting. Domyślnie limit jest jedną migawką co dziesięć minut.By default, the limit is one snapshot every ten minutes.
  • Maksymalnie 50 migawek dziennie można przekazać.No more than 50 snapshots per day may be uploaded.

OgraniczeniaLimitations

Domyślny okres przechowywania danych wynosi 15 dni.The default data retention period is 15 days. Dla każdego wystąpienia Application Insights dozwolonych jest maksymalnie 50 migawek dziennie.For each Application Insights instance, a maximum number of 50 snapshots is allowed per day.

Publikuj symbolePublish symbols

Snapshot Debugger wymaga plików symboli na serwerze produkcyjnym, aby zdekodować zmienne i zapewnić środowisko debugowania w programie Visual Studio.The Snapshot Debugger requires symbol files on the production server to decode variables and to provide a debugging experience in Visual Studio. Wersja 15,2 (lub nowsza) programu Visual Studio 2017 publikuje symbole dla kompilacji wydań domyślnie, gdy publikuje je w App Service.Version 15.2 (or above) of Visual Studio 2017 publishes symbols for release builds by default when it publishes to App Service. W poprzednich wersjach należy dodać następujący wiersz do pliku profilu publikowania, .pubxml Aby symbole zostały opublikowane w trybie wydania: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>

W przypadku obliczeń na platformie Azure i innych typów upewnij się, że pliki symboli znajdują się w tym samym folderze głównej aplikacji. dll (zazwyczaj wwwroot/bin ) lub są dostępne w bieżącej ścieżce.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.

Uwaga

Więcej informacji o różnych opcjach symboli dostępnych można znaleźć w dokumentacji programu Visual Studio.For more information on the different symbol options that are available consult the Visual Studio documentation. Aby uzyskać najlepsze wyniki, zalecamy użycie "Full", "Portable" lub "Embedded".For best results, we recommend using “Full”, “Portable” or “Embedded”.

Zoptymalizowane kompilacjeOptimized builds

W niektórych przypadkach zmienne lokalne nie mogą być wyświetlane w kompilacjach wydania z powodu optymalizacji, które są stosowane przez kompilator JIT.In some cases, local variables can't be viewed in release builds because of optimizations that are applied by the JIT compiler. Jednak w usłudze Azure App Services Snapshot Collector może dezoptymalizować wyrzucanie metod, które są częścią planu kolekcji.However, in Azure App Services, the Snapshot Collector can deoptimize throwing methods that are part of its Collection Plan.

Porada

Zainstaluj rozszerzenie witryny Application Insights w App Service, aby uzyskać pomoc w zakresie deoptymalizacji.Install the Application Insights Site Extension in your App Service to get deoptimization support.

Następne krokiNext steps

Włącz Snapshot Debugger Application Insights dla aplikacji:Enable Application Insights Snapshot Debugger for your application:

Poza Application Insights Snapshot Debugger:Beyond Application Insights Snapshot Debugger: