Dica de arquivos

Um arquivo de dica ajuda o ambiente de desenvolvimento integrado do Visual Studio (IDE) a interpretar identificadores de Visual C++, como os nomes das funções e de macros.Quando você abre um projeto Visual C++, o sistema de análise do IDE analisa o código em cada arquivo de origem no projeto e coleta informações sobre cada identificador.Nos usos da IDE que informações oferecer suporte a recursos como o navegador de Modo de Exibição de Classe e o Barra de navegação.

O sistema de análise, que é introduzido em Visual C++ 2010, entende a sintaxe de C/C++ mas pode interpretar errado uma instrução que contém uma macro.A instrução pode ser má se a macro faz com que o código-fonte é sintaticamente incorreto como gravada.A instrução pode se tornar sintaticamente correta quando o código é compilado e o preprocesser substitui identificador macro com sua definição. O sistema de análise sem ter que criar o projeto que usa arquivos de dica para interpretar macros. Portanto, um recurso procurando como Modo de Exibição de Classe fica imediatamente disponível.

Um arquivo de dica contém as dicasusuário personalizáveis, que têm a mesma sintaxe que definições de macro ++.Visual C++ inclui um arquivo interno de dica que é suficiente para a maioria dos projetos, mas você pode criar seus próprios arquivos de dica para melhorar a maneira que o Visual Studio trata identificadores.

Cenário

Suponha que o código a seguir é um arquivo de origem que você examine com o navegador de Modo de Exibição de Classe .A macro de STDMETHOD declara um método chamado myMethod que utiliza um parâmetro e retorna um ponteiro para HRESULT.

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

As seguintes definições macro estão em um arquivo de cabeçalho separado.

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

O sistema de análise não pode interpretar o código-fonte porque uma função chamada STDMETHOD parece ser declarada, e essa declaração é sintaticamente incorreta porque tem duas listas de parâmetros.O sistema de análise não abre o arquivo de cabeçalho para descobrir as definições para STDMETHOD, STDMETHODCALLTYPE, e macros de HRESULT .Porque o sistema de análise não pode interpretar a macro de STDMETHOD , ignora a instrução inteira e depois continuará a análise.

O sistema de análise não usa arquivos de cabeçalho porque seu projeto pode depender de um ou mais arquivos de cabeçalho importantes.Se qualquer arquivo de cabeçalho muda, o sistema de análise pode ter que reexaminar todos os arquivos de cabeçalho em seu projeto, que diminui o desempenho do IDE.Em vez disso, o sistema de análise usa as dicas que especificam como manipular STDMETHOD, STDMETHODCALLTYPE, e macros de HRESULT .

Como você souber que você precisa de uma dica?E se você precisar de um tipo que dica, você deve criar?Um sinal que uma dica é necessário é se a exibição de um identificador em Modo de Exibição de Classe é inconsistente com a exibição em Editor.Por exemplo, Modo de Exibição de Classe não pode exibir um membro da classe que você sabe existente, ou o nome do membro está incorreto.Para obter mais informações sobre tipos de dicas que determinam problemas comuns, consulte macros que exigem uma dica?a seção consulte posteriormente neste tópico.

Arquitetura

Os arquivos de dica pertencem aos diretórios físicos, não os diretórios lógicos descritos em Gerenciador de Soluções.Você não tem que adicionar um arquivo de dica ao seu projeto para o arquivo de dica tenha um efeito.A dica dos usos do sistema de análise arquivos somente quando analisa arquivos de origem.

Cada arquivo de dica é chamado cpp.hint.Portanto, vários diretórios podem conter um arquivo de dica mas somente um arquivo de dica pode ocorrer em um diretório específico.

Seu projeto pode ser afetado por zero ou mais arquivos por de dica.Se não houver nenhum arquivo de dica, o sistema de análise usa técnicas de recuperação de erro ignorar o código-fonte indecifrável.Caso contrário, o sistema de análise usa a seguir estratégia para localizar e coletar dicas.

Ordem de Pesquisa

O sistema de análise diretórios procura por arquivos de dica na seguinte ordem.

• O diretório que contém o pacote de instalação para Visual C++ (vcpackages).Este diretório contém um arquivo interno de dica que descreve símbolos em arquivos do sistema frequentemente usados, como windows.h.Portanto, o projeto automaticamente herda a maioria dos dicas de que precisa.

• O caminho do diretório raiz de um arquivo de origem para o diretório que contém o próprio arquivo de origem.Em um projeto típico do Visual C++, o diretório raiz contém o arquivo de solução ou de projeto.

  A exceção a essa regra é se um arquivo de interrupção é o caminho para o arquivo de origem.Um arquivo de parada fornece controle adicional sobre a ordem de pesquisa e é qualquer arquivo que é chamado cpp.stop.Em vez de partir do diretório raiz, o sistema de análise procura do diretório que contém o arquivo de parada a pasta que contém o arquivo de origem.Em um projeto típico, você não precisa de um arquivo de interrupção.

Coleta de dica

Um arquivo de dica contém zero ou mais dicas.Uma dica é definido ou excluído assim como a macro de energia AC /C ++.Ou seja, a diretiva pré-processamento de #define cria ou redefinir uma dica, e a política de #undef exclui uma dica.

