Debugmomentaufnahmen von Ausnahmen in .NET-AppsDebug snapshots on exceptions in .NET apps

Wenn eine Ausnahme auftritt, können Sie automatisch eine Debugmomentaufnahme von Ihrer aktiven Webanwendung erfassen.When an exception occurs, you can automatically collect a debug snapshot from your live web application. Die Momentaufnahme zeigt den Status des Quellcodes und der Variablen in dem Moment, in dem die Ausnahme ausgelöst wurde.The snapshot shows the state of source code and variables at the moment the exception was thrown. Der Momentaufnahmedebugger in Azure Application Insights überwacht Ausnahmetelemetriedaten aus Ihrer Web-App.The Snapshot Debugger in Azure Application Insights monitors exception telemetry from your web app. Er erfasst Momentaufnahmen Ihrer am häufigsten ausgelösten Ausnahmen, damit Sie die erforderlichen Informationen zur Diagnose von Problemen in der Produktion erhalten.It collects snapshots on your top-throwing exceptions so that you have the information you need to diagnose issues in production. Binden Sie das NuGet-Paket des Momentaufnahmesammlers in Ihre Anwendung ein, und konfigurieren Sie optional Parameter für die Datensammlung in ApplicationInsights.config. Momentaufnahmen finden Sie im Application Insights-Portal unter Ausnahmen.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.

Sie können Debugmomentaufnahmen im Portal anzeigen, um die Aufrufliste anzuzeigen und die Variablen in jedem Aufruflistenrahmen zu überprüfen.You can view debug snapshots in the portal to see the call stack and inspect variables at each call stack frame. Öffnen Sie zum Verbessern Ihrer Debugleistung mit Quellcode die Momentaufnahmen mit Visual Studio 2019 Enterprise.To get a more powerful debugging experience with source code, open snapshots with Visual Studio 2019 Enterprise. In Visual Studio können Sie auch Andockpunkte festlegen, um interaktiv Momentaufnahmen zu erstellen, ohne auf eine Ausnahme zu warten.In Visual Studio, you can also set Snappoints to interactively take snapshots without waiting for an exception.

Debugmomentaufnahmen werden 15 Tage lang gespeichert.Debug snapshots are stored for 15 days. Diese Aufbewahrungsrichtlinie wird für jede Anwendung separat festgelegt.This retention policy is set on a per-application basis. Wenn Sie diesen Wert erhöhen möchten, können Sie eine Erhöhung anfordern, indem Sie einen Supportfall im Azure-Portal eröffnen.If you need to increase this value, you can request an increase by opening a support case in the Azure portal.

Aktivieren des Application Insights-Momentaufnahmedebuggers für Ihre AnwendungEnable Application Insights Snapshot Debugger for your application

Die Momentaufnahmesammlung ist für folgende Anwendungen verfügbar:Snapshot collection is available for:

  • .NET Framework- und ASP.NET-Anwendungen, die mit .NET Framework 4.5 oder höher ausgeführt werden.NET Framework and ASP.NET applications running .NET Framework 4.5 or later.
  • .NET Core 2.0- und ASP.NET Core 2.0-Anwendungen, die unter Windows ausgeführt werden.NET Core 2.0 and ASP.NET Core 2.0 applications running on Windows.

Die folgenden Umgebungen werden unterstützt:The following environments are supported:

Hinweis

Clientanwendungen (z.B. WPF, Windows Forms oder UWP) werden nicht unterstützt.Client applications (for example, WPF, Windows Forms or UWP) are not supported.

Wenn Sie den Momentaufnahmedebugger aktiviert haben, aber keine Momentaufnahmen angezeigt werden, lesen Sie unseren Leitfaden zur Problembehandlung.If you've enabled Snapshot Debugger but aren't seeing snapshots, check our Troubleshooting guide.

Erteilen von BerechtigungenGrant permissions

Der Zugriff auf Momentaufnahmen wird durch die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) geschützt.Access to snapshots is protected by role-based access control (RBAC). Um eine Momentaufnahme zu überprüfen, muss Ihnen zuerst die erforderliche Rolle durch einen Abonnementbesitzer zugewiesen werden.To inspect a snapshot, you must first be added to the necessary role by a subscription owner.

Hinweis

Weder Besitzer noch Mitwirkende erhalten diese Rolle automatisch.Owners and contributors do not automatically have this role. Wenn sie Momentaufnahmen anzeigen möchten, müssen sie sich die Rolle selbst zuweisen.If they want to view snapshots, they must add themselves to the role.

