Hinweisdateien

A Hinweisdatei hilft Visual Studio integrierten Entwicklungsumgebung (IDE) Interpretation von Visual C++-Bezeichnern, z. B. die Namen von Funktionen und Makros.Wenn Sie Visual C++-Projekts, der IDE öffnen Analysesystem analysiert den Code in jeder Quelldatei im Projekt, und sammelt Informationen zu allen Bezeichnern.Dann die IDE diese Informationen verwendet, um Funktionen zu unterstützen, z. B. die Klassenansicht Browser und die Navigationsleiste.

Das Analysesystem, das in eingeführt Visual C++ 2010, versteht die C/C++-Syntax aber eine Anweisung, die ein Makro enthält fehlinterpretiert werden können.Die Anweisung kann falsch interpretiert werden, wenn das Makro bewirkt, den Quellcode dass und syntaktisch falschen.Die Anweisung wird syntaktisch richtig, wenn der Quellcode kompiliert und die Preprocesser ersetzt die Makrobezeichner mit ihrer Definition. Das Analysesystem funktioniert, ohne das Projekt zu erstellen, da es Hinweisdateien verwendet, um Makros zu interpretieren. Aus diesem Grund eine Funktion zum Durchsuchen wie Klassenansicht ist sofort verfügbar.

Eine Hinweisdatei enthält benutzerdefinierbare Hinweise, die die gleiche Syntax wie C/C++-Makrodefinitionen haben.Visual C++ enthält eine integrierte Hinweisdatei, die für die meisten Projekte ausreichend ist, aber Sie können Ihre eigenen Hinweisdateien um besser in Visual Studio Bezeichner behandelt erstellen.

Szenario

Davon ausgehen, dass der folgende Code in einer Quelldatei, die Sie mit Überprüfen der Klassenansicht Browser.Die STDMETHOD Makro deklariert eine Methode namens myMethod die einen Parameter und gibt einen Zeiger auf ein HRESULT.

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

Die folgenden Makrodefinitionen befinden sich in einer separaten Headerdatei.

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

Das Analysesystem Quellcode nicht interpretieren kann, da eine Funktion mit dem Namen STDMETHOD deklariert werden, angezeigt wird, und diese Erklärung ist syntaktisch falsch, da es zwei Parameterlisten enthält.Das Analysesystem kann nicht die Header-Datei, um die Definitionen für entdecken die STDMETHOD, STDMETHODCALLTYPE, und HRESULT Makros.Da das Analysesystem nicht interpretieren kann die STDMETHOD Makro, es ignoriert die ganze Anweisung und setzt die Analyse fort.

Das Analysesystem verwendet keine Headerdateien, da das Projekt auf eine oder mehrere wichtige Headerdateien abhängen könnte.Wenn eine Headerdatei ändert, möglicherweise das Analysesystem alle Headerdateien im Projekt nochmals die verlangsamt die Leistung der IDE.Stattdessen verwendet das Analysesystem Hinweise, die angeben, wie behandeln, die STDMETHOD, STDMETHODCALLTYPE, und HRESULT Makros.

Woher wissen Sie, dass ein Hinweis benötigt?Und wenn ein Hinweis benötigt wird, welche Art sollten Sie erstellen?Ein Zeichen, dass ein Hinweis benötigt wird, ist Wenn die Ansicht eines Bezeichners in Klassenansicht stimmt nicht mit der Ansicht in der Editor.Zum Beispiel Klassenansicht möglicherweise nicht anzeigen wird ein Klassenmember, den Sie kennen vorhanden ist oder den Namen des Members ist falsch.Weitere Informationen zu den Arten von hinweisen, die häufige Probleme zu beheben, finden Sie unter dem was Macros Require A Hint? Abschnitt weiter unten in diesem Thema.

Architektur

Hinweisdateien beziehen sich auf physische Verzeichnisse, nicht auf die logische Verzeichnisse sind die in den Projektmappen-Explorer.Sie müssen keinen dem Projekt für die Hinweisdatei Auswirkungen haben eine Hinweisdatei hinzufügen.Das Analysesystem verwendet Hinweisdateien nur, wenn es Quelldateien analysiert.

Jede Hinweisdatei wird mit dem Namen cpp.Hint.Daher können viele Verzeichnisse eine Hinweisdatei enthalten, aber nur eine Hinweisdatei kann in einem bestimmten Verzeichnis auftreten.

Das Projekt kann von 0 (null) oder mehrere Hinweisdateien beeinflusst werden.Wenn keine Hinweisdateien vorhanden sind, verwendet das Analysesystem Fehler Wiederherstellungstechniken Quellcode nicht entziffert werden ignoriert.Andernfalls verwendet das Analysesystem die folgende Strategie zum Suchen und Sammeln von hinweisen.

