Korzystanie z SymStore

SymStore (symstore.exe) to narzędzie do tworzenia magazynów symboli. Znajduje się on w pakiecie Narzędzia debugowania dla systemu Windows.

SymStore przechowuje symbole w formacie, który umożliwia debugerowi wyszukiwanie symboli na podstawie sygnatury czasowej i rozmiaru obrazu (dla pliku dbg lub pliku wykonywalnego) lub sygnatury i wieku (dla pliku pdb). Zaletą magazynu symboli nad tradycyjnym formatem przechowywania symboli jest to, że wszystkie symbole mogą być przechowywane lub odnajdywane na tym samym serwerze i pobierane przez debugger bez konieczności posiadania wcześniejszej wiedzy, który produkt zawiera odpowiedni symbol.

Należy pamiętać, że na tym samym serwerze nie można przechowywać wielu wersji plików symboli .pdb (na przykład publicznych i prywatnych), ponieważ każdy z nich zawiera ten sam podpis i wiek.

Transakcje magazynu SymStore

Każde wywołanie usługi SymStore jest rejestrowane jako transakcja. Istnieją dwa typy transakcji: dodawanie i usuwanie.

Po utworzeniu magazynu symboli zostanie utworzony katalog o nazwie "000admin" w katalogu głównym serwera. Katalog 000admin zawiera jeden plik dla każdej transakcji, a także pliki dziennika Server.txt i History.txt. Plik Server.txt zawiera listę wszystkich transakcji, które znajdują się obecnie na serwerze. Plik History.txt zawiera chronologiczną historię wszystkich transakcji.

Za każdym razem, gdy program SymStore przechowuje lub usuwa pliki symboli, tworzony jest nowy numer transakcji. Następnie plik, którego nazwa to ten numer transakcji, jest tworzony w 000admin. Ten plik zawiera listę wszystkich plików lub wskaźników, które zostały dodane do magazynu symboli podczas tej transakcji. Jeśli transakcja zostanie usunięta, usługa SymStore odczytuje plik transakcji, aby określić, które pliki i wskaźniki powinny zostać usunięte.

Opcje dodaj i usuń określają, czy ma zostać wykonana transakcja dodawania lub usuwania. Dołączenie opcji /p z operacją dodawania określa, że wskaźnik ma zostać dodany; Pominięcie opcji /p określa, że ma zostać dodany rzeczywisty plik symboli.

Istnieje również możliwość utworzenia magazynu symboli w dwóch oddzielnych etapach. W pierwszym etapie użyjesz narzędzia SymStore z opcją /x, aby utworzyć plik indeksu. W drugim etapie używasz SymStore z opcją /y, aby utworzyć rzeczywisty magazyn plików lub wskaźników na podstawie informacji zawartych w pliku indeksu.

Może to być przydatna technika z różnych powodów. Na przykład umożliwia to łatwe odtworzenie magazynu symboli, jeśli magazyn zostanie w jakiś sposób utracony, o ile plik indeksu nadal istnieje. A może komputer zawierający pliki symboli ma powolne połączenie sieciowe z komputerem, na którym zostanie utworzony magazyn symboli. W takim przypadku można utworzyć plik indeksu na tej samej maszynie co pliki symboli, przenieść plik indeksu na drugą maszynę, a następnie utworzyć magazyn na drugiej maszynie.

Aby uzyskać pełną listę wszystkich parametrów SymStore, zobacz SymStore Command-Line Options.

Uwaga

Usługa SymStore nie obsługuje równoczesnych transakcji od wielu użytkowników. Zaleca się wyznaczenie jednego użytkownika jako "administratora" magazynu symboli i odpowiedzialnego za wszystkie transakcje dodawania i usuwania.

 

Przykłady transakcji

Oto dwa przykłady dodawania wskaźników symboli dla kompilacji 3790 systemu Windows Server 2003 do \\sampledir\symsrv:

symstore add /r /p /f \\BuildServer\BuildShare\3790free\symbols\*.*
   /s \\sampledir\symsrv /t "Windows Server 2003" /v "Build 3790 x86 free"
   /c "Sample add"
symstore add /r /p /f \\BuildServer\BuildShare\3790Chk\symbols\*.* 
   /s \\sampledir\symsrv /t "Windows Server 2003" /v "Build 3790 x86 checked"
   /c "Sample add"

W poniższym przykładzie usługa SymStore dodaje rzeczywiste pliki symboli dla projektu aplikacji w folderze \\largeapp\appserver\bins do folderu \\testdir\symsrv:

symstore add /r /f \\largeapp\appserver\bins\*.* /s \\testdir\symsrv 
   /t "Large Application" /v "Build 432" /c "Sample add"

