Macros de signalement d’erreurs et de débogage

Article
10/12/2023

Ces macros fournissent des installations de débogage et de trace utiles.

Nom	Description
_ATL_DEBUG_INTERFACES	Écrit, dans la fenêtre de sortie, toutes les fuites d’interface détectées lorsqu’elles `_Module.Term` sont appelées.
_ATL_DEBUG_QI	Écrit tous les appels dans `QueryInterface` la fenêtre de sortie.
ATLASSERT	Effectue la même fonctionnalité que la macro _ASSERTE trouvée dans la bibliothèque d’exécution C.
ATLENSURE	Effectue la validation des paramètres. Appel `AtlThrow` si nécessaire
ATLTRACENOTIMPL	Envoie un message à l’appareil de vidage que la fonction spécifiée n’est pas implémentée.
ATLTRACE	Signale des avertissements à un appareil de sortie, tels que la fenêtre du débogueur, en fonction des indicateurs et niveaux indiqués. Inclus pour la compatibilité descendante.
ATLTRACE2	Signale des avertissements à un appareil de sortie, tels que la fenêtre du débogueur, en fonction des indicateurs et niveaux indiqués.

_ATL_DEBUG_INTERFACES

Définissez cette macro avant d’inclure tous les fichiers d’en-tête ATL pour effectuer le suivi de tous et Release d’appels sur les AddRef interfaces de vos composants vers la fenêtre de sortie.

#define _ATL_DEBUG_INTERFACES

Notes

La sortie de trace s’affiche comme indiqué ci-dessous :

ATL: QIThunk - 2008 AddRef : Object = 0x00d81ba0 Refcount = 1 CBug - IBug

La première partie de chaque trace sera toujours ATL: QIThunk. Ensuite, il s’agit d’une valeur identifiant le thunk d’interface en cours d’utilisation. Un thunk d’interface est un objet utilisé pour conserver un nombre de références et fournir la fonctionnalité de suivi utilisée ici. Un nouveau jeu d’interface est créé sur chaque appel à l’exception QueryInterface des demandes de l’interface IUnknown (dans ce cas, le même thunk est retourné chaque fois pour se conformer aux règles d’identité de COM).

Ensuite, vous verrez AddRef ou Release indiquez quelle méthode a été appelée. Après cela, vous verrez une valeur identifiant l’objet dont le nombre de références d’interface a été modifié. La valeur tracée est le this pointeur de l’objet.

Le nombre de références suivi est le nombre de références sur ce thunk après AddRef ou Release a été appelé. Notez que ce nombre de références peut ne pas correspondre au nombre de références de l’objet. Chaque thunk conserve son propre nombre de références pour vous aider à vous conformer pleinement aux règles de comptage de référence de COM.

Le dernier élément d’informations suivi est le nom de l’objet et l’interface affectée par l’appel ou Release l’appelAddRef.

Toutes les fuites d’interface détectées lorsque le serveur s’arrête et _Module.Term sont appelées seront enregistrées comme suit :

ATL: QIThunk - 2005 LEAK : Object = 0x00d81ca0 Refcount = 1 MaxRefCount = 1 CBug - IBug

Les informations fournies ici sont mappée directement aux informations fournies dans les instructions de trace précédentes. Vous pouvez donc examiner les nombres de références tout au long de la durée de vie d’un jeu d’interface. En outre, vous obtenez une indication du nombre maximal de références sur ce jeu d’interface.

Remarque

_ATL_DEBUG_INTERFACES pouvez être utilisé dans les builds de vente au détail.

_ATL_DEBUG_QI

Écrit tous les appels dans QueryInterface la fenêtre de sortie.

#define _ATL_DEBUG_QI

Notes

En cas d’échec d’un QueryInterface appel, la fenêtre de sortie s’affiche :

nom de l’interface - failed

ATLASSERT

La macro ATLASSERT effectue les mêmes fonctionnalités que la macro _ASSERTE trouvée dans la bibliothèque d’exécution C.

ATLASSERT(booleanExpression);

Paramètres

booleanExpression
Expression (pointeurs inclus) qui prend une valeur différente de zéro ou 0.

Notes

Dans les builds de débogage, ATLASSERT évalue booleanExpression et génère un rapport de débogage lorsque le résultat est false.

Spécifications

En-tête : atldef.h

ATLENSURE

Cette macro est utilisée pour valider les paramètres passés à une fonction.

ATLENSURE(booleanExpression);
ATLENSURE_THROW(booleanExpression, hr);

