Utilisation de SymStore

Article
06/03/2023

SymStore (symstore.exe) est un outil permettant de créer des magasins de symboles. Il est inclus dans le package Outils de débogage pour Windows .

SymStore stocke les symboles dans un format qui permet au débogueur de rechercher les symboles en fonction de l’horodatage et de la taille de l’image (pour un fichier .dbg ou exécutable), ou de la signature et de l’âge (pour un fichier .pdb). L’avantage du magasin de symboles par rapport au format de stockage de symboles traditionnel est que tous les symboles peuvent être stockés ou référencés sur le même serveur et récupérés par le débogueur sans savoir au préalable quel produit contient le symbole correspondant.

Notez que plusieurs versions des fichiers de symboles .pdb (par exemple, les versions publiques et privées) ne peuvent pas être stockées sur le même serveur, car elles contiennent chacune la même signature et la même ancienneté.

SymStore Transactions

Chaque appel à SymStore est enregistré en tant que transaction. Il existe deux types de transactions : ajouter et supprimer.

Lorsque le magasin de symboles est créé, un répertoire appelé « 000admin » est créé sous la racine du serveur. Le répertoire 000admin contient un fichier pour chaque transaction, ainsi que les fichiers journaux Server.txt et History.txt. Le fichier Server.txt contient une liste de toutes les transactions qui se trouvent actuellement sur le serveur. Le fichier History.txt contient un historique chronologique de toutes les transactions.

Chaque fois que SymStore stocke ou supprime des fichiers de symboles, un nouveau numéro de transaction est créé. Ensuite, un fichier, dont le nom est ce numéro de transaction, est créé dans 000admin. Ce fichier contient la liste de tous les fichiers ou pointeurs qui ont été ajoutés au magasin de symboles pendant cette transaction. Si une transaction est supprimée, SymStore lit son fichier transaction pour déterminer les fichiers et les pointeurs qu’il doit supprimer.

Les options add et del spécifient si une transaction d’ajout ou de suppression doit être effectuée. L’inclusion de l’option /p avec une opération d’ajout spécifie qu’un pointeur doit être ajouté ; L’omission de l’option /p spécifie que le fichier de symboles réel doit être ajouté.

Il est également possible de créer le magasin de symboles en deux étapes distinctes. Dans la première étape, vous utilisez SymStore avec l’option /x pour créer un fichier d’index. Dans la deuxième étape, vous utilisez SymStore avec l’option /y pour créer le magasin réel de fichiers ou de pointeurs à partir des informations contenues dans le fichier d’index.

Cette technique peut être utile pour diverses raisons. Par instance, cela permet de recréer facilement le magasin de symboles si le magasin est perdu d’une manière ou d’une autre, tant que le fichier d’index existe toujours. Ou peut-être que l’ordinateur contenant les fichiers de symboles a une connexion réseau lente à l’ordinateur sur lequel le magasin de symboles sera créé. Dans ce cas, vous pouvez créer le fichier d’index sur la même machine que les fichiers de symboles, transférer le fichier d’index vers la deuxième machine, puis créer le magasin sur la deuxième machine.

Pour obtenir la liste complète de tous les paramètres SymStore, consultez Options de Command-Line SymStore.

Notes

SymStore ne prend pas en charge les transactions simultanées de plusieurs utilisateurs. Il est recommandé qu’un utilisateur soit désigné « administrateur » du magasin de symboles et soit responsable de toutes les transactions add et del .

Exemples de transactions

Voici deux exemples de SymStore ajoutant des pointeurs de symbole pour la build 3790 de Windows Server 2003 à \\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"

Dans l’exemple suivant, SymStore ajoute les fichiers de symboles réels pour un projet d’application dans \\largeapp\appserver\bins à \\testdir\symsrv :

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

Voici un exemple d’utilisation d’un fichier d’index. Tout d’abord, SymStore crée un fichier d’index basé sur la collection de fichiers de symboles dans \\largeapp\appserver\bins\. Dans ce cas, le fichier d’index est placé sur un troisième ordinateur, \\hubserver\hubshare. Vous utilisez l’option /g pour spécifier que le préfixe de fichier « \\largeapp\appserver » peut changer à l’avenir :

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

Supposons maintenant que vous déplacez tous les fichiers de symboles de la machine \\largeapp\appserver et que vous les placez sur \\myarchive\appserver. Vous pouvez ensuite créer le magasin de symboles lui-même à partir du fichier d’index \\hubserver\hubshare\myindex.txt comme suit :

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"

Enfin, voici un exemple de SymStore supprimant un fichier ajouté par une transaction précédente. Consultez la section suivante pour obtenir une explication de la façon de déterminer l’ID de transaction (dans ce cas, 0000000096).

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

Fichiers compressés

SymStore peut être utilisé avec des fichiers compressés de deux manières différentes.

Utilisez SymStore avec l’option /p pour stocker des pointeurs vers les fichiers de symboles. Une fois SymStore terminé, compressez les fichiers auxquels les pointeurs font référence.
Utilisez SymStore avec l’option /x pour créer un fichier d’index. Une fois SymStore terminé, compressez les fichiers répertoriés dans le fichier d’index. Ensuite, utilisez SymStore avec l’option /y (et, si vous le souhaitez, l’option /p ) pour stocker les fichiers ou les pointeurs vers les fichiers dans le magasin de symboles. (SymStore n’a pas besoin de décompresser les fichiers pour effectuer cette opération.)

Votre serveur de symboles sera chargé de décompresser les fichiers quand ils sont nécessaires.

