Pomocníci sad SDK pro ladění
Tyto funkce a deklarace jsou globální pomocné funkce pro implementaci ladicích modulů, vyhodnocovačů výrazů a poskytovatelů symbolů v jazyce C++.
Poznámka:
V tuto chvíli neexistují žádné spravované verze těchto funkcí a deklarací.
Aby byly ladicí moduly, vyhodnocovače výrazů a zprostředkovatele symbolů používané sadou Visual Studio, musí být zaregistrované. To se provádí nastavením podklíčů registru a položek, jinak označovaných jako "nastavení metrik". Následující globální funkce jsou navržené tak, aby zjednodušily proces aktualizace těchto metrik. V části Umístění registru zjistíte rozložení jednotlivých podklíčů registru, které jsou aktualizovány těmito funkcemi.
Obecné funkce metrik
Jedná se o obecné funkce používané ladicími moduly. Specializované funkce pro vyhodnocovače výrazů a zprostředkovatele symbolů jsou podrobně popsány později.
GetMetric – metoda
Načte hodnotu metriky z registru.
HRESULT GetMetric(
LPCWSTR pszMachine,
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
DWORD * pdwValue,
LPCWSTR pszAltRoot
);
| Parametr | Popis |
|---|---|
| pszMachine | [v] Název pravděpodobně vzdáleného počítače, jehož registr bude zapsán (NULL znamená místní počítač). |
| pszType | [v] Jeden z typů metrik. |
| GuidSection | [v] IDENTIFIKÁTOR GUID konkrétního modulu, vyhodnocovače, výjimky atd. Určuje pododdíl pod typem metriky pro určitý prvek. |
| PszMetric | [v] Metrika, která se má získat. To odpovídá určitému názvu hodnoty. |
| pdwValue | [v] Umístění úložiště hodnoty z metriky. Existuje několik variant GetMetric, které můžou vrátit DWORD (jako v tomto příkladu), BSTR, IDENTIFIKÁTOR GUID nebo pole identifikátorů GUID. |
| pszAltRoot | [v] Alternativní kořen registru, který se má použít. Nastavte na NULL výchozí hodnotu. |
SetMetric – metoda
Nastaví zadanou hodnotu metriky v registru.
HRESULT SetMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
const DWORD dwValue,
bool fUserSpecific,
LPCWSTR pszAltRoot
);
| Parametr | Popis |
|---|---|
| pszType | [v] Jeden z typů metrik. |
| GuidSection | [v] IDENTIFIKÁTOR GUID konkrétního modulu, vyhodnocovače, výjimky atd. Určuje pododdíl pod typem metriky pro určitý prvek. |
| PszMetric | [v] Metrika, která se má získat. To odpovídá určitému názvu hodnoty. |
| dwValue | [v] Umístění úložiště hodnoty v metrice. Existuje několik variant SetMetric, které mohou ukládat DWORD (v tomto příkladu), BSTR, IDENTIFIKÁTOR GUID nebo pole identifikátorů GUID. |
| fUserSpecific | [v] TRUE, pokud je metrika specifická pro uživatele a pokud by měla být zapsána do podregistru uživatele místo hivu místního počítače. |
| pszAltRoot | [v] Alternativní kořen registru, který se má použít. Nastavte na NULL výchozí hodnotu. |
RemoveMetric – metoda
Odebere zadanou metriku z registru.
HRESULT RemoveMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
LPCWSTR pszAltRoot
);
| Parametr | Popis |
|---|---|
| pszType | [v] Jeden z typů metrik. |
| GuidSection | [v] IDENTIFIKÁTOR GUID konkrétního modulu, vyhodnocovače, výjimky atd. Určuje pododdíl pod typem metriky pro určitý prvek. |
| PszMetric | [v] Metrika, která se má odebrat. To odpovídá určitému názvu hodnoty. |
| pszAltRoot | [v] Alternativní kořen registru, který se má použít. Nastavte na NULL výchozí hodnotu. |
EnumMetricSections – metoda
Vytvoří výčet různých částí metrik v registru.
HRESULT EnumMetricSections(
LPCWSTR pszMachine,
LPCWSTR pszType,
GUID * rgguidSections,
DWORD * pdwSize,
LPCWSTR pszAltRoot
);
| Parametr | Popis |
|---|---|
| pszMachine | [v] Název pravděpodobně vzdáleného počítače, jehož registr bude zapsán (NULL znamená místní počítač). |
| pszType | [v] Jeden z typů metrik. |
| rgguidSections | [in, out] Předem přidělené pole identifikátorů GUID, které se má vyplnit. |
| pdwSize | [v] Maximální počet identifikátorů GUID, které lze uložit v rgguidSections poli. |
| pszAltRoot | [v] Alternativní kořen registru, který se má použít. Nastavte na NULL výchozí hodnotu. |
Funkce vyhodnocovače výrazů
| Function | Popis |
|---|---|
| GetEEMetric | Načte hodnotu metriky z registru. |
| SetEEMetric | Nastaví zadanou hodnotu metriky v registru. |
| RemoveEEMetric | Odebere zadanou metriku z registru. |
| GetEEMetricFile | Získá název souboru ze zadané metriky a načte ho a vrátí obsah souboru jako řetězec. |
Funkce výjimek
| Function | Popis |
|---|---|
| GetExceptionMetric | Načte hodnotu metriky z registru. |
| SetExceptionMetric | Nastaví zadanou hodnotu metriky v registru. |
| RemoveExceptionMetric | Odebere zadanou metriku z registru. |
| RemoveAllExceptionMetrics | Odebere všechny metriky výjimek z registru. |
Funkce zprostředkovatele symbolů
| Function | Popis |
|---|---|
| GetSPMetric | Načte hodnotu metriky z registru. |
| SetSPMetric | Nastaví zadanou hodnotu metriky v registru. |
| RemoveSPMetric | Odebere zadanou metriku z registru. |
Funkce výčtu
| Function | Popis |
|---|---|
| Výčty | Vytvoří výčet všech metrik pro zadaný typ metriky. |
| EnumDebugEngine | Vytvoří výčet registrovaných ladicích modulů. |
| EnumEEs | Vytvoří výčet vyhodnocovačů registrovaných výrazů. |
| EnumExceptionMetrics | Vytvoří výčet všech metrik výjimek. |
Definice metrik
Tyto definice lze použít pro předdefinované názvy metrik. Názvy odpovídají různým klíčům registru a názvům hodnot a jsou definovány jako široké řetězce znaků: například extern LPCWSTR metrictypeEngine.
| Předdefinované typy metrik | Popis: Základní klíč pro...... |
|---|---|
| metrictypeEngine | Všechny metriky ladicího stroje. |
| metrictypePortSupplier | Všechny metriky dodavatele portů. |
| metrictypeException | Všechny metriky výjimek. |
| metricttypeEEExtension | Všechna rozšíření vyhodnocovače výrazů. |
| Vlastnosti ladicího stroje | Popis |
|---|---|
| metricAddressBP | Nastavte na nenulovou hodnotu a označte podporu pro zarážky adres. |
| metricAlwaysLoadLocal | Nastavte na nenulový, aby se ladicí modul vždy načetl místně. |
| metricLoadInDebuggeeSession | NEPOUŽÍVÁ SE |
| metricLoadedByDebuggee | Nastavte na nenulovou hodnotu, což znamená, že ladicí modul bude vždy načten s laděným programem nebo programem, který je laděný. |
| metricAttach | Nastavte na nenulové označení podpory přílohy k existujícím programům. |
| metricCallStackBP | Nastavte na nenulovou hodnotu a označte podporu zarážek zásobníku volání. |
| metricConditionalBP | Nastavte na nenulovou hodnotu a označte podporu pro nastavení podmíněných zarážek. |
| metricDataBP | Nastavte na nenulovou hodnotu, která označuje podporu nastavení zarážek u změn v datech. |
| metricDisassembly | Nastavte na nenulovou hodnotu, která označuje podporu pro výrobu výpisu zpětného překladu. |
| metricDumpWriting | Nastavte na nenulovou hodnotu, která označuje podporu zápisu výpisu paměti (výpis paměti do výstupního zařízení). |
| metricENC | Nastavte na hodnotu nenulové, která označuje podporu pro funkci Upravit a pokračovat. Poznámka: Vlastní ladicí modul by nikdy neměl toto nastavení nastavit nebo by ho měl vždy nastavit na hodnotu 0. |
| metricExceptions | Nastavte na nenulové označení podpory výjimek. |
| metricFunctionBP | Nastavte na hodnotu nenulovou, která označuje podporu pojmenovaných zarážek (zarážky, které se zarážky zalomí při volání určitého názvu funkce). |
| metricHitCountBP | Nastavte na nenulovou hodnotu a označte podporu nastavení zarážek "bod dosažení" (zarážky, které se aktivují až po dosažení určitého počtu pokusů). |
| metricJITDebug | Nastavte na nenulovou hodnotu, která označuje podporu ladění za běhu (ladicí program se spustí, když dojde k výjimce spuštěného procesu). |
| metricMemory | NEPOUŽÍVÁ SE |
| metricPortSupplier | Pokud je implementovaný, nastavte ho na CLSID dodavatele portu. |
| metricRegisters | NEPOUŽÍVÁ SE |
| metricSetNextStatement | Nastavte na nenulové nastavení podpory pro nastavení dalšího příkazu (který přeskočí provádění zprostředkujících příkazů). |
| metricSuspendThread | Nastavte na hodnotu nenulové, která označuje podporu pro pozastavení provádění vlákna. |
| metricWarnIfNoSymbols | Pokud uživatel nemá žádné symboly, nastavte na nenulové číslo. |
| metricProgramProvider | Nastavte ho na CLSID zprostředkovatele programu. |
| metricAlwaysLoadProgramProviderLocal | Nastavte tuto hodnotu na nenulu a označte, že zprostředkovatel programu by měl být vždy načten místně. |
| metricEngineCanWatchProcess | Nastavte tuto hodnotu na nenulu a označte, že ladicí modul bude sledovat události procesu místo zprostředkovatele programu. |
| Ladění metricRemote | Nastavte tuto hodnotu na nenulové, aby označí podporu vzdáleného ladění. |
| metricEncUseNativeBuilder | Nastavte tuto hodnotu na nenulovou, aby bylo možné určit, že Správce úprav a pokračování by měl použít ladicí modul encbuild.dll k sestavení pro upravit a pokračovat. Poznámka: Vlastní ladicí modul by nikdy neměl toto nastavení nastavit nebo by ho měl vždy nastavit na hodnotu 0. |
| metricLoadUnderWOW64 | Nastavte tuto hodnotu na nenulovou, aby bylo zřejmé, že ladicí modul by měl být načten v procesu ladění v rámci WOW při ladění 64bitového procesu; v opačném případě se ladicí modul načte v procesu sady Visual Studio (který běží pod WOW64). |
| metricLoadProgramProviderUnderWOW64 | Nastavte tuto hodnotu na nenulovou, aby se při ladění 64bitového procesu pod WOW načetl zprostředkovatel programu. jinak se načte v procesu sady Visual Studio. |
| metricStopOnExceptionCrossingManagedBoundary | Nastavte tuto hodnotu na nenulovou hodnotu, aby se proces zastavil, pokud dojde k neošetřené výjimce napříč spravovanými nebo nespravovanými hranicemi kódu. |
| metricAutoSelectPriority | Nastavte tuto možnost na prioritu automatického výběru ladicího modulu (vyšší hodnoty se rovná vyšší prioritě). |
| metricAutoSelectIncompatibleList | Klíč registru obsahující položky, které určují identifikátory GUID pro ladicí moduly, které se mají v automatickém výběru ignorovat. Tyto položky jsou číslo (0, 1, 2 atd.) s identifikátorem GUID vyjádřeným jako řetězec. |
| metricIncompatibleList | Klíč registru obsahující položky, které určují identifikátory GUID pro ladicí moduly, které nejsou kompatibilní s tímto ladicím modulem. |
| metricDisableJITOptimization | Nastavte tuto hodnotu na nenulovou, aby se při ladění zakázaly optimalizace za běhu (pro spravovaný kód). |
| Vlastnosti vyhodnocovače výrazů | Popis |
|---|---|
| metricEngine | To obsahuje počet ladicích modulů, které podporují zadaný vyhodnocovací modul výrazu. |
| metricPreloadModules | Nastavte tuto hodnotu na nenulovou, aby se označovaly, že moduly by se měly předem načíst při spuštění vyhodnocovače výrazů v programu. |
| metricThisObjectName | Nastavte ho na název objektu "this". |
| Vlastnosti rozšíření vyhodnocovače výrazů | Popis |
|---|---|
| metricExtensionDll | Název knihovny DLL, která podporuje toto rozšíření. |
| metricExtensionRegistersSupported | Seznam podporovaných registrů |
| metricExtensionRegistersEntryPoint | Vstupní bod pro přístup k registrům. |
| metricExtensionTypesSupported | Seznam podporovaných typů |
| metricExtensionTypesEntryPoint | Vstupní bod pro přístup k typům |
| Vlastnosti dodavatele portu | Popis |
|---|---|
| metricPortPickerCLSID | CLSID nástroje pro výběr portů (dialogové okno, které uživatel může použít k výběru portů a přidání portů pro ladění). |
| metricDisallowUserEnteredPorts | Nenulové, pokud uživatelem zadané porty nelze přidat do dodavatele portu (to způsobí, že dialogové okno pro výběr portů je v podstatě jen pro čtení). |
| metricPidBase | ID základního procesu používané dodavatelem portu při přidělování ID procesů. |
| Předdefinované typy úložiště SP | Popis |
|---|---|
| storetypeFile | Symboly jsou uloženy v samostatném souboru. |
| storetypeMetadata | Symboly jsou uloženy jako metadata v sestavení. |
| Různé vlastnosti | Popis |
|---|---|
| metricShowNonUserCode | Nastavte na nenulový, aby se zobrazil kód uživatele. |
| metricJustMyCodeStepping | Nastavte tuto hodnotu na nenulu, aby bylo možné označit, že krokování může nastat pouze v uživatelském kódu. |
| metricCLSID | CLSID pro objekt konkrétního typu metriky. |
| metricName | Uživatelsky přívětivý název objektu konkrétního typu metriky. |
| metricLanguage | Název jazyka. |
Umístění registru
Metriky se čtou a zapisují do registru, konkrétně v podklíči VisualStudio .
Poznámka:
Ve většině případů se metriky zapíšou do HKEY_LOCAL_MACHINE klíče. Někdy ale HKEY_CURRENT_USER bude cílovým klíčem. Dbgmetric.lib zpracovává oba klíče. Při získávání metriky se nejprve prohledá HKEY_CURRENT_USER a pak HKEY_LOCAL_MACHINE. Když nastavujete metriku, parametr určuje, který klíč nejvyšší úrovně se má použít.
[klíč registru]\
Software\
Microsoft\
VisualStudio\
[kořen verze]\
[kořen metriky]\
[typ metriky]\
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
| Zástupný symbol | Popis |
|---|---|
| [klíč registru] | HKEY_CURRENT_USER nebo HKEY_LOCAL_MACHINE. |
| [kořen verze] | Verze sady Visual Studio (například 7.0, 7.1nebo 8.0). Tento kořenový adresář však lze také upravit pomocí přepínače /rootsuffix na devenv.exe. U VSIP je tento modifikátor obvykle Exp, takže kořen verze by byl například 8.0Exp. |
| [kořen metriky] | To je buď AD7Metrics nebo AD7Metrics(Debug), v závislosti na tom, jestli se používá ladicí verze dbgmetric.lib. Poznámka: Jestli se používá dbgmetric.lib, měla by být tato konvence vytváření názvů dodržena, pokud máte rozdíly mezi verzí ladění a verzí, které se musí promítnout do registru. |
| [typ metriky] | Typ metriky, která má být zapsána: Engine, ExpressionEvaluator, SymbolProvideratd. Všechny jsou definovány jako v dbgmetric.h jako metricTypeXXXX, kde XXXX je konkrétní název typu. |
| [metrika] | Název položky, která se má přiřadit k hodnotě, aby se nastavil metrika. Skutečná organizace metrik závisí na typu metriky. |
| [hodnota metriky] | Hodnota přiřazená k metrice. Typ, který má mít hodnota (řetězec, číslo atd.), závisí na metrice. |
Poznámka:
Všechny identifikátory GUID jsou uloženy ve formátu {GUID}. Například {123D150B-FA18-461C-B218-45B3E4589F9B}.
Ladicí moduly
Následuje organizace metrik ladicího modulu v registru. Engine je název typu metriky pro ladicí modul a odpovídá [typu metriky] ve výše uvedeném podstromu registru.
Engine\
[guid motoru]\
CLSID = [guid třídy]
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
PortSupplier\
0 = [identifikátor GUID dodavatele portu]
1 = [identifikátor GUID dodavatele portu]
| Zástupný symbol | Popis |
|---|---|
| [guid motoru] | Identifikátor GUID ladicího modulu. |
| [guid třídy] | IDENTIFIKÁTOR GUID třídy, která implementuje tento ladicí modul. |
| [identifikátor GUID dodavatele portu] | Identifikátor GUID dodavatele portu, pokud existuje. Mnoho ladicí moduly používají výchozího dodavatele portů, a proto nezadávají vlastního dodavatele. V tomto případě chybí podklíč PortSupplier . |
Dodavatelé portů
Následuje organizace metrik dodavatele portů v registru. PortSupplier je název typu metriky pro dodavatele portu a odpovídá [typu metriky].
PortSupplier\
[identifikátor GUID dodavatele portu]\
CLSID = [guid třídy]
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
| Zástupný symbol | Popis |
|---|---|
| [identifikátor GUID dodavatele portu] | Identifikátor GUID dodavatele portu |
| [guid třídy] | Identifikátor GUID třídy, která implementuje tohoto dodavatele portu |
Zprostředkovatelé symbolů
Následuje uspořádání metrik dodavatelů symbolů v registru. SymbolProviderje název typu metriky pro zprostředkovatele symbolů a odpovídá [typu metriky].
SymbolProvider\
[guid zprostředkovatele symbolů]\
file\
CLSID = [guid třídy]
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
metadata\
CLSID = [guid třídy]
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
| Zástupný symbol | Popis |
|---|---|
| [guid zprostředkovatele symbolů] | Identifikátor GUID zprostředkovatele symbolů |
| [guid třídy] | IDENTIFIKÁTOR GUID třídy, která implementuje tohoto zprostředkovatele symbolů |
Vyhodnocovače výrazů
Následuje uspořádání metrik vyhodnocovače výrazů v registru. ExpressionEvaluator je název typu metriky pro vyhodnocovače výrazů a odpovídá [typu metriky].
Poznámka:
Typ ExpressionEvaluator metriky není definován v dbgmetric.h, protože se předpokládá, že všechny změny metrik pro vyhodnocovače výrazů projdou příslušnými funkcemi vyhodnocovače výrazů (rozložení ExpressionEvaluator podklíče je poněkud složité, takže podrobnosti jsou skryté uvnitř dbgmetric.lib).
ExpressionEvaluator\
[identifikátor GUID jazyka]\
[guid dodavatele]\
CLSID = [guid třídy]
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
Engine\
0 = [guid ladicího stroje]
1 = [guid ladicího stroje]
| Zástupný symbol | Popis |
|---|---|
| [identifikátor GUID jazyka] | Identifikátor GUID jazyka |
| [guid dodavatele] | Identifikátor GUID dodavatele |
| [guid třídy] | IDENTIFIKÁTOR GUID třídy, která implementuje tento vyhodnocovače výrazů |
| [guid ladicího stroje] | Identifikátor GUID ladicího modulu, se kterým tento vyhodnocovače výrazů pracuje |
Rozšíření vyhodnocovače výrazů
Následuje uspořádání metrik rozšíření vyhodnocovače výrazů v registru. EEExtensions je název typu metriky pro rozšíření vyhodnocovače výrazů a odpovídá [typu metriky].
EEExtensions\
[guid rozšíření]\
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
| Zástupný symbol | Popis |
|---|---|
| [guid rozšíření] | Identifikátor GUID rozšíření vyhodnocovače výrazů |
Výjimky
Následuje uspořádání metrik výjimek v registru. Exception je název typu metriky pro výjimky a odpovídá [typu metriky].
Exception\
[guid ladicího stroje]\
[Typy výjimek]\
[výjimka]\
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
[výjimka]\
[metrika] = [hodnota metriky]
[metrika] = [hodnota metriky]
| Zástupný symbol | Popis |
|---|---|
| [guid ladicího stroje] | Identifikátor GUID ladicího modulu, který podporuje výjimky. |
| [Typy výjimek] | Obecný název podklíče identifikující třídu výjimek, které lze zpracovat. Typické názvy jsou výjimky C++, výjimky Win32, výjimky modulu CLR (Common Language Runtime) a nativní kontroly za běhu. Tyto názvy se také používají k identifikaci konkrétní třídy výjimky pro uživatele. |
| [výjimka] | Název výjimky: například _com_error nebo Control-Break. Tyto názvy slouží také k identifikaci konkrétní výjimky pro uživatele. |
Požadavky
Tyto soubory se nacházejí v instalačním adresáři sady Microsoft Visual Studio 2010 SDK (ve výchozím nastavení [ jednotka]\Program Files\Microsoft Visual Studio 2010 SDK\).
Hlavička: includes\dbgmetric.h
Knihovna: libs\ad2de.lib, libs\dbgmetric.lib