Fichiers hint

A fichier hint aide à la Visual Studio environnement de développement intégré (IDE) d'interpréter des identificateurs Visual C++, telles que les noms de fonctions et macros.Lorsque vous ouvrez un projet Visual C++, l'IDE système d'analyse analyse le code dans chaque fichier source dans le projet et recueille des informations sur chaque identificateur.Ensuite, l'IDE utilise ces informations pour prendre en charge des fonctionnalités telles que la Affichage de classes navigateur et le Barre de navigation.

Le système d'analyse, qui est introduit dans Visual C++ 2010, comprend la syntaxe C/C++ mais peut mal interpréter une instruction contenant une macro.L'instruction peut être mal interprétée si la macro, le code source être incorrecte lors de l'écriture.L'instruction peut devenir syntaxiquement correcte lorsque le code source est compilé et que le préprocesseur remplace le identificateur de la macro avec sa définition. Le système d'analyse fonctionne sans avoir à générer le projet, car il utilise des fichiers hint pour interpréter les macros. Par conséquent, une fonctionnalité d'exploration tels que Affichage de classes est immédiatement disponible.

Un fichier hint contient personnalisables par l'utilisateur conseils, qui ont la même syntaxe que les définitions de macros C/C++.Visual C++ inclut un fichier hint intégré qui est suffisant pour la plupart des projets, mais vous pouvez créer vos propres fichiers hint pour améliorer la façon dont Visual Studio gère les identificateurs.

Scénario

Supposons que le code suivant dans un fichier source que vous examinez avec les Affichage de classes navigateur.Le STDMETHOD macro déclare une méthode nommée myMethod qui prend un paramètre et retourne un pointeur vers un HRESULT.

// Source code file.
STDMETHOD(myMethod)(int parameter1);

Les définitions de macro suivants sont dans un fichier d'en-tête distinct.

// Header file.
#define STDMETHOD(method) HRESULT (STDMETHODCALLTYPE * method)
#define STDMETHODCALLTYPE __stdcall
#define HRESULT void*

Le système d'analyse ne peut pas interpréter le code source, car une fonction appelée STDMETHOD semble être déclarée, et cette déclaration a une syntaxe incorrecte, car il comporte deux listes de paramètres.Le système d'analyse ne s'ouvre pas le fichier d'en-tête pour découvrir les définitions pour la STDMETHOD, STDMETHODCALLTYPE, et HRESULT macros.Étant donné que le système d'analyse ne peut pas interpréter le STDMETHOD macro, il ignore toute l'instruction et poursuit l'analyse.

Le système d'analyse n'utilise pas les fichiers d'en-tête, car votre projet peut dépendre d'un ou plusieurs fichiers d'en-tête importants.Si n'importe quel fichier d'en-tête change, le système d'analyse devra éventuellement réexaminer tous les fichiers d'en-tête dans votre projet, ce qui ralentit les performances de l'IDE.En revanche, le système d'analyse utilise les indications qui spécifient comment gérer la STDMETHOD, STDMETHODCALLTYPE, et HRESULT macros.

Comment savez-vous que vous avez besoin d'une indication ?Et si vous avez besoin d'une indication, quel type devez-vous créer ?Est un signe qu'une indication est nécessaire si l'affichage d'un identificateur dans Affichage de classes est incohérent avec l'affichage dans le Éditeur.Par exemple, Affichage de classes peut ne pas afficher un membre de la classe dont vous savez qu'il existe, ou le nom du membre est incorrect.Pour plus d'informations sur les types d'indications permettant de résoudre les problèmes courants, consultez les les Macros Require A Hint? section plus loin dans cette rubrique.

Architecture

Fichiers hint concernent les répertoires physiques, pas les répertoires logiques décrits dans L'Explorateur de solutions.Vous n'avez pas à ajouter un fichier hint à votre projet pour le fichier hint ait un effet.Le système d'analyse utilise des fichiers hint uniquement lorsqu'il analyse les fichiers source.

Chaque fichier hint est appelé cpp.hint.Par conséquent, de nombreux répertoires peuvent contenir un fichier hint, mais seul fichier hint peut se produire dans un répertoire particulier.

