Captures instantanées de débogage sur exceptions levées dans des applications .NETDebug snapshots on exceptions in .NET apps

Quand une exception se produit, vous pouvez collecter automatiquement une capture instantanée de débogage à partir de votre application web dynamique.When an exception occurs, you can automatically collect a debug snapshot from your live web application. La capture instantanée indique l’état du code source et des variables au moment où l’exception a été levée.The snapshot shows the state of source code and variables at the moment the exception was thrown. Le Débogueur de capture instantanée d’Azure Application Insights analyse la télémétrie des exceptions à partir de votre application web.The Snapshot Debugger in Azure Application Insights monitors exception telemetry from your web app. Il collecte des captures instantanées sur les principales exceptions levées afin que vous disposiez des informations dont vous avez besoin pour diagnostiquer des problèmes de production.It collects snapshots on your top-throwing exceptions so that you have the information you need to diagnose issues in production. Incluez le package NuGet de collecte des captures instantanées dans votre application, et configurez éventuellement les paramètres de collecte dans ApplicationInsights.config. Les captures instantanées apparaissent sur les exceptions dans le portail 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.

Vous pouvez afficher les captures instantanées de débogage dans le portail pour consulter la pile des appels et inspecter les variables à chaque frame de pile des appels.You can view debug snapshots in the portal to see the call stack and inspect variables at each call stack frame. Pour améliorer la puissance de débogage du code source, ouvrez les instantanés avec Visual Studio 2019 Entreprise.To get a more powerful debugging experience with source code, open snapshots with Visual Studio 2019 Enterprise. Dans Visual Studio, vous pouvez également définir des points de capture instantanée pour prendre des captures instantanées de manière interactive sans attendre la levée d’une exception.In Visual Studio, you can also set Snappoints to interactively take snapshots without waiting for an exception.

Les captures instantanées de débogage sont stockées pendant 15 jours.Debug snapshots are stored for 15 days. Cette stratégie de rétention est définie application par application.This retention policy is set on a per-application basis. Si vous devez augmenter cette valeur, faites-en la demande en ouvrant une demande de support dans le portail Azure.If you need to increase this value, you can request an increase by opening a support case in the Azure portal.

Activer le Débogueur de capture instantanée Application Insights pour votre applicationEnable Application Insights Snapshot Debugger for your application

La collecte de captures instantanées est disponible pour :Snapshot collection is available for:

  • les applications .NET framework et ASP.NET exécutant .NET Framework 4.5 ou version ultérieure ;.NET Framework and ASP.NET applications running .NET Framework 4.5 or later.
  • les applications .NET core 2.0 et ASP.NET Core 2.0 s’exécutant sous Windows..NET Core 2.0 and ASP.NET Core 2.0 applications running on Windows.

Les environnements suivants sont pris en charge :The following environments are supported:

Notes

Les applications clientes (par exemple, WPF, Windows Forms ou UWP) ne sont pas prises en charge.Client applications (for example, WPF, Windows Forms or UWP) are not supported.

Si vous avez activé le Débogueur de capture instantanée et que vous ne voyez pas les instantanés, consultez notre Guide de résolution des problèmes.If you've enabled Snapshot Debugger but aren't seeing snapshots, check our Troubleshooting guide.

Accorder des autorisationsGrant permissions

L’accès aux captures instantanées est protégé par le contrôle d’accès en fonction du rôle (RBAC).Access to snapshots is protected by role-based access control (RBAC). Pour que vous puissiez examiner une capture instantanée, un propriétaire d’abonnement doit d’abord vous ajouter au rôle nécessaire.To inspect a snapshot, you must first be added to the necessary role by a subscription owner.

Notes

Les propriétaires et contributeurs ne disposent pas automatiquement de ce rôle.Owners and contributors do not automatically have this role. S’ils souhaitent afficher des captures instantanées, ils doivent s’ajouter eux-mêmes au rôle.If they want to view snapshots, they must add themselves to the role.

