Chemin d'accès aux symboles pour les débogueurs Windows

Article
07/08/2024

Le chemin d’accès aux symboles spécifie les emplacements où les débogueurs Windows, tels que WinDbg, KD, CDB et NTST, recherchent des fichiers de symboles. Pour plus d’informations sur les symboles et les fichiers de symboles, consultez Symboles.

Certains compilateurs, y compris Microsoft Visual Studio, mettent des fichiers de symboles dans le même répertoire que les fichiers binaires. Les fichiers de symboles et les fichiers binaires vérifiés contiennent des informations de chemin d’accès et de nom de fichier, ce qui permet au débogueur de rechercher automatiquement les fichiers de symboles. Si vous déboguez un processus en mode utilisateur sur l’ordinateur sur lequel l’exécutable a été généré et si les fichiers de symboles se trouvent à leur emplacement d’origine, le débogueur peut localiser les fichiers de symboles sans définir le chemin d’accès aux symboles.

Dans la plupart des autres cas, vous devez définir le chemin d’accès des symboles pour pointer vers vos emplacements de fichier de symboles.

Conseil

Utilisez .symfix pour définir un chemin d’accès par défaut au serveur de symboles publics Microsoft public public qui fonctionne bien dans de nombreuses situations.

Syntaxe du chemin d’accès aux symboles

Le chemin de symbole du débogueur est une chaîne qui se compose de plusieurs chemins d’accès de répertoire séparés par des points-virgules. Par exemple : C:\Dir1;C:\Dir2\DirA;C:\Dir2\DirB.

Les chemins d’accès relatifs sont pris en charge. Toutefois, vous devez ajouter une lettre de lecteur ou un partage réseau avant chaque chemin, sauf si vous démarrez toujours le débogueur à partir du même répertoire. Les partages réseau sont également pris en charge.

Pour chaque répertoire du chemin de symbole, le débogueur recherche dans trois répertoires. Par exemple, si le chemin d’accès aux symboles inclut C:\Dir1 et que le débogueur recherche des informations de symboles pour une DLL, le débogueur recherche les informations de symbole dans les répertoires suivants, répertoriés dans l’ordre :

C:\Dir1\symbols\dll
C:\Dir1\dll
C:\Dir1

Le débogueur répète ensuite ce processus pour chaque répertoire dans le chemin du symbole. Enfin, le débogueur recherche dans le répertoire actif, puis dans le répertoire actif avec ..\dll ajouté à celui-ci. Le débogueur ajoute ..\dll, ..\exeou ..\sys, selon les fichiers binaires qu’il débogue.

Les fichiers de symboles ont des horodatages de date et d’heure. Le débogueur recherche toujours les symboles qui correspondent à l’horodatage sur les fichiers binaires qu’il débogue. Vous n’avez pas à vous soucier du débogueur à l’aide des symboles incorrects qu’il trouve en premier dans cette séquence. Pour plus d’informations sur les réponses lorsque les fichiers de symboles ne sont pas disponibles, consultez Noms de symboles correspondants.

Une façon de définir le chemin du symbole consiste à entrer la commande .sympath. Pour obtenir d’autres façons de définir le chemin d’accès aux symboles, consultez Contrôler le chemin d’accès aux symboles plus loin dans cette rubrique.

Symboles de cache localement

Vous devez mettre en cache vos symboles localement. Une façon de mettre en cache les symboles localement consiste à inclure cache*; ou cache*localsymbolcache;* dans votre chemin d’accès aux symboles.

Si vous incluez la chaîne cache*; dans votre chemin d’accès aux symboles, les symboles chargés à partir d’un élément qui apparaît à droite de cette chaîne sont stockés dans le répertoire de cache de symboles par défaut sur l’ordinateur local. Par exemple, la commande suivante indique au débogueur d’obtenir des symboles du partage réseau nommé \\someshare et de mettre en cache les symboles à l’emplacement par défaut sur l’ordinateur local.

