Déboguer des exceptions dans les applications .NET à l’aide du Débogueur de capture instantanée

  • Article

Le Débogueur de capture instantanée vous permet de collecter automatiquement un instantané de débogage lorsqu’une exception se produit dans votre application .NET en direct. Les captures instantanées de débogage collectés montrent l’état du code source et des variables au moment où l’exception a été levée.

Le Débogueur de capture instantanée dans Application Insights :

  • Surveille les journaux générés par le système de votre application web.
  • Collecte les captures instantanées sur vos principales levées d’exception.
  • Fournit les informations dont vous avez besoin pour diagnostiquer les problèmes en production.

En savoir plus sur les processus du débogueur et du chargeur de captures instantanées.

Applications et environnements pris en charge

Cette section répertorie les applications et les environnements pris en charge.

Applications

La collecte de captures instantanées est disponible pour :

Environnements

Les environnements suivants sont pris en charge :

Notes

Les applications clientes (par exemple, WPF, Windows Forms ou UWP) ne sont pas prises en charge.

Conditions préalables à l’utilisation du débogueur de capture instantanée

Packages et configurations

Autorisations

  • Vérifiez que vous êtes ajouté au rôle de débogueur de capture instantanée Application Insights pour la capture instantanée Application Insights cible.

Fonctionnement du Débogueur de capture instantanée

Le Débogueur de capture instantanée est implémenté comme Processeur de données de télémétrie Application Insights. Quand votre application s’exécute, le processeur de données de télémétrie du Débogueur de capture instantanée est ajouté au pipeline de journaux générés par le système de votre application.

Important

Les instantanés peuvent contenir des données personnelles ou d’autres informations sensibles dans les valeurs des variables et des paramètres. Les données des instantanés sont stockées dans la même région que votre ressource Application Insights.

Processus de débogueur de capture instantanée

Le processus de débogueur de capture instantanée démarre et se termine par la méthode TrackException. Une capture instantanée de processus est un clone suspendu du processus en cours d’exécution, de sorte que vos utilisateurs n’ont pas d’interruption.

  1. Votre application lève le TrackException.

  2. Le débogueur de capture instantanée surveille les exceptions à mesure qu’elles sont levées en s’abonnant à l’événement AppDomain.CurrentDomain.FirstChanceException.

  3. Un compteur est incrémenté pour l’ID de problème.

    • Lorsque le compteur atteint la valeur ThresholdForSnapshotting, l’ID de problème est ajouté à un plan de collecte.

    Remarque

    La valeur minimale ThresholdForSnapshotting par défaut est 1. Avec cette valeur, votre application doit déclencher la même exception à deux reprises avant qu’une capture instantanée soit créée.

  4. L’identifiant du problème de l’événement d’exception est calculé et comparé aux identifiants du problème dans le plan de collecte.

  5. S’il existe une correspondance entre les ID de problèmes, une capture instantanée de rapport du processus en cours d’exécution est créée.

    • Un identificateur unique est attribué à l’instantané et l’exception est marquée avec cet identificateur.

    Remarque

    Le taux de création de capture instantanée est limité par le paramètre SnapshotsPerTenMinutesLimit. Par défaut, la limite est d’une capture instantanée toutes les 10 minutes.

  6. Une fois que le gestionnaire FirstChanceException a retourné l’exception levée, celle-ci est traitée normalement.

  7. L’exception atteint à nouveau la méthode TrackException et est signalée à Application Insights, avec l’identifiant de la capture instantanée.

Remarque

Définissez IsEnabledInDeveloperMode sur true si vous voulez générer des captures instantanées lorsque vous déboguez dans Visual Studio.

Processus du chargeur de capture instantanée

Bien que le processus de débogueur de capture instantanée continue à s’exécuter et à traiter le trafic vers les utilisateurs avec peu d’interruption, la capture instantanée est remise au processus du chargeur de captures instantanées. Le nom du chargeur de capture instantanée :

  1. Crée un minidump.

  2. Charge le minidump dans Application Insights, ainsi que tous les fichiers de symboles (.pdb) pertinents.

Remarque

Au maximum 50 captures instantanées peuvent être chargées par jour.

Si vous avez activé le Débogueur de capture instantanée et que vous ne voyez pas d’instantanés, consultez le Guide de résolution des problèmes.

Limites

Cette section décrit les limitations du Débogueur de capture instantanée.

  • Conservation des données

    Les captures instantanées de débogage sont stockées pendant 15 jours. La stratégie de conservation des données par défaut est définie par application. Si vous devez augmenter cette valeur, faites-en la demande en ouvrant une demande de support dans le portail Azure. Pour chaque instance Application Insights, un nombre maximal de 50 instantanés est autorisé par jour.

  • Publiez des symboles

    Le Débogueur de capture instantanée nécessite des fichiers de symboles sur le serveur de production pour :

    • Décoder des variables
    • Fournir une expérience de débogage dans Visual Studio

    Les versions 15.2 et ultérieures de Visual Studio 2017 publient par défaut les symboles des builds de mise en production lorsqu’elles publient dans 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 :

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    Pour Azure Compute et d’autres types, assurez-vous que les fichiers de symboles sont soit :

    • Dans le même dossier de l’application principale .dll (généralement wwwroot/bin), ou
    • Disponible sur le chemin d’accès actuel.

    Pour plus d’informations sur les différentes options de symbole disponibles, consultez la documentation de Visual Studio. Pour optimiser les résultats, nous vous recommandons d’utiliser les options « Full », « Portable » ou « Embedded ».

  • Builds optimisées

    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.

    Toutefois, le Débogueur de capture instantanée dans App Service peut « désoptimiser » des méthodes de levée faisant partie de son plan de collecte.

    Conseil

    Installez l’extension de site Application Insights dans votre instance d’App Service pour obtenir un support de « désoptimisation ».

Étapes suivantes

Activez le Débogueur de capture instantanée Application Insights pour votre application :

Notes de publication pour Microsoft.ApplicationInsights.SnapshotCollector

Cette section contient les notes de publication relatives au package NuGet Microsoft.ApplicationInsights.SnapshotCollector pour les applications .NET, qui est utilisé par le Débogueur de capture instantanée Application Insights.

Découvrez-en plus sur le Débogueur de capture instantanée Azure Application Insights pour les applications .NET.

Pour signaler des bogues et envoyer des commentaires, créez un problème sur GitHub.

Notes

Le support de l’ingestion de clé d’instrumentation prendra fin le 31 mars 2025. L’ingestion de clé d’instrumentation continuera de fonctionner, mais nous ne fournirons plus de mises à jour ni de support pour la fonctionnalité. Passez aux chaînes de connexion pour tirer parti des nouvelles fonctionnalités.

1.4.6

Version intermédiaire visant à résoudre une régression lors de l’utilisation d’applications .NET 8.

Résolution des bogues

  • Les exceptions levées à partir de méthodes générées dynamiquement (par exemple, des arborescences d’expressions compilées) dans .NET 8 ne sont pas suivies correctement. Fixe.

1.4.5

Une version point pour traiter un bogue signalé par l’utilisateur.

Résolution des bogues

  • Correction d’AccessViolationException lors de la lecture de certains fichiers PDB.

Modifications

  • Ajout d’un fichier ReadMe (Lisez-moi) au package NuGet.
  • Mise à jour du fichier msdia140.dll.

1.4.4

Une version point pour traiter un bogue signalé par l’utilisateur.

Résolution des bogues

Modifications

  • Réduction du niveau des messages d’échec d’analyse PDB de Erreur à Avertissement.
  • Mise à jour du fichier msdia140.dll.
  • Une connexion de service est évitée si le débogueur est désactivé via les paramètres d’extension de site.

1.4.3

Une version point pour traiter un bogue signalé par l’utilisateur.

Résolution des bogues

1.4.2

Une version point pour traiter un bogue signalé par l’utilisateur.

Résolution des bogues

Correction de ArgumentException : les délégués doivent être du même type.

1.4.1

Une version point pour rétablir un changement cassant introduit dans la version 1.4.0.

Résolution des bogues

Correction de Méthode introuvable dans WebJobs.

1.4.0

Ajout de plusieurs améliorations et de la prise en charge de l’authentification Microsoft Entra pour l’ingestion d’Application Insights.

Modifications

  • Réduction de la taille du package Snapshot Collector de 60 %, passant de 10,34 Mo à 4,11 Mo.
  • netstandard2.0 ciblé uniquement dans Snapshot Collector.
  • Passage de la dépendance du SDK Application Insights à 2.15.0.
  • Rajout de MinidumpWithThreadInfo lors de l’écriture des sauvegardes.
  • Ajout de CompatibilityVersion pour améliorer la synchronisation entre l’agent Snapshot Collector et le chargeur de capture instantanée en cas de changements cassants.
  • Modification de l’algorithme de nommage LogFile SnapshotUploader pour éviter les E/S de fichier excessives dans App Service.
  • Ajout de pid, role name et process start time aux métadonnées de blob chargées.
  • Utilisation de System.Diagnostics.Process dans Snapshot Collector et Snapshot Uploader.

Nouvelles fonctionnalités

Ajout de l’authentification Microsoft Entra à SnapshotCollector. Pour en savoir plus sur l’authentification Microsoft Entra dans Application Insights, consultez Authentification Microsoft Entra pour Application Insights.

1.3.7.5

Version point permettant de rétroporter un correctif à partir de 1.4.0-pre.

Résolution des bogues

Correction d’ObjectDisposedException à l’arrêt.

1.3.7.4

Version intermédiaire qui résout un problème découvert lors du test du scénario d'attachement sans code d'App Service.

Modifications

La cible netcoreapp3.0 dépend maintenant de Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (elle dépendait auparavant de >= 2.1.2).

1.3.7.3

Une version mineure corrective qui résout quelques problèmes à fort impact.

Résolution des bogues

  • Correction de la découverte de fichiers PDB dans le dossier wwwroot/bin, qui a été rompue lors de la modification de l’algorithme de recherche de symboles dans la version 1.3.6.
  • Correction de ExtractWasCalledMultipleTimesException bruyant dans la télémétrie.

1.3.7

Modifications

La cible netcoreapp2.0 de SnapshotCollector dépend de Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (une nouvelle fois). Ce changement rétablit le comportement antérieur à la version 1.3.5. Nous avons essayé de la mettre à niveau dans la version 1.3.6, mais cela a rompu certains scénarios App Service.

Nouvelles fonctionnalités

Snapshot Collector lit et analyse ConnectionString à partir de la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING ou de TelemetryConfiguration. Il sert essentiellement à définir le point de terminaison pour la connexion au service de capture instantanée. Pour plus d’informations, consultez la documentation sur les chaînes de connexion.

Résolution des bogues

Passage à l’utilisation de HttpClient pour toutes les cibles sauf net45, car WebRequest échouait dans certains environnements en raison d’un SecurityProtocol incompatible (requiert TLS 1.2).

1.3.6

Modifications

  • SnapshotCollector dépend maintenant de Microsoft.ApplicationInsights>= 2.5.1 pour tous les frameworks cibles. Cette exigence peut être un changement cassant si votre application dépend d’une version antérieure du SDK Microsoft.ApplicationInsights.
  • Suppression de la prise en charge de TLS 1.0 et 1.1 dans le chargeur de capture instantanée.
  • La période des analyses PDB est désormais de 24 heures par défaut, au lieu de 15 minutes. Configurable via PdbRescanInterval sur SnapshotCollectorConfiguration.
  • L’analyse PDB recherche uniquement les dossiers de niveau supérieur, au lieu de procéder de manière récursive. Il peut s’agir d’un changement cassant si vos symboles se trouvent dans des sous-dossiers du dossier binaire.

Nouvelles fonctionnalités

  • Rotation des journaux dans SnapshotUploader pour éviter de remplir le dossier des journaux avec des fichiers anciens.
  • Prise en charge de la désoptimisation (par le biais de ReJIT on attach) pour les applications .NET Core 3.0.
  • Ajout de symboles au package NuGet.
  • Définissez davantage de métadonnées lorsque vous chargez des minidumps.
  • Ajout d’une propriété Initialized à SnapshotCollectorTelemetryProcessor. Il s’agit d’un CancellationToken, qui est annulé quand Snapshot Collector est initialisé et connecté au point de terminaison de service.
  • Les captures instantanées peuvent désormais être prises pour les exceptions dans les méthodes générées dynamiquement. Par exemple, les arborescences d’expressions compilées générées par des requêtes Entity Framework.

Résolution des bogues

  • Chargement de Snapshot Collector par AmbiguousMatchException en raison de Status Monitor.
  • La méthode d'extension GetSnapshotCollector recherche maintenant tous les TelemetrySinks.
  • Non-démarrage du chargeur de capture instantanée sur les plateformes non prises en charge.
  • Gestion d’InvalidOperationException lors de la désoptimisation des méthodes dynamiques (par exemple, Entity Framework).

1.3.5

  • Ajout de la prise en charge des clouds souverains (les anciennes versions ne fonctionnent pas dans les clouds souverains).
  • Ajout de Snapshot Collector facilité par AddSnapshotCollector(). Pour plus d’informations, consultez Activer le débogueur de capture instantanée pour les applications .NET dans Azure App Service.
  • Utilisez le paramètre MD5 FISMA pour vérifier les blocs d’objets blob. Ce paramètre permet d’éviter l’algorithme de chiffrement MD5 .NET par défaut, qui n’est pas disponible quand le système d’exploitation est défini sur le mode compatible FIPS.
  • Les frames .NET Framework sont ignorés lors de la désoptimisation des appels de fonction. Contrôlez ce comportement avec le paramètre de configuration DeoptimizeIgnoredModules.
  • Ajout du paramètre de configuration DeoptimizeMethodCount qui permet la désoptimisation de plusieurs appels de fonction.

1.3.4

  • Autorisation des clés d’instrumentation structurée.
  • Amélioration de la robustesse du chargeur de capture instantanée. Poursuite du démarrage même si les anciens journaux du chargeur ne peuvent pas être déplacés.
  • Réactivation du signalement de données de télémétrie supplémentaires quand SnapshotUploader.exe se termine immédiatement (était désactivé dans la version 1.3.3).
  • Données de télémétrie interne simplifiées.
  • Fonctionnalité expérimentale : plans de collecte par Snappoint : ajoutez snapshotOnFirstOccurence. Pour plus d'informations, consultez cet article GitHub.

1.3.3

Correction du bogue qui empêchait SnapshotUploader.exe de répondre et de charger les captures instantanées pour les applications .NET Core.

1.3.2

  • Fonctionnalité expérimentale : plans de collecte par Snappoint. Pour plus d'informations, consultez cet article GitHub.
  • SnapshotUploader.exe se ferme quand le runtime décharge l’AppDomain à partir duquel SnapshotCollector est chargé, au lieu d’attendre que le processus se termine. Cette action améliore la fiabilité du collecteur quand il est hébergé dans IIS.
  • Ajout d’une configuration qui permet à plusieurs instances SnapshotCollector utilisant la même clé d’instrumentation de partager le même processus SnapshotUploader : ShareUploaderProcess (true par défaut).
  • Plus de données de télémétrie signalées lorsque SnapshotUploader.exe se ferme immédiatement.
  • Réduction du nombre de fichiers de prise en charge dont SnapshotUploader.exe a besoin pour écrire sur le disque.

1.3.1

  • Suppression de la prise en charge de la collecte des captures instantanées avec l’API RtlCloneUserProcess et prise en charge uniquement de l’API PssCaptureSnapshots.
  • Augmentation de 1 à 3 de la limite par défaut du nombre de captures instantanées pouvant être effectuées en 10 minutes.
  • SnapshotUploader.exe est autorisé à négocier TLS 1.1 et 1.2.
  • Davantage de données de télémétrie signalées lorsque SnapshotUploader journalise un avertissement ou une erreur.
  • Arrêt de la prise de captures instantanées quand le service back-end signale que le quota quotidien a été atteint (50 captures instantanées par jour).
  • Ajout d’une vérification supplémentaire dans SnapshotUploader.exe pour empêcher que deux instances s’exécutent en même temps.

1.3.0

Modifications

  • Pour les applications ciblant .NET Framework, Snapshot Collector dépend maintenant de la version 2.3.0 ou de versions ultérieures de Microsoft.ApplicationInsights. Auparavant, il s’agissait de la version 2.2.0 ou ultérieure. Nous pensons que ce changement ne sera pas un problème pour la plupart des applications. Indiquez-nous si ce changement vous empêche d’utiliser la dernière version de Snapshot Collector.
  • Utilisation de délais de temporisation exponentiels dans le chargeur de capture instantanée lors de nouvelles tentatives de chargement.
  • Utilisation de ServerTelemetryChannel (si disponible) pour la création de rapports plus fiables sur les données de télémétrie.
  • Utilisez SdkInternalOperationsMonitor lors de la connexion initiale au service de Débogueur de capture instantanée pour qu’il soit ignoré par le suivi des dépendances.
  • Amélioration de la télémétrie autour de la connexion initiale au débogueur de capture instantanée.
  • Signalement de davantage de données de télémétrie pour :
    • La version d’App Service.
    • Instances de calcul Azure.
    • Conteneurs.
    • L’application Azure Functions.

Résolution des bogues

  • Quand l’intervalle de réinitialisation du compteur de problèmes est défini sur 24 jours, cela est interprété comme étant 24 heures.
  • Correction d’un bogue lié au fait que le chargeur de capture instantanée arrêtait de traiter de nouvelles captures instantanées en cas d’exception lors de la suppression d’une capture instantanée.

1.2.3

Correction de la signature avec nom fort avec les binaires du chargeur de capture instantanée.

1.2.2

Modifications

  • Les fichiers nécessaires pour SnapshotUploader(64).exe sont désormais incorporés en tant que ressources dans la DLL principale. Cela signifie que le dossier SnapshotCollectorFiles n’est plus créé, ce qui simplifie la génération et le déploiement, et réduit l’encombrement dans l’Explorateur de solutions. Lors de la mise à niveau, veillez à passer en revue les modifications apportées à votre fichier .csproj. Le fichier Microsoft.ApplicationInsights.SnapshotCollector.targets n’est plus nécessaire.
  • La télémétrie est journalisée dans votre ressource Application Insights même si ProvideAnonymousTelemetry est défini sur false. Grâce à ce changement, nous pouvons implémenter une fonctionnalité de contrôle d’intégrité dans le portail Azure. ProvideAnonymousTelemetry n’affecte que les données de télémétrie envoyées à Microsoft pour le support et l’amélioration du produit.
  • Quand TempFolder ou ShadowCopyFolder sont redirigés vers des variables d’environnement, le collecteur est maintenu inactif jusqu’à ce que ces variables d’environnement soient définies.
  • Pour les applications qui se connectent à Internet via un serveur proxy, Snapshot Collector détecte désormais automatiquement les paramètres de proxy et les transmet à SnapshotUploader.exe.
  • Réduction de la priorité du processus SnapshotUploader (dans la mesure du possible). Toutefois, la règle peut être ignorée à l’aide de l’option IsLowPrioirtySnapshotUploader.
  • Ajout d’une méthode d’extension GetSnapshotCollector sur TelemetryConfiguration pour les scénarios où vous souhaitez configurer Snapshot Collector par programmation.
  • Définition de la version du SDK Application Insights (au lieu de la version de l’application) dans la télémétrie côté client.
  • Envoi du premier événement de pulsation au bout de deux minutes.

Résolution des bogues

  • Correction de l’exception NullReferenceException quand des exceptions ont des dictionnaires de données Null ou immuables.
  • Dans le chargeur, la mise en correspondance des fichiers PDB fait l’objet de plusieurs nouvelles tentatives en cas de violation de partage.
  • Correction des doublons de données de télémétrie quand plusieurs threads appellent le pipeline de télémétrie au démarrage.

1.2.1

Modifications

  • Les fichiers de commentaires de documentation XML sont désormais inclus dans le package NuGet.
  • Ajout d’une méthode d’extension ExcludeFromSnapshotting sur System.Exception pour les scénarios où vous savez que vous avez une exception bruyante et que vous souhaitez éviter de créer des captures instantanées pour celle-ci.
  • Ajout d’une propriété de configuration IsEnabledWhenProfiling dont la valeur par défaut est true. Il s’agit d’un changement par rapport aux versions précédentes où la création de captures instantanées était temporairement désactivée si Application Insights Profiler exécutait une collecte détaillée. Vous pouvez récupérer l’ancien comportement en affectant à cette propriété la valeur false.

Résolution des bogues

  • Signature de SnapshotUploader64.exe de façon correcte.
  • Protection contre la double initialisation du processeur de télémétrie.
  • La double journalisation des données de télémétrie est évitée dans les applications avec plusieurs pipelines.
  • Correction d’un bogue lié à l’heure d’expiration d’un plan de collecte, qui pouvait empêcher les captures instantanées au bout de 24 heures.

1.2.0

Le changement le plus important de cette version (qui a motivé le passage à un nouveau numéro de version mineure) est une réécriture du pipeline de création et de gestion des captures instantanées. Dans les versions précédentes, cette fonctionnalité était implémentée en code natif (ProductionBreakpoints.dll* et SnapshotHolder.exe*). La nouvelle implémentation est en totalité du code managé avec des appels P/Invoke.

Pour cette première version utilisant le nouveau pipeline, nous ne nous sommes pas éloignés du comportement d’origine. La nouvelle implémentation permet une meilleure génération de rapports d’erreurs et ouvre la porte à des améliorations futures.

Autres modifications apportées dans cette version

  • MinidumpUploader.exe a été renommé SnapshotUploader.exe (ou SnapshotUploader64.exe).
  • Ajout d’une télémétrie de chronométrage aux demandes de désoptimisation et de réoptimisation.
  • Ajout de la compression gzip pour les chargements de minidump.
  • Résolution d’un problème lié au verrouillage des fichiers PDB, empêchant une mise à niveau de site.
  • Journalisation du nom du dossier d’origine (SnapshotCollectorFiles) lors de la copie en mémoire fantôme.
  • Ajustement des limites de mémoire pour les processus 64 bits pour empêcher les redémarrages de site en raison de mémoire insuffisante.
  • Résolution d’un problème lié au fait que les captures instantanées étaient toujours collectées, même après la désactivation de leur création.
  • Journalisation des événements de pulsation dans la ressource AI du client.
  • Amélioration de la vitesse des captures instantanées grâce à la suppression de « Source » de l’ID du problème.

1.1.2

Modifications

  • Augmentation des données de télémétrie d’utilisation.
  • Détection et signalement de la version et du système d’exploitation .NET.
  • Détection et signalement d’autres environnements Azure (Azure Cloud Services, Azure Service Fabric).
  • Enregistrement et signalement des métriques d’exception (nombre d’exceptions de première chance et nombre d’appels TrackException) dans les données de télémétrie de pulsation.

Résolution des bogues

  • Correction de la gestion de SqlException où l’exception interne (Win32Exception) n’est pas levée.
  • Suppression des espaces à droite des dossiers de symboles, qui entraînaient une analyse incorrecte des arguments de ligne de commande pour MinidumpUploader.
  • Les échecs de connexion au point de terminaison de l’agent du Débogueur de capture instantanée ne font plus l’objet de nouvelles tentatives infinies.

1.1.0

Modifications

  • Renforcement de la protection de la mémoire hôte. Cette fonctionnalité réduit l’impact sur la mémoire de l’ordinateur hôte.
  • Amélioration de l’expérience d’affichage des captures instantanées dans le portail Azure.