File dei suggerimenti

A file dei suggerimenti Consente di Visual Studio l'ambiente di sviluppo integrato (IDE) di interpretare gli identificatori di Visual C++, ad esempio i nomi di funzioni e macro.Quando si apre un progetto Visual C++, l'IDE sistema di analisi Analizza il codice in ogni file di origine nel progetto e raccoglie le informazioni su ogni identificatore.L'IDE utilizza tali informazioni per supportare le funzionalità di Visualizzazione classi browser e il Barra di spostamento.

Il sistema di analisi è stata introdotta in Visual C++ 2010, riconosce la sintassi C/C++ ma può interpretare erroneamente un'istruzione che contiene una macro.L'istruzione può essere interpretato erroneamente se la macro fa sì che il codice sorgente sia sintatticamente errato così come viene scritto.L'istruzione può diventare sintatticamente corretta quando viene compilato il codice sorgente e il preprocessore sostituisce il identificatore di macro con la relativa definizione. Il sistema di analisi funziona senza la necessità di compilare il progetto perché utilizza i file dei suggerimenti per interpretare le macro. Pertanto, una funzionalità di esplorazione come Visualizzazione classi è immediatamente disponibile.

Un file dei suggerimenti contiene personalizzabili dall'utente suggerimenti, che hanno la stessa sintassi di C/C++ definizioni di macro.Visual C++ include un file dei suggerimenti incorporato che è sufficiente per la maggior parte dei progetti, ma è possibile creare i proprio file dei suggerimenti per migliorare il modo in cui che Visual Studio gestisce gli identificatori.

Scenario

Si supponga che il codice seguente è contenuto in un file di origine che si esamina con il Visualizzazione classi browser.Il STDMETHOD macro dichiara un metodo denominato myMethod che accetta un parametro e restituisce un puntatore a un HRESULT.

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

Le definizioni di macro riportato di seguito sono in un file di intestazione.

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

Il sistema di analisi non è in grado di interpretare il codice sorgente poiché una funzione denominata STDMETHOD sembra essere dichiarata e tale dichiarazione è sintatticamente errata perché dispone di due elenchi di parametri.Il sistema di analisi non apre il file di intestazione per individuare le definizioni per il STDMETHOD, STDMETHODCALLTYPE, e HRESULT macro.Poiché il sistema di analisi non è in grado di interpretare il STDMETHOD macro, ignora l'intera istruzione e quindi continua ad analizzare.

Il sistema di analisi non utilizza i file di intestazione perché il progetto potrebbe dipendere da uno o più file di intestazione importanti.Se viene modificato alcun file di intestazione, il sistema di analisi potrebbe essere necessario riesaminare tutti i file di intestazione nel progetto, rallentando le prestazioni dell'IDE.Il sistema di analisi utilizza invece dei suggerimenti che consentono di specificano come gestire il STDMETHOD, STDMETHODCALLTYPE, e HRESULT macro.

Come si fa a sapere che è necessario un suggerimento?E se è necessario un suggerimento, il tipo deve essere?Un segno che è necessario un suggerimento è se la visualizzazione di un identificatore in Visualizzazione classi non è coerente con la visualizzazione nel Editor.Ad esempio, Visualizzazione classi potrebbe non visualizzare esiste un membro della classe che si è certi o il nome del membro non è corretto.Per ulteriori informazioni sui tipi di suggerimenti che possono risolvere problemi comuni, vedere la cosa Macros Require A Hint? sezione più avanti in questo argomento.

Architettura

I file dei suggerimenti riguardano le directory fisiche, non le directory logiche illustrato nella Esplora.Non è necessario aggiungere un file dei suggerimenti per il progetto per il file dei suggerimenti abbia effetto.Il sistema di analisi utilizza i file dei suggerimenti solo quando analizza il file di origine.

Ogni file dei suggerimenti è denominato cpp.Pertanto, molte directory possono contenere un file dei suggerimenti ma solo un file dei suggerimenti può verificarsi in una directory specifica.

Il progetto può dipendere da zero o più file dei suggerimenti.Se non sono presenti file dei suggerimenti, il sistema di analisi utilizza tecniche di ripristino di errore per ignorare il codice sorgente indecifrabile.In caso contrario, il sistema di analisi utilizza la strategia seguente per trovare e raccogliere suggerimenti.

Ordine di ricerca

Il sistema di analisi viene eseguita nelle directory per i file dei suggerimenti nell'ordine seguente.

• La directory che contiene il pacchetto di installazione di Visual C++ (vcpackages).Questa directory contiene un file dei suggerimenti incorporato che descrive i simboli nei file di sistema utilizzate di frequente, ad esempio h.Di conseguenza, il progetto eredita automaticamente la maggior parte dei suggerimenti di cui necessita.

• Il percorso dalla directory radice di un file di origine nella directory contenente il file di origine.In un progetto di Visual C++ tipico, la directory principale contiene il file di soluzione o un progetto.

  L'eccezione a questa regola si verifica se un file di interruzione è il percorso del file di origine.Un file di interruzione fornisce maggiore controllo sull'ordine di ricerca ed è un file denominato cpp.Anziché iniziare dalla directory principale, il sistema di analisi Cerca dalla directory contenente il file di interruzione alla directory contenente il file di origine.In un progetto tipico, non è necessario un file di interruzione.

Raccolta di suggerimenti

Un file dei suggerimenti contiene zero o più suggerimenti.Un suggerimento è definito o eliminato come una macro di C/C++.Vale a dire il #define direttiva del preprocessore crea o ridefinisce un suggerimento e la #undef direttiva elimina un suggerimento.

Il sistema di analisi apre ciascun file dei suggerimenti nell'ordine di ricerca descritto in precedenza, accumula i parametri di ciascun file in un insieme di suggerimenti validi, quindi utilizza i suggerimenti validi per interpretare gli identificatori nel codice.

Il sistema di analisi utilizza le regole seguenti per accumulare suggerimenti.

• Se il nuovo suggerimento è specificato un nome non è già stato definito, il nuovo suggerimento aggiunge il nome ai suggerimenti validi.

• Se il nuovo suggerimento è specificato un nome già definito, il nuovo suggerimento ridefinisce il suggerimento esistente.

• Se il nuovo suggerimento è un #undef la direttiva che specifica un suggerimento valido esistente, il nuovo suggerimento elimina quello esistente.

La prima regola indica che i suggerimenti validi vengono ereditate dai file dei suggerimenti precedentemente aperti.Le ultime due regole indicano suggerimenti che possono verificano in seguito nell'ordine di ricerca possono eseguire l'override di suggerimenti che si sono verificati precedentemente.Ad esempio, è possibile eseguire l'override dei suggerimenti precedenti se si crea un file dei suggerimenti nella directory che contiene un file di origine.

Per una descrizione di come vengono raccolti i suggerimenti, vedere la Esempio sezione più avanti in questo argomento.

Sintassi

Parametri vengono creati ed eliminati con la stessa sintassi di direttive per il preprocessore che consente di creare ed eliminare macro.Infatti, il sistema di analisi utilizza il preprocessore C/C++ per valutare i suggerimenti.Per ulteriori informazioni sulle direttive del preprocessore, vedere Direttiva #define (C/C++) e Direttiva #undef (C/C++).

Gli elementi di sintassi solo anomali sono il @<, @=, e @> stringhe di sostituzione.Si tratta di stringhe di sostituzione specifiche del file dei suggerimenti che vengono utilizzati solo con mappa macro.Una mappa è un insieme di macro che correlano dati, funzioni o eventi ad altri dati, funzioni o gestori eventi.Ad esempio, MFC vengono utilizzate per creare mappe messaggi, e ATL vengono utilizzate per creare oggetto mappe.Le stringhe di sostituzione specifiche del file dei suggerimenti indicano gli elementi iniziale, intermedi e finali di una mappa.Solo il nome di una macro di mapping è significativo.Pertanto, ogni stringa di sostituzione nasconde intenzionalmente l'implementazione della macro.

Suggerimenti per utilizzano la sintassi seguente.