.sympath cache*;\\someshare

Si vous incluez la chaîne cache*localsymbolcache; dans le chemin de votre symbole, les symboles chargés à partir d’un élément qui apparaît à droite de cette chaîne sont stockés dans le répertoire localsymbolcache .

Par exemple, la commande suivante indique au débogueur d’obtenir des symboles à partir du partage \\someshare réseau et de mettre en cache les symboles dans le c:\MySymbols répertoire.

.sympath cache*C:\MySymbols;\\someshare

Utilisation d’un serveur de symboles : srv*

Si vous êtes connecté à Internet ou à un réseau d’entreprise, le moyen le plus efficace d’accéder aux symboles consiste à utiliser un serveur de symboles tel que le serveur de symboles publics Microsoft public. Vous pouvez utiliser un serveur de symboles à l’aide de l’une des chaînes suivantes dans votre chemin d’accès aux symboles.

Chaîne srv*

Si vous incluez la chaîne srv* dans votre chemin de symbole, le débogueur utilise un serveur de symboles pour obtenir des symboles à partir du magasin de symboles par défaut. Par exemple, la commande suivante indique au débogueur d’obtenir des symboles à partir du magasin de symboles par défaut. Ces symboles ne sont pas mis en cache sur l’ordinateur local.
```
.sympath srv*
```
Chaîne srv*symbolstore

Si vous incluez la chaîne srv*symbolstore dans le chemin de votre symbole, le débogueur utilise un serveur de symboles pour obtenir des symboles à partir du symbolstore. Par exemple, la commande suivante indique au débogueur d’obtenir des symboles à partir du magasin de serveurs de symboles Microsoft. Ces symboles ne sont pas mis en cache sur l’ordinateur local.
```
.sympath srv*https://msdl.microsoft.com/download/symbols
```
Chaîne srv*localsymbolcache*symbolstore

Si vous incluez la chaîne srv*localcache*symbolstore dans votre chemin de symbole, le débogueur utilise un serveur de symboles pour obtenir des symboles à partir du magasin de symboles et les met en cache dans le répertoire localcache . Par exemple, la commande suivante indique au débogueur d’obtenir des symboles à partir du serveurhttps://msdl.microsoft.com/download/symbols de symboles Microsoft et de mettre en cache les symboles dans c:\MyServerSymbols.
```
.sympath srv*C:\MyServerSymbols*https://msdl.microsoft.com/download/symbols
```

Si vous avez un répertoire sur votre ordinateur où vous placez manuellement des symboles, n’utilisez pas ce répertoire comme cache pour les symboles obtenus à partir d’un serveur de symboles. Utilisez plutôt deux répertoires distincts. Par exemple, vous pouvez placer manuellement des symboles dans c:\MyRegularSymbols et ensuite désigner c:\MyServerSymbols comme cache pour les symboles obtenus à partir d’un serveur. L’exemple suivant montre comment spécifier les deux répertoires dans votre chemin d’accès aux symboles.

.sympath C:\MyRegularSymbols;srv*C:\MyServerSymbols*https://msdl.microsoft.com/download/symbols

Pour plus d’informations sur les serveurs de symboles et les magasins de symboles, consultez magasins de symboles personnalisés et serveurs de symboles.

Combiner cache* et srv*

Si vous incluez la chaîne cache*; dans votre chemin d’accès aux symboles, les symboles chargés à partir d’un élément qui apparaît à droite de cette chaîne sont stockés dans le répertoire de cache de symboles par défaut sur l’ordinateur local. Par exemple, la commande suivante indique au débogueur d’obtenir des symboles à partir du magasin de serveurs de symboles Microsoft et de les mettre en cache dans le répertoire de cache de symboles par défaut.

.sympath cache*;srv*https://msdl.microsoft.com/download/symbols

Par exemple, la commande suivante indique au débogueur d’obtenir des symboles à partir du magasin de serveurs de symboles Microsoft et de mettre en cache les symboles dans le c:\MySymbols répertoire.

