Programmes d’assistance SDK pour le débogage
Ces fonctions et déclarations sont des fonctions d’assistance globales pour implémenter des moteurs de débogage, des évaluateurs d’expression et des fournisseurs de symboles en C++.
Remarque
Il n’existe actuellement aucune version managée de ces fonctions et déclarations.
Pour que les moteurs de débogage, les évaluateurs d’expression et les fournisseurs de symboles soient utilisés par Visual Studio, ils doivent être inscrits. Pour ce faire, définissez les sous-clés et les entrées du Registre, sinon appelées « paramètres de métriques ». Les fonctions globales suivantes sont conçues pour faciliter le processus de mise à jour de ces métriques. Consultez la section sur les emplacements du Registre pour connaître la disposition de chaque sous-clé de Registre mise à jour par ces fonctions.
Fonctions de métriques générales
Il s’agit de fonctions générales utilisées par les moteurs de débogage. Les fonctions spécialisées pour les évaluateurs d’expression et les fournisseurs de symboles sont détaillées ultérieurement.
GetMetric, méthode
Récupère une valeur de métrique à partir du Registre.
HRESULT GetMetric(
LPCWSTR pszMachine,
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
DWORD * pdwValue,
LPCWSTR pszAltRoot
);
| Paramètre | Description |
|---|---|
| pszMachine | [in] Nom d’un ordinateur éventuellement distant dont le registre sera écrit (NULL signifie ordinateur local). |
| pszType | [in] Un des types de métriques. |
| guidSection | [in] GUID d’un moteur spécifique, évaluateur, exception, etc. Cela spécifie une sous-section sous un type de métrique pour un élément spécifique. |
| pszMetric | [in] Métrique à obtenir. Cela correspond à un nom de valeur spécifique. |
| pdwValue | [in] Emplacement de stockage de la valeur à partir de la métrique. Il existe plusieurs versions de GetMetric qui peuvent retourner un DWORD (comme dans cet exemple), un BSTR, un GUID ou un tableau de GUID. |
| pszAltRoot | [in] Une autre racine de Registre à utiliser. Définissez cette option pour NULL utiliser la valeur par défaut. |
SetMetric, méthode
Définit la valeur de métrique spécifiée dans le Registre.
HRESULT SetMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
const DWORD dwValue,
bool fUserSpecific,
LPCWSTR pszAltRoot
);
| Paramètre | Description |
|---|---|
| pszType | [in] Un des types de métriques. |
| guidSection | [in] GUID d’un moteur spécifique, évaluateur, exception, etc. Cela spécifie une sous-section sous un type de métrique pour un élément spécifique. |
| pszMetric | [in] Métrique à obtenir. Cela correspond à un nom de valeur spécifique. |
| dwValue | [in] Emplacement de stockage de la valeur dans la métrique. Il existe plusieurs versions de SetMetric qui peuvent stocker un DWORD (dans cet exemple), un BSTR, un GUID ou un tableau de GUID. |
| fUserSpecific | [in] TRUE si la métrique est spécifique à l’utilisateur et si elle doit être écrite dans la ruche de l’utilisateur au lieu de la ruche de l’ordinateur local. |
| pszAltRoot | [in] Une autre racine de Registre à utiliser. Définissez cette option pour NULL utiliser la valeur par défaut. |
RemoveMetric, méthode
Supprime la métrique spécifiée du Registre.
HRESULT RemoveMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
LPCWSTR pszAltRoot
);
| Paramètre | Description |
|---|---|
| pszType | [in] Un des types de métriques. |
| guidSection | [in] GUID d’un moteur spécifique, évaluateur, exception, etc. Cela spécifie une sous-section sous un type de métrique pour un élément spécifique. |
| pszMetric | [in] Métrique à supprimer. Cela correspond à un nom de valeur spécifique. |
| pszAltRoot | [in] Une autre racine de Registre à utiliser. Définissez cette option pour NULL utiliser la valeur par défaut. |
EnumMetricSections, méthode
Énumère les différentes sections de métrique dans le Registre.
HRESULT EnumMetricSections(
LPCWSTR pszMachine,
LPCWSTR pszType,
GUID * rgguidSections,
DWORD * pdwSize,
LPCWSTR pszAltRoot
);
| Paramètre | Description |
|---|---|
| pszMachine | [in] Nom d’un ordinateur éventuellement distant dont le registre sera écrit (NULL signifie ordinateur local). |
| pszType | [in] Un des types de métriques. |
| rgguidSections | [in, out] Tableau préalloué de GUID à remplir. |
| pdwSize | [in] Nombre maximal de GUID pouvant être stockés dans le rgguidSections tableau. |
| pszAltRoot | [in] Une autre racine de Registre à utiliser. Définissez cette option pour NULL utiliser la valeur par défaut. |
Fonctions évaluateurs d’expression
| Fonction | Description |
|---|---|
| GetEEMetric | Récupère une valeur de métrique à partir du Registre. |
| SetEEMetric | Définit la valeur de métrique spécifiée dans le Registre. |
| RemoveEEMetric | Supprime la métrique spécifiée du Registre. |
| GetEEMetricFile | Obtient un nom de fichier à partir de la métrique spécifiée et le charge, en retournant le contenu du fichier sous forme de chaîne. |
Fonctions d’exception
| Fonction | Description |
|---|---|
| GetExceptionMetric | Récupère une valeur de métrique à partir du Registre. |
| SetExceptionMetric | Définit la valeur de métrique spécifiée dans le Registre. |
| RemoveExceptionMetric | Supprime la métrique spécifiée du Registre. |
| RemoveAllExceptionMetrics | Supprime toutes les métriques d’exception du Registre. |
Fonctions du fournisseur de symboles
| Fonction | Description |
|---|---|
| GetSPMetric | Récupère une valeur de métrique à partir du Registre. |
| SetSPMetric | Définit la valeur de métrique spécifiée dans le Registre. |
| RemoveSPMetric | Supprime la métrique spécifiée du Registre. |
Fonctions d’énumération
| Fonction | Description |
|---|---|
| EnumMetricSections | Énumère toutes les métriques pour un type de métrique spécifié. |
| EnumDebugEngine | Énumère les moteurs de débogage inscrits. |
| EnumEEs | Énumère les évaluateurs d’expression inscrits. |
| EnumExceptionMetrics | Énumère toutes les métriques d’exception. |
Définitions de métriques
Ces définitions peuvent être utilisées pour les noms de métriques prédéfinis. Les noms correspondent à différentes clés de Registre et noms de valeurs et sont tous définis en tant que chaînes de caractères larges : par exemple. extern LPCWSTR metrictypeEngine
| Types de métriques prédéfinis | Description : Clé de base pour.... |
|---|---|
| metrictypeEngine | Toutes les métriques du moteur de débogage. |
| metrictypePortSupplier | Toutes les métriques des fournisseurs de ports. |
| metrictypeException | Toutes les métriques d’exception. |
| metricttypeEEExtension | Toutes les extensions de l’évaluateur d’expression. |
| Propriétés du moteur de débogage | Description |
|---|---|
| metricAddressBP | Affectez la valeur différente de zéro pour indiquer la prise en charge des points d’arrêt d’adresse. |
| metricAlwaysLoadLocal | Affectez la valeur différente de zéro pour toujours charger le moteur de débogage localement. |
| metricLoadInDebuggeeSession | NON UTILISÉ |
| metricLoadedByDebuggee | Défini sur différent de zéro pour indiquer que le moteur de débogage sera toujours chargé avec ou par le programme en cours de débogage. |
| metricAttach | Affectez la valeur différente de zéro pour indiquer la prise en charge de la pièce jointe aux programmes existants. |
| metricCallStackBP | Affectez la valeur différente de zéro pour indiquer la prise en charge des points d’arrêt de la pile des appels. |
| metricConditionalBP | Définissez la valeur différente de zéro pour indiquer la prise en charge du paramètre des points d’arrêt conditionnels. |
| metricDataBP | Définissez la valeur différente de zéro pour indiquer la prise en charge du paramètre des points d’arrêt sur les modifications apportées aux données. |
| metricDisassembly | Définissez la valeur différente de zéro pour indiquer la prise en charge de la production d’une liste désassembleur. |
| metricDumpWriting | Affectez la valeur différente de zéro pour indiquer la prise en charge de l’écriture de vidage (vidage de la mémoire sur un appareil de sortie). |
| metricENC | Affectez la valeur différente de zéro pour indiquer la prise en charge de La modification et de la poursuite. Remarque : Un moteur de débogage personnalisé ne doit jamais définir cette valeur ou doit toujours le définir sur 0. |
| metricExceptions | Affectez la valeur différente de zéro pour indiquer la prise en charge des exceptions. |
| metricFunctionBP | Affectez la valeur différente de zéro pour indiquer la prise en charge des points d’arrêt nommés (points d’arrêt qui arrêtent lorsqu’un nom de fonction est appelé). |
| metricHitCountBP | Affectez la valeur différente de zéro pour indiquer la prise en charge du paramètre des points d’arrêt « point d’accès » (points d’arrêt déclenchés uniquement après avoir atteint un certain nombre de fois). |
| metricJITDebug | Défini sur différent de zéro pour indiquer la prise en charge du débogage juste-à-temps (le débogueur est lancé lorsqu’une exception se produit dans un processus en cours d’exécution). |
| metricMemory | NON UTILISÉ |
| metricPortSupplier | Définissez-le sur le CLSID du fournisseur de ports si un fournisseur est implémenté. |
| metricRegisters | NON UTILISÉ |
| metricSetNextStatement | Affectez la valeur différente de zéro pour indiquer la prise en charge de la définition de l’instruction suivante (qui ignore l’exécution d’instructions intermédiaires). |
| metricSuspendThread | Affectez la valeur différente de zéro pour indiquer la prise en charge de l’interruption de l’exécution de threads. |
| metricWarnIfNoSymbols | Défini sur différent de zéro pour indiquer que l’utilisateur doit être averti s’il n’y a pas de symboles. |
| metricProgramProvider | Définissez-le sur le CLSID du fournisseur de programmes. |
| metricAlwaysLoadProgramProviderLocal | Définissez cette valeur sur différente de zéro pour indiquer que le fournisseur de programme doit toujours être chargé localement. |
| metricEngineCanWatchProcess | Définissez cette valeur sur différent de zéro pour indiquer que le moteur de débogage surveille les événements de processus au lieu du fournisseur de programmes. |
| metricRemoteDebugging | Définissez cette valeur sur différente de zéro pour indiquer la prise en charge du débogage à distance. |
| metricEncUseNativeBuilder | Définissez cette valeur sur différente de zéro pour indiquer que le Gestionnaire de modification et de continue doit utiliser la dll encbuild.dll du moteur de débogage pour générer pour Modifier et Continuer. Remarque : Un moteur de débogage personnalisé ne doit jamais définir cette valeur ou doit toujours le définir sur 0. |
| metricLoadUnderWOW64 | Définissez cette valeur sur différente de zéro pour indiquer que le moteur de débogage doit être chargé dans le processus de débogage sous WOW lors du débogage d’un processus 64 bits ; sinon, le moteur de débogage sera chargé dans le processus Visual Studio (qui s’exécute sous WOW64). |
| metricLoadProgramProviderUnderWOW64 | Définissez cette valeur sur différente de zéro pour indiquer que le fournisseur de programmes doit être chargé dans le processus de débogage lors du débogage d’un processus 64 bits sous WOW ; sinon, il sera chargé dans le processus Visual Studio. |
| metricStopOnExceptionCrossingManagedBoundary | Définissez cette valeur sur différent de zéro pour indiquer que le processus doit s’arrêter si une exception non gérée est levée sur des limites de code managées/non managées. |
| metricAutoSelectPriority | Définissez cette valeur sur une priorité pour la sélection automatique du moteur de débogage (les valeurs supérieures sont supérieures). |
| metricAutoSelectIncompatibleList | Clé de Registre contenant des entrées qui spécifient des GUID pour les moteurs de débogage à ignorer dans la sélection automatique. Ces entrées sont un nombre (0, 1, 2, et ainsi de suite) avec un GUID exprimé sous forme de chaîne. |
| metricIncompatibleList | Clé de Registre contenant des entrées qui spécifient des GUID pour les moteurs de débogage incompatibles avec ce moteur de débogage. |
| metricDisableJITOptimization | Définissez cette valeur sur différente de zéro pour indiquer que les optimisations juste-à-temps (pour le code managé) doivent être désactivées pendant le débogage. |
| Propriétés de l’évaluateur d’expression | Description |
|---|---|
| metricEngine | Cela contient le nombre de moteurs de débogage qui prennent en charge l’évaluateur d’expression spécifié. |
| metricPreloadModules | Définissez cette valeur sur différent de zéro pour indiquer que les modules doivent être préchargés lorsqu’un évaluateur d’expression est lancé sur un programme. |
| metricThisObjectName | Définissez cette valeur sur le nom de l’objet « this ». |
| Propriétés de l’extension évaluateur d’expression | Description |
|---|---|
| metricExtensionDll | Nom de la dll qui prend en charge cette extension. |
| metricExtensionRegistersSupported | Liste des registres pris en charge. |
| metricExtensionRegistersEntryPoint | Point d’entrée pour accéder aux registres. |
| metricExtensionTypesSupported | Liste des types pris en charge. |
| metricExtensionTypesEntryPoint | Point d’entrée pour l’accès aux types. |
| Propriétés du fournisseur de ports | Description |
|---|---|
| metricPortPickerCLSID | CLSID du sélecteur de ports (boîte de dialogue que l’utilisateur peut utiliser pour sélectionner des ports et ajouter des ports à utiliser pour le débogage). |
| metricDisallowUserEnteredPorts | Différent de zéro si les ports entrés par l’utilisateur ne peuvent pas être ajoutés au fournisseur de ports (cela rend la boîte de dialogue sélecteur de ports essentiellement en lecture seule). |
| metricPidBase | ID de processus de base utilisé par le fournisseur de ports lors de l’allocation des ID de processus. |
| Types de magasin de services prédéfinis | Description |
|---|---|
| storetypeFile | Les symboles sont stockés dans un fichier distinct. |
| storetypeMetadata | Les symboles sont stockés sous forme de métadonnées dans un assembly. |
| Propriétés diverses | Description |
|---|---|
| metricShowNonUserCode | Définissez cette valeur sur différent de zéro pour afficher le code non-utilisateur. |
| metricJustMyCodeStepping | Définissez cette valeur sur différente de zéro pour indiquer que l’exécution pas à pas peut se produire uniquement dans le code utilisateur. |
| metricCLSID | CLSID pour un objet d’un type de métrique spécifique. |
| metricName | Nom convivial d’un objet d’un type de métrique spécifique. |
| metricLanguage | Nom de la langue. |
Emplacements du Registre
Les métriques sont lues et écrites dans le Registre, en particulier dans la VisualStudio sous-clé.
Remarque
La plupart du temps, les métriques sont écrites dans la clé HKEY_LOCAL_MACHINE. Toutefois, parfois, HKEY_CURRENT_USER sera la clé de destination. Dbgmetric.lib gère les deux clés. Lors de l’obtention d’une métrique, elle recherche d’abord HKEY_CURRENT_USER, puis HKEY_LOCAL_MACHINE. Lorsqu’il définit une métrique, un paramètre spécifie la clé de niveau supérieur à utiliser.
[clé de Registre]\
Software\
Microsoft\
VisualStudio\
[racine de version]\
[racine de métrique]\
[type de métrique]\
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
| Espace réservé | Description |
|---|---|
| [clé de Registre] | HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE. |
| [racine de version] | Version de Visual Studio (par exemple, 7.0, 7.1ou 8.0). Toutefois, cette racine peut également être modifiée à l’aide du commutateur /rootsuffix vers devenv.exe. Pour VSIP, ce modificateur est généralement Exp, de sorte que la racine de version serait, par exemple, 8.0Exp. |
| [racine de métrique] | Il s’agit de l’une AD7Metrics ou de l’autre AD7Metrics(Debug), selon que la version de débogage de dbgmetric.lib est utilisée. Remarque : si dbgmetric.lib est utilisé ou non, cette convention d’affectation de noms doit être respectée si vous avez des différences entre les versions de débogage et de mise en production qui doivent être reflétées dans le Registre. |
| [type de métrique] | Type de métrique à écrire : Engine, ExpressionEvaluator, SymbolProvider, etc. Elles sont toutes définies comme dans dbgmetric.h, metricTypeXXXXoù XXXX est le nom de type spécifique. |
| [métrique] | Nom d’une entrée à attribuer à une valeur pour définir la métrique. L’organisation réelle des métriques dépend du type de métrique. |
| [valeur de la métrique] | Valeur affectée à la métrique. Le type que la valeur doit avoir (chaîne, nombre, etc.) dépend de la métrique. |
Remarque
Tous les GUID sont stockés au format .{GUID} Par exemple : {123D150B-FA18-461C-B218-45B3E4589F9B}.
Déboguer les moteurs
Voici l’organisation des métriques des moteurs de débogage dans le Registre. Engine est le nom du type de métrique d’un moteur de débogage et correspond à [type de métrique] dans la sous-arborescence de Registre ci-dessus.
Engine\
[guid du moteur]\
CLSID = [guid de classe]
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
PortSupplier\
0 = [guid du fournisseur de ports]
1 = [guid du fournisseur de ports]
| Espace réservé | Description |
|---|---|
| [guid du moteur] | GUID du moteur de débogage. |
| [guid de classe] | GUID de la classe qui implémente ce moteur de débogage. |
| [guid du fournisseur de ports] | GUID du fournisseur de ports, le cas échéant. De nombreux moteurs de débogage utilisent le fournisseur de ports par défaut et ne spécifient donc pas leur propre fournisseur. Dans ce cas, la sous-clé PortSupplier est absente. |
Fournisseurs de ports
Voici l’organisation des métriques des fournisseurs de ports dans le Registre. PortSupplier est le nom du type de métrique d’un fournisseur de ports et correspond à [type de métrique].
PortSupplier\
[guid du fournisseur de ports]\
CLSID = [guid de classe]
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
| Espace réservé | Description |
|---|---|
| [guid du fournisseur de ports] | GUID du fournisseur de ports |
| [guid de classe] | GUID de la classe qui implémente ce fournisseur de ports |
Fournisseurs de symboles
Voici l’organisation des métriques de fournisseur de symboles dans le Registre. SymbolProvider est le nom du type de métrique pour le fournisseur de symboles et correspond à [type de métrique].
SymbolProvider\
[guid du fournisseur de symboles]\
file\
CLSID = [guid de classe]
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
metadata\
CLSID = [guid de classe]
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
| Espace réservé | Description |
|---|---|
| [guid du fournisseur de symboles] | GUID du fournisseur de symboles |
| [guid de classe] | GUID de la classe qui implémente ce fournisseur de symboles |
Évaluateurs d’expression
Voici l’organisation des métriques de l’évaluateur d’expression dans le Registre. ExpressionEvaluator est le nom du type de métrique de l’évaluateur d’expression et correspond à [type de métrique].
Remarque
Le type de métrique pour ExpressionEvaluator lequel il n’est pas défini dans dbgmetric.h, car il est supposé que toutes les modifications de métrique pour les évaluateurs d’expression passeront par les fonctions de métrique d’évaluateur d’expression appropriées (la disposition de la ExpressionEvaluator sous-clé est quelque peu compliquée, de sorte que les détails sont masqués dans dbgmetric.lib).
ExpressionEvaluator\
[guid de langue]\
[guid du fournisseur]\
CLSID = [guid de classe]
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
Engine\
0 = [guid du moteur de débogage]
1 = [guid du moteur de débogage]
| Espace réservé | Description |
|---|---|
| [guid de langue] | GUID d’une langue |
| [guid du fournisseur] | GUID d’un fournisseur |
| [guid de classe] | GUID de la classe qui implémente cet évaluateur d’expression |
| [guid du moteur de débogage] | GUID d’un moteur de débogage avec lequel cet évaluateur d’expression fonctionne |
Extensions de l’évaluateur d’expression
Voici l’organisation des métriques d’extension de l’évaluateur d’expression dans le Registre. EEExtensions est le nom du type de métrique pour les extensions de l’évaluateur d’expression et correspond à [type de métrique].
EEExtensions\
[guid d’extension]\
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
| Espace réservé | Description |
|---|---|
| [guid d’extension] | GUID d’une extension évaluateur d’expression |
Exceptions
Voici l’organisation des métriques d’exceptions dans le Registre. Exception est le nom du type de métrique pour les exceptions et correspond à [type de métrique].
Exception\
[guid du moteur de débogage]\
[types d’exceptions]\
[exception]\
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
[exception]\
[metric] = [valeur de la métrique]
[metric] = [valeur de la métrique]
| Espace réservé | Description |
|---|---|
| [guid du moteur de débogage] | GUID d’un moteur de débogage qui prend en charge les exceptions. |
| [types d’exceptions] | Titre général de la sous-clé identifiant la classe d’exceptions pouvant être gérée. Les noms classiques sont des exceptions C++, des exceptions Win32, des exceptions Common Language Runtime et des vérifications d’exécution natives. Ces noms sont également utilisés pour identifier une classe d’exception particulière à l’utilisateur. |
| [exception] | Nom d’une exception : par exemple, _com_error ou Control-Break. Ces noms sont également utilisés pour identifier une exception particulière à l’utilisateur. |
Spécifications
Ces fichiers se trouvent dans le répertoire d’installation du Kit de développement logiciel (SDK) Microsoft Visual Studio 2010 (par défaut, [lecteur]\Program Files\Microsoft Visual Studio 2010 SDK\).
En-tête : includes\dbgmetric.h
Bibliothèque : libs\ad2de.lib, libs\dbgmetric.lib