Votre projet peut être affecté par zéro ou plusieurs fichiers hint.S'il n'y a aucun fichier hint, le système d'analyse utilise des techniques de récupération d'erreur à ignorer le code source indéchiffrable.Dans le cas contraire, le système d'analyse utilise la stratégie suivante pour rechercher et rassembler des indications.

Ordre de recherche

Le système d'analyse recherche les répertoires des fichiers hint dans l'ordre suivant.

• Le répertoire qui contient le package d'installation de Visual C++)vcpackages).Ce répertoire contient un fichier hint intégré qui décrit les symboles dans les fichiers systèmes fréquemment utilisés, tels que Windows.h.Par conséquent, votre projet hérite automatiquement de la plupart des indicateurs dont il a besoin.

• Le chemin d'accès à partir du répertoire racine d'un fichier source dans le répertoire qui contient le fichier source lui-même.Dans un projet Visual C++ classique, le répertoire racine contient le fichier solution ou projet.

  L'exception à cette règle est si un fichier d'arrêt est le chemin d'accès au fichier source.Un fichier d'arrêt offre un contrôle supplémentaire sur l'ordre de recherche et est un fichier nommé cpp.Stop.Au lieu de démarrer à partir du répertoire racine, le système d'analyse recherche à partir du répertoire qui contient le fichier d'arrêt dans le répertoire qui contient le fichier source.Dans un projet classique, vous n'avez pas besoin d'un fichier d'arrêt.

Regroupement des indications

Un fichier hint contient zéro ou plusieurs conseils.Un indicateur est défini ou supprimé comme une macro C/C++.Autrement dit, le #define directive de préprocesseur crée ou redéfinit une indication et le #undef la directive supprime une indication.

Le système d'analyse ouvre chaque fichier hint dans l'ordre de recherche décrit précédemment, regroupe les indications de chaque fichier dans un ensemble de indications effectives, puis utilise les indications effectives pour interpréter les identificateurs dans votre code.

Le système d'analyse utilise les règles suivantes pour rassembler des indications.

• Si la nouvelle indication spécifie un nom qui n'est pas déjà défini, la nouvelle indication ajoute le nom à ces indications effectives.

• Si la nouvelle indication spécifie un nom qui est déjà défini, elle redéfinit l'indication existante.

• Si la nouvelle indication est un #undef la directive qui spécifie une indication effective existante, elle supprime l'indication existante.

La première règle signifie que les indications effectives sont héritées des fichiers hint précédemment ouverts.Les deux dernières règles signifient que les indications qui se produisent plus loin dans l'ordre de recherche peuvent remplacer des indications qui s'est produite précédemment.Par exemple, vous pouvez substituer des indications précédentes si vous créez un fichier hint dans le répertoire qui contient un fichier source.

Pour une représentation de la collecte des indicateurs, consultez le Exemple section plus loin dans cette rubrique.

Syntaxe

Les indications sont créées et supprimées avec la même syntaxe que les directives de préprocesseur qui créent et suppriment des macros.En fait, le système d'analyse utilise le préprocesseur C/C++ pour évaluer les indications.Pour plus d'informations sur les directives de préprocesseur, consultez #define, directive (C/C++) et #undef, directive (C/C++).

Les seuls éléments syntaxiques inhabituels sont les @<, @=, et @> chaînes de remplacement.Il s'agit de chaînes de remplacement spécifiques contenues dans les fichiers hint sont utilisées uniquement avec carte macros.Un mappage est un ensemble de macros qui lient des données, des événements ou des fonctions à d'autres données, les fonctions ou les gestionnaires d'événements.Par exemple, MFC utilise des mappages pour créer tables des messages, et ATL utilise des mappages pour créer mappages d'objet.Les chaînes de remplacement spécifique de fichier hint indiquent les éléments de départ, intermédiaires et de fin d'un mappage.Seul le nom d'une macro de mappage est significatif.Par conséquent, chaque chaîne de remplacement masque intentionnellement l'implémentation de la macro.