Si vous utilisez SymSrv comme serveur de symboles, toute compression doit être effectuée à l’aide de l’outil compress.exe distribué avec le Kit de développement logiciel (SDK) Microsoft Windows. Les fichiers compressés doivent avoir un trait de soulignement comme dernier caractère dans leurs extensions de fichier (par exemple, module1.pd_ ou module2.db_). Pour plus d’informations, consultez Utilisation de SymSrv.

Fichiers server.txt et history.txt

Lorsqu’une transaction est ajoutée, plusieurs éléments d’informations sont ajoutés à server.txt et history.txt pour la fonctionnalité de recherche future. Voici un exemple de ligne dans server.txt et history.txt pour une transaction d’ajout :

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

Il s’agit d’une ligne séparée par des virgules. Les champs sont définis comme suit.

Champ	Description
0000000096	Numéro d’ID de transaction, tel que créé par SymStore.
ajouter	Type de transaction. Ce champ peut être ajouté ou del.
ptr	Indique si des fichiers ou des pointeurs ont été ajoutés. Ce champ peut être fichier ou ptr.
10/09/99	Date à laquelle la transaction s’est produite.
00:08:32	Heure à laquelle la transaction a démarré.
Windows XP	Produit.
x86 fre	Version (facultatif).
Ajouté à partir de	Commentaire (facultatif)
Inutilisé	(Réservé pour une utilisation ultérieure.)

Voici quelques exemples de lignes du fichier transaction 0000000096. Chaque ligne enregistre le répertoire et l’emplacement du fichier ou du pointeur qui a été ajouté au répertoire.

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

Si vous utilisez une transaction del pour annuler les transactions d’ajout d’origine, ces lignes seront supprimées de server.txt et la ligne suivante sera ajoutée à history.txt :

0000000105,del,0000000096

Les champs de la transaction de suppression sont définis comme suit.

Champ	Description
0000000105	Numéro d’ID de transaction, tel que créé par SymStore.
del	Type de transaction. Ce champ peut être ajouté ou del.
0000000096	Transaction supprimée.

Format de stockage des symboles

SymStore utilise le système de fichiers lui-même comme base de données. Il crée une grande arborescence de répertoires, avec des noms de répertoires basés sur des éléments tels que les horodatages du fichier de symboles, les signatures, l’âge et d’autres données.

Par exemple, une fois que plusieurs fichiers acpi.dbg différents ont été ajoutés au serveur, les répertoires peuvent ressembler à ceci :

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

Dans cet exemple, le chemin de recherche du fichier de symbole acpi.dbg peut ressembler à ceci : \\mybuilds\symsrv\acpi.dbg\37cdb03962040.

Trois fichiers peuvent exister à l’intérieur du répertoire de recherche :

Si le fichier a été stocké, acpi.dbg y existera.
Si un pointeur a été stocké, un fichier appelé file.ptr existera et contiendra le chemin d’accès au fichier de symboles réel.
Fichier appelé refs.ptr, qui contient la liste de tous les emplacements actuels pour acpi.dbg avec cet horodatage et cette taille d’image qui sont actuellement ajoutés au magasin de symboles.

L’affichage de la liste de répertoires de \\mybuilds\symsrv\acpi.dbg\37cdb03962040 donne les éléments suivants :

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

Le fichier file.ptr contient la chaîne de texte « \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg ». Étant donné qu’il n’existe aucun fichier appelé acpi.dbg dans ce répertoire, le débogueur essaie de trouver le fichier à l’adresse \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg.

Le contenu de refs.ptr est utilisé uniquement par SymStore, et non par le débogueur. Ce fichier contient un enregistrement de toutes les transactions qui ont eu lieu dans ce répertoire. Un exemple de ligne de refs.ptr peut être :

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

Cela montre qu’un pointeur vers \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg a été ajouté avec la transaction « 0000000026 ».

Certains fichiers de symboles restent constants par le biais de différents produits ou builds ou d’un produit particulier. Le fichier msvcrt.pdb en est un exemple. L’exécution d’un répertoire de \\mybuilds\symsrv\msvcrt.pdb montre que seules deux versions de msvcrt.pdb ont été ajoutées au serveur de symboles :

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

Toutefois, l’exécution d’un répertoire de \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2 montre que refs.ptr contient plusieurs pointeurs.

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

Le contenu de \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2\refs.ptr est le suivant :

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

Cela montre que le même msvcrt.pdb a été utilisé pour plusieurs builds de symboles stockés sur \\mybuilds\symsrv.

Voici un exemple de répertoire qui contient un mélange d’ajouts de fichiers et de pointeurs :

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

Dans ce cas, refs.ptr a le contenu suivant :

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

Ainsi, les transactions 43, 44 et 45 ont ajouté le même fichier au serveur, et les transactions 46 et 47 ont ajouté des pointeurs. Si les transactions 43, 44 et 45 sont supprimées, le fichier dbghelp.dbg est supprimé du répertoire. Le répertoire aura ensuite le contenu suivant :

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

Maintenant file.ptr contient « \\sampledir2\bin\symbols\retail\dll\dbghelp.dbg », et refs.ptr contient

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

Chaque fois que la dernière entrée dans refs.ptr est un pointeur, le fichier file.ptr existe et contient le chemin d’accès au fichier associé. Chaque fois que l’entrée finale dans refs.ptr est un fichier, aucun fichier.ptr n’existe dans ce répertoire. Par conséquent, toute opération de suppression qui supprime l’entrée finale dans refs.ptr peut entraîner la création, la suppression ou la modification de file.ptr.

Partager via