Suchreihenfolge

Das Analysesystem sucht Verzeichnissen nach Hinweisdateien in der folgenden Reihenfolge.

• Das Verzeichnis, das das Installationspaket für Visual C++ (enthältvcpackages).Dieses Verzeichnis enthält eine integrierte Hinweisdatei, die Symbole in häufig verwendeten Systemdateien, z. B. beschreibt Windows.h.Infolgedessen erbt das Projekt automatisch die meisten der Hinweise, die es benötigt.

• Der Pfad vom Stammverzeichnis einer Quelldatei in das Verzeichnis, das die Quelldatei selbst enthält.In einem typischen Visual C++-Projekt enthält das Stammverzeichnis die Projektmappe oder Projekt-Datei.

  Ausnahme dieser Regel besteht, wenn ein Stop-Datei ist der Pfad zur Quelldatei.Eine Stoppdatei bieten zusätzliche Steuerungsmöglichkeiten für die Suchreihenfolge und wird jede Datei mit dem Namen cpp.Stop.Statt das Root-Verzeichnis ab, durchsucht das Analysesystem aus dem Verzeichnis mit die Stoppdatei in das Verzeichnis, die die Quelldatei enthält.In einem typischen Projekt ist eine Stoppdatei nicht erforderlich.

Erfassen von Hinweisen

Eine Hinweisdatei enthält NULL oder mehr Hinweise.Ein Hinweis definiert oder wie ein C/C++-Makro gelöscht.Das heißt, die #define Präprozessor-Direktive erstellt oder definiert einen Hinweis neu und die #undef -Direktive löscht einen Hinweis.

Das Analysesystem öffnet jede Hinweisdatei in der weiter oben beschriebenen Suchreihenfolge, stellt die Hinweise aller Dateien von Effektive Hinweise, und klicken Sie dann mithilfe dieser effektiven Hinweise interpretiert die Bezeichner im Code.

Das Analysesystem verwendet die folgenden Regeln sammelt Hinweise.

• Wenn der neue Hinweis einen Namen, der noch nicht definiert ist angibt, mit der neue Hinweis den effektiven Hinweisen den Namen hinzugefügt.

• Wenn der neue Hinweis einen Namen, der bereits definiert ist angibt, wird der neue Hinweis den vorhandenen Hinweis neu definiert.

• Wenn der neue Hinweis eine #undef die Richtlinie, die einen vorhandenen effektiven Hinweis angibt, löscht der neue Hinweis den vorhandenen Hinweis.

Die erste Regel besagt, dass effektive Hinweise von zuvor geöffneten Hinweisdateien geerbt werden.Die letzten beiden Regeln besagen, dass hinweisen, die später in der Suchreihenfolge Hinweise überschreiben können, die zuvor aufgetreten sind.Sie können z. B. alle vorherigen Hinweise überschreiben, wenn Sie eine Hinweisdatei im Verzeichnis erstellen, die eine Quelldatei enthält.

Erfassung von Hinweisen wird, finden Sie in der Beispiel weiter unten in diesem Thema.

Syntax

Hinweise werden erstellt und mit der gleichen Syntax wie die Präprozessor-Direktiven, die erstellen und Löschen von Makros gelöscht.In der Tat verwendet das Analysesystem C/C++-Präprozessor die Hinweise zu bewerten.Weitere Informationen über die Präprozessordirektiven finden Sie unter #define-Direktive (C/C++) und #undef-Direktive (C/C++).

Die einzigen außergewöhnlichen Syntaxelemente sind die @<, @=, und @> Ersetzbare Zeichenfolgen dargestellt.Dies sind die Hinweisdateien spezifische Ersetzungszeichenfolgen, die nur mit verwendet werden Karte Makros.Eine Karte ist eine Reihe von Makros, die Daten, Funktionen oder Ereignisse mit anderen Daten, Funktionen oder Ereignishandlern zusammenhängen.Zum Beispiel MFC verwendet Zuordnungen zum Erstellen Meldungszuordnungen, und ATL verwendet Zuordnungen zum Erstellen Objekt-Karten.Die Hinweisdateien spezifische Ersetzungszeichenfolgen geben Sie die Elemente Start-, zwischen- und Endelemente einer Zuordnung an.Nur der Name eines Zuordnungsmakros dar.Daher Blendet jede Ersetzungszeichenfolge die Implementierung des Makros absichtlich aus.

Hinweise verwenden die folgende Syntax.