Oto przykład użycia pliku indeksu. Najpierw usługa SymStore tworzy plik indeksu na podstawie kolekcji plików symboli w folderze \\largeapp\appserver\bins\. W takim przypadku plik indeksu jest umieszczany na trzecim komputerze \\hubserver\hubshare. Użyj opcji /g, aby określić, że prefiks pliku "\\largeapp\appserver" może ulec zmianie w przyszłości:

symstore add /r /p /g \\largeapp\appserver /f 
   \\largeapp\appserver\bins\*.* 
   /x \\hubserver\hubshare\myindex.txt

Teraz załóżmy, że przenosisz wszystkie pliki symboli z maszyny \\largeapp\appserver i umieszczasz je na \\myarchive\appserver. Następnie możesz utworzyć sam magazyn symboli z pliku indeksu \\hubserver\hubshare\myindex.txt w następujący sposób:

symstore add /y \\hubserver\hubshare\myindex.txt 
   /g \\myarchive\appserver /s \\sampledir\symsrv /p 
   /t "Large Application" /v "Build 432" /c "Sample Add from Index"

Na koniec oto przykład usuwania pliku dodanego przez poprzednią transakcję przez usługę SymStore. Zapoznaj się z poniższą sekcją, aby uzyskać wyjaśnienie sposobu określania identyfikatora transakcji (w tym przypadku 0000000096).

symstore del /i 0000000096 /s \\sampledir\symsrv

Skompresowane pliki

Magazyn SymStore może być używany z skompresowanymi plikami na dwa różne sposoby.

1. Użyj pliku SymStore z opcją /p, aby przechowywać wskaźniki do plików symboli. Po zakończeniu programu SymStore skompresuj pliki, do których odwołują się wskaźniki.
2. Użyj programu SymStore z opcją /x, aby utworzyć plik indeksu. Po zakończeniu programu SymStore skompresuj pliki wymienione w pliku indeksu. Następnie użyj opcji SymStore z opcją /y (i, jeśli chcesz, opcja /p) do przechowywania plików lub wskaźników do plików w magazynie symboli. (Program SymStore nie musi dekompresować plików, aby wykonać tę operację).

Serwer symboli będzie odpowiedzialny za rozpakowanie plików, gdy będą potrzebne.

Jeśli używasz programu SymSrv jako serwera symboli, należy wykonać kompresję przy użyciu narzędzia compress.exe dystrybuowanego za pomocą zestawu Microsoft Windows Software Development Kit (SDK). Skompresowane pliki powinny mieć podkreślenie jako ostatni znak w swoich rozszerzeniach plików (na przykład module1.pd_ lub module2.db_). Aby uzyskać szczegółowe informacje, zobacz Using SymSrv.

Pliki server.txt i history.txt

Po dodaniu transakcji kilka elementów informacji jest dodawanych do server.txt i history.txt na potrzeby przyszłych funkcji wyszukiwania. Poniżej przedstawiono przykład wiersza w server.txt i history.txt dla transakcji dodawania:

0000000096,add,ptr,10/09/99,00:08:32,Windows XP,x86 fre 1.156c-RTM-2,Added from \\mybuilds\symbols,

Jest to linia rozdzielona przecinkami. Pola są definiowane w następujący sposób.

Pole	Opis
0000000096	Numer identyfikatora transakcji utworzony przez usługę SymStore.
dodawać	Typ transakcji. Wartość tego pola może być add lub del.
ptr	Określa, czy dodano pliki, czy wskaźniki. To pole może być plikiem lub ptr.
10/09/99	Data wystąpienia transakcji.
00:08:32	Czas rozpoczęcia transakcji.
Windows XP	Produkt.
x86 fre	Wersja (opcjonalnie).
Dodano z	Komentarz (opcjonalnie)
Nieużywane	(Zarezerwowane do późniejszego użycia).

 

Oto kilka przykładowych wierszy z pliku transakcji 0000000096. Każdy wiersz rejestruje katalog i lokalizację pliku lub wskaźnika, który został dodany do katalogu.

canon800.dbg\35d9fd51b000,\\mybuilds\symbols\sp4\dll\canon800.dbg
canonlbp.dbg\35d9fd521c000,\\mybuilds\symbols\sp4\dll\canonlbp.dbg
certadm.dbg\352bf2f48000,\\mybuilds\symbols\sp4\dll\certadm.dbg
certcli.dbg\352bf2f1b000,\\mybuilds\symbols\sp4\dll\certcli.dbg
certcrpt.dbg\352bf04911000,\\mybuilds\symbols\sp4\dll\certcrpt.dbg
certenc.dbg\352bf2f7f000,\\mybuilds\symbols\sp4\dll\certenc.dbg

Jeśli użyjesz transakcji del, aby cofnąć oryginalne dodać transakcje, te wiersze zostaną usunięte z server.txt, a następujący wiersz zostanie dodany do history.txt:

0000000105,del,0000000096

Pola dla transakcji usuwania są definiowane w następujący sposób.

Pole	Opis
0000000105	Numer identyfikatora transakcji utworzony przez usługę SymStore.
Del	Typ transakcji. To pole może być dodaj lub usuń.
0000000096	Transakcja, która została usunięta.

 

Format magazynu symboli

Usługa SymStore używa samego systemu plików jako bazy danych. Tworzy duże drzewo katalogów z nazwami katalogów na podstawie takich elementów, jak sygnatury czasowe pliku symboli, podpisy, wiek i inne dane.

Na przykład po dodaniu kilku różnych plików acpi.dbg do serwera katalogi mogą wyglądać następująco:

Directory of \\mybuilds\symsrv\acpi.dbg
10/06/1999  05:46p      <DIR>          .
10/06/1999  05:46p      <DIR>          ..
10/04/1999  01:54p      <DIR>          37cdb03962040
10/04/1999  01:49p      <DIR>          37cdb04027740
10/04/1999  12:56p      <DIR>          37e3eb1c62060
10/04/1999  12:51p      <DIR>          37e3ebcc27760
10/04/1999  12:45p      <DIR>          37ed151662060
10/04/1999  12:39p      <DIR>          37ed15dd27760
10/04/1999  11:33a      <DIR>          37f03ce962020
10/04/1999  11:21a      <DIR>          37f03cf7277c0
10/06/1999  05:38p      <DIR>          37fa7f00277e0
10/06/1999  05:46p      <DIR>          37fa7f01620a0

W tym przykładzie ścieżka dostępu dla pliku symboli acpi.dbg może wyglądać następująco: \\mybuilds\symsrv\acpi.dbg\37cdb03962040.

W katalogu wyszukiwania mogą istnieć trzy pliki.

1. Jeśli plik został zapisany, plik acpi.dbg będzie tam istniał.
2. Jeśli wskaźnik został zapisany, plik o nazwie file.ptr będzie istnieć i zawierać ścieżkę do rzeczywistego pliku symboli.
3. Plik o nazwie refs.ptr, który zawiera listę wszystkich bieżących lokalizacji dla acpi.dbg z przypisanym znacznikiem czasu i rozmiarem obrazu, które zostały dodane do magazynu symboli.

Wyświetlenie listy katalogów \\mybuilds\symsrv\acpi.dbg\37cdb03962040 daje następujące elementy:

10/04/1999  01:54p                  52 file.ptr
10/04/1999  01:54p                  67 refs.ptr

Plik file.ptr zawiera ciąg tekstowy "\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg". Ponieważ w tym katalogu nie ma pliku o nazwie acpi.dbg, debuger spróbuje znaleźć plik w folderze \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg.

Zawartość refs.ptr jest używana tylko przez SymStore, a nie przez debuger. Ten plik zawiera rekord wszystkich transakcji, które miały miejsce w tym katalogu. Przykładowa linia z pliku refs.ptr może być:

0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg

To pokazuje, że wskaźnik do \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg został dodany z transakcją "0000000026".

Niektóre pliki symboli pozostają niezmienne w różnych produktach lub kompilacjach, lub w określonym produkcie. Jednym z przykładów jest plik msvcrt.pdb. Wyświetlenie zawartości katalogu \\mybuilds\symsrv\msvcrt.pdb pokazuje, że do serwera symboli dodano tylko dwie wersje pliku msvcrt.pdb.

Directory of \\mybuilds\symsrv\msvcrt.pdb
10/06/1999  05:37p      <DIR>          .
10/06/1999  05:37p      <DIR>          ..
10/04/1999  11:19a      <DIR>          37a8f40e2
10/06/1999  05:37p      <DIR>          37f2c2272

Jednak wykonanie katalogu \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2 pokazuje, że element refs.ptr ma w nim kilka wskaźników.

Directory of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2
10/05/1999  02:50p              54     file.ptr
10/05/1999  02:50p           2,039     refs.ptr

Zawartość pliku \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2\refs.ptr jest następująca:

0000000001,ptr,\\mybuilds\symbols\x86\2137\symbols\dll\msvcrt.pdb
0000000002,ptr,\\mybuilds\symbols\x86\2137.chk\symbols\dll\msvcrt.pdb
0000000003,ptr,\\mybuilds\symbols\x86\2138\symbols\dll\msvcrt.pdb
0000000004,ptr,\\mybuilds\symbols\x86\2138.chk\symbols\dll\msvcrt.pdb
0000000005,ptr,\\mybuilds\symbols\x86\2139\symbols\dll\msvcrt.pdb
0000000006,ptr,\\mybuilds\symbols\x86\2139.chk\symbols\dll\msvcrt.pdb
0000000007,ptr,\\mybuilds\symbols\x86\2140\symbols\dll\msvcrt.pdb
0000000008,ptr,\\mybuilds\symbols\x86\2140.chk\symbols\dll\msvcrt.pdb
0000000009,ptr,\\mybuilds\symbols\x86\2136\symbols\dll\msvcrt.pdb
0000000010,ptr,\\mybuilds\symbols\x86\2136.chk\symbols\dll\msvcrt.pdb
0000000011,ptr,\\mybuilds\symbols\x86\2135\symbols\dll\msvcrt.pdb
0000000012,ptr,\\mybuilds\symbols\x86\2135.chk\symbols\dll\msvcrt.pdb
0000000013,ptr,\\mybuilds\symbols\x86\2134\symbols\dll\msvcrt.pdb
0000000014,ptr,\\mybuilds\symbols\x86\2134.chk\symbols\dll\msvcrt.pdb
0000000015,ptr,\\mybuilds\symbols\x86\2133\symbols\dll\msvcrt.pdb
0000000016,ptr,\\mybuilds\symbols\x86\2133.chk\symbols\dll\msvcrt.pdb
0000000017,ptr,\\mybuilds\symbols\x86\2132\symbols\dll\msvcrt.pdb
0000000018,ptr,\\mybuilds\symbols\x86\2132.chk\symbols\dll\msvcrt.pdb
0000000019,ptr,\\mybuilds\symbols\x86\2131\symbols\dll\msvcrt.pdb
0000000020,ptr,\\mybuilds\symbols\x86\2131.chk\symbols\dll\msvcrt.pdb
0000000021,ptr,\\mybuilds\symbols\x86\2130\symbols\dll\msvcrt.pdb
0000000022,ptr,\\mybuilds\symbols\x86\2130.chk\symbols\dll\msvcrt.pdb
0000000023,ptr,\\mybuilds\symbols\x86\2129\symbols\dll\msvcrt.pdb
0000000024,ptr,\\mybuilds\symbols\x86\2129.chk\symbols\dll\msvcrt.pdb
0000000025,ptr,\\mybuilds\symbols\x86\2128\symbols\dll\msvcrt.pdb
0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\dll\msvcrt.pdb
0000000027,ptr,\\mybuilds\symbols\x86\2141\symbols\dll\msvcrt.pdb
0000000028,ptr,\\mybuilds\symbols\x86\2141.chk\symbols\dll\msvcrt.pdb
0000000029,ptr,\\mybuilds\symbols\x86\2142\symbols\dll\msvcrt.pdb
0000000030,ptr,\\mybuilds\symbols\x86\2142.chk\symbols\dll\msvcrt.pdb

Pokazuje to, że ten sam plik msvcrt.pdb był używany dla wielu kompilacji symboli przechowywanych w folderze \\mybuilds\symsrv.

Oto przykład katalogu zawierającego kombinację dodatków do pliku i wskaźnika:

Directory of E:\symsrv\dbghelp.dbg\38039ff439000
10/12/1999  01:54p         141,232     dbghelp.dbg
10/13/1999  04:57p              49     file.ptr
10/13/1999  04:57p             306     refs.ptr

W tym przypadku plik refs.ptr ma następującą zawartość:

0000000043,file,e:\binaries\symbols\retail\dll\dbghelp.dbg
0000000044,file,f:\binaries\symbols\retail\dll\dbghelp.dbg
0000000045,file,g:\binaries\symbols\retail\dll\dbghelp.dbg
0000000046,ptr,\\sampledir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\sampledir2\bin\symbols\retail\dll\dbghelp.dbg

W związku z tym transakcje 43, 44 i 45 dodały ten sam plik do serwera, a transakcje 46 i 47 dodały wskaźniki. Jeśli transakcje 43, 44 i 45 zostaną usunięte, plik dbghelp.dbg zostanie usunięty z katalogu. Następnie katalog będzie miał następującą zawartość:

Directory of e:\symsrv\dbghelp.dbg\38039ff439000
10/13/1999  05:01p                   49 file.ptr
10/13/1999  05:01p                 130 refs.ptr

Teraz plik.ptr zawiera "\\sampledir2\bin\symbols\retail\dll\dbghelp.dbg", a plik refs.ptr zawiera

0000000046,ptr,\\sampledir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\sampledir2\bin\symbols\retail\dll\dbghelp.dbg

Za każdym razem, gdy ostatni wpis w pliku refs.ptr jest wskaźnikiem, plik file.ptr będzie istnieć i zawierać ścieżkę do skojarzonego pliku. Za każdym razem, gdy ostatni wpis w pliku refs.ptr jest plikiem, żaden plik.ptr nie istnieje w tym katalogu. W związku z tym każda operacja usuwania, która usuwa ostatni wpis w pliku refs.ptr, może spowodować utworzenie, usunięcie lub zmianę pliku.ptr.