Les propriétaires d’abonnement doivent attribuer le rôle Application Insights Snapshot Debugger aux utilisateurs chargés d’examiner les captures instantanées.Subscription owners should assign the Application Insights Snapshot Debugger role to users who will inspect snapshots. Ce rôle peut être attribué à des utilisateurs ou à des groupes par les propriétaires d’abonnements pour la ressource Application Insights cible, ou pour son groupe de ressources ou son abonnement.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. Accédez à la ressource Application Insights dans le portail Azure.Navigate to the Application Insights resource in the Azure portal.
  2. Cliquez sur Contrôle d’accès (IAM) .Click Access control (IAM).
  3. Cliquez sur le bouton +Ajouter une attribution de rôle.Click the +Add role assignment button.
  4. Sélectionnez Débogueur de capture instantanée d’Application Insights dans la liste déroulante Rôles.Select Application Insights Snapshot Debugger from the Roles drop-down list.
  5. Entrez le nom de l’utilisateur à ajouter.Search for and enter a name for the user to add.
  6. Cliquez sur le bouton Enregistrer pour ajouter l’utilisateur au rôle.Click the Save button to add the user to the role.

Important

Les captures instantanées des valeurs de variables et de paramètres peuvent contenir des informations personnelles ou sensibles.Snapshots can potentially contain personal and other sensitive information in variable and parameter values.

Afficher les instantanés dans le portailView Snapshots in the Portal

Lorsqu’une exception s’est produite dans votre application et qu’un instantané a été créé, des captures instantanées devraient s’afficher.After an exception has occurred in your application and a snapshot has been created, you should have snapshots to view. Il peut s’écouler 5 à 10 minutes entre le moment où une exception se produit et celui où un instantané est prêt et peut être consulté à partir du portail.It can take 5 to 10 minutes from an exception occurring to a snapshot ready and viewable from the portal. Pour afficher les captures instantanées, dans le volet Échec, sélectionnez le bouton Opérations lors de l’affichage de l’onglet Opérations, ou sélectionnez le bouton Exceptions lorsque vous affichez l’onglet Exceptions :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:

Page Échecs

Sélectionnez une opération ou une exception dans le volet droit pour ouvrir le volet Détails de la transaction de bout en bout, puis sélectionnez l’événement d’exception.Select an operation or exception in the right pane to open the End-to-End Transaction Details pane, then select the exception event. Si une capture instantanée est disponible pour l’exception donnée, le bouton Ouvrir la capture instantanée de débogage s’affiche dans le volet de droite avec les détails de l’exception.If a snapshot is available for the given exception, an Open Debug Snapshot button appears on the right pane with details for the exception.

Bouton Ouvrir la capture instantanée de débogage sur l’exception

Une pile d’appel et un volet de variables s’affichent dans la vue Capture instantanée de débogage.In the Debug Snapshot view, you see a call stack and a variables pane. Quand vous sélectionnez des images de la pile d’appel dans le volet correspondant, vous voyez les variables et les paramètres locaux de cet appel de fonction dans le volet des variables.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.

Afficher la capture instantanée de débogage dans le portail

Les captures instantanées peuvent contenir des informations sensibles. Par défaut, elles ne sont pas visibles.Snapshots might include sensitive information, and by default they aren't viewable. Pour afficher les captures instantanées, le rôle Application Insights Snapshot Debugger doit vous être attribué.To view snapshots, you must have the Application Insights Snapshot Debugger role assigned to you.

Afficher les instantanés dans Visual Studio 2017 Enterprise ou une version ultérieureView Snapshots in Visual Studio 2017 Enterprise or above

  1. Cliquez sur le bouton Télécharger la capture instantanée pour télécharger un fichier .diagsession, qui peut être ouvert par Visual Studio Enterprise.Click the Download Snapshot button to download a .diagsession file, which can be opened by Visual Studio Enterprise.

  2. Pour ouvrir le fichier .diagsession, vous devez avoir installé le composant Débogueur de capture instantanée Visual Studio.To open the .diagsession file, you need to have the Snapshot Debugger Visual Studio component installed. Le composant Débogueur de capture instantanée est un composant obligatoire de la charge de travail ASP.NET dans Visual Studio qui peut être sélectionné dans la liste des composants individuels de Visual Studio Installer.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. Si vous utilisez une version de Visual Studio antérieure à Visual Studio 2017 version 15.5, vous devez installer l’extension à partir de 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. Une fois le fichier de capture instantanée ouvert, la page de débogage de minidump s’affiche dans Visual Studio.After you open the snapshot file, the Minidump Debugging page in Visual Studio appears. Cliquez sur Debug Managed Code (Déboguer le code managé) pour démarrer le débogage de la capture instantanée.Click Debug Managed Code to start debugging the snapshot. La capture instantanée s’ouvre sur la ligne de code où l’exception a été levée et vous permet de déboguer l’état actuel du processus.The snapshot opens to the line of code where the exception was thrown so that you can debug the current state of the process.

    Afficher la capture instantanée de débogage dans Visual Studio