Syntax	Bedeutung
#defineHinweis-nameErsetzungszeichenfolge #defineHinweis-name(Parameter, ...)Ersetzungszeichenfolge	Eine Präprozessordirektive, die einen neuen Hinweis oder definiert einen vorhandenen Hinweis.Nach der Direktive ersetzt der Präprozessor jedes Vorkommen von Hinweis-name im Quellcode mit Ersetzungszeichenfolge. Das zweite Syntaxformat definiert einen Hinweis.Wenn Sie ein Hinweis im Quellcode vorkommt, ersetzt die Präprozessor erste jedes Vorkommen von Parameter in Ersetzungszeichenfolge durch das entsprechende Argument im Quellcode, und klicken Sie dann ersetzt Hinweis-name mit Ersetzungszeichenfolge.
@<	Eine Hinweisdatei spezifische Ersetzungszeichenfolge den Beginn einer Gruppe von Zuordnungselementen angibt.
@=	Eine Hinweisdatei spezifische Ersetzungszeichenfolge ein intermediate Map-Elements angibt.Eine Zuordnung kann mehrere Zuordnungselemente verfügen.
@>	Eine Hinweisdatei spezifische Ersetzungszeichenfolge das Ende einer Gruppe von Zuordnungselementen angibt.
#undefHinweis-name	Der Präprozessor-Direktive, die einen vorhandenen Hinweis löscht.Der Name des Hinweises erfolgt über die Hinweis-name Bezeichner.
//Kommentar	Ein einzeiliger Kommentar.
/*Kommentar*/	Ein mehrzeiliger Kommentar.

Welche Makros erfordern einen Hinweis?

Bestimmte Typen von Makros können das Analysesystem beeinträchtigen.Dieser Abschnitt beschreibt die Typen von Makros, die ein Problem verursachen kann und den Typ der Hinweis, dass Sie erstellen können, um dieses Problem zu lösen.

Störende Makros

Einige Makros bewirken, dass das Analysesystem Quellcode falsch interpretiert, aber ohne Beeinträchtigung des Browsers ignoriert werden können.Z. B. die Source Code Annotation Language (SAL) Makros aufgelöst in C++-Attribute, mit deren Hilfe Sie Programmierfehler finden.Wenn Sie Code durchsuchen SAL-Anmerkungen ignorieren möchten, empfiehlt es sich um eine Hinweisdatei erstellen, die die Anmerkungen ausblendet.

Der Parameter Geben Sie in den folgenden Quellcode für die FormatWindowClassName() Funktion ist PXSTR, und der Parametername ist szBuffer.Allerdings das Analysesystem verwechselt die _Pre_notnull_ und _Post_z_ SAL-Anmerkungen für den Parametertyp oder den Namen des Parameters.

Quellcode:

static void FormatWindowClassName(_Pre_notnull_ _Post_z_ PXSTR-SzBuffer)

Strategie: NULL-definition

Die Strategie in dieser Situation besteht darin, die SAL-Anmerkungen zu behandeln, als ob sie nicht vorhanden waren.Geben Sie hierzu einen Hinweis, dessen Ersetzungszeichenfolge null ist.Infolgedessen ignoriert das Analysesystem die Anmerkungen und die Klassenansicht Browser wird nicht angezeigt.(Visual C++ umfasst eine integrierte Hinweisdatei, die SAL-Anmerkungen ausblendet.)

Hinweisdatei:

#define _Pre_notnull_

Verborgene C/C++-Sprachelemente

Ein typischer Grund dafür, dass das Analysesystem Quellcode falsch interpretiert wird, wenn ein Makro blendet ein C/C++-aus Markierungszeichen oder Schlüsselwort Token.Das heißt, enthält möglicherweise ein Makro nur einen Teil eines Markierungszeichenpaars enthält, wie z. B. <>, [], {}, und ().

Im folgenden Quellcode der START_NAMESPACE Makro blendet eine linke geschweifte Klammer){).

Quellcode:

#define START_NAMESPACE Namespace MyProject {

Strategie: Direkte Kopie

Wenn die Semantik eines Makros für die Browsererfahrung entscheidend sind, erstellen Sie einen Hinweis, der mit dem Makro identisch ist.Das Analysesystem löst das Makro in der Definition in der Hinweisdatei.

Beachten Sie, dass wenn das Makro in der Quelldatei andere Makros enthält, werden diese Makros interpretiert werden nur, wenn sie bereits in der Gruppe der effektiven Hinweisen befinden.

Hinweisdatei:

#define START_NAMESPACE Namespace MyProject {

Karten

Eine Zuordnung besteht aus Makros, die ein Startelement, EndElement und keine oder mehrere Zwischenelemente festlegen.Das Analysesystem Karten falsch interpretiert wird, da jedes C/C++-Sprachelemente ausblendet und die Syntax einer vollständigen C/C++-Anweisung auf viele separate Makros verteilt wird.

Der folgende Quellcode definiert die BEGIN_CATEGORY_MAP, IMPLEMENTED_CATEGORY, und END_CATEGORY_MAP Makros.

Quellcode:

#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 ); }

Strategie: Identifizieren Sie Zuordnungselemente

Geben Sie Hinweise für den Anfang, Mitte (falls vorhanden) und Ende einer Zuordnung.Verwenden Sie die Ersatzzeichenfolgen spezielle Karte, @<, @=, und @>.Weitere Informationen finden Sie unter der Syntax Abschnitt in diesem Thema.

Hinweisdatei:

// 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() @>

Zusammengesetzte Makros

Zusammengesetzte Makros enthalten ein oder mehrere Arten von Makros, die das Analysesystem durcheinanderbringen.

Der folgende Quellcode enthält die START_NAMESPACE Makro, das den Beginn eines Namespacebereichs angibt, und die BEGIN_CATEGORY_MAP Makro, das den Beginn einer Zuordnung angibt.

Quellcode:

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Strategie: Direkte Kopie

Hinweise zum Erstellen der START_NAMESPACE und BEGIN_CATEGORY_MAP Makros, und erstellen Sie einen Hinweis für die NSandMAP Makro, das das gleiche wie zuvor für den Quellcode dargestellt wird.Alternativ können ein zusammengesetztes Makro nur aus störenden Makros und Leerraum besteht, Sie einen Hinweis definieren, dessen Ersetzungszeichenfolge eine null-Definition ist.

In diesem Beispiel wird angenommen START_NAMESPACE hat bereits einen Hinweis, wie beschrieben in diesem Thema in der Verborgene C/C++-Sprachelemente Unterüberschrift.Und übernehmen BEGIN_CATEGORY_MAP verfügt über einen Hinweis, wie weiter oben unter Karten.

Hinweisdatei:

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Umständliche Makros

Einige Makros können vom Analysesystem interpretiert werden, der Quellcode ist jedoch schwierig zu lesen, da das Makro lang oder zu komplex ist.Aus Gründen der besseren Lesbarkeit können Sie einen Hinweis bereitstellen, der die Anzeige des Makros vereinfacht.

Quellcode:

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

Strategie: Vereinfachung

Erstellen Sie einen Hinweis, der eine einfachere Makrodefinition anzeigt.

Hinweisdatei:

#define STDMETHOD(methodName) void* methodName

Beispiel

Das folgende Beispiel veranschaulicht, wie Hinweise aus Hinweisdateien zusammengefasst werden.Stoppdateien werden in diesem Beispiel nicht verwendet.

Die folgende Abbildung stellt einige physische Verzeichnisse in einem Visual C++-Projekt.Hinweisdateien befinden sich der vcpackages, Debuggen, A1, und A2 Verzeichnisse.

Hinweisdateiverzeichnisse

Verzeichnisse und Hinweisdateiinhalte

Die folgende Tabelle listet die Verzeichnisse in diesem Projekt, die Hinweisdateien und den Inhalt dieser Hinweisdateien enthalten.Nur einige der vielen Hinweise in der vcpackages Verzeichnishinweisdatei werden aufgelistet.

Verzeichnis	Hinweisdateiinhalt
vcpackages	// vcpackages (partial list) #define _In_ #define _In_opt_ #define _In_z_ #define _In_opt_z_ #define _In_count_(size)
Debuggen	// Debug #undef _In_ #define OBRACE { #define CBRACE } #define RAISE_EXCEPTION(x) throw (x) #define START_NAMESPACE namespace MyProject { #define END_NAMESPACE }
A1	// A1 #define START_NAMESPACE namespace A1Namespace {
A2	// A2 #undef OBRACE #undef CBRACE

Effektive Hinweise

Die folgende Tabelle enthält die effektiven Hinweise für die Quelldateien in diesem Projekt.

Quelldatei	Effektive Hinweise
A1_A2_B.cpp	// 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 }

Die folgenden Hinweise gelten für die obige Tabelle.

• Die effektiven Hinweise stammen aus der vcpackages, Debuggen, A1, und A2 Verzeichnisse.

• Die #undef die Richtlinie in der Debuggen Hinweisdatei entfernt die #define _In_ Hinweis der vcpackages Verzeichnishinweisdatei.

• Die Hinweisdatei in der A1 Verzeichnis wird neu definiert START_NAMESPACE.

• Die #undef Hinweis der A2 Verzeichnis entfernt die Hinweise für OBRACE und CBRACE in der Debuggen Verzeichnishinweisdatei.

Siehe auch

Referenz

#define-Direktive (C/C++)

#undef-Direktive (C/C++)

Meldungszuordnungen (MFC)

Konzepte

Für Visual C++-Projekte erstellte Dateitypen

SAL-Anmerkungen

Weitere Ressourcen

Erstellen und Steuern von Umgebungsfenstern

Meldungszuordnungs-Makros (ATL)

Objektzuordnungs-Makros