.sympath cache*C:\MySymbols;srv*https://msdl.microsoft.com/download/symbols

Utiliser AgeStore pour réduire la taille du cache

Vous pouvez utiliser l’outil AgeStore pour supprimer les fichiers mis en cache antérieurs à une date spécifiée ou pour supprimer suffisamment de fichiers anciens afin que la taille du cache résultante soit inférieure à une quantité spécifiée. Ce nettoyage des fichiers de cache est utile si votre magasin en aval est trop volumineux.

Chargement de symboles différés

Le comportement par défaut du débogueur consiste à utiliser le chargement de symboles différés, également appelé chargement différé de symboles. Ce type de chargement signifie que les symboles ne sont pas chargés tant qu’ils ne sont pas requis.

Lorsque le chemin du symbole est modifié, par exemple en utilisant la commande .sympath, tous les modules chargés avec des symboles d’exportation sont rechargés de manière différée.

Les symboles des modules avec des symboles PDB complets sont rechargés de manière différée si le nouveau chemin d’accès n’inclut plus le chemin d’accès d’origine utilisé pour charger les symboles PDB. Si le nouveau chemin inclut toujours le chemin d’accès d’origine au fichier de symboles PDB, ces symboles ne sont pas rechargés de manière différée.

Vous pouvez désactiver le chargement de symboles différés dans CDB et KD à l’aide de l’option de ligne de commande -s. Vous pouvez également forcer le chargement de symboles à l’aide de la commande de symboles de chargement ld ou à l’aide de la commande du module .reload avec l’option /f .

Artefacts Azure DevOps Services

Un serveur de symboles est disponible avec Azure Artifacts dans Azure DevOps Services. Pour en savoir plus sur l’utilisation d’Azure Artifacts dans WinDbg, consultez Débogage avec des symboles dans WinDbg. Pour obtenir des informations générales sur les symboles générés par Azure, consultez vue d’ensemble des symboles.

Contrôler le chemin d’accès aux symboles

Pour contrôler le chemin d’accès aux symboles, vous pouvez sélectionner l’une des méthodes suivantes :

Utilisez la commande .symfix set symbol store path pour définir un chemin d’accès par défaut au serveur de symboles Microsoft public qui fonctionne bien dans de nombreuses situations. Pour définir un cache local, tapez .symfix C:\MyCachesimplement .
Utilisez la commande .sympath pour afficher, définir, modifier ou ajouter au chemin d’accès.
Avant de démarrer le débogueur, utilisez les variables d’environnement et _NT_ALT_SYMBOL_PATH les _NT_SYMBOL_PATH variables d’environnement pour définir le chemin d’accès. Le chemin d’accès aux symboles est créé en ajoutant _NT_SYMBOL_PATH après _NT_ALT_SYMBOL_PATH. En règle générale, le chemin d’accès est défini par le biais du _NT_SYMBOL_PATH. Toutefois, vous pouvez utiliser _NT_ALT_SYMBOL_PATH pour remplacer ces paramètres dans des cas spéciaux, par exemple si vous avez des versions privées de fichiers de symboles partagés. Si vous essayez d’ajouter un répertoire non valide via ces variables d’environnement, le débogueur ignore ce répertoire.
Lorsque vous démarrez le débogueur, utilisez l’option de ligne de commande -y pour définir le chemin d’accès.
Dans WinDbg uniquement, vous pouvez utiliser le fichier | Commande Chemin du fichier de symbole ou appuyez CTRL+S sur pour afficher, définir, modifier ou ajouter au chemin d’accès.

Si vous utilisez l’option de ligne de commande -sins, le débogueur ignore la variable d’environnement de chemin d’accès au symbole.

Dépannage

Utilisez !sym bruyant ou l’option de ligne de commande -n WinDbg pour afficher des détails supplémentaires à mesure que les symboles sont chargés. Pour obtenir des stratégies de résolution des problèmes supplémentaires, consultez Vérification des symboles.