Utilisation de SymSrv

SymSrv fournit des fichiers de symboles à partir de magasins de symboles centralisés. Ces magasins peuvent contenir n’importe quel nombre de fichiers de symboles, correspondant à n’importe quel nombre de programmes ou de systèmes d’exploitation. Les magasins peuvent également contenir des fichiers binaires, qui sont particulièrement utiles lors du débogage de fichiers minidump.

Les magasins peuvent contenir le symbole réel et les fichiers binaires ou simplement des pointeurs vers des fichiers de symboles. Si le magasin contient des pointeurs, SymSrv récupère les fichiers réels directement à partir de leurs sources.

SymSrv peut également séparer un grand magasin de symboles en un sous-ensemble plus petit qui convient pour une tâche de débogage spécialisée.

Enfin, SymSrv peut obtenir des fichiers de symboles à partir d’une source HTTP ou HTTPS à l’aide des informations de connexion fournies par le système d’exploitation. SymSrv prend en charge les sites HTTPS protégés par des cartes à puce, des certificats, ainsi que des connexions et mots de passe standard.

Définition du chemin du symbole

Comme décrit dans Chemins de symboles, le chemin du symbole (_NT_SYMBOL_PATH variable d’environnement) peut être composé de plusieurs éléments de chemin séparés par des points-virgules. Si un ou plusieurs de ces éléments de chemin commencent par le texte « srv* », l’élément est un serveur de symboles et utilise SymSrv pour localiser les fichiers de symboles.

Notes

Si le texte « srv* » n’est pas spécifié, mais que l’élément chemin d’accès réel est un magasin de serveur de symboles, le gestionnaire de symboles agit comme si « srv* » était spécifié. Le gestionnaire de symboles effectue cette détermination en recherchant l’existence d’un fichier appelé « pingme.txt » dans le répertoire racine du chemin spécifié.

 

Tout comme les chemins de symboles sont constitués d’éléments de chemin de symbole séparés par des points-virgules, les serveurs de symboles sont constitués d’éléments de magasin de symboles séparés par des astérisques. Il peut y avoir jusqu’à 10 magasins de symboles après le préfixe « srv* ». Les magasins répertoriés à gauche de la liste sont appelés magasins en aval et les magasins situés à droite sont appelés amont magasins.

srv\**SymbolStore* srv\**SymbolStore1***SymbolStoreN*

Si un seul élément de magasin de symboles est inclus dans le chemin d’accès, SymSrv tente d’utiliser le fichier demandé directement à partir de ce magasin.

S’il existe deux magasins de symboles dans le chemin d’accès, SymSrv recherche le fichier de symboles dans le magasin de symboles le plus à gauche. Si le fichier est présent, il est utilisé. S’il n’est pas là, SymSrv regarde dans le magasin de symboles immédiatement à droite. Si le fichier s’y trouve, il est copié dans le magasin de gauche et ouvert à partir de là.

S’il existe plus de deux magasins, ce comportement continue à droite jusqu’à ce que le fichier soit trouvé ou qu’il n’y ait plus de magasins dans la liste.

Le fichier n’est jamais ouvert à partir d’un magasin, mais du magasin le plus à gauche. Si le fichier se trouve ailleurs dans la chaîne, il est copié dans chaque magasin à gauche de celui-ci. Ce processus de copie est appelé « cascade » et offre certains avantages qui seront déclarés plus loin dans ce document.

Types de magasins de symboles

Le tableau suivant affiche des exemples des types de magasins de symboles pris en charge.

Type de magasin de symboles	Description
\\server\share	Chemin d’accès UNC complet à un partage sur un serveur distant.
c:\LocalCache	Chemin d’accès à un répertoire sur l’ordinateur client.
https://InternetSite	URL d’un site web hébergeant les symboles. Doit être le magasin le plus à droite de la liste et ne doit pas être le seul magasin de la liste.
https://SecureInternetSite	URL d’un site web sécurisé hébergeant les symboles. Cela peut prendre en charge les mots de passe, les informations d’identification de connexion Windows, les certificats et les cartes à puce. Doit être le magasin le plus à droite de la liste et ne doit pas être le seul magasin de la liste.
<blank>	S’il n’y a pas de texte entre deux astérisque, cela indique le magasin en aval par défaut. L’emplacement est défini en appelant SymSetHomeDirectory. La valeur par défaut est un répertoire nommé « sym » juste en dessous du répertoire du programme de l’application appelante. Il s’agit parfois du cache local par défaut.

 

Étant donné qu’un magasin de symboles http ne peut pas être écrit dans, il doit s’agir du magasin le plus à droite de la liste. Si un magasin de symboles http se trouvait au milieu ou à gauche de la liste de magasins, il ne serait pas possible de copier les fichiers trouvés dans celui-ci et la chaîne serait rompue. En outre, étant donné que le gestionnaire de symboles ne peut pas ouvrir un fichier à partir d’un site web, un magasin HTTP ne doit pas être le magasin le plus à gauche ou uniquement dans la liste. Si SymSrv reçoit ce chemin de symbole, il tente de récupérer en copiant le fichier dans le magasin en aval par défaut et de l’ouvrir à partir de là, que le magasin en aval par défaut soit indiqué ou non dans le chemin du symbole.

Exemples

Pour utiliser SymSrv avec un magasin de symboles sur \\mybuilds\mysymbols, définissez le chemin de symbole suivant :

set _NT_SYMBOL_PATH= srv*\\mybuilds\mysymbols

Pour définir le chemin des symboles afin que le débogueur copie les fichiers de symboles d’un magasin de symboles sur \\mybuilds\mysymbols dans votre répertoire local c:\localsymbols, utilisez :

set _NT_SYMBOL_PATH=srv*c:\localsymbols*\\mybuilds\mysymbols

Pour définir le chemin du symbole afin que le débogueur copie les fichiers de symboles d’un magasin de symboles sur \\mybuilds\mysymbols vers le magasin en aval par défaut (généralement c:\debuggers\sym), utilisez :

set _NT_SYMBOL_PATH=srv**\\mybuilds\mysymbols

Pour utiliser un magasin en cascade, définissez le chemin de symbole suivant :

set _NT_SYMBOL_PATH = srv*c:\localsymbols*\\NearbyServer\store*https://DistantServer

Dans cet exemple, SymSrv recherche d’abord le fichier dans c:\localsymbols. S’il y est trouvé, il retourne un chemin d’accès au fichier. Sinon, SymSrv recherche le fichier dans \\NearbyServer\store. S’il y est trouvé, SymSrv copie le fichier dans c:\localsymbols et retourne un chemin d’accès au fichier ; s’il est introuvable, SymSrv recherche le fichier dans https://DistantServer, et s’il y est trouvé, SymSrv copie le fichier dans \\NearbyServer\store, puis dans c:\localsymbols.

Ce dernier exemple montre comment la conception judicieuse d’un chemin de symbole peut être utilisée pour optimiser le téléchargement des symboles. Si vous avez un site de travail avec un groupe de débogueurs et qu’ils doivent tous obtenir des symboles à partir d’un emplacement distant, vous pouvez configurer un serveur commun avec un magasin de symboles près de tous les débogueurs. Ensuite, configurez chaque débogueur avec le chemin de symbole ci-dessus. Le premier débogueur qui nécessite une certaine version de foo.pdb le télécharge à partir de https://DistantServer \\NearbyServer\store, puis sur sa propre machine dans c:\localsymbols. Le débogueur suivant qui nécessite le même fichier pourra le télécharger à partir de \\NearbyServer\store, car il a déjà été téléchargé à cet emplacement par le débogueur précédent. Cette mise en cache à plusieurs niveaux permet d’économiser beaucoup de temps et de bande passante réseau.

Microsoft Symbol Store

Microsoft fournit l’accès à un serveur de symboles Internet qui contient des fichiers de symboles pour les nombreuses versions du système d’exploitation Windows. Il n’est pas garanti que ce catalogue de symboles soit complet, mais il est étendu. D’autres produits Microsoft sont également représentés.

Le serveur de symboles Internet est rempli d’une variété de symboles Windows pour les systèmes d’exploitation Microsoft Windows, notamment les correctifs à chaud, les Service Packs, les packages cumulatifs de sécurité et les versions commerciales. Des symboles sont également disponibles sur le serveur pour les versions bêta actuelles et les versions candidates pour les produits Windows, ainsi qu’une variété d’autres produits Microsoft, tels que Microsoft Internet Explorer.

Si vous avez accès à Internet pendant le débogage, vous pouvez configurer le débogueur pour télécharger les symboles en fonction des besoins pendant une session de débogage, plutôt que de télécharger des fichiers de symboles séparément avant une session de débogage. Les symboles sont téléchargés dans un emplacement de répertoire que vous spécifiez, puis le débogueur les charge à partir de là.

L’URL du magasin de symboles Microsoft est https://msdl.microsoft.com/download/symbols. L’exemple suivant montre comment définir le chemin du symbole du débogueur (remplacez le chemin d’accès de votre magasin en aval par c:\DownstreamStore) :