Paramètres

booleanExpression
Spécifie une expression booléenne à tester.

rh
Spécifie un code d’erreur à retourner.

Notes

Ces macros fournissent un mécanisme permettant de détecter et de notifier l’utilisateur d’une utilisation incorrecte des paramètres.

La macro appelle ATLASSERT et si la condition échoue.AtlThrow

Dans le cas ATLENSURE, AtlThrow est appelé avec E_FAIL.

Dans le cas ATLENSURE_THROW, AtlThrow est appelé avec le HRESULT spécifié.

La différence entre ATLENSURE et ATLASSERT est que ATLENSURE lève une exception dans les builds Release ainsi que dans les builds Debug.

Exemple

void MyImportantFunction(char* psz)
{
   ATLENSURE(NULL != psz);

   char mysz[64];
   strcpy_s(mysz, sizeof(mysz), psz);
}

Spécifications

En-tête : afx.h

ATLTRACENOTIMPL

Dans les builds de débogage d’ATL, envoie la chaîne « funcname n’est pas implémentée » à l’appareil de vidage et retourne E_NOTIMPL.

ATLTRACENOTIMPL(funcname);

Paramètres

funcname
[in] Chaîne contenant le nom de la fonction qui n’est pas implémentée.

Notes

Dans les builds release, retourne simplement E_NOTIMPL.

Exemple

ATLTRACENOTIMPL(_T("IOleControl::GetControlInfo"));

Spécifications

En-tête : atltrace.h

ATLTRACE

Signale des avertissements à un appareil de sortie, tels que la fenêtre du débogueur, en fonction des indicateurs et niveaux indiqués. Inclus pour la compatibilité descendante.

ATLTRACE(exp);

ATLTRACE(
    DWORD category,
    UINT  level,
    LPCSTR lpszFormat, ...);

Paramètres

exp
[in] Chaîne et variables à envoyer à la fenêtre de sortie ou à toute application qui intercepte ces messages.

category
[in] Type d’événement ou de méthode sur lequel signaler. Consultez les remarques pour obtenir la liste des catégories.

level
[in] Niveau de suivi à signaler. Pour plus d’informations, consultez les remarques.

lpszFormat
[in] Chaîne mise en forme à envoyer à l’appareil de vidage.

Notes

Consultez ATLTRACE2 pour obtenir une description d’ATLTRACE. ATLTRACE et ATLTRACE2 ont le même comportement, ATLTRACE est inclus pour la compatibilité descendante.

ATLTRACE2

Signale des avertissements à un appareil de sortie, tels que la fenêtre du débogueur, en fonction des indicateurs et niveaux indiqués.

ATLTRACE2(exp);

ATLTRACE2(
    DWORD category,
    UINT level,
    LPCSTR lpszFormat,  ...);

Paramètres

exp
[in] Chaîne à envoyer à la fenêtre de sortie ou à toute application qui intercepte ces messages.

category
[in] Type d’événement ou de méthode sur lequel signaler. Consultez les remarques pour obtenir la liste des catégories.

level
[in] Niveau de suivi à signaler. Pour plus d’informations, consultez les remarques.

lpszFormat
[in] Chaîne de printfformat de style à utiliser pour créer une chaîne à envoyer à l’appareil de vidage.

Notes

La forme courte de ATLTRACE2 écrit une chaîne dans la fenêtre de sortie du débogueur. La deuxième forme de ATLTRACE2 écrit également la sortie dans la fenêtre de sortie du débogueur, mais est soumise aux paramètres de l’outil de trace ATL/MFC (voir l’exemple ATLTraceTool). Par exemple, si vous définissez le niveau sur 4 et que l’outil de trace ATL/MFC est de niveau 0, le message ne s’affiche pas. le niveau peut être 0, 1, 2, 3 ou 4. La valeur par défaut, 0, signale uniquement les problèmes les plus graves.

Le paramètre de catégorie répertorie les indicateurs de trace à définir. Ces indicateurs correspondent aux types de méthodes pour lesquelles vous souhaitez signaler. Les tableaux ci-dessous répertorient les indicateurs de trace valides que vous pouvez utiliser pour le paramètre de catégorie .

Indicateurs de trace ATL