O sistema de análise abre cada arquivo de dica em descrito anteriormente ordem de pesquisa, accumulate dicas de cada arquivo em um conjunto de dicas vigorem seguida, usa as dicas eficazes para interpretar os identificadores em seu código.

O sistema de análise usa as seguintes regras para acumular dicas.

• Se o novo dica especifica um nome que já não está definido, o novo dica adiciona o nome para dicas vigor.

• Se o novo dica especifica um nome que já está definido, o novo dica redefine o dica existente.

• Se o novo dica é uma diretiva de #undef que especifica uma dica eficiente existente, o novo dica exclui a dica existente.

A primeira regra significa que as dicas efetivas são herdadas dos arquivos anteriormente abertos de dica.As duas regras mais recentes significa que as dicas que ocorrem posteriormente na ordem de pesquisa podem substituir as dicas que ocorreram anteriormente.Por exemplo, você pode substituir todos os dicas anteriores se você criar um arquivo de dica no diretório que contém um arquivo de origem.

Para obter uma descrição de como dicas são coletados, consulte a seção de Example posteriormente neste tópico.

Sintaxe

Dicas são criados e excluídos com a mesma sintaxe que as diretivas pré-processamento que cria e exclusões macros.Na verdade, o sistema de análise usa o pré-processador de C/C++ para avaliar as dicas.Para obter mais informações sobre as diretivas pré-processamento, consulte # Definir diretiva (C/C++) e #undef diretiva (C/C++).

Os únicos elementos incomuns de sintaxe são @<, @=, e cadeias de caracteres de substituição de @> .Essas são as cadeias de caracteres específicas de substituição de dica- Arquivo que são usadas somente com macros de mapa .Um mapa é um conjunto de macros que relacionam dados, funções, ou eventos para outros dados, funções, ou manipuladores de eventos.Por exemplo, MFC usa mapeamentos para criar mapas de mensagem, e mapas dos usos de ATL para criar mapas de objeto.As cadeias de caracteres específicas de substituição de dica- Arquivo indicam iniciar, intermediária, e finalizar os elementos de um mapa.Somente o nome de uma macro de mapa é significativo.Portanto, cada cadeia de caracteres de substituição oculta intencionalmente a implementação de macro.

Dicas use a seguinte sintaxe.

Sintaxe	Significado
#definedica-nomesubstituição-cadeia de caracteres #definedica-nome(parâmetro,…)substituição-cadeia de caracteres	Uma política de preprocesser que define um novo dica ou redefina uma dica existente.Após a diretiva, o pré-processador substitui cada ocorrência de dica-nome no código-fonte com substituição-cadeia de caracteres. O segundo formulário de sintaxe define a função como a dica.Se a função como a dica ocorre no código-fonte, o primeiro pré-processador substitui cada ocorrência de parâmetro em substituição-cadeia de caracteres com o argumento correspondente no código-fonte e em seguida, substitui dica-nome com substituição-cadeia de caracteres.
@<	Dica- Arquivo substituição-cadeia de caracteres específica que indica o início de um conjunto de elementos de mapa.
@=	Dica- Arquivo substituição-cadeia de caracteres específica que indica um elemento intermediário de mapa.Um mapa pode ter vários elementos de mapa.
@>	Dica- Arquivo substituição-cadeia de caracteres específica que indica o fim de um conjunto de elementos de mapa.
#undefdica-nome	A diretiva pré-processamento que exclui uma dica existente.O nome de dica é fornecido pelo identificador de dica-nome .
//comentário	Uma única linha comentário.
/*comentário*/	Um comentário de várias linhas.

Macros que exigem uma dica?

Determinados tipos de macros pode interferir com o sistema de análise.Esta seção descreve os tipos de macros que podem causar um problema, e o tipo de dica que você pode criar para resolver este problema.

Macros disruptivos

Alguns macros fazem com que o sistema de análise interprete errado o código-fonte, mas podem ser ignorados sem danificar sua experiência navegando.Por exemplo, macros de linguagem de anotação de código-fonte (SAL) determinam aos atributos de C++ que ajudam você a localizar erros de programação.Se você desejar ignorar anotações de SAL como você procurar o código, você pode querer criar um arquivo de dica que ocultasse a anotação.

No seguinte código fonte, o tipo de parâmetro para a função de FormatWindowClassName() é PXSTR, e o nome de parâmetro é szBuffer.No entanto, o sistema de análise confunde anotações de SAL de _Pre_notnull_ e de _Post_z_ pelo tipo de parâmetro ou o nome do parâmetro.

O código-fonte:

static void FormatWindowClassName(_Pre_notnull_ _Post_z_ PXSTR szBuffer)

Definição de zero deEstratégia:

A estratégia nessa situação é manipular as anotações de SAL como se não existia.Para fazer isso, especifique uma dica cuja cadeia de caracteres de substituição é nulo.Portanto, o sistema de análise ignora as anotações, e o navegador de Modo de Exibição de Classe não exibe as.(O Visual C++ inclui um arquivo interno de dica que oculta a anotação de SAL.)