srv*c:\DownstreamStore*https://msdl.microsoft.com/download/symbols

Fichiers compressés

SymSrv est compatible avec les magasins de symboles qui contiennent des fichiers compressés, tant que cette compression a été préformée avec l’outil compress.exe distribué avec le Kit de ressources Windows Server 2003. 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 SymStore.

En cas de cascade, les fichiers ne sont pas décompressés, sauf si le magasin cible est le magasin le plus à gauche dans le chemin d’accès. S’il n’y a qu’un seul magasin dans le chemin et qu’il contient un fichier compressé, SymSrv copie le fichier dans le magasin en aval par défaut et l’ouvre à partir de là, même si le magasin en aval par défaut n’est pas indiqué dans le chemin du symbole.

DbgHelp 6.1 et versions antérieures : Si les fichiers du magasin master sont compressés, vous devez utiliser un magasin en aval. SymSrv désactive tous les fichiers avant de les copier dans le magasin en aval.

Suppression du cache

Si vous utilisez un magasin en aval comme cache, vous pouvez supprimer ce répertoire à tout moment pour économiser de l’espace disque.

Il est possible d’avoir un vaste magasin de symboles qui comprend des fichiers de symboles pour de nombreux programmes ou versions Windows différents. Si vous mettez à niveau la version de Windows utilisée sur votre ordinateur cible, les fichiers de symboles mis en cache correspondent tous à la version antérieure. Ces fichiers mis en cache ne seront plus d’une utilisation supplémentaire, ce qui peut être un bon moment pour supprimer le cache.

Outils de débogage pour Windows est fourni avec un utilitaire appelé agestore.exe qui supprime de manière sélective les fichiers d’une arborescence de répertoires, en laissant les fichiers les plus récemment utilisés. Cet outil est conçu pour supprimer les fichiers inutilisés des magasins de serveurs de symboles. Il vous permet de contrôler de nombreuses options, notamment les algorithmes de date de coupure et de taille de répertoire.

Répertoire du cache plat

Il est possible de déclarer le magasin en aval par défaut sous la forme d’un répertoire plat, plutôt que d’une arborescence de symboles standard. Pour ce faire, appelez la fonction SymSetOptions avec SYMOPT_FLAT_DIRECTORY (cela définit également l’option SSRVOPT_FLAT_DEFAULT_STORE dans SymSrv). Veillez à appeler SymSetHomeDirectory avant de le faire . sinon, les fichiers de symboles peuvent être écrits dans le répertoire du programme.

Fichiers de pointeur

SymStore peut créer et utiliser des fichiers qui pointent vers un fichier cible plutôt que vers le fichier cible lui-même. Si un magasin de symboles contient un tel fichier de pointeur, la valeur par défaut consiste à copier le fichier à partir de l’emplacement indiqué dans le fichier de pointeur vers le magasin. Pour configurer un magasin de sorte que le fichier de pointeur soit copié au lieu du fichier vers lequel il pointe, créez un fichier nommé wantsptr.txt à la racine du magasin cible. Le contenu de wantsptr.txt n’est pas important, seulement la présence du fichier.

Exclusion de fichiers de la liste de symboles

Pour exclure des fichiers d’une recherche de symboles, vous pouvez spécifier leurs noms dans symsrv.ini ou dans le Registre. Pour spécifier les fichiers dans symsrv.ini, créez une section nommée Exclusions et répertoriez les fichiers. Les noms de fichiers peuvent contenir des caractères génériques, comme illustré dans l’exemple suivant :

[Exclusions]
dbghelp.pdb
symsrv.*
mso*

Symsrv.ini doit se trouver dans le même répertoire que symsrv.dll. Dans la plupart des installations, le fichier n’existe pas et vous devez en créer un nouveau.

Vous pouvez également stocker les fichiers à exclure dans le Registre. Créez la clé de Registre suivante : HKEY_LOCAL_MACHINE\Software\Microsoft\Symbol Server\Exclusions. Stockez chaque nom de fichier sous forme de valeur de chaîne (REG_SZ) dans cette clé. Le nom de la valeur de chaîne spécifie le nom du fichier à exclure. Vous pouvez utiliser le contenu de la valeur de chaîne pour stocker un commentaire décrivant la raison pour laquelle le fichier est exclu.

Installation

Le serveur de symboles SymSrv (symsrv.dll) est inclus dans le package Outils de débogage pour Windows. Il doit être installé dans le même répertoire que la copie de dbghelp.dll que vous chargez. Pour plus d’informations, consultez Appel de la bibliothèque DbgHelp.