Abonnementbesitzer sollten Benutzern, die Momentaufnahmen untersuchen, die Rolle Application Insights Snapshot Debugger zuweisen.Subscription owners should assign the Application Insights Snapshot Debugger role to users who will inspect snapshots. Abonnementbesitzer können diese Rolle einzelnen Benutzern oder Gruppen für die Application Insights-Zielressource oder für die dazugehörige Ressourcengruppe oder das dazugehörige Abonnement zuweisen.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. Navigieren Sie im Azure-Portal zu der Application Insights-Ressource.Navigate to the Application Insights resource in the Azure portal.
  2. Klicken Sie auf Zugriffssteuerung (IAM) .Click Access control (IAM).
  3. Klicken Sie auf die Schaltfläche Rollenzuweisung hinzufügen.Click the +Add role assignment button.
  4. Wählen Sie in der Dropdownliste Rollen die Option Application Insights-Momentaufnahmedebugger aus.Select Application Insights Snapshot Debugger from the Roles drop-down list.
  5. Suchen Sie nach dem hinzuzufügenden Benutzer, und geben Sie einen Namen für ihn ein.Search for and enter a name for the user to add.
  6. Klicken Sie auf die Schaltfläche Speichern, um den Benutzer der Rolle hinzuzufügen.Click the Save button to add the user to the role.

Wichtig

In Variablen- und Parameterwerten von Momentaufnahmen können persönliche und andere vertrauliche Informationen enthalten sein.Snapshots can potentially contain personal and other sensitive information in variable and parameter values.

Anzeigen von Momentaufnahmen im PortalView Snapshots in the Portal

Nachdem in Ihrer Anwendung eine Ausnahme aufgetreten ist und eine Momentaufnahme erstellt wurde, sollten Momentaufnahmen zum Anzeigen vorhanden sein.After an exception has occurred in your application and a snapshot has been created, you should have snapshots to view. Nach einer Ausnahme kann es 5 bis 10 Minuten dauern, bis eine Momentaufnahme abgeschlossen ist und im Portal angezeigt werden kann.It can take 5 to 10 minutes from an exception occurring to a snapshot ready and viewable from the portal. Wählen Sie zum Anzeigen von Momentaufnahmen im Bereich Fehler die Schaltfläche Vorgänge auf der Registerkarte Vorgänge bzw. die Schaltfläche Ausnahmen auf der Registerkarte Ausnahmen aus: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:

Seite „Fehler“

Wählen Sie einen Vorgang oder eine Ausnahme im rechten Bereich aus, um den Bereich End-to-End-Transaktionsdetails zu öffnen, und wählen Sie dann das Ausnahmeereignis aus.Select an operation or exception in the right pane to open the End-to-End Transaction Details pane, then select the exception event. Wenn eine Momentaufnahme für die entsprechende Ausnahme verfügbar ist, wird im rechten Bereich die Schaltfläche Debugmomentaufnahme öffnen mit Details für die Ausnahme angezeigt.If a snapshot is available for the given exception, an Open Debug Snapshot button appears on the right pane with details for the exception.

Schaltfläche zum Erstellen einer Debug-Momentaufnahme für eine Ausnahme

In der Ansicht der Debug-Momentaufnahme sehen Sie eine Aufrufliste und einen Variablenbereich.In the Debug Snapshot view, you see a call stack and a variables pane. Wenn Sie Frames der Aufrufliste im Aufruflistenbereich auswählen, können Sie lokale Variablen und Parameter für diesen Funktionsaufruf im Variablenbereich anzeigen.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.

Anzeigen der Debug-Momentaufnahme im Portal

Momentaufnahmen enthalten möglicherweise vertrauliche Informationen und können standardmäßig nicht angezeigt werden.Snapshots might include sensitive information, and by default they aren't viewable. Zum Anzeigen von Momentaufnahmen muss Ihnen die Rolle Application Insights Snapshot Debugger zugewiesen sein.To view snapshots, you must have the Application Insights Snapshot Debugger role assigned to you.

Anzeigen von Momentaufnahmen in Visual Studio 2017 Enterprise oder höherView Snapshots in Visual Studio 2017 Enterprise or above

  1. Klicken Sie auf die Schaltfläche Momentaufnahme herunterladen, um eine Datei vom Typ .diagsession herunterzuladen, die von Visual Studio Enterprise geöffnet werden kann.Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio Enterprise.

  2. Um die Datei .diagsession öffnen zu können, muss der Visual Studio-Momentaufnahmedebugger installiert sein.To open the .diagsession file, you need to have the Snapshot Debugger Visual Studio component installed. Der Momentaufnahmedebugger ist eine erforderliche Komponente der ASP.net-Workload in Visual Studio und kann im Visual Studio-Installer in der Liste mit den Einzelkomponenten ausgewählt werden.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. Bei Visual Studio-Versionen vor Visual Studio 2017 Version 15.5 muss die Erweiterung über den Visual Studio Marketplace installiert werden.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. Nach dem Öffnen der Momentaufnahmedatei erscheint in Visual Studio die Minidump-Debugging-Seite.After you open the snapshot file, the Minidump Debugging page in Visual Studio appears. Klicken Sie auf Debug Managed Code (Verwalteten Code debuggen), um mit dem Debuggen der Momentaufnahme zu beginnen.Click Debug Managed Code to start debugging the snapshot. Die Momentaufnahme wird bei der Codezeile geöffnet, in der die Ausnahme ausgelöst wurde, damit Sie den aktuellen Zustand des Prozesses debuggen können.The snapshot opens to the line of code where the exception was thrown so that you can debug the current state of the process.

    Anzeigen der Debugmomentaufnahme in Visual Studio

Die heruntergeladene Momentaufnahme enthält alle Symboldateien, die auf Ihrem Webanwendungsserver gefunden wurden.The downloaded snapshot includes any symbol files that were found on your web application server. Diese Symboldateien sind zum Zuordnen von Quellcode und Momentaufnahmedaten erforderlich.These symbol files are required to associate snapshot data with source code. Achten Sie bei App Service-Apps darauf, dass die Symbolbereitstellung aktiviert ist, wenn Sie Ihre Web-Apps veröffentlichen.For App Service apps, make sure to enable symbol deployment when you publish your web apps.

Funktionsweise von MomentaufnahmenHow snapshots work

Der Snapshot Collector wird als Application Insights-Telemetrieprozessor implementiert.The Snapshot Collector is implemented as an Application Insights Telemetry Processor. Wenn die Anwendung ausgeführt wird, wird der Snapshot Collector-Telemetrieprozessor der Telemetriepipeline Ihrer Anwendung hinzugefügt.When your application runs, the Snapshot Collector Telemetry Processor is added to your application's telemetry pipeline. Bei jedem Aufruf von TrackException durch Ihre Anwendung berechnet der Snapshot Collector auf der Grundlage der Art der ausgelösten Ausnahme und der auslösenden Methode eine Problem-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. Bei jedem Aufruf von „TrackException“ durch Ihre Anwendung erhöht sich der Zähler für die entsprechende Problem-ID.Each time your application calls TrackException, a counter is incremented for the appropriate Problem ID. Wenn der Zähler den Wert ThresholdForSnapshotting erreicht, wird die Problem-ID einem Sammlungsplan hinzugefügt.When the counter reaches the ThresholdForSnapshotting value, the Problem ID is added to a Collection Plan.

Der Snapshot Collector abonniert auch das Ereignis AppDomain.CurrentDomain.FirstChanceException, um ausgelöste Ausnahmen zu überwachen.The Snapshot Collector also monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event. Wenn dieses Ereignis ausgelöst wird, wird die Problem-ID der Ausnahme berechnet und mit den Problem-IDs im Sammlungsplan verglichen.When that event fires, the Problem ID of the exception is computed and compared against the Problem IDs in the Collection Plan. Ist eine Entsprechung vorhanden, wird eine Momentaufnahme des ausgeführten Prozesses erstellt.If there's a match, then a snapshot of the running process is created. Der Momentaufnahme wird ein eindeutiger Bezeichner zugewiesen, und die Ausnahme wird mit diesem Bezeichner gekennzeichnet.The snapshot is assigned a unique identifier and the exception is stamped with that identifier. Nach Ausführung des Handlers „FirstChanceException“ wird die ausgelöste Ausnahme ganz normal verarbeitet.After the FirstChanceException handler returns, the thrown exception is processed as normal. Letztendlich erreicht die Ausnahme wieder die Methode „TrackException“ und wird zusammen mit dem Momentaufnahmebezeichner an Application Insights gemeldet.Eventually, the exception reaches the TrackException method again where it, along with the snapshot identifier, is reported to Application Insights.

Der Hauptprozess wird mit minimaler Unterbrechung weiter ausgeführt und stellt weiter Datenverkehr für Benutzer bereit.The main process continues to run and serve traffic to users with little interruption. In der Zwischenzeit wird die Momentaufnahme an den Snapshot Uploader-Prozess übergeben.Meanwhile, the snapshot is handed off to the Snapshot Uploader process. Der Snapshot Uploader erstellt einen Minidump mit allen relevanten Symboldateien (PDB-Dateien) und lädt ihn in Application Insights hoch.The Snapshot Uploader creates a minidump and uploads it to Application Insights along with any relevant symbol (.pdb) files.