Arquivo de dica:

#define _Pre_notnull_

Elementos de linguagem C/C++ de escondidos

Uma razão típica que o sistema de análise interpreta errado o código-fonte é se uma macro oculta a energia AC /C ++ punctuator ou símbolo de palavra-chave .Ou seja, uma macro pode conter a metade de um par de punctuators, como <>, [], {}, e ().

No seguinte código fonte, a macro de START_NAMESPACE oculta uma chave esquerda desirmanada ({).

O código-fonte:

#define START_NAMESPACE namespace MyProject {

Impressão direta deEstratégia:

Se a semântica de uma macro é fundamental para a experiência procurando, crie uma dica que é idêntico ao macro.O sistema de análise resolve a macro à definição no arquivo de dica.

Observe que se a macro no arquivo de origem contiver outros macros, esses macros são interpretados somente se já estão no conjunto de dicas vigor.

Dica Arquivo:

#define START_NAMESPACE namespace MyProject {

Mapas

Um mapa consiste em macros que designarem um elemento inicial, finalizando o elemento, e zero ou mais elementos intermediários.O sistema de análise interpreta errado mapas porque cada macro de mapa oculta os elementos de linguagem de ++, e a sintaxe de uma declaração completa de C/C++ é atribuída entre vários macros separados.

O seguinte código define BEGIN_CATEGORY_MAP, IMPLEMENTED_CATEGORY, e macros de END_CATEGORY_MAP .

O código-fonte:

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

Estratégia: identifica os elementos de mapa

Especificar dicas para o início, o meio (se houver), e elementos de extremidade de um mapa.Use as cadeias de caracteres especiais, @<, @=, e @>substituição de mapa.Para obter mais informações, consulte a seção de Syntax neste tópico.

Dica Arquivo:

// 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 compostos

Macros compostos contêm um ou mais dos tipos de macro que confundem o sistema de análise.

O seguinte código contém a macro de START_NAMESPACE , especificando o início de um escopo de namespace, e a macro de BEGIN_CATEGORY_MAP , especificando o início de um mapa.

O código-fonte:

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Impressão direta deEstratégia:

Crie dicas para macros de START_NAMESPACE e de BEGIN_CATEGORY_MAP , e então crie uma dica para a macro de NSandMAP que é o mesmo como mostrado anteriormente para o código-fonte.Como alternativa, se uma macro composto consiste somente de macros e o espaço em branco disruptivos, você pode definir uma dica cuja cadeia de caracteres de substituição é uma definição nula.

Nesse exemplo, suponha START_NAMESPACE já tiver uma dica conforme descrito nesse tópico em subtítulo de Concealed C/C++ Language Elements .E suponha BEGIN_CATEGORY_MAP tem uma dica como descrito anteriormente em Maps.

Dica Arquivo:

#define NSandMAP START_NAMESPACE BEGIN_CATEGORY_MAP

Macros incómodos

Alguns macros podem ser interpretados pelo sistema de análise, mas o código-fonte é difícil de ler porque a macro é longo ou complexas.Para facilitar a leitura, você pode fornecer uma dica que simplifica a exibição de macro.

O código-fonte:

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

Simplificação deEstratégia:

Crie uma dica que exibe uma definição macro mais simples.

Dica Arquivo:

#define STDMETHOD(methodName) void* methodName

Exemplo

O exemplo a seguir ilustra como dicas são acumulados dos arquivos de dica.Parar arquivos não são usados neste exemplo.

A ilustração a seguir descreve alguns dos diretórios físicos em um projeto Visual C++.Os arquivos de dica estão em vcpackages, em Debug, em A1, e diretórios de A2 .

Diretórios de Arquivo de dica

Diretórios e conteúdo de Arquivo de dica

A tabela a seguir lista os diretórios no projeto que contém arquivos de dica, e o conteúdo desses dica arquivo.Somente alguns de muitos dicas no arquivo de dica de diretório de vcpackages são listados.

Diretório	Conteúdo do Arquivo de dica
vcpackages	// vcpackages (partial list) #define _In_ #define _In_opt_ #define _In_z_ #define _In_opt_z_ #define _In_count_(size)
Depuração	// 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

Dicas efetivas

A tabela a seguir lista as dicas eficazes para os arquivos de origem no projeto.

Source File	Dicas efetivas
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 }

As seguintes notas se aplicam a tabela acima.

• Dicas são efetivas de vcpackages, de Debug, de A1, e pastas de A2 .

• A política de #undef no arquivo de dica de Debug removeu a dica de #define _In_ no arquivo de dica de diretório de vcpackages .

• O arquivo de dica no diretório de A1 redefine START_NAMESPACE.

• A dica de #undef no diretório de A2 removeu dicas para OBRACE e CBRACE no arquivo de dica de diretório de Debug .

Consulte também

Referência

# Definir diretiva (C/C++)

#undef diretiva (C/C++)

Mapas de mensagem (MFC)

Conceitos

Tipos de arquivo, criados para projetos do Visual C++

SAL anotações

Outros recursos

Criar e controlar o ambiente Windows

Macros do mapa de mensagens (ATL)

Macros do mapa de objeto