Sintassi	Significato
#definenome-suggerimentostringa di sostituzione #definenome-suggerimento(parametro, ...)stringa di sostituzione	Una direttiva del preprocessore che definisce un nuovo suggerimento o ridefinisce un suggerimento esistente.Dopo la direttiva del preprocessore sostituisce ogni occorrenza di nome-suggerimento nel codice sorgente con stringa di sostituzione. La seconda forma di sintassi definisce un suggerimento simile a funzione.In caso di un suggerimento simile a funzione nel codice sorgente, il primo per il preprocessore sostituisce ogni occorrenza di parametro in stringa di sostituzione con il corrispondente argomento nel codice sorgente e quindi sostituisce nome-suggerimento con stringa di sostituzione.
@<	Specifica una file dei suggerimenti stringa di sostituzione che indica l'inizio di un insieme di elementi di mappa.
@=	Specifica una file dei suggerimenti stringa di sostituzione che indica un elemento di mappa intermedio.Una mappa può contenere più elementi.
@>	Specifica una file dei suggerimenti stringa di sostituzione che indica la fine di un insieme di elementi di mappa.
#undefnome-suggerimento	La direttiva del preprocessore che consente di eliminare un suggerimento esistente.Viene fornito il nome del suggerimento per la nome-suggerimento identificatore.
//commento	Un commento a riga singola.
/*commento*/	Un commento su più righe.

Ciò che le macro è necessario un suggerimento?

Determinati tipi di macro possono interferire con il sistema di analisi.In questa sezione vengono descritti i tipi di macro che possono causare un problema e il tipo di suggerimento che è possibile creare per risolvere il problema.

Macro dannose

Alcune macro determina il sistema di analisi errata interpretazione di codice sorgente, ma può essere ignorato senza comprometterne l'esplorazione.Ad esempio, i (Source Code Annotation LanguageSAL) macro si risolvono in attributi C++ che consentono di trovare i bug di programmazione.Se si desidera ignorare le annotazioni SAL durante l'esplorazione del codice, è possibile creare un file dei suggerimenti che nasconda le annotazioni.

Nel codice sorgente riportato di seguito, il tipo di parametro per il FormatWindowClassName() è in funzione PXSTR, e il nome del parametro è szBuffer.Tuttavia, il sistema di analisi confonde le _Pre_notnull_ e _Post_z_ Annotazioni SAL per il tipo di parametro o il nome del parametro.

Codice sorgente:

static void FormatWindowClassName( Pre_notnull _ Post_z _ SzBuffer PXSTR)

Strategia: Definizione di null

La strategia in questa situazione consiste nel trattare le annotazioni SAL come se non esistessero.A tale scopo, specificare un suggerimento la cui stringa di sostituzione sia null.Di conseguenza, il sistema di analisi ignora le annotazioni e Visualizzazione classi browser non vengono visualizzate.(Visual C++ include un file dei suggerimenti incorporato che nasconde le annotazioni SAL).

File dei suggerimenti:

#define Pre_notnull _

Elementi del linguaggio C/C++ nascosti

Un motivo tipico che il sistema di analisi interpreta in modo errato codice sorgente è quando una macro nasconde un C/C++ segno di punteggiatura o parola chiave token.Che una macro potrebbe infatti contenere metà di una coppia di segni di punteggiatura, ad esempio <>, [], {}, e ().

