Helper SDK per il debug
Queste funzioni e dichiarazioni sono funzioni helper globali per l'implementazione di motori di debug, analizzatori di espressioni e provider di simboli in C++.
Nota
Al momento non sono disponibili versioni gestite di queste funzioni e dichiarazioni.
Affinché i motori di debug, gli analizzatori di espressioni e i provider di simboli vengano usati da Visual Studio, devono essere registrati. Questa operazione viene eseguita impostando sottochiavi e voci del Registro di sistema, altrimenti note come "impostazione delle metriche". Le funzioni globali seguenti sono progettate per semplificare il processo di aggiornamento di queste metriche. Vedere la sezione percorsi del Registro di sistema per scoprire il layout di ogni sottochiave del Registro di sistema aggiornata da queste funzioni.
Funzioni metriche generali
Queste sono funzioni generali usate dai motori di debug. Le funzioni specializzate per gli analizzatori di espressioni e i provider di simboli sono descritte più avanti.
Metodo GetMetric
Recupera un valore della metrica dal Registro di sistema.
HRESULT GetMetric(
LPCWSTR pszMachine,
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
DWORD * pdwValue,
LPCWSTR pszAltRoot
);
| Parametro | Descrizione |
|---|---|
| pszMachine | [in] Nome di un computer eventualmente remoto il cui registro verrà scritto (NULL significa computer locale). |
| pszType | [in] Uno dei tipi di metrica. |
| guidSection | [in] GUID di un motore specifico, analizzatore, eccezione e così via. Specifica una sottosezione in un tipo di metrica per un elemento specifico. |
| pszMetric | [in] Metrica da ottenere. Corrisponde a un nome di valore specifico. |
| pdwValue | [in] Posizione di archiviazione del valore dalla metrica. Esistono diversi tipi di GetMetric che possono restituire un DWORD (come in questo esempio), un BSTR, un GUID o una matrice di GUID. |
| pszAltRoot | [in] Radice alternativa del Registro di sistema da usare. Impostare su NULL per usare l'impostazione predefinita. |
SetMetric, metodo
Imposta il valore della metrica specificato nel Registro di sistema.
HRESULT SetMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
const DWORD dwValue,
bool fUserSpecific,
LPCWSTR pszAltRoot
);
| Parametro | Descrizione |
|---|---|
| pszType | [in] Uno dei tipi di metrica. |
| guidSection | [in] GUID di un motore specifico, analizzatore, eccezione e così via. Specifica una sottosezione in un tipo di metrica per un elemento specifico. |
| pszMetric | [in] Metrica da ottenere. Corrisponde a un nome di valore specifico. |
| dwValue | [in] Posizione di archiviazione del valore nella metrica. Esistono diversi tipi di SetMetric in grado di archiviare un DWORD (in questo esempio), un BSTR, un GUID o una matrice di GUID. |
| fUserSpecific | [in] TRUE se la metrica è specifica dell'utente e se deve essere scritta nell'hive dell'utente anziché nell'hive del computer locale. |
| pszAltRoot | [in] Radice alternativa del Registro di sistema da usare. Impostare su NULL per usare l'impostazione predefinita. |
RemoveMetric, metodo
Rimuove la metrica specificata dal Registro di sistema.
HRESULT RemoveMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
LPCWSTR pszAltRoot
);
| Parametro | Descrizione |
|---|---|
| pszType | [in] Uno dei tipi di metrica. |
| guidSection | [in] GUID di un motore specifico, analizzatore, eccezione e così via. Specifica una sottosezione in un tipo di metrica per un elemento specifico. |
| pszMetric | [in] Metrica da rimuovere. Corrisponde a un nome di valore specifico. |
| pszAltRoot | [in] Radice alternativa del Registro di sistema da usare. Impostare su NULL per usare l'impostazione predefinita. |
Metodo EnumMetricSections
Enumera le varie sezioni delle metriche nel Registro di sistema.
HRESULT EnumMetricSections(
LPCWSTR pszMachine,
LPCWSTR pszType,
GUID * rgguidSections,
DWORD * pdwSize,
LPCWSTR pszAltRoot
);
| Parametro | Descrizione |
|---|---|
| pszMachine | [in] Nome di un computer eventualmente remoto il cui registro verrà scritto (NULL significa computer locale). |
| pszType | [in] Uno dei tipi di metrica. |
| rgguidSections | [in, out] Matrice preallocata di GUID da compilare. |
| pdwSize | [in] Numero massimo di GUID che è possibile archiviare nella rgguidSections matrice. |
| pszAltRoot | [in] Radice alternativa del Registro di sistema da usare. Impostare su NULL per usare l'impostazione predefinita. |
Funzioni dell'analizzatore di espressioni
| Funzione | Descrizione |
|---|---|
| Get edizione Enterprise Metric | Recupera un valore della metrica dal Registro di sistema. |
| Set edizione Enterprise Metric | Imposta il valore della metrica specificato nel Registro di sistema. |
| Remove edizione Enterprise Metric | Rimuove la metrica specificata dal Registro di sistema. |
| GetEEMetricFile | Ottiene un nome di file dalla metrica specificata e lo carica, restituendo il contenuto del file come stringa. |
Funzioni di eccezione
| Funzione | Descrizione |
|---|---|
| GetExceptionMetric | Recupera un valore della metrica dal Registro di sistema. |
| SetExceptionMetric | Imposta il valore della metrica specificato nel Registro di sistema. |
| RemoveExceptionMetric | Rimuove la metrica specificata dal Registro di sistema. |
| RemoveAllExceptionMetrics | Rimuove tutte le metriche delle eccezioni dal Registro di sistema. |
Funzioni del provider di simboli
| Funzione | Descrizione |
|---|---|
| GetSPMetric | Recupera un valore della metrica dal Registro di sistema. |
| SetSPMetric | Imposta il valore della metrica specificato nel Registro di sistema. |
| RemoveSPMetric | Rimuove la metrica specificata dal Registro di sistema. |
Funzioni di enumerazione
| Funzione | Descrizione |
|---|---|
| EnumMetricSections | Enumera tutte le metriche per un tipo di metrica specificato. |
| EnumDebugEngine | Enumera i motori di debug registrati. |
| EnumEEs | Enumera gli analizzatori di espressioni registrate. |
| EnumExceptionMetrics | Enumera tutte le metriche delle eccezioni. |
Definizioni delle metriche
Queste definizioni possono essere usate per i nomi di metrica predefiniti. I nomi corrispondono a varie chiavi e nomi di valore del Registro di sistema e sono tutti definiti come stringhe di caratteri wide, ad esempio extern LPCWSTR metrictypeEngine.
| Tipi di metriche predefiniti | Descrizione: chiave di base per... |
|---|---|
| metrictypeEngine | Tutte le metriche del motore di debug. |
| metrictypePortSupplier | Tutte le metriche relative ai fornitori di porte. |
| metrictypeException | Tutte le metriche delle eccezioni. |
| metricttype edizione Enterprise Extension | Tutte le estensioni dell'analizzatore di espressioni. |
| Proprietà del motore di debug | Descrizione |
|---|---|
| metricAddressBP | Impostare su diverso da zero per indicare il supporto per i punti di interruzione degli indirizzi. |
| metricAlwaysLoadLocal | Impostare su diverso da zero per caricare sempre il motore di debug in locale. |
| metricLoadInDebuggeeSession | NON IN USO |
| metricLoadedByDebuggee | Impostare su diverso da zero per indicare che il motore di debug verrà sempre caricato con o dal programma sottoposto a debug. |
| metricAttach | Impostare su diverso da zero per indicare il supporto per l'allegato ai programmi esistenti. |
| metricCallStackBP | Impostare su diverso da zero per indicare il supporto per i punti di interruzione dello stack di chiamate. |
| metricConditionalBP | Impostare su diverso da zero per indicare il supporto per l'impostazione dei punti di interruzione condizionali. |
| metricDataBP | Impostare su diverso da zero per indicare il supporto per l'impostazione dei punti di interruzione sulle modifiche apportate ai dati. |
| metricDisassembly | Impostare su diverso da zero per indicare il supporto per la produzione di un elenco disassembly. |
| metricDumpWriting | Impostare su diverso da zero per indicare il supporto per la scrittura di dump (il dump della memoria in un dispositivo di output). |
| metricENC | Impostare su diverso da zero per indicare il supporto per Modifica e Continuazione. Nota: un motore di debug personalizzato non deve mai impostare questo valore o deve sempre impostarlo su 0. |
| metricExceptions | Impostare su diverso da zero per indicare il supporto per le eccezioni. |
| metricFunctionBP | Impostare su diverso da zero per indicare il supporto per i punti di interruzione denominati (punti di interruzione che si interrompono quando viene chiamato un determinato nome di funzione). |
| metricHitCountBP | Impostare su diverso da zero per indicare il supporto per l'impostazione dei punti di interruzione "hit point" (punti di interruzione attivati solo dopo aver raggiunto un determinato numero di volte). |
| metricJITDebug | Impostare su diverso da zero per indicare il supporto per il debug JIT (il debugger viene avviato quando si verifica un'eccezione in un processo in esecuzione). |
| metricMemory | NON IN USO |
| metricPortSupplier | Impostarlo sul CLSID del fornitore di porte se ne viene implementato uno. |
| metricRegisters | NON IN USO |
| metricSetNextStatement | Impostare su diverso da zero per indicare il supporto per l'impostazione dell'istruzione successiva (che ignora l'esecuzione di istruzioni intermedie). |
| metricSuspendThread | Impostare su diverso da zero per indicare il supporto per la sospensione dell'esecuzione del thread. |
| metricWarnIfNoSymbols | Impostare su diverso da zero per indicare che l'utente deve ricevere una notifica se non sono presenti simboli. |
| metricProgramProvider | Impostare questa proprietà sul CLSID del provider di programmi. |
| metricAlwaysLoadProgramProviderLocal | Impostare questo valore su diverso da zero per indicare che il provider di programmi deve essere sempre caricato in locale. |
| metricEngineCanWatchProcess | Impostare questo valore su diverso da zero per indicare che il motore di debug eseguirà la verifica degli eventi di elaborazione anziché del provider di programmi. |
| metricRemoteDebugging | Impostare questo valore su diverso da zero per indicare il supporto per il debug remoto. |
| metricEncUseNativeBuilder | Impostare questo valore su diverso da zero per indicare che Edit and Continue Manager deve usare il file encbuild.dll del motore di debug per la compilazione per Modifica e Continuazione. Nota: un motore di debug personalizzato non deve mai impostare questo valore o deve sempre impostarlo su 0. |
| metricLoadUnderWOW64 | Impostare questo valore su diverso da zero per indicare che il motore di debug deve essere caricato nel processo di debug in WOW durante il debug di un processo a 64 bit; in caso contrario, il motore di debug verrà caricato nel processo di Visual Studio (in esecuzione in WOW64). |
| metricLoadProgramProviderUnderWOW64 | Impostare questo valore su diverso da zero per indicare che il provider di programmi deve essere caricato nel processo di debug durante il debug di un processo a 64 bit in WOW; in caso contrario, verrà caricato nel processo di Visual Studio. |
| metricStopOnExceptionCrossingManagedBoundary | Impostare questo valore su diverso da zero per indicare che il processo deve arrestarsi se viene generata un'eccezione non gestita attraverso limiti di codice gestiti o non gestiti. |
| metricAutoSelectPriority | Impostare questa opzione su una priorità per la selezione automatica del motore di debug (i valori più alti sono uguali a priorità più alta). |
| metricAutoSelectIncompatibleList | Chiave del Registro di sistema contenente voci che specificano GUID per i motori di debug da ignorare nella selezione automatica. Queste voci sono un numero (0, 1, 2 e così via) con un GUID espresso come stringa. |
| metricIncompatibleList | Chiave del Registro di sistema contenente voci che specificano GUID per i motori di debug incompatibili con questo motore di debug. |
| metricDisableJITOptimization | Impostare questo valore su diverso da zero per indicare che le ottimizzazioni JIT (per il codice gestito) devono essere disabilitate durante il debug. |
| Proprietà dell'analizzatore di espressioni | Descrizione |
|---|---|
| metricEngine | Contiene il numero di motori di debug che supportano l'analizzatore di espressioni specificato. |
| metricPreloadModules | Impostare questo valore su diverso da zero per indicare che i moduli devono essere precaricati quando un analizzatore di espressioni viene avviato su un programma. |
| metricThisObjectName | Impostarlo sul nome dell'oggetto "this". |
| Proprietà dell'estensione dell'analizzatore di espressioni | Descrizione |
|---|---|
| metricExtensionDll | Nome della dll che supporta questa estensione. |
| metricExtensionRegistersSupported | Elenco dei registri supportati. |
| metricExtensionRegistersEntryPoint | Punto di ingresso per l'accesso ai registri. |
| metricExtensionTypesSupported | Elenco dei tipi supportati. |
| metricExtensionTypesEntryPoint | Punto di ingresso per l'accesso ai tipi. |
| Proprietà fornitore porta | Descrizione |
|---|---|
| metricPortPickerCLSID | CLSID della selezione porte (una finestra di dialogo che l'utente può usare per selezionare le porte e aggiungere porte da usare per il debug). |
| metricDisallowUserEnteredPorts | Diverso da zero se le porte immesse dall'utente non possono essere aggiunte al fornitore di porte (in questo modo la finestra di dialogo di selezione porta è essenzialmente di sola lettura). |
| metricPidBase | ID del processo di base usato dal fornitore di porte durante l'allocazione degli ID processo. |
| Tipi di archivio SP predefiniti | Descrizione |
|---|---|
| storetypeFile | I simboli vengono archiviati in un file separato. |
| storetypeMetadata | I simboli vengono archiviati come metadati in un assembly. |
| Proprietà varie | Descrizione |
|---|---|
| metricShowNonUserCode | Impostare questo valore su diverso da zero per visualizzare il codice non utente. |
| metricJustMyCodeStepping | Impostare questo valore su diverso da zero per indicare che l'istruzione può verificarsi solo nel codice utente. |
| metricCLSID | CLSID per un oggetto di un tipo di metrica specifico. |
| metricName | Nome descrittivo per un oggetto di un tipo di metrica specifico. |
| metricLanguage | Nome della lingua. |
Percorsi del Registro di sistema
Le metriche vengono lette e scritte nel Registro di sistema, in particolare nella VisualStudio sottochiave.
Nota
Nella maggior parte dei casi, le metriche verranno scritte nella chiave HKEY_LOCAL_MACHINE. Tuttavia, a volte HKEY_CURRENT_Uedizione Standard R sarà la chiave di destinazione. Dbgmetric.lib gestisce entrambe le chiavi. Quando si ottiene una metrica, cerca prima HKEY_CURRENT_Uedizione Standard R, quindi HKEY_LOCAL_MACHINE. Quando si imposta una metrica, un parametro specifica la chiave di primo livello da usare.
[chiave del Registro di sistema]\
Software\
Microsoft\
VisualStudio\
[versione radice]\
[radice metrica]\
[tipo di metrica]\
[metric] = [valore metrico]
[metric] = [valore metrico]
[metric] = [valore metrico]
| Segnaposto | Descrizione |
|---|---|
| [chiave del Registro di sistema] | HKEY_CURRENT_USER o HKEY_LOCAL_MACHINE. |
| [versione radice] | Versione di Visual Studio (ad esempio, 7.0, 7.1o 8.0). Tuttavia, questa radice può anche essere modificata usando l'opzione /rootuffix per devenv.exe. Per VSIP, questo modificatore è in genere Exp, quindi la radice della versione sarà, ad esempio, 8.0Exp. |
| [radice metrica] | Si tratta di AD7Metrics o AD7Metrics(Debug), a seconda che venga usata la versione di debug di dbgmetric.lib. Nota: se viene usato dbgmetric.lib, questa convenzione di denominazione deve essere rispettata se sono presenti differenze tra le versioni di debug e di rilascio che devono essere riflesse nel Registro di sistema. |
| [tipo di metrica] | Tipo di metrica da scrivere: Engine, ExpressionEvaluator, e SymbolProvidercosì via. Questi sono tutti definiti come in dbgmetric.h come metricTypeXXXX, dove XXXX è il nome di tipo specifico. |
| [metrica] | Nome di una voce a cui assegnare un valore per impostare la metrica. L'organizzazione effettiva delle metriche dipende dal tipo di metrica. |
| [valore metrico] | Valore assegnato alla metrica. Il tipo che il valore deve avere (stringa, numero e così via) dipende dalla metrica. |
Nota
Tutti i GUID vengono archiviati nel formato .{GUID} Ad esempio: {123D150B-FA18-461C-B218-45B3E4589F9B}.
Motori di debug
Di seguito è riportata l'organizzazione delle metriche dei motori di debug nel Registro di sistema. Engine è il nome del tipo di metrica per un motore di debug e corrisponde a [tipo di metrica] nel sottoalbero del Registro di sistema precedente.
Engine\
[guid motore]\
CLSID = [guid di classe]
[metric] = [valore metrico]
[metric] = [valore metrico]
[metric] = [valore metrico]
PortSupplier\
0 = [port supplier guid]
1 = [port supplier guid]
| Segnaposto | Descrizione |
|---|---|
| [guid motore] | GUID del motore di debug. |
| [guid di classe] | GUID della classe che implementa questo motore di debug. |
| [port supplier guid] | GUID del fornitore di porte, se presente. Molti motori di debug usano il fornitore di porte predefinito e pertanto non specificano il proprio fornitore. In questo caso, la sottochiave PortSupplier sarà assente. |
Fornitori di porte
Di seguito è riportata l'organizzazione delle metriche dei fornitori di porte nel Registro di sistema. PortSupplier è il nome del tipo di metrica per un fornitore di porte e corrisponde a [tipo di metrica].
PortSupplier\
[port supplier guid]\
CLSID = [guid di classe]
[metric] = [valore metrico]
[metric] = [valore metrico]
| Segnaposto | Descrizione |
|---|---|
| [port supplier guid] | GUID del fornitore di porte |
| [guid di classe] | GUID della classe che implementa questo fornitore di porte |
Provider di simboli
Di seguito è riportata l'organizzazione delle metriche dei fornitori di simboli nel Registro di sistema. SymbolProvider è il nome del tipo di metrica per il provider di simboli e corrisponde a [tipo di metrica].
SymbolProvider\
[guid provider di simboli]\
file\
CLSID = [guid di classe]
[metric] = [valore metrico]
[metric] = [valore metrico]
metadata\
CLSID = [guid di classe]
[metric] = [valore metrico]
[metric] = [valore metrico]
| Segnaposto | Descrizione |
|---|---|
| [guid provider di simboli] | GUID del provider di simboli |
| [guid di classe] | GUID della classe che implementa questo provider di simboli |
Analizzatori di espressioni
Di seguito è riportata l'organizzazione delle metriche dell'analizzatore di espressioni nel Registro di sistema. ExpressionEvaluator è il nome del tipo di metrica per l'analizzatore di espressioni e corrisponde a [tipo di metrica].
Nota
Il tipo di metrica per ExpressionEvaluator non è definito in dbgmetric.h, perché si presuppone che tutte le modifiche delle metriche per gli analizzatori di espressioni attraverseranno le funzioni di metrica dell'analizzatore di espressioni appropriate (il layout della ExpressionEvaluator sottochiave è piuttosto complicato, quindi i dettagli sono nascosti all'interno di dbgmetric.lib).
ExpressionEvaluator\
[guid lingua]\
[guid fornitore]\
CLSID = [guid di classe]
[metric] = [valore metrico]
[metric] = [valore metrico]
Engine\
0 = [GUID del motore di debug]
1 = [GUID del motore di debug]
| Segnaposto | Descrizione |
|---|---|
| [guid lingua] | GUID di una lingua |
| [guid fornitore] | GUID di un fornitore |
| [guid di classe] | GUID della classe che implementa questo analizzatore di espressioni |
| [GUID del motore di debug] | GUID di un motore di debug usato da questo analizzatore di espressioni |
Estensioni dell'analizzatore di espressioni
Di seguito è riportata l'organizzazione delle metriche di estensione dell'analizzatore di espressioni nel Registro di sistema. EEExtensions è il nome del tipo di metrica per le estensioni dell'analizzatore di espressioni e corrisponde a [tipo di metrica].
EEExtensions\
[GUID estensione]\
[metric] = [valore metrico]
[metric] = [valore metrico]
| Segnaposto | Descrizione |
|---|---|
| [GUID estensione] | GUID di un'estensione dell'analizzatore di espressioni |
Eccezioni
Di seguito è riportata l'organizzazione delle metriche delle eccezioni nel Registro di sistema. Exception è il nome del tipo di metrica per le eccezioni e corrisponde a [tipo di metrica].
Exception\
[GUID del motore di debug]\
[tipi di eccezione]\
[eccezione]\
[metric] = [valore metrico]
[metric] = [valore metrico]
[eccezione]\
[metric] = [valore metrico]
[metric] = [valore metrico]
| Segnaposto | Descrizione |
|---|---|
| [GUID del motore di debug] | GUID di un motore di debug che supporta le eccezioni. |
| [tipi di eccezione] | Titolo generale per la sottochiave che identifica la classe di eccezioni che è possibile gestire. I nomi tipici sono eccezioni C++, eccezioni Win32, eccezioni Common Language Runtime e controlli di runtime nativi. Questi nomi vengono usati anche per identificare una determinata classe di eccezione per l'utente. |
| [eccezione] | Nome di un'eccezione: ad esempio, _com_error o Control-Break. Questi nomi vengono usati anche per identificare una particolare eccezione all'utente. |
Requisiti
Questi file si trovano nella directory di installazione di Microsoft Visual Studio 2010 SDK (per impostazione predefinita[ unità]\Programmi\Microsoft Visual Studio 2010 SDK\).
Intestazione: includes\dbgmetric.h
Libreria: libs\ad2de.lib, libs\dbgmetric.lib