Les indications utilisent la syntaxe suivante.

Les Macros nécessitent une indication ?

Certains types de macros peuvent interférer avec le système d'analyse.Cette section décrit les types de macros qui peuvent provoquer un problème et le type d'indication, que vous pouvez créer pour résoudre ce problème.

Macros perturbatrices

Certaines macros provoquent le système d'analyse interprète le code source, mais peuvent être ignorées sans gêner votre navigation.Par exemple, le (Source Code Annotation LanguageSAL) macros résoudre aux attributs C++ qui vous aident à rechercher des bogues de programmation.Si vous souhaitez ignorer les annotations SAL lorsque vous parcourez le code, vous souhaiterez créer un fichier hint qui masque l'annotation.

Dans le code source suivant, le type de paramètre pour le FormatWindowClassName() fonction est PXSTR, et le nom de paramètre est szBuffer.Toutefois, le système d'analyse confond le _Pre_notnull_ et _Post_z_ Annotations SAL pour le type de paramètre ou le nom du paramètre.

Code source :

FormatWindowClassName void statique(_Pre_notnull_ _Post_z_ SzBuffer PXSTR)

Stratégie : Définition null

La stratégie dans cette situation consiste à traiter les annotations SAL comme s'ils n'existaient pas.Pour ce faire, spécifiez une indication dont la chaîne de remplacement est null.Par conséquent, le système d'analyse ignore les annotations et le Affichage de classes navigateur ne les affiche pas.(Visual C++ inclut un fichier hint intégré qui masque les annotations SAL.)

Fichier hint :

#define _Pre_notnull_

Éléments du langage C/C++ cachés

Général, le système d'analyse interprète le code source de façon erronée est si une macro masque un C/C++ / / / délimiteur ou mot clé jeton.Autrement dit, une macro peut contenir la moitié d'une paire de signes de ponctuation, tels que <>, [], {}, et ().

Dans le code source suivant, la START_NAMESPACE macro masque une accolade ouvrante non couplée){).

Code source :

#define START_NAMESPACE espace de noms MyProject {

Stratégie : Copie directe

Si la sémantique d'une macro est essentielle à l'expérience de navigation, créez une indication qui est identique à la macro.Le système d'analyse résout la macro à la définition dans le fichier hint.

Notez que si la macro dans le fichier source contienne d'autres macros, ces macros sont interprétées uniquement si elles sont déjà dans le jeu d'indications effectives.

Fichier hint :

#define START_NAMESPACE espace de noms MyProject {

Cartes

Un mappage est composé de macros qui désignent un élément de départ, élément de fin et zéro ou plusieurs éléments intermédiaires.Le système d'analyse interprète les cartes, car chaque macro de mappage masque les éléments du langage C/C++ et la syntaxe d'une instruction C/C++ complète est répartie sur plusieurs macros différentes.

Le code source suivant définit la BEGIN_CATEGORY_MAP, IMPLEMENTED_CATEGORY, et END_CATEGORY_MAP macros.

Code source :

#define BEGIN_CATEGORY_MAP(x)\
static const struct ATL::_ATL_CATMAP_ENTRY* GetCategoryMap() throw() {\
static const struct ATL::_ATL_CATMAP_ENTRY pMap[] = {
#define IMPLEMENTED_CATEGORY( catid ) { _ATL_CATMAP_ENTRY_IMPLEMENTED, &catid },
#define END_CATEGORY_MAP()\
   { _ATL_CATMAP_ENTRY_END, NULL } };\
   return( pMap ); }

Stratégie : Identifier les éléments de mappage

Spécifiez des indications pour le début, milieu (le cas échéant) et de fin, les éléments d'un mappage.Utilisez les chaînes de remplacement de mappage spéciales, @<, @=, et @>.Pour plus d'informations, consultez le Syntaxe section dans cette rubrique.

Fichier hint :

// Start of the map.
#define BEGIN_CATEGORY_MAP(x) @<
// Intermediate map element.
#define IMPLEMENTED_CATEGORY( catid ) @=
// Intermediate map element.
#define REQUIRED_CATEGORY( catid ) @=
// End of the map.
#define END_CATEGORY_MAP() @>