La capture instantanée téléchargée contient tous les fichiers de symboles détectés sur votre serveur d’applications web.The downloaded snapshot includes any symbol files that were found on your web application server. Ces fichiers de symboles sont nécessaires pour associer les données de capture instantanée au code source.These symbol files are required to associate snapshot data with source code. Pour les applications App Service, veillez à activer le déploiement des symboles lorsque vous publiez vos applications web.For App Service apps, make sure to enable symbol deployment when you publish your web apps.

Fonctionnement des captures instantanéesHow snapshots work

Le collecteur de captures instantanées est implémenté en tant que Processeur d’Application Insights Telemetry.The Snapshot Collector is implemented as an Application Insights Telemetry Processor. Lorsque votre application s’exécute, le processeur de télémétrie du collecteur de captures instantanées est ajouté au pipeline de télémétrie de votre application.When your application runs, the Snapshot Collector Telemetry Processor is added to your application's telemetry pipeline. Chaque fois que votre application appelle TrackException, le collecteur de captures instantanées calcule un ID de problème à partir du type de l’exception levée et de la méthode de levée de l’exception.Each time your application calls TrackException, the Snapshot Collector computes a Problem ID from the type of exception being thrown and the throwing method. Chaque fois que votre application appelle TrackException, un compteur est incrémenté pour l’ID de problème approprié.Each time your application calls TrackException, a counter is incremented for the appropriate Problem ID. Lorsque le compteur atteint la valeur ThresholdForSnapshotting, l’ID de problème est ajouté à un Plan de collecte.When the counter reaches the ThresholdForSnapshotting value, the Problem ID is added to a Collection Plan.

Le collecteur de captures instantanées analyse également les exceptions à mesure qu’elles sont levées en s’abonnant à l’événement AppDomain.CurrentDomain.FirstChanceException.The Snapshot Collector also monitors exceptions as they're thrown by subscribing to the AppDomain.CurrentDomain.FirstChanceException event. Lorsque cet événement se déclenche, l’ID de problème de l’exception est calculé et comparé aux ID de problème figurant dans le Plan de collecte.When that event fires, the Problem ID of the exception is computed and compared against the Problem IDs in the Collection Plan. S’il existe une correspondance, un instantané du processus en cours d’exécution est créé.If there's a match, then a snapshot of the running process is created. Un identificateur unique est attribué à l’instantané et l’exception est marquée avec cet identificateur.The snapshot is assigned a unique identifier and the exception is stamped with that identifier. Après fois que le gestionnaire FirstChanceException a retourné l’exception levée, celle-ci est traitée normalement.After the FirstChanceException handler returns, the thrown exception is processed as normal. Finalement, l’exception atteint à nouveau la méthode TrackException où elle est signalée à Application Insights avec l’identificateur de capture instantanée.Eventually, the exception reaches the TrackException method again where it, along with the snapshot identifier, is reported to Application Insights.

Le processus principal continue à s’exécuter et à assurer le trafic pour les utilisateurs avec une courte interruption.The main process continues to run and serve traffic to users with little interruption. Pendant ce temps, l’instantané est remis au processus du chargeur de capture instantanée.Meanwhile, the snapshot is handed off to the Snapshot Uploader process. Le chargeur de capture instantanée crée un minidump et le charge sur Application Insights, ainsi que tous les fichiers de symboles (.pdb) pertinents.The Snapshot Uploader creates a minidump and uploads it to Application Insights along with any relevant symbol (.pdb) files.

Conseil

  • Une capture instantanée de processus est un clone suspendu du processus en cours d’exécution.A process snapshot is a suspended clone of the running process.
  • La création de l’instantané prend environ de 10 à 20 millisecondes.Creating the snapshot takes about 10 to 20 milliseconds.
  • La valeur par défaut de ThresholdForSnapshotting est 1.The default value for ThresholdForSnapshotting is 1. Il s’agit également la valeur minimale.This is also the minimum value. Par conséquent, votre application doit déclencher la même exception à deux reprises avant qu’un instantané soit créé.Therefore, your app has to trigger the same exception twice before a snapshot is created.
  • Définissez IsEnabledInDeveloperMode sur true si vous voulez générer des captures instantanées lors d’un débogage dans Visual Studio.Set IsEnabledInDeveloperMode to true if you want to generate snapshots while debugging in Visual Studio.
  • Le taux de création de capture instantanée est limité par le paramètre SnapshotsPerTenMinutesLimit.The snapshot creation rate is limited by the SnapshotsPerTenMinutesLimit setting. Par défaut, la limite est d’une capture instantanée toutes les dix minutes.By default, the limit is one snapshot every ten minutes.
  • Au maximum 50 captures instantanées peuvent être chargées par jour.No more than 50 snapshots per day may be uploaded.

LimitesLimitations

Par défaut, la période de conservation des données est de 15 jours.The default data retention period is 15 days. Pour chaque instance Application Insights, un nombre maximal de 50 instantanés est autorisé par jour.For each Application Insights instance, a maximum number of 50 snapshots is allowed per day.

Publier des symbolesPublish symbols

Le débogueur de captures instantanées nécessite que des fichiers de symboles se trouvent sur le serveur de production pour le décodage des variables et pour fournir une fonctionnalité de débogage dans Visual Studio.The Snapshot Debugger requires symbol files on the production server to decode variables and to provide a debugging experience in Visual Studio. La version 15.2 de Visual Studio 2017 (ou ultérieure) publie les symboles des builds de mise en production par défaut lors de sa publication dans App Service.Version 15.2 (or above) of Visual Studio 2017 publishes symbols for release builds by default when it publishes to App Service. Dans les versions antérieures, vous devez ajouter la ligne suivante à votre fichier de profil de publication .pubxml afin que les symboles soient publiés en mode Mise en production :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>

Pour Calcul Azure et d’autres types, vérifiez que les fichiers de symboles se trouvent dans le même dossier que le fichier .dll de l’application principale (généralement wwwroot/bin), ou sont disponibles dans le chemin d’accès actuel.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.

Notes

Pour plus d’informations sur les différentes options de symbole disponibles, voir la documentation de Visual Studio.For more information on the different symbol options that are available consult the Visual Studio documentation. Pour optimiser les résultats, nous vous recommandons d’utiliser les options « Full », « Portable » ou « Embedded ».For best results, we recommend using “Full”, “Portable” or “Embedded”.

Optimisation des versionsOptimized builds

Dans certains cas, des variables locales sont invisibles dans les builds de mise en production en raison d’optimisations appliquées par le compilateur JIT.In some cases, local variables can't be viewed in release builds because of optimizations that are applied by the JIT compiler. Toutefois, dans Azure App Services, le collecteur de captures instantanées peut « désoptimiser » des méthodes de levée d’exception faisant partie de son Plan de collecte.However, in Azure App Services, the Snapshot Collector can deoptimize throwing methods that are part of its Collection Plan.

Conseil

Installez l’extension de site Application Insights dans votre App Service pour obtenir un support de « désoptimisation ».Install the Application Insights Site Extension in your App Service to get deoptimization support.

Étapes suivantesNext steps

Activez le Débogueur de capture instantanée Application Insights pour votre application :Enable Application Insights Snapshot Debugger for your application:

Au-delà du Débogueur de capture instantanée d’Application Insights :Beyond Application Insights Snapshot Debugger: