Auxiliares do SDK para depuração
Essas funções e declarações são funções auxiliares globais para implementar mecanismos de depuração, avaliadores de expressão e provedores de símbolos em C++.
Observação
Não há versões gerenciadas dessas funções e declarações no momento.
Para que mecanismos de depuração, avaliadores de expressão e provedores de símbolos sejam usados pelo Visual Studio, eles devem ser registrados. Isso é feito definindo subchaves e entradas do Registro, também conhecido como "configuração de métricas". As funções globais a seguir foram projetadas para facilitar o processo de atualização dessas métricas. Consulte a seção Locais do Registro para descobrir o layout de cada subchave do Registro atualizada por essas funções.
Funções métricas gerais
Essas são funções gerais usadas por mecanismos de depuração. Funções especializadas para avaliadores de expressão e provedores de símbolos são detalhadas posteriormente.
GetMetric Método
Recupera um valor de métrica do Registro.
HRESULT GetMetric(
LPCWSTR pszMachine,
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
DWORD * pdwValue,
LPCWSTR pszAltRoot
);
| Parâmetro | Descrição |
|---|---|
| pszMáquina | [em] Nome de uma máquina possivelmente remota cujo registro será escrito (NULL significa máquina local). |
| pszType | [em] Um dos tipos métricos. |
| guidSeção | [em] GUID de um mecanismo específico, avaliador, exceção, etc. Isso especifica uma subseção em um tipo de métrica para um elemento específico. |
| pszMétrico | [em] A métrica a ser obtida. Isso corresponde a um nome de valor específico. |
| Valor pdw; | [em] O local de armazenamento do valor da métrica. Há vários tipos de GetMetric que podem retornar um DWORD (como neste exemplo), um BSTR, um GUID ou uma matriz de GUIDs. |
| pszAltRoot | [em] Uma raiz de registro alternativa a ser usada. Defina como NULL para usar o padrão. |
SetMetric Método
Define o valor de métrica especificado no Registro.
HRESULT SetMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
const DWORD dwValue,
bool fUserSpecific,
LPCWSTR pszAltRoot
);
| Parâmetro | Descrição |
|---|---|
| pszType | [em] Um dos tipos métricos. |
| guidSeção | [em] GUID de um mecanismo específico, avaliador, exceção, etc. Isso especifica uma subseção em um tipo de métrica para um elemento específico. |
| pszMétrico | [em] A métrica a ser obtida. Isso corresponde a um nome de valor específico. |
| dwValor | [em] O local de armazenamento do valor na métrica. Há vários tipos de SetMetric que podem armazenar um DWORD (neste exemplo), um BSTR, um GUID ou uma matriz de GUIDs. |
| fUserSpecific | [em] TRUE se a métrica for específica do usuário e se ela deve ser gravada no hive do usuário em vez da colmeia da máquina local. |
| pszAltRoot | [em] Uma raiz de registro alternativa a ser usada. Defina como NULL para usar o padrão. |
Método RemoveMetric
Remove a métrica especificada do registro.
HRESULT RemoveMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
LPCWSTR pszAltRoot
);
| Parâmetro | Descrição |
|---|---|
| pszType | [em] Um dos tipos métricos. |
| guidSeção | [em] GUID de um mecanismo específico, avaliador, exceção, etc. Isso especifica uma subseção em um tipo de métrica para um elemento específico. |
| pszMétrico | [em] A métrica a ser removida. Isso corresponde a um nome de valor específico. |
| pszAltRoot | [em] Uma raiz de registro alternativa a ser usada. Defina como NULL para usar o padrão. |
Método EnumMetricSections
Enumera as várias seções métricas no Registro.
HRESULT EnumMetricSections(
LPCWSTR pszMachine,
LPCWSTR pszType,
GUID * rgguidSections,
DWORD * pdwSize,
LPCWSTR pszAltRoot
);
| Parâmetro | Descrição |
|---|---|
| pszMáquina | [em] Nome de uma máquina possivelmente remota cujo registro será escrito (NULL significa máquina local). |
| pszType | [em] Um dos tipos métricos. |
| rgguidSeções | [dentro, fora] Matriz pré-alocada de GUIDs a serem preenchidos. |
| pdwTamanho | [em] O número máximo de GUIDs que podem ser armazenados na rgguidSections matriz. |
| pszAltRoot | [em] Uma raiz de registro alternativa a ser usada. Defina como NULL para usar o padrão. |
Funções do avaliador de expressão
| Função | Descrição |
|---|---|
| GetEEMetric | Recupera um valor de métrica do Registro. |
| SetEEMetric | Define o valor de métrica especificado no Registro. |
| RemoveEEMetric | Remove a métrica especificada do registro. |
| GetEEMetricFile | Obtém um nome de arquivo da métrica especificada e o carrega, retornando o conteúdo do arquivo como uma cadeia de caracteres. |
Funções de exceção
| Função | Descrição |
|---|---|
| GetExceptionMetric | Recupera um valor de métrica do Registro. |
| SetExceptionMetric | Define o valor de métrica especificado no Registro. |
| RemoveExceptionMetric | Remove a métrica especificada do registro. |
| RemoveAllExceptionMetrics | Remove todas as métricas de exceção do Registro. |
Funções do provedor de símbolos
| Função | Descrição |
|---|---|
| GetSPMetric | Recupera um valor de métrica do Registro. |
| SetSPMetric | Define o valor de métrica especificado no Registro. |
| RemoveSPMetric | Remove a métrica especificada do registro. |
Funções de enumeração
| Função | Descrição |
|---|---|
| EnumMetricSeções | Enumera todas as métricas para um tipo de métrica especificado. |
| EnumDebugEngine | Enumera os mecanismos de depuração registrados. |
| EnumEEs | Enumera os avaliadores de expressão registrados. |
| EnumExceptionMetrics | Enumera todas as métricas de exceção. |
Definições de métrica
Essas definições podem ser usadas para nomes de métricas predefinidos. Os nomes correspondem a várias chaves do Registro e nomes de valor e são todos definidos como cadeias de caracteres largas: por exemplo, extern LPCWSTR metrictypeEngine.
| Tipos de métricas predefinidos | Descrição: A chave base para.... |
|---|---|
| metrictypeEngine | Todas as métricas do mecanismo de depuração. |
| metrictypePortSupplier | Todas as métricas do fornecedor portuário. |
| metrictypeException | Todas as métricas de exceção. |
| metricttypeEEExtensão | Todas as extensões do avaliador de expressão. |
| Propriedades do mecanismo de depuração | Descrição |
|---|---|
| metricAddressBP | Defina como diferente de zero para indicar suporte para pontos de interrupção de endereço. |
| metricAlwaysLoadLocal | Defina como diferente de zero para sempre carregar o mecanismo de depuração localmente. |
| metricLoadInDebuggeeSession | NÃO USADO |
| metricLoadedByDebuggee | Defina como diferente de zero para indicar que o mecanismo de depuração sempre será carregado com ou pelo programa que está sendo depurado. |
| metricAttach | Defina como diferente de zero para indicar suporte para anexo a programas existentes. |
| metricCallStackBP | Defina como diferente de zero para indicar suporte para pontos de interrupção de pilha de chamadas. |
| metricConditionalBP | Defina como diferente de zero para indicar suporte para a configuração de pontos de interrupção condicionais. |
| metricDataBP | Defina como diferente de zero para indicar suporte para a configuração de pontos de interrupção em alterações nos dados. |
| metricDisassembly | Defina como diferente de zero para indicar suporte para a produção de uma listagem de desmontagem. |
| metricDumpWriting | Defina como diferente de zero para indicar suporte para gravação de despejo (o despejo de memória para um dispositivo de saída). |
| métricaENC | Defina como diferente de zero para indicar suporte para Editar e Continuar. Nota: Um mecanismo de depuração personalizado nunca deve definir isso ou sempre deve defini-lo como 0. |
| metricExceptions | Defina como diferente de zero para indicar suporte para exceções. |
| metricFunctionBP | Defina como diferente de zero para indicar suporte para pontos de interrupção nomeados (pontos de interrupção que quebram quando um determinado nome de função é chamado). |
| metricHitCountBP | Defina como diferente de zero para indicar suporte para a configuração de pontos de interrupção de "ponto de acerto" (pontos de interrupção que são acionados somente após serem atingidos um determinado número de vezes). |
| metricJITDebug | Defina como diferente de zero para indicar suporte para depuração just-in-time (o depurador é iniciado quando ocorre uma exceção em um processo em execução). |
| metricMemory | NÃO USADO |
| metricPortSupplier | Defina isso como o CLSID do fornecedor da porta se um for implementado. |
| metricRegisters | NÃO USADO |
| metricSetNextStatement | Defina como diferente de zero para indicar suporte para definir a próxima instrução (que ignora a execução de instruções intermediárias). |
| metricSuspendThread | Defina como diferente de zero para indicar suporte para suspender a execução do thread. |
| metricWarnIfNoSymbols | Defina como diferente de zero para indicar que o usuário deve ser notificado se não houver símbolos. |
| metricProgramProvider | Defina isso como o CLSID do provedor do programa. |
| metricAlwaysLoadProgramProviderLocal | Defina isso como diferente de zero para indicar que o provedor de programa sempre deve ser carregado localmente. |
| metricEngineCanWatchProcess | Defina isso como diferente de zero para indicar que o mecanismo de depuração observará eventos de processo em vez do provedor do programa. |
| metricRemoteDebugging | Defina isso como diferente de zero para indicar suporte para depuração remota. |
| metricEncUseNativeBuilder | Defina isso como diferente de zero para indicar que o Gerenciador de Edição e Continuação deve usar o encbuild do mecanismo de depuração.dll para compilar para Editar e Continuar. Nota: Um mecanismo de depuração personalizado nunca deve definir isso ou sempre deve defini-lo como 0. |
| metricLoadUnderWOW64 | Defina isso como diferente de zero para indicar que o mecanismo de depuração deve ser carregado no processo de depuração em WOW ao depurar um processo de 64 bits; caso contrário, o mecanismo de depuração será carregado no processo do Visual Studio (que está sendo executado em WOW64). |
| metricLoadProgramProviderUnderWOW64 | Defina isso como diferente de zero para indicar que o provedor de programa deve ser carregado no processo de depuração ao depurar um processo de 64 bits em WOW; caso contrário, ele será carregado no processo do Visual Studio. |
| metricStopOnExceptionCrossingManagedBoundary | Defina isso como diferente de zero para indicar que o processo deve parar se uma exceção não tratada for lançada através dos limites de código gerenciado/não gerenciado. |
| metricAutoSelectPriority | Defina isso como uma prioridade para seleção automática do mecanismo de depuração (valores mais altos são iguais a prioridade mais alta). |
| metricAutoSelectIncompatibleList | Chave do Registro que contém entradas que especificam GUIDs para mecanismos de depuração a serem ignorados na seleção automática. Essas entradas são um número (0, 1, 2 e assim por diante) com um GUID expresso como uma cadeia de caracteres. |
| metricIncompatibleList | Chave do Registro que contém entradas que especificam GUIDs para mecanismos de depuração incompatíveis com esse mecanismo de depuração. |
| metricDisableJITOptimization | Defina isso como diferente de zero para indicar que as otimizações just-in-time (para código gerenciado) devem ser desabilitadas durante a depuração. |
| Propriedades do avaliador de expressão | Descrição |
|---|---|
| metricEngine | Isso contém o número de mecanismos de depuração que oferecem suporte ao avaliador de expressão especificado. |
| metricPreloadModules | Defina isso como diferente de zero para indicar que os módulos devem ser pré-carregados quando um avaliador de expressão é iniciado em um programa. |
| metricThisObjectName | Defina isso como o nome do objeto "this". |
| Propriedades da extensão do avaliador de expressão | Descrição |
|---|---|
| metricExtensionDll | Nome da dll que suporta esta extensão. |
| metricExtensionRegistersSupported | Lista de registros suportados. |
| metricExtensionRegistersEntryPoint | Ponto de entrada para acesso aos registros. |
| metricExtensionTypesSupported | Lista de tipos suportados. |
| metricExtensionTypesEntryPoint | Ponto de entrada para acessar tipos. |
| Propriedades do fornecedor portuário | Descrição |
|---|---|
| metricPortPickerCLSID | O CLSID do seletor de portas (uma caixa de diálogo que o usuário pode usar para selecionar portas e adicionar portas a serem usadas para depuração). |
| metricDisallowUserEnteredPorts | Diferente de zero se as portas inseridas pelo usuário não puderem ser adicionadas ao fornecedor da porta (isso torna a caixa de diálogo do seletor de portas essencialmente somente leitura). |
| metricPidBase | O ID do processo base usado pelo fornecedor da porta ao alocar IDs de processo. |
| Tipos de armazenamento de SP predefinidos | Descrição |
|---|---|
| storetypeFile | Os símbolos são armazenados em um arquivo separado. |
| storetypeMetadados | Os símbolos são armazenados como metadados em um assembly. |
| Propriedades Diversas | Descrição |
|---|---|
| metricShowNonUserCode | Defina isso como diferente de zero para mostrar o código de não usuário. |
| metricJustMyCodeStepping | Defina isso como diferente de zero para indicar que a revisão pode ocorrer somente no código do usuário. |
| metricCLSID | CLSID para um objeto de um tipo de métrica específico. |
| metricName | Nome amigável para um objeto de um tipo de métrica específico. |
| métricaLinguagem | Nome do idioma. |
Locais de registro
As métricas são lidas e gravadas no registro, especificamente na VisualStudio subchave.
Observação
Na maioria das vezes, as métricas serão gravadas na chave HKEY_LOCAL_MACHINE. No entanto, às vezes HKEY_CURRENT_USER será a chave de destino. Dbgmetric.lib manipula ambas as chaves. Ao obter uma métrica, ele pesquisa primeiro HKEY_CURRENT_USER e, em seguida, HKEY_LOCAL_MACHINE. Quando ele está definindo uma métrica, um parâmetro especifica qual chave de nível superior usar.
[chave do Registro]\
Software\
Microsoft\
VisualStudio\
[raiz da versão]\
[raiz métrica]\
[tipo métrico]\
[métrica] = [valor métrico]
[métrica] = [valor métrico]
[métrica] = [valor métrico]
| Espaço reservado | Descrição |
|---|---|
| [chave do Registro] | HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE. |
| [raiz da versão] | A versão do Visual Studio (por exemplo, , 7.07.1ou 8.0). No entanto, essa raiz também pode ser modificada usando a opção /rootsuffix para devenv.exe. Para VSIP, esse modificador é normalmente Exp, então a raiz da versão seria, por exemplo, 8.0Exp. |
| [raiz métrica] | Isso é ou AD7Metrics AD7Metrics(Debug), dependendo se a versão de depuração do dbgmetric.lib é usada. Nota: Independentemente de dbgmetric.lib ser usado ou não, essa convenção de nomenclatura deve ser respeitada se você tiver diferenças entre as versões de depuração e lançamento que devem ser refletidas no registro. |
| [tipo métrico] | O tipo de métrica a ser escrita: Engine, , ExpressionEvaluator, SymbolProvideretc. Todos eles são definidos como em dbgmetric.h como metricTypeXXXX, onde XXXX é o nome do tipo específico. |
| [métrica] | O nome de uma entrada a ser atribuída um valor para definir a métrica. A organização real das métricas depende do tipo de métrica. |
| [valor métrico] | O valor atribuído à métrica. O tipo que o valor deve ter (string, number, etc.) depende da métrica. |
Observação
Todos os GUIDs são armazenados no formato de {GUID}. Por exemplo, {123D150B-FA18-461C-B218-45B3E4589F9B}.
Mecanismos de depuração
A seguir está a organização das métricas dos mecanismos de depuração no registro. Engine é o nome do tipo de métrica para um mecanismo de depuração e corresponde a [tipo de métrica] na subárvore do Registro acima.
Engine\
[GUID do motor]\
CLSID = [GUID de classe]
[métrica] = [valor métrico]
[métrica] = [valor métrico]
[métrica] = [valor métrico]
PortSupplier\
0 = [GUID do fornecedor portuário]
1 = [GUID do fornecedor portuário]
| Espaço reservado | Descrição |
|---|---|
| [GUID do motor] | O GUID do mecanismo de depuração. |
| [GUID de classe] | O GUID da classe que implementa esse mecanismo de depuração. |
| [GUID do fornecedor portuário] | O GUID do fornecedor portuário, se houver. Muitos mecanismos de depuração usam o fornecedor de porta padrão e, portanto, não especificam seu próprio fornecedor. Nesse caso, a subchave PortSupplier estará ausente. |
Fornecedores de porta
A seguir está a organização das métricas do fornecedor portuário no registro. PortSupplier é o nome do tipo de métrica para um fornecedor de porta e corresponde a [tipo de métrica].
PortSupplier\
[GUID do fornecedor portuário]\
CLSID = [GUID de classe]
[métrica] = [valor métrico]
[métrica] = [valor métrico]
| Espaço reservado | Descrição |
|---|---|
| [GUID do fornecedor portuário] | O GUID do fornecedor do porto |
| [GUID de classe] | O GUID da classe que implementa este fornecedor de porta |
Provedores de símbolos
A seguir está a organização das métricas de fornecedor de símbolo no registro. SymbolProvider é o nome do tipo de métrica para o provedor de símbolo e corresponde a [tipo de métrica].
SymbolProvider\
[GUID do provedor de símbolos]\
file\
CLSID = [GUID de classe]
[métrica] = [valor métrico]
[métrica] = [valor métrico]
metadata\
CLSID = [GUID de classe]
[métrica] = [valor métrico]
[métrica] = [valor métrico]
| Espaço reservado | Descrição |
|---|---|
| [GUID do provedor de símbolos] | O GUID do provedor de símbolos |
| [GUID de classe] | O GUID da classe que implementa esse provedor de símbolos |
Avaliadores de Expressão
A seguir está a organização das métricas do avaliador de expressão no registro. ExpressionEvaluator é o nome do tipo de métrica para o avaliador de expressão e corresponde a [tipo de métrica].
Observação
O tipo de métrica para não é definido em dbgmetric.h, pois presume-se que todas as alterações de métrica para ExpressionEvaluator avaliadores de expressão passarão pelas funções métricas apropriadas do avaliador de expressão (o layout da subchave é um pouco complicado, portanto, os detalhes ficam ocultos dentro de ExpressionEvaluator dbgmetric.lib).
ExpressionEvaluator\
[GUID de idioma]\
[GUID do fornecedor]\
CLSID = [GUID de classe]
[métrica] = [valor métrico]
[métrica] = [valor métrico]
Engine\
0 = [GUID do mecanismo de depuração]
1 = [GUID do mecanismo de depuração]
| Espaço reservado | Descrição |
|---|---|
| [GUID de idioma] | O GUID de um idioma |
| [GUID do fornecedor] | O GUID de um fornecedor |
| [GUID de classe] | O GUID da classe que implementa esse avaliador de expressão |
| [GUID do mecanismo de depuração] | O GUID de um mecanismo de depuração com o qual esse avaliador de expressão trabalha |
Extensões do Avaliador de Expressão
A seguir está a organização das métricas de extensão do avaliador de expressão no registro. EEExtensions é o nome do tipo de métrica para as extensões do avaliador de expressão e corresponde a [tipo de métrica].
EEExtensions\
[GUID de extensão]\
[métrica] = [valor métrico]
[métrica] = [valor métrico]
| Espaço reservado | Descrição |
|---|---|
| [GUID de extensão] | O GUID de uma extensão do avaliador de expressão |
Exceções
A seguir está a organização das métricas de exceções no registro. Exception é o nome do tipo de métrica para as exceções e corresponde a [tipo de métrica].
Exception\
[GUID do mecanismo de depuração]\
[tipos de exceção]\
[exceção]\
[métrica] = [valor métrico]
[métrica] = [valor métrico]
[exceção]\
[métrica] = [valor métrico]
[métrica] = [valor métrico]
| Espaço reservado | Descrição |
|---|---|
| [GUID do mecanismo de depuração] | O GUID de um mecanismo de depuração que oferece suporte a exceções. |
| [tipos de exceção] | Um título geral para a subchave que identifica a classe de exceções que podem ser manipuladas. Os nomes típicos são exceções C++, exceções Win32, exceções do Common Language Runtime e verificações nativas de tempo de execução. Esses nomes também são usados para identificar uma classe específica de exceção para o usuário. |
| [exceção] | Um nome para uma exceção: por exemplo, _com_error ou Control-Break. Esses nomes também são usados para identificar uma exceção específica para o usuário. |
Requisitos
Esses arquivos estão localizados no diretório de instalação do SDK do Microsoft Visual Studio 2010 (por padrão, [unidade]\Arquivos de Programas\Microsoft Visual Studio 2010 SDK\).
Cabeçalho: includes\dbgmetric.h
Biblioteca: libs\ad2de.lib, libs\dbgmetric.lib