Nel codice sorgente riportato di seguito, il START_NAMESPACE macro nasconde un (parentesi graffa sinistra spaiata{).

Codice sorgente:

#define START_NAMESPACE spazio dei nomi MyProject {

Strategia: Copia diretta

Se la semantica di una macro è fondamentale per l'esplorazione, creare un suggerimento che è identico alla macro.Il sistema di analisi consente di risolvere la macro per la definizione nel file dei suggerimenti.

Si noti che se la macro nel file di origine contiene altre macro, le macro verranno interpretate solo se sono già inclusi nel set di suggerimenti validi.

File dei suggerimenti:

#define START_NAMESPACE spazio dei nomi MyProject {

Mappe

Una mappa è costituita da macro che designano un elemento iniziale, l'elemento finale e zero o più elementi intermedi.Il sistema di analisi interpreta in modo errato le mappe perché ogni macro di mapping nasconde elementi del linguaggio C/C++ e la sintassi di un'istruzione C/C++ completa è distribuita tra più macro distinte.

Il codice sorgente riportato di seguito definisce il BEGIN_CATEGORY_MAP, IMPLEMENTED_CATEGORY, e END_CATEGORY_MAP macro.

Codice sorgente:

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

Strategia: Identificare gli elementi di mappa

Suggerimenti per l'avvio, il centro (se presente) e la fine di specificare gli elementi di una mappa.Utilizzare le stringhe di sostituzione della carta speciale, @<, @=, e @>.Per ulteriori informazioni, vedere la Sintassi sezione in questo argomento.

File dei suggerimenti:

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

Macro composite

Le macro composite contengono uno o più tipi di macro che confondere il sistema di analisi.

Il codice sorgente riportato di seguito contiene il START_NAMESPACE macro, che specifica l'inizio di un ambito dello spazio dei nomi, e BEGIN_CATEGORY_MAP macro, che specifica l'inizio di una mappa.

Codice sorgente:

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Strategia: Copia diretta

Creare dei suggerimenti per la START_NAMESPACE e BEGIN_CATEGORY_MAP macro, quindi creare un suggerimento per la NSandMAP macro è analoga a quella illustrata in precedenza per il codice sorgente.In alternativa, se una macro composita è costituita solo da macro dannose e spazio vuoto, è possibile definire un suggerimento la cui stringa di sostituzione sia una definizione null.

In questo esempio, si supponga che START_NAMESPACE esiste già un suggerimento come descritto in questo argomento nel Elementi del linguaggio C/C++ nascosti sottotitolo.E si presuppone BEGIN_CATEGORY_MAP è un suggerimento come descritto in precedenza in Mappe.

File dei suggerimenti:

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Macro di disturbo

Alcune macro possono essere interpretate dal sistema di analisi, ma il codice sorgente è di difficile lettura perché la macro è lunga o complessa.Per una maggiore leggibilità, è possibile fornire un suggerimento che semplifichi la visualizzazione della macro.

Codice sorgente:

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

Strategia: Semplificazione

Creare un suggerimento che visualizzi una definizione di macro più semplice.

File dei suggerimenti:

#define STDMETHOD(methodName) void * NomeMetodo

Esempio

Nell'esempio riportato di seguito viene illustrato come i suggerimenti vengono accumulati dai file dei suggerimenti.In questo esempio non vengono utilizzati i file di interruzione.

Nella figura seguente vengono illustrate alcune delle directory fisica in un progetto di Visual C++.File dei suggerimenti che compongono il vcpackages, Eseguire il debug, A1, e A2 Directory.

Directory dei File dei suggerimenti

Suggerimento contenuto del File e directory

Nella tabella seguente elenca le directory del progetto che contengono i file dei suggerimenti e il contenuto di questi file dei suggerimenti.Solo alcuni dei numerosi suggerimenti nel vcpackages file dei suggerimenti directory sono elencati.

Directory	Sommario dei File dei suggerimenti
vcpackages	// vcpackages (partial list) #define _In_ #define _In_opt_ #define _In_z_ #define _In_opt_z_ #define _In_count_(size)
Eseguire il debug	// 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

Suggerimenti validi

Nella tabella seguente sono elencati i suggerimenti validi per i file di origine di questo progetto.

File di origine	Suggerimenti validi
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 }

Le note seguenti si applicano alla tabella precedente.

• Suggerimenti validi provengono dal vcpackages, Eseguire il debug, A1, e A2 Directory.

• Il #undef direttiva del Eseguire il debug file dei suggerimenti rimosso il #define _In_ Suggerimento nel vcpackages file dei suggerimenti directory.

• File dei suggerimenti nel A1 Directory ridefinisce START_NAMESPACE.

• Il #undef Suggerimento nel A2 suggerimenti per rimuovere directory OBRACE e CBRACE nel Eseguire il debug file dei suggerimenti directory.

Vedere anche

Riferimenti

Direttiva #define (C/C++)

Direttiva #undef (C/C++)

Mappe messaggi (MFC)

Concetti

Tipi di file creati per i progetti di Visual C++

Annotazioni SAL

Altre risorse

Creazione e controllo delle finestre di ambiente

Macro della mappa messaggi (ATL)

Macro della mappa oggetto