Tipp

  • Bei einer Prozessmomentaufnahme handelt es sich um einen angehaltenen Klon des ausgeführten Prozesses.A process snapshot is a suspended clone of the running process.
  • Die Erstellung der Momentaufnahme dauert 10 bis 20 Millisekunden.Creating the snapshot takes about 10 to 20 milliseconds.
  • Der Standardwert für ThresholdForSnapshotting ist „1“.The default value for ThresholdForSnapshotting is 1. Das ist gleichzeitig auch der Mindestwert.This is also the minimum value. Ihre App muss die gleiche Ausnahme also zweimal auslösen, bevor eine Momentaufnahme erstellt wird.Therefore, your app has to trigger the same exception twice before a snapshot is created.
  • Legen Sie IsEnabledInDeveloperMode auf „true“ fest, wenn Sie beim Debuggen in Visual Studio Momentaufnahmen generieren möchten.Set IsEnabledInDeveloperMode to true if you want to generate snapshots while debugging in Visual Studio.
  • Die Rate der Momentaufnahmenerstellung wird durch die Einstellung SnapshotsPerTenMinutesLimit begrenzt.The snapshot creation rate is limited by the SnapshotsPerTenMinutesLimit setting. Standardmäßig ist das Limit auf eine einzelne Momentaufnahme pro zehn Minuten festgelegt.By default, the limit is one snapshot every ten minutes.
  • Pro Tag können maximal 50 Momentaufnahmen hochgeladen werden.No more than 50 snapshots per day may be uploaded.

EinschränkungenLimitations

Die standardmäßige Datenaufbewahrungsdauer beträgt 15 Tage.The default data retention period is 15 days. Für jede Application Insights-Instanz ist eine maximale Anzahl von 50 Momentaufnahmen pro Tag zulässig.For each Application Insights instance, a maximum number of 50 snapshots is allowed per day.

Veröffentlichen von SymbolenPublish symbols

Für den Momentaufnahmedebugger müssen Symboldateien auf dem Produktionsserver vorhanden sein, um Variablen zu decodieren und eine gute Debugleistung in Visual Studio zu erzielen.The Snapshot Debugger requires symbol files on the production server to decode variables and to provide a debugging experience in Visual Studio. Die Version 15.2 (oder höher) von Visual Studio 2017 veröffentlicht Symbole für Releasebuilds standardmäßig im Rahmen der Veröffentlichung für App Service.Version 15.2 (or above) of Visual Studio 2017 publishes symbols for release builds by default when it publishes to App Service. In Vorgängerversionen müssen Sie der Veröffentlichungsprofildatei vom Typ .pubxml die folgende Zeile hinzufügen, um Symbole im Releasemodus zu veröffentlichen: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>

Stellen Sie für Azure Compute und andere Typen sicher, dass die Symboldateien im selben Ordner wie die DLL-Datei der Hauptanwendung (in der Regel wwwroot/bin) liegen oder unter dem aktuellen Pfad verfügbar sind.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.

Hinweis

Weitere Informationen zu den verschiedenen verfügbaren Symboloptionen finden Sie in der Visual Studio-Dokumentation.For more information on the different symbol options that are available consult the Visual Studio documentation. Um optimale Ergebnisse zu erzielen, wird die Verwendung von „full“, „portable“ oder „embedded“ empfohlen.For best results, we recommend using “Full”, “Portable” or “Embedded”.

Optimierte BuildsOptimized builds

In einigen Fällen können lokale Variablen aufgrund von Optimierungen, die durch den JIT-Compiler angewendet werden, nicht in Releasebuilds angezeigt werden.In some cases, local variables can't be viewed in release builds because of optimizations that are applied by the JIT compiler. In Azure App Services kann der Snapshot Collector allerdings Auslösemethoden deoptimieren, die Teil des entsprechenden Sammlungsplans sind.However, in Azure App Services, the Snapshot Collector can deoptimize throwing methods that are part of its Collection Plan.

Tipp

Installieren Sie in Ihrer App Service-Instanz die Application Insights-Websiteerweiterung, um Deoptimierungsunterstützung zu erhalten.Install the Application Insights Site Extension in your App Service to get deoptimization support.

Nächste SchritteNext steps

Aktivieren des Application Insights-Momentaufnahmedebuggers für Ihre Anwendung:Enable Application Insights Snapshot Debugger for your application:

Über den Application Insights-Momentaufnahmedebugger hinaus:Beyond Application Insights Snapshot Debugger: