Diagnostiquer les erreurs avec les Assistants de débogage managés

Les Assistants Débogage managé sont des aides au débogage qui fonctionnent avec le Common Language Runtime (CLR) pour fournir des informations sur l’état d’exécution. Les Assistants génèrent des messages d'information sur les événements du runtime que vous ne pouvez pas intercepter en temps normal. Vous pouvez utiliser les Assistants Débogage managé pour isoler les bogues d'application difficiles à déceler qui se produisent pendant les phases de transition entre un code managé et un code non managé.

Vous pouvez activer ou désactiver tous les Assistants Débogage managé en ajoutant une clé au Registre Windows ou en définissant une variable d’environnement. Vous pouvez activer des Assistants Débogage managé spécifiques à l'aide de paramètres de configuration d'application. Vous pouvez définir des paramètres de configuration supplémentaires pour certains Assistants Débogage managé dans le fichier de configuration de l'application. Comme ces fichiers de configuration sont analysés au chargement du runtime, vous devez activer l'Assistant Débogage managé avant que l'application managée ne démarre. Vous ne pouvez pas l'activer pour les applications qui ont déjà démarré.

Le tableau suivant répertorie les Assistants Débogage managé fournis avec .NET Framework.

Par défaut, le .NET Framework active une partie des Assistants Débogage managé pour tous les débogueurs managés. Vous pouvez afficher l’ensemble par défaut dans Visual Studio en cliquant sur Windows>Paramètres d’exception dans le menu Déboguer et en développant la liste Assistants Débogage managé.

Activer et désactiver des Assistants Débogage managé

Vous pouvez activer et désactiver les Assistants Débogage managé en utilisant une clé de Registre, une variable d'environnement et des paramètres de configuration d'application. Vous devez activer la clé de Registre ou la variable d'environnement pour utiliser les paramètres de configuration d'application.

Clé de Registre

Pour activer les Assistants Débogage managé, ajoutez la sous-clé HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\MDA (type REG_SZ, valeur 1) au Registre Windows. Copiez l’exemple suivant dans un fichier texte nommé MDAEnable.reg. Ouvrez l’Éditeur du Registre Windows (RegEdit.exe) et, dans le menu Fichier, choisissez Importer. Sélectionnez le fichier MDAEnable.reg pour activer les Assistants Débogage managé sur cet ordinateur. Définir la sous-clé sur la valeur de chaîne 1 (pas sur la valeur DWORD 1) active la lecture des paramètres d’Assistant Débogage managé à partir du fichier nom_application.suffixe.mda.config. Par exemple, le fichier de configuration d’Assistant Débogage managé pour le Bloc-notes porterait le nom notepad.exe.mda.config.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework]
"MDA"="1"

Si l'ordinateur exécute une application 32 bits sur un système d'exploitation 64 bits, la clé MDA doit être définie comme suit :

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework]
"MDA"="1"

Consultez Paramètres de configuration spécifiques à l’application. Le paramètre de Registre peut être remplacé par la variable d’environnement COMPLUS_MDA. Pour plus d’informations, consultez Variable d’environnement.

Pour désactiver les Assistants Débogage managé, définissez la sous-clé MDA sur 0 (zéro) à l’aide de l’Éditeur du Registre Windows.

Par défaut, certains Assistants Débogage managé sont activés quand vous exécutez une application qui est attachée à un débogueur, même sans que la clé de Registre soit ajoutée. Vous pouvez désactiver ces Assistants en exécutant le fichier MDADisable.reg, comme indiqué précédemment dans cette section.

Variable d’environnement

L’activation des Assistants Débogage managé peut également être contrôlée par la variable d’environnement COMPLUS_MDA, qui remplace la clé de Registre. La chaîne COMPLUS_MDA est une liste de noms d’Assistant Débogage managé ou d’autres chaînes de contrôle spéciales séparés par des points-virgules et sans distinction minuscules/majuscules. Démarrer sous un débogueur managé ou non managé active par défaut un ensemble d'Assistants Débogage managé. Pour ce faire, la valeur de la variable d'environnement ou de la clé de Registre doit être implicitement ajoutée au début de la liste délimitée par des points-virgules qui répertorie les Assistants Débogage managé activés par défaut sous les débogueurs. Les chaînes de contrôle spéciales sont les suivantes :

• 0 : désactive tous les Assistants Débogage managé.

• 1 : lit les paramètres d’Assistant Débogage managé dans le fichier nom_application.mda.config.

• managedDebugger : active explicitement tous les Assistants Débogage managé qui sont implicitement activés quand un exécutable managé est démarré sous un débogueur.

• unmanagedDebugger : active explicitement tous les Assistants Débogage managé qui sont implicitement activés quand un exécutable non managé est démarré sous un débogueur.

En cas de conflit de paramètres, les paramètres les plus récents remplacent les paramètres antérieurs :

• COMPLUS_MDA=0 désactive tous les Assistants Débogage managé, y compris ceux qui sont implicitement activés sous un débogueur.

• COMPLUS_MDA=gcUnmanagedToManaged active gcUnmanagedToManaged outre tout Assistant Débogage managé implicitement activé sous un débogueur.

• COMPLUS_MDA=0;gcUnmanagedToManaged active gcUnmanagedToManaged, mais désactive tout Assistant Débogage managé implicitement activé sous un débogueur.

Paramètres de configuration spécifiques à l’application

Vous pouvez activer, désactiver et configurer certains Assistants séparément dans le fichier de configuration d'Assistant Débogage managé propre à l'application. Vous ne pouvez utiliser un fichier de configuration d’application pour configurer des Assistants Débogage managé que si la clé de Registre MDA ou la variable d’environnement COMPLUS_MDA est définie. En règle générale, le fichier de configuration d'application se trouve dans le même répertoire que le fichier exécutable (.exe) de l'application. Le nom de fichier prend la forme ApplicationName.mda.config; par exemple, notepad.exe.mda.config. Les assistants activés dans le fichier de configuration de l’application peuvent avoir des attributs ou des éléments conçus pour contrôler le comportement de cet assistant.

L’exemple suivant illustre l’activation et la configuration du marshaling :

<mdaConfig>
  <assistants>
    <marshaling>
      <methodFilter>
        <match name="*"/>
      </methodFilter>
      <fieldFilter>
        <match name="*"/>
      </fieldFilter>
    </marshaling>
  </assistants>
</mdaConfig>

L’Assistant Débogage managé Marshaling émet des informations sur le type managé qui est marshalé en un type non managé pour chaque transition de code managé vers un code non managé dans l’application. L’Assistant Débogage managé Marshaling peut également filtrer les noms des champs de méthode et de structure fournis dans les éléments enfants methodFilter et fieldFilter, respectivement.

L’exemple suivant illustre l’activation de plusieurs Assistants Débogage managé à l’aide de leurs paramètres par défaut :

<mdaConfig>
  <assistants>
    <illegalPrepareConstrainedRegion />
    <invalidCERCall />
    <openGenericCERCall />
    <virtualCERCall />
  </assistants>
</mdaConfig>

Exceptions de l’assistant Débogage managé

Quand un Assistant Débogage managé est activé, il est actif même si votre code n’est pas en cours d’exécution sous un débogueur. Si un événement d'Assistant Débogage managé est déclenché en l'absence de débogueur, le message de l'événement est présenté dans une boîte de dialogue d'exception non gérée, bien qu'il ne s'agisse pas d'une exception non gérée. Pour éviter l'affichage de la boîte de dialogue, supprimez les paramètres de désactivation de l'Assistant Débogage managé quand votre code ne s'exécute pas dans un environnement de débogage.

Lorsque votre code s’exécute dans l’environnement de développement intégré (IDE) Visual Studio, vous pouvez éviter la boîte de dialogue d’exception qui apparaît pour des événements MDA spécifiques. Pour ce faire, dans le menu Débogage, choisissez Windows>Paramètres d’exception. Dans la boîte de dialogue Paramètres d’exception, développez la liste Assistants Débogage managé, puis décochez la case Arrêter en cas d’exception levée pour l’Assistant Débogage managé concerné. Vous pouvez également utiliser cette boîte de dialogue pour activer l’affichage des boîtes de dialogue d’exception des Assistants Débogage managé.

Sortie de l'Assistant Débogage managé

La sortie de l’Assistant Débogage managé est similaire à l’exemple suivant, qui illustre la sortie de l’Assistant Débogage managé PInvokeStackImbalance.

Un appel à la fonction PInvoke « MDATest! MDATest.Program::StdCall » a déséquilibré la pile. Cela est probablement dû au fait que la signature PInvoke managée ne correspond pas à la signature cible non managée. Vérifiez que la convention d’appel et les paramètres de la signature PInvoke correspondent à la signature non managée cible.

Voir aussi

• Débogage, traçage et profilage