Macros composites

Macros composites contiennent un ou plusieurs des types de macro qui confondez pas le système d'analyse.

Le code source suivant contient la START_NAMESPACE macro, qui spécifie le début d'une portée espace de noms, et le BEGIN_CATEGORY_MAP macro, qui spécifie le début d'un mappage.

Code source :

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Stratégie : Copie directe

Créer des indications pour le START_NAMESPACE et BEGIN_CATEGORY_MAP macros, puis créez une indication pour le NSandMAP macro qui est identique à celle indiquée précédemment pour le code source.Vous pouvez également, si une macro composite consiste uniquement les macros sans interruption de service et les espaces, vous pouvez définir une indication dont la chaîne de remplacement est une définition null.

Dans cet exemple, supposons que START_NAMESPACE ait déjà une indication comme décrit dans cette rubrique dans le Éléments du langage C/C++ cachés sous-position.Et supposons BEGIN_CATEGORY_MAP ait une indication comme décrit précédemment dans Cartes.

Fichier hint :

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Macros gênantes

Certaines macros peuvent être interprétées par le système d'analyse, mais le code source est difficile à lire parce que la macro est longue ou complexe.Pour des raisons de lisibilité, vous pouvez fournir une indication qui simplifie l'affichage de la macro.

Code source :

#define HRESULT STDMETHOD(methodName) (STDMETHODCALLTYPE * methodName)

Stratégie : Simplification

Créez une indication qui affiche une définition de macro simple.

Fichier hint :

#define STDMETHOD(methodName) void* methodName

Exemple

L'exemple suivant illustre la façon dont les indications sont accumulées à partir de fichiers hint.Fichier d'arrêt n'est pas utilisés dans cet exemple.

L'illustration suivante décrit certains des répertoires physiques dans un projet Visual C++.Fichiers hint se trouvent dans le vcpackages, Débogage, A1, et A2 répertoires.

Répertoires de fichiers hint

Répertoires et contenu des fichiers Hint

Le tableau suivant répertorie les répertoires de ce projet qui contiennent des fichiers hint et le contenu de ces fichiers hint.Qu'une partie des différentes indications contenues dans le vcpackages fichier hint du répertoire sont répertoriés.

// vcpackages (partial list)
#define _In_
#define _In_opt_
#define _In_z_
#define _In_opt_z_
#define _In_count_(size)

// Debug
#undef _In_
#define OBRACE {
#define CBRACE }
#define RAISE_EXCEPTION(x) throw (x)
#define START_NAMESPACE namespace MyProject {
#define END_NAMESPACE }

// A1
#define START_NAMESPACE namespace A1Namespace {

// A2
#undef OBRACE
#undef CBRACE

Indications effectives

Le tableau suivant répertorie les indications effectives pour les fichiers source dans ce projet.

// vcpackages (partial list)
#define _In_opt_
#define _In_z_
#define _In_opt_z_
#define _In_count_(size)
// Debug...
#define RAISE_EXCEPTION(x) throw (x)
// A1
#define START_NAMESPACE namespace A1Namespace { 
// ...Debug
#define END_NAMESPACE }

Les remarques suivantes s'appliquent au tableau précédent.

• Les indications effectives proviennent du vcpackages, Débogage, A1, et A2 répertoires.

• Le #undef la directive dans le Débogage fichier hint supprimé le #define _In_ Conseil dans le vcpackages fichier hint du répertoire.

• Le fichier hint dans le A1 redéfinit le répertoire START_NAMESPACE.

• Le #undef Conseil dans le A2 répertoire supprimé les indications pour OBRACE et CBRACE dans le Débogage fichier hint du répertoire.

Voir aussi

Référence

#define, directive (C/C++)

#undef, directive (C/C++)

Les tables des messages (MFC)

Concepts

Types de fichiers créés pour les projets Visual C++

Annotations SAL

Autres ressources

Création et contrôle de fenêtres d'environnement

Macros de table des messages (ATL)

Macros de mappage d'objets