Pomocnicy zestawu SDK do debugowania
Te funkcje i deklaracje to globalne funkcje pomocnicze do implementowania aparatów debugowania, ewaluatorów wyrażeń i dostawców symboli w języku C++.
Uwaga
Obecnie nie ma zarządzanych wersji tych funkcji i deklaracji.
Aby aparaty debugowania, ewaluatory wyrażeń i dostawcy symboli były używane przez program Visual Studio, muszą być zarejestrowane. Można to zrobić, ustawiając podklucze i wpisy rejestru, inaczej nazywane "ustawianiem metryk". Następujące funkcje globalne zostały zaprojektowane w celu ułatwienia procesu aktualizowania tych metryk. Zobacz sekcję dotyczącą lokalizacji rejestru, aby dowiedzieć się, jak układ każdego podklucza rejestru jest aktualizowany przez te funkcje.
Ogólne funkcje metryk
Są to ogólne funkcje używane przez aparaty debugowania. Wyspecjalizowane funkcje dla ewaluatorów wyrażeń i dostawców symboli są szczegółowo opisane w dalszej części.
GetMetric, metoda
Pobiera wartość metryki z rejestru.
HRESULT GetMetric(
LPCWSTR pszMachine,
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
DWORD * pdwValue,
LPCWSTR pszAltRoot
);
| Parametr | Opis |
|---|---|
| pszMachine | [in] Nazwa maszyny zdalnej, której rejestr zostanie zapisany (NULL oznacza maszynę lokalną). |
| pszType | [in] Jeden z typów metryk. |
| guidSection | [in] Identyfikator GUID określonego aparatu, ewaluatora, wyjątku itp. Określa podsekcję pod typem metryki dla określonego elementu. |
| pszMetric | [in] Metryka do uzyskania. Odpowiada to określonej nazwie wartości. |
| pdwValue | [in] Lokalizacja magazynu wartości z metryki. Istnieje kilka odmian getmetric, które mogą zwrócić DWORD (jak w tym przykładzie), BSTR, identyfikator GUID lub tablicę identyfikatorów GUID. |
| pszAltRoot | [in] Alternatywny katalog główny rejestru do użycia. Ustaw wartość na , aby NULL użyć wartości domyślnej. |
SetMetric, metoda
Ustawia określoną wartość metryki w rejestrze.
HRESULT SetMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
const DWORD dwValue,
bool fUserSpecific,
LPCWSTR pszAltRoot
);
| Parametr | Opis |
|---|---|
| pszType | [in] Jeden z typów metryk. |
| guidSection | [in] Identyfikator GUID określonego aparatu, ewaluatora, wyjątku itp. Określa podsekcję pod typem metryki dla określonego elementu. |
| pszMetric | [in] Metryka do uzyskania. Odpowiada to określonej nazwie wartości. |
| dwValue | [in] Lokalizacja magazynu wartości w metryce. Istnieje kilka odmian setmetric, które mogą przechowywać DWORD (w tym przykładzie), BSTR, identyfikator GUID lub tablicę identyfikatorów GUID. |
| fUserSpecific | [in] Wartość TRUE, jeśli metryka jest specyficzna dla użytkownika i jeśli powinna zostać zapisana w gałęzi użytkownika zamiast gałęzi komputera lokalnego. |
| pszAltRoot | [in] Alternatywny katalog główny rejestru do użycia. Ustaw wartość na , aby NULL użyć wartości domyślnej. |
RemoveMetric, metoda
Usuwa metryki z rejestru.
HRESULT RemoveMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
LPCWSTR pszAltRoot
);
| Parametr | Opis |
|---|---|
| pszType | [in] Jeden z typów metryk. |
| guidSection | [in] Identyfikator GUID określonego aparatu, ewaluatora, wyjątku itp. Określa podsekcję pod typem metryki dla określonego elementu. |
| pszMetric | [in] Metryka do usunięcia. Odpowiada to określonej nazwie wartości. |
| pszAltRoot | [in] Alternatywny katalog główny rejestru do użycia. Ustaw wartość na , aby NULL użyć wartości domyślnej. |
EnumMetricSections, metoda
Wylicza różne sekcje metryk w rejestrze.
HRESULT EnumMetricSections(
LPCWSTR pszMachine,
LPCWSTR pszType,
GUID * rgguidSections,
DWORD * pdwSize,
LPCWSTR pszAltRoot
);
| Parametr | Opis |
|---|---|
| pszMachine | [in] Nazwa maszyny zdalnej, której rejestr zostanie zapisany (NULL oznacza maszynę lokalną). |
| pszType | [in] Jeden z typów metryk. |
| rgguidSections | [in, out] Wstępnie alokowana tablica identyfikatorów GUID do wypełnienia. |
| pdwSize | [in] Maksymalna liczba identyfikatorów GUID, które można przechowywać w tablicy rgguidSections . |
| pszAltRoot | [in] Alternatywny katalog główny rejestru do użycia. Ustaw wartość na , aby NULL użyć wartości domyślnej. |
Funkcje ewaluatora wyrażeń
| Function | opis |
|---|---|
| GetEEMetric | Pobiera wartość metryki z rejestru. |
| SetEEMetric | Ustawia określoną wartość metryki w rejestrze. |
| RemoveEEMetric | Usuwa metryki z rejestru. |
| GetEEMetricFile | Pobiera nazwę pliku z określonej metryki i ładuje ją, zwracając zawartość pliku jako ciąg. |
Funkcje wyjątków
| Function | opis |
|---|---|
| GetExceptionMetric | Pobiera wartość metryki z rejestru. |
| SetExceptionMetric | Ustawia określoną wartość metryki w rejestrze. |
| RemoveExceptionMetric | Usuwa metryki z rejestru. |
| RemoveAllExceptionMetrics | Usuwa wszystkie metryki wyjątków z rejestru. |
Funkcje dostawcy symboli
| Function | opis |
|---|---|
| GetSPMetric | Pobiera wartość metryki z rejestru. |
| SetSPMetric | Ustawia określoną wartość metryki w rejestrze. |
| RemoveSPMetric | Usuwa metryki z rejestru. |
Funkcje wyliczenia
| Function | opis |
|---|---|
| EnumMetricSections | Wylicza wszystkie metryki dla określonego typu metryki. |
| EnumDebugEngine | Wylicza zarejestrowane aparaty debugowania. |
| EnumEEs | Wylicza zarejestrowanych ewaluatorów wyrażeń. |
| EnumExceptionMetrics | Wylicza wszystkie metryki wyjątków. |
Definicje metryk
Te definicje mogą służyć do wstępnie zdefiniowanych nazw metryk. Nazwy odpowiadają różnym kluczom rejestru i nazwom wartości i są definiowane jako ciągi znaków szerokich: na przykład extern LPCWSTR metrictypeEngine.
| Wstępnie zdefiniowane typy metryk | Opis: Klucz podstawowy dla.... |
|---|---|
| metrictypeEngine | Wszystkie metryki aparatu debugowania. |
| metrictypePortSupplier | Wszystkie metryki dostawcy portów. |
| metrictypeException | Wszystkie metryki wyjątków. |
| metricttypeEEExtension | Wszystkie rozszerzenia ewaluatora wyrażeń. |
| Właściwości aparatu debugowania | opis |
|---|---|
| metricAddressBP | Ustaw wartość nonzero, aby wskazać obsługę punktów przerwania adresów. |
| metricAlwaysLoadLocal | Ustaw wartość nonzero, aby zawsze ładować aparat debugowania lokalnie. |
| metricLoadInDebuggeeSession | NIEUŻYWANE |
| metricLoadedByDebuggee | Ustaw wartość nonzero, aby wskazać, że aparat debugowania będzie zawsze ładowany z debugowaniem lub przez debugowany program. |
| metricAttach | Ustaw wartość nonzero, aby wskazać obsługę załącznika do istniejących programów. |
| metricCallStackBP | Ustaw wartość nonzero, aby wskazać obsługę punktów przerwania stosu wywołań. |
| metricConditionalBP | Ustaw wartość nonzero, aby wskazać obsługę ustawienia warunkowych punktów przerwania. |
| metricDataBP | Ustaw wartość nonzero, aby wskazać obsługę ustawienia punktów przerwania dla zmian w danych. |
| metricDisassembly | Ustaw wartość nonzero, aby wskazać obsługę produkcji listy dezasemblacji. |
| metricDumpWriting | Ustaw wartość nonzero, aby wskazać obsługę zapisywania zrzutu (zrzut pamięci do urządzenia wyjściowego). |
| metrykaENC | Ustaw wartość nonzero, aby wskazać obsługę opcji Edytuj i Kontynuuj. Uwaga: niestandardowy aparat debugowania nigdy nie powinien ustawiać tego ustawienia lub zawsze powinien ustawić go na 0. |
| metricExceptions | Ustaw wartość nonzero, aby wskazać obsługę wyjątków. |
| metricFunctionBP | Ustaw wartość nonzero, aby wskazać obsługę nazwanych punktów przerwania (punkty przerwania, które przerywają działanie po wywołaniu określonej nazwy funkcji). |
| metricHitCountBP | Ustaw wartość nonzero, aby wskazać obsługę ustawienia punktów przerwania "punkt trafienia" (punkty przerwania, które są wyzwalane tylko po osiągnięciu określonej liczby razy). |
| metricJITDebug | Ustaw wartość nonzero, aby wskazać obsługę debugowania just in time (debuger jest uruchamiany, gdy wyjątek występuje w uruchomionym procesie). |
| metricMemory | NIEUŻYWANE |
| metricPortSupplier | Ustaw wartość parametru CLSID dostawcy portów, jeśli jest wdrożony. |
| metricRegisters | NIEUŻYWANE |
| metricSetNextStatement | Ustaw wartość nonzero, aby wskazać obsługę ustawienia następnej instrukcji (która pomija wykonywanie instrukcji pośrednich). |
| metricSuspendThread | Ustaw wartość nonzero, aby wskazać obsługę wstrzymania wykonywania wątku. |
| metricWarnIfNoSymbols | Ustaw wartość nonzero, aby wskazać, że użytkownik powinien być powiadamiany, jeśli nie ma żadnych symboli. |
| metricProgramProvider | Ustaw tę wartość na clSID dostawcy programu. |
| metricAlwaysLoadProgramProviderLocal | Ustaw tę wartość na wartość nonzero, aby wskazać, że dostawca programu powinien być zawsze ładowany lokalnie. |
| metricEngineCanWatchProcess | Ustaw tę wartość na wartość nonzero, aby wskazać, że aparat debugowania będzie obserwować zdarzenia procesu zamiast dostawcy programu. |
| metricRemoteDebugging | Ustaw tę wartość na wartość nonzero, aby wskazać obsługę zdalnego debugowania. |
| metricEncUseNativeBuilder | Ustaw tę wartość na wartość nonzero, aby wskazać, że Menedżer edycji i kontynuowania powinien używać biblioteki encbuild.dll aparatu debugowania do kompilacji na potrzeby edycji i kontynuowania. Uwaga: niestandardowy aparat debugowania nigdy nie powinien ustawiać tego ustawienia lub zawsze powinien ustawić go na 0. |
| metricLoadUnderWOW64 | Ustaw tę wartość na wartość nonzero, aby wskazać, że aparat debugowania powinien zostać załadowany w procesie debugowania w obszarze WOW podczas debugowania procesu 64-bitowego; W przeciwnym razie aparat debugowania zostanie załadowany w procesie programu Visual Studio (uruchomionym w obszarze WOW64). |
| metricLoadProgramProviderUnderWOW64 | Ustaw tę wartość na wartość niezerową, aby wskazać, że dostawca programu powinien zostać załadowany w procesie debugowania podczas debugowania procesu 64-bitowego w obszarze WOW; w przeciwnym razie zostanie załadowany w procesie programu Visual Studio. |
| metricStopOnExceptionCrossingManagedBoundary | Ustaw tę wartość na wartość nonzero, aby wskazać, że proces powinien zostać zatrzymany, jeśli nieobsługiwany wyjątek zostanie zgłoszony przez granice kodu zarządzanego/niezarządzanego. |
| metricAutoSelectPriority | Ustaw ten priorytet na automatyczny wybór aparatu debugowania (wyższe wartości są równe wyższym priorytetowi). |
| metricAutoSelectIncompatibleList | Klucz rejestru zawierający wpisy, które określają identyfikatory GUID dla aparatów debugowania, które mają być ignorowane w automatycznym zaznaczeniu. Te wpisy są liczbą (0, 1, 2 itd.) z identyfikatorem GUID wyrażonym jako ciąg. |
| metricIncompatibleList | Klucz rejestru zawierający wpisy określające identyfikatory GUID dla aparatów debugowania, które są niezgodne z tym aparatem debugowania. |
| metricDisableJITOptimization | Ustaw tę wartość na wartość nonzero, aby wskazać, że optymalizacje just in time (dla kodu zarządzanego) powinny być wyłączone podczas debugowania. |
| Właściwości ewaluatora wyrażeń | opis |
|---|---|
| metricEngine | Obejmuje to liczbę aparatów debugowania, które obsługują określonego ewaluatora wyrażeń. |
| metricPreloadModules | Ustaw tę wartość na wartość nonzero, aby wskazać, że moduły powinny zostać wstępnie załadowane po uruchomieniu ewaluatora wyrażeń względem programu. |
| metricThisObjectName | Ustaw tę wartość na nazwę obiektu "this". |
| Właściwości rozszerzenia ewaluatora wyrażeń | opis |
|---|---|
| metricExtensionDll | Nazwa biblioteki DLL, która obsługuje to rozszerzenie. |
| metricExtensionRegistersSupported | Lista obsługiwanych rejestrów. |
| metricExtensionRegistersEntryPoint | Punkt wejścia na potrzeby uzyskiwania dostępu do rejestrów. |
| metricExtensionTypesSupported | Lista obsługiwanych typów. |
| metricExtensionTypesEntryPoint | Punkt wejścia na potrzeby uzyskiwania dostępu do typów. |
| Właściwości dostawcy portów | opis |
|---|---|
| metricPortPickerCLSID | Identyfikator CLSID selektora portów (okno dialogowe, za pomocą których użytkownik może wybrać porty i dodać porty do użycia do debugowania). |
| metricDisallowUserEnteredPorts | Niezero, jeśli nie można dodać portów wprowadzonych przez użytkownika do dostawcy portów (powoduje to, że okno dialogowe selektora portów jest zasadniczo tylko do odczytu). |
| metricPidBase | Podstawowy identyfikator procesu używany przez dostawcę portów podczas przydzielania identyfikatorów procesów. |
| Wstępnie zdefiniowane typy magazynów SP | opis |
|---|---|
| storetypeFile | Symbole są przechowywane w osobnym pliku. |
| storetypeMetadata | Symbole są przechowywane jako metadane w zestawie. |
| Różne właściwości | opis |
|---|---|
| metricShowNonUserCode | Ustaw tę wartość na wartość nonzero, aby wyświetlić kod nieużytkownika. |
| metricJustMyCodeStepping | Ustaw tę wartość na wartość nonzero, aby wskazać, że kroki mogą wystąpić tylko w kodzie użytkownika. |
| metricCLSID | CLSID dla obiektu określonego typu metryki. |
| metricName | Przyjazna dla użytkownika nazwa obiektu określonego typu metryki. |
| metricLanguage | Nazwa języka. |
Lokalizacje rejestru
Metryki są odczytywane i zapisywane w rejestrze, w szczególności w podkluczu VisualStudio .
Uwaga
W większości przypadków metryki zostaną zapisane w kluczu HKEY_LOCAL_MACHINE. Jednak czasami HKEY_CURRENT_USER będzie kluczem docelowym. Plik Dbgmetric.lib obsługuje oba klucze. Podczas pobierania metryki najpierw wyszukuje HKEY_CURRENT_USER, a następnie HKEY_LOCAL_MACHINE. Podczas ustawiania metryki parametr określa klucz najwyższego poziomu do użycia.
[klucz rejestru]\
Software\
Microsoft\
VisualStudio\
[wersja główna]\
[katalog główny metryki]\
[typ metryki]\
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
| Symbol zastępczy | opis |
|---|---|
| [klucz rejestru] | Usługa HKEY_CURRENT_USER lub HKEY_LOCAL_MACHINE. |
| [wersja główna] | Wersja programu Visual Studio (na przykład , 7.0, 7.1lub 8.0). Ten katalog główny można jednak również zmodyfikować za pomocą przełącznika /rootsuffix w pliku devenv.exe. W przypadku programu VSIP ten modyfikator jest zazwyczaj exp, więc katalog główny wersji to na przykład 8.0Exp. |
| [katalog główny metryki] | Jest to wartość AD7Metrics lub AD7Metrics(Debug), w zależności od tego, czy używana jest wersja debugowania dbgmetric.lib. Uwaga: Niezależnie od tego, czy jest używana biblioteka dbgmetric.lib, ta konwencja nazewnictwa powinna być zgodna, jeśli masz różnice między wersjami debugowania i wydania, które muszą zostać odzwierciedlone w rejestrze. |
| [typ metryki] | Typ metryki do zapisania: Engine, ExpressionEvaluator, SymbolProvideritp. Są one zdefiniowane jako w dbgmetric.h jako metricTypeXXXX, gdzie XXXX jest określoną nazwą typu. |
| [metryka] | Nazwa wpisu, który ma zostać przypisany do wartości w celu ustawienia metryki. Rzeczywista organizacja metryk zależy od typu metryki. |
| [wartość metryki] | Wartość przypisana do metryki. Typ wartości powinien mieć wartość (ciąg, liczba itp.) zależy od metryki. |
Uwaga
Wszystkie identyfikatory GUID są przechowywane w formacie {GUID}. Na przykład {123D150B-FA18-461C-B218-45B3E4589F9B}.
Aparaty debugowania
Poniżej przedstawiono organizację metryk aparatów debugowania w rejestrze. Engine to nazwa typu metryki aparatu debugowania i odpowiada [typowi metryki] w powyższym poddrzewie rejestru.
Engine\
[identyfikator GUID aparatu]\
CLSID = [identyfikator GUID klasy]
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
PortSupplier\
0 = [identyfikator GUID dostawcy portów]
1 = [identyfikator GUID dostawcy portów]
| Symbol zastępczy | opis |
|---|---|
| [identyfikator GUID aparatu] | Identyfikator GUID aparatu debugowania. |
| [identyfikator GUID klasy] | Identyfikator GUID klasy, która implementuje ten aparat debugowania. |
| [identyfikator GUID dostawcy portów] | Identyfikator GUID dostawcy portów, jeśli istnieje. Wiele aparatów debugowania używa domyślnego dostawcy portów i dlatego nie określa własnego dostawcy. W takim przypadku podklucz PortSupplier będzie nieobecny. |
Dostawcy portów
Poniżej przedstawiono organizację metryk dostawcy portów w rejestrze. PortSupplier to nazwa typu metryki dostawcy portów i odpowiada [typowi metryki].
PortSupplier\
[identyfikator GUID dostawcy portów]\
CLSID = [identyfikator GUID klasy]
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
| Symbol zastępczy | opis |
|---|---|
| [identyfikator GUID dostawcy portów] | Identyfikator GUID dostawcy portów |
| [identyfikator GUID klasy] | Identyfikator GUID klasy implementujący tego dostawcę portów |
Dostawcy symboli
Poniżej przedstawiono organizację metryk dostawcy symboli w rejestrze. SymbolProvider to nazwa typu metryki dostawcy symboli i odpowiada [typowi metryki].
SymbolProvider\
[identyfikator GUID dostawcy symboli]\
file\
CLSID = [identyfikator GUID klasy]
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
metadata\
CLSID = [identyfikator GUID klasy]
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
| Symbol zastępczy | opis |
|---|---|
| [identyfikator GUID dostawcy symboli] | Identyfikator GUID dostawcy symboli |
| [identyfikator GUID klasy] | Identyfikator GUID klasy implementujący tego dostawcę symboli |
Ewaluatory wyrażeń
Poniżej przedstawiono organizację metryk ewaluatora wyrażeń w rejestrze. ExpressionEvaluator to nazwa typu metryki dla ewaluatora wyrażeń i odpowiada [typowi metryki].
Uwaga
Typ metryki dla ExpressionEvaluator elementu nie jest zdefiniowany w pliku dbgmetric.h, ponieważ zakłada się, że wszystkie zmiany metryk dla ewaluatorów wyrażeń będą przechodzić przez odpowiednie funkcje metryki ewaluatora wyrażeń (układ ExpressionEvaluator podklucza jest nieco skomplikowany, więc szczegóły są ukryte wewnątrz dbgmetric.lib).
ExpressionEvaluator\
[identyfikator GUID języka]\
[identyfikator GUID dostawcy]\
CLSID = [identyfikator GUID klasy]
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
Engine\
0 = [identyfikator GUID aparatu debugowania]
1 = [identyfikator GUID aparatu debugowania]
| Symbol zastępczy | opis |
|---|---|
| [identyfikator GUID języka] | Identyfikator GUID języka |
| [identyfikator GUID dostawcy] | Identyfikator GUID dostawcy |
| [identyfikator GUID klasy] | Identyfikator GUID klasy implementujący ten ewaluator wyrażeń |
| [identyfikator GUID aparatu debugowania] | Identyfikator GUID aparatu debugowania współdziałający z tym ewaluatorem wyrażeń |
Rozszerzenia ewaluatora wyrażeń
Poniżej przedstawiono organizację metryk rozszerzenia ewaluatora wyrażeń w rejestrze. EEExtensions to nazwa typu metryki dla rozszerzeń ewaluatora wyrażeń i odpowiada [typowi metryki].
EEExtensions\
[extension guid]\
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
| Symbol zastępczy | opis |
|---|---|
| [extension guid] | Identyfikator GUID rozszerzenia ewaluatora wyrażeń |
Wyjątki
Poniżej przedstawiono organizację metryk wyjątków w rejestrze. Exception to nazwa typu metryki dla wyjątków i odpowiada [typowi metryki].
Exception\
[identyfikator GUID aparatu debugowania]\
[typy wyjątków]\
[wyjątek]\
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
[wyjątek]\
[metryka] = [wartość metryki]
[metryka] = [wartość metryki]
| Symbol zastępczy | opis |
|---|---|
| [identyfikator GUID aparatu debugowania] | Identyfikator GUID aparatu debugowania, który obsługuje wyjątki. |
| [typy wyjątków] | Ogólny tytuł podklucza identyfikujący klasę wyjątków, które można obsłużyć. Typowe nazwy to wyjątki języka C++, wyjątki Win32, wyjątki środowiska uruchomieniowego języka wspólnego i natywne testy czasu wykonywania. Te nazwy są również używane do identyfikowania konkretnej klasy wyjątku dla użytkownika. |
| [wyjątek] | Nazwa wyjątku: na przykład _com_error lub Break-Break. Te nazwy są również używane do identyfikowania określonego wyjątku dla użytkownika. |
Wymagania
Te pliki znajdują się w katalogu instalacyjnym zestawu SDK programu Microsoft Visual Studio 2010 (domyślnie [dysk]\Program Files\Microsoft Visual Studio 2010 SDK\).
Nagłówek: includes\dbgmetric.h
Biblioteka: libs\ad2de.lib, libs\dbgmetric.lib