AtL, catégorie	Description
`atlTraceGeneral`	Rapports sur toutes les applications ATL. Valeur par défaut.
`atlTraceCOM`	Rapports sur les méthodes COM.
`atlTraceQI`	Signale les appels QueryInterface.
`atlTraceRegistrar`	Signale l’inscription d’objets.
`atlTraceRefcount`	Signale la modification du nombre de références.
`atlTraceWindowing`	Rapports sur les méthodes Windows ; par exemple, signale un ID de mappage de messages non valide.
`atlTraceControls`	Rapports sur les contrôles ; par exemple, signale lorsqu’un contrôle ou sa fenêtre est détruit.
`atlTraceHosting`	Signale les messages d’hébergement ; par exemple, signale lorsqu’un client dans un conteneur est activé.
`atlTraceDBClient`	Rapports sur le modèle consommateur OLE DB ; par exemple, lorsqu’un appel à GetData échoue, la sortie peut contenir hrESULT.
`atlTraceDBProvider`	Rapports sur le modèle de fournisseur OLE DB ; par exemple, signale si la création d’une colonne a échoué.
`atlTraceSnapin`	Rapports pour l’application SnapIn MMC.
`atlTraceNotImpl`	Signale que la fonction indiquée n’est pas implémentée.
`atlTraceAllocation`	Signale les messages imprimés par les outils de débogage de mémoire dans atldbgmem.h.

Indicateurs de trace MFC

Catégorie MFC	Description
`traceAppMsg`	Messages MFC à usage général. Toujours recommandé.
`traceDumpContext`	Messages de CDumpContext.
`traceWinMsg`	Messages du code de gestion des messages de MFC.
`traceMemory`	Messages du code de gestion de la mémoire de MFC.
`traceCmdRouting`	Messages du code de routage des commandes Windows de MFC.
`traceHtml`	Messages de la prise en charge de la boîte de dialogue DHTML de MFC.
`traceSocket`	Messages de la prise en charge du socket de MFC.
`traceOle`	Messages de la prise en charge OLE de MFC.
`traceDatabase`	Messages de la prise en charge de la base de données de MFC.
`traceInternet`	Messages du support Internet de MFC.

Pour déclarer une catégorie de trace personnalisée, déclarez une instance globale de la CTraceCategory classe comme suit :

CTraceCategory MY_CATEGORY(_T("MyCategoryName"), 1);

Le nom de catégorie, MY_CATEGORY dans cet exemple, est le nom que vous spécifiez au paramètre de catégorie . Le premier paramètre est le nom de catégorie qui apparaîtra dans l’outil de trace ATL/MFC. Le deuxième paramètre est le niveau de trace par défaut. Ce paramètre est facultatif et le niveau de trace par défaut est 0.

Pour utiliser une catégorie définie par l’utilisateur :

ATLTRACE2(MY_CATEGORY, 2, _T("a message in a custom category"));

Pour spécifier que vous souhaitez filtrer les messages de trace, insérez des définitions pour ces macros dans Stdafx.h avant l’instruction #include <atlbase.h> .

Vous pouvez également définir le filtre dans les directives de préprocesseur dans la boîte de dialogue Pages de propriétés. Cliquez sur l’onglet Préprocesseur , puis insérez le global dans la zone d’édition Définitions de préprocesseur.

Atlbase.h contient les définitions par défaut des macros ATLTRACE2 et ces définitions seront utilisées si vous ne définissez pas ces symboles avant le traitement d’atlbase.h.

Dans les builds de mise en production, ATLTRACE2 se compile sur (void) 0.

ATLTRACE2 limite le contenu de la chaîne à envoyer à l’appareil de vidage à plus de 1 023 caractères, après la mise en forme.

ATLTRACE et ATLTRACE2 ont le même comportement, ATLTRACE est inclus pour la compatibilité descendante.

Exemple

int i = 1;
ATLTRACE2(atlTraceGeneral, 4, "Integer = %d\n", i);
// Output: 'Integer = 1'

Voir aussi

Macros
Fonctions globales de signalement d’erreurs et de débogage

Partager via

Macros de signalement d’erreurs et de débogage

_ATL_DEBUG_INTERFACES

Notes

_ATL_DEBUG_QI

Notes

ATLASSERT

Paramètres

Notes

Spécifications

ATLENSURE

Paramètres

Notes

Exemple

Spécifications

ATLTRACENOTIMPL

Paramètres

Notes

Exemple

Spécifications

ATLTRACE

Paramètres

Notes

ATLTRACE2

Paramètres

Notes

Indicateurs de trace ATL

Indicateurs de trace MFC

Exemple

Voir aussi

Commentaires

Ressources supplémentaires