Spécifiez les fichiers de symboles (.pdb) et les fichiers sources dans le débogueur Visual Studio (C#, C++, Visual Basic, F#)

Les fichiers de base de données de programme (.pdb), également appelés fichiers de symboles, relient les identificateurs et les instructions du code source de votre projet aux identificateurs et instructions correspondants des applications compilées. Ces fichiers de mappage lient le débogueur à votre code source, ce qui permet le débogage.

Lorsque vous générez un projet à partir de l’IDE Visual Studio en utilisant la configuration de compilation de débogage standard, le compilateur crée les fichiers de symboles appropriés. Cet article explique comment gérer les fichiers de symboles dans l’IDE, par exemple :

• Configurer l’emplacement des fichiers de symboles
• Chargez des symboles lors du débogage
• Options du compilateur pour les symboles.

Pour obtenir une explication détaillée des fichiers de symboles, consultez les rubriques suivantes :

• Comprendre les fichiers de symboles et les paramètres de symbole Visual Studio

Fonctionnement des fichiers de symboles

Le fichier .pdb contient les informations d’état du débogage et du projet qui permettent la liaison incrémentielle d’une configuration de débogage de votre application. Le débogueur Visual Studio utilise des fichiers .pdb pour déterminer deux éléments clés d’informations lors du débogage :

• Nom du fichier source et numéro de ligne à afficher dans l’IDE Visual Studio.
• Emplacement de l’application où s’arrêter pour un point d’arrêt.

Les fichiers de symboles affichent également l’emplacement des fichiers sources, et éventuellement le serveur à partir duquel les récupérer.

Le débogueur charge uniquement les fichiers .pdb qui correspondent exactement aux fichiers .pdb créés lors de la génération d’une application (autrement dit, les fichiers .pdb d’origine ou les copies). Cette duplication exacte est nécessaire, car la disposition des applications peut changer même si le code lui-même n’a pas changé. Pour plus d’informations, consultez Pourquoi Visual Studio exige-t-il que les fichiers de symboles du débogueur correspondent exactement aux fichiers binaires avec lesquels ils ont été créés ?

Conseil

Pour déboguer du code en dehors du code source de votre projet, tel que le code Windows ou le code tiers que vous appelez, vous devez spécifier l’emplacement des fichiers .pdb du code externe (et éventuellement, les fichiers sources), qui doivent correspondre exactement aux builds de votre application.

Où le débogueur recherche des symboles

Lorsque vous déboguez un projet dans l’IDE Visual Studio, le débogueur charge automatiquement les fichiers de symboles qu’il peut trouver par défaut.

Remarque

Lors du débogage du code managé sur un appareil distant, tous les fichiers de symboles doivent se trouver sur l’ordinateur local ou dans un emplacement spécifié dans les options du débogueur.

Le débogueur recherche les fichiers de symboles aux emplacements suivants :

1. Dossier du projet.

2. Emplacement spécifié à l’intérieur de la DLL ou du fichier exécutable (.exe).

   Par défaut, si vous avez créé une DLL ou un fichier .exe sur votre ordinateur, l’éditeur de liens place le chemin d’accès complet et le nom de fichier .pdb associé dans la DLL ou le fichier .exe. Le débogueur vérifie si le fichier de symboles existe à cet emplacement.

3. Même dossier que le fichier DLL ou .exe.

4. Tous les emplacements spécifiés dans les options du débogueur pour les fichiers de symboles. Pour ajouter et activer des emplacements de symboles, consultez Configurer les emplacements des symboles et les options de chargement.

   • Tout dossier de cache de symboles locaux.

   • Serveurs de symboles et emplacements réseau, Internet ou locaux spécifiés, tels que les serveurs de symboles Microsoft s’ils sont sélectionnés. Visual Studio peut télécharger les fichiers de symboles de débogage à partir de serveurs de symboles qui implémentent le protocole symsrv. Visual Studio Team Foundation Server et les outils de débogage pour Windows sont deux outils qui peuvent utiliser des serveurs de symboles.

     Les serveurs de symboles que vous pouvez utiliser sont les suivants :

     Serveurs de symboles Microsoft publics : pour déboguer un incident qui se produit lors d’un appel à une DLL système ou à une bibliothèque tierce, vous avez souvent besoin de fichiers .pdb système. Les fichiers .pdb système contiennent des symboles pour les DLL Windows, les fichiers .exe et les pilotes de périphérique. Vous pouvez obtenir des symboles pour les systèmes d’exploitation Windows, MDAC, IIS, ISA et .NET à partir des serveurs de symboles Microsoft publics.

     serveurs de symboles sur un réseau interne ou sur votre ordinateur local: votre équipe ou votre entreprise peut créer des serveurs de symboles pour vos propres produits et comme cache pour les symboles provenant de sources externes. Vous pouvez avoir un serveur de symboles sur votre propre ordinateur.

     serveurs de symboles tiers: des fournisseurs tiers d’applications et de bibliothèques Windows peuvent fournir un accès au serveur de symboles sur Internet.

Avertissement

Si vous utilisez un serveur de symboles autre que les serveurs de symboles Microsoft publics, assurez-vous que le serveur de symboles et son chemin d’accès sont fiables. Étant donné que les fichiers de symboles peuvent contenir du code exécutable arbitraire, vous pouvez être exposé aux menaces de sécurité.

Configurer l’emplacement des fichiers de symboles et les options de chargement

Le débogueur vérifie par défaut différents emplacements pour les symboles. Consultez Où le débogueur recherche des symboles.

Dans la page Outils>Options>Symboles>de débogage, vous pouvez :

• Spécifiez et sélectionnez des chemins de recherche pour les fichiers de symboles.
• Spécifiez des serveurs de symboles pour les composants Microsoft, Windows ou tiers.
• Spécifiez les modules pour lesquels vous souhaitez ou non que le débogueur charge automatiquement des symboles.
• Modifiez ces paramètres pendant le débogage actif. Consultez Symboles de chargement lors du débogage.

Pour spécifier les emplacements des symboles et les options de chargement :

Remarque

Ces options ont été mises à jour dans Visual Studio 2022 version 17.12 Preview 1.

1. Dans Visual Studio, ouvrez Outils>Options>Débogage>Symboles (ou Débogage>Options>Symboles).

2. Sous Emplacements des fichiers de symboles (.pdb),

   • Pour utiliser les serveurs de symboles Microsoft ou le serveur de symboles NuGet.org , cochez la case.

   • Pour ajouter un nouvel emplacement de serveur de symboles,

     1. Sélectionnez le symbole + dans la barre d’outils.
     2. Tapez l’URL (http), le partage réseau ou le chemin local du serveur de symboles ou de l’emplacement du symbole dans le champ de texte. La saisie semi-automatique des instructions vous aide à rechercher le format correct.

   outils

   Note

   Seul le dossier spécifié est recherché. Vous devez ajouter des entrées pour tous les sous-dossiers que vous souhaitez rechercher.

   • Pour ajouter un nouvel emplacement de serveur de symboles Azure DevOps :

     1. Sélectionnez l’icône dans la barre d’outils.

     2. Dans la boîte de dialogue Se connecter au serveur de symboles Azure DevOps, choisissez l’un des serveurs de symboles disponibles, puis sélectionnez Se connecter.

        Pour plus d'informations, voir Ajout du serveur de symboles Azure Artifacts.

   • Pour modifier l’ordre de chargement des emplacements des symboles, utilisez Ctrl+Haut et Ctrl+Bas, ou les icônes flèche Haut et Bas.

   • Pour modifier une URL ou un chemin d’accès, double-cliquez sur l’entrée, ou sélectionnez-la, puis appuyez sur F2 .

   • Pour supprimer une entrée, sélectionnez-la, puis sélectionnez l’icône -.

3. (Facultatif) Pour améliorer les performances de chargement des symboles, sous symboles cache dans ce répertoire, tapez un chemin d’accès de dossier local vers lequel les serveurs de symboles peuvent copier des symboles.

Remarque

Ne placez pas le cache de symboles locaux dans un dossier protégé, comme C :\Windows ou un sous-dossier. Utilisez plutôt un dossier en lecture-écriture.

Remarque

Si vous avez défini la variable d’environnement _NT_SYMBOL_PATH, elle remplace la valeur définie sous symboles cache dans ce répertoire.

4. Spécifiez les modules que vous souhaitez que le débogueur charge à partir des emplacements du fichier de symboles (.pdb) au démarrage.

   • Sélectionnez Choisir automatiquement les symboles de module à rechercher (recommandé) pour permettre à Visual Studio de décider quels symboles rechercher et charger. Par défaut, Visual Studio charge automatiquement les symboles générés par votre solution ouverte et charge tous les symboles supplémentaires nécessaires pour effectuer des opérations de débogage courantes. Cela réduit le nombre de fichiers qui doivent être recherchés et chargés par Visual Studio, ce qui améliore les performances du débogueur. Pour forcer le chargement de symboles supplémentaires, cliquez sur le lien Spécifier les filtres de module.

   • Sélectionnez Rechercher tous les symboles des modules, sauf ceux qui sont exclus, pour forcer Visual Studio à charger tous les symboles dans votre processus débogué. Cela n’est pas recommandé, car il peut ralentir votre expérience de débogage. Si vous sélectionnez cette option, vous pouvez forcer Visual Studio à ignorer certains symboles en cliquant sur le lien Spécifier les filtres de module.

5. Sélectionnez OK.

Spécifier des filtres de module

Les options Choisir automatiquement les symboles de module à rechercher et Rechercher tous les symboles de module sauf exclusion vous permettent de contrôler plus précisément les symboles recherchés lors du débogage. Choisissez Spécifier des filtres de module pour affiner votre expérience.

Par défaut, la boîte de dialogue suivante s'affiche lorsque l'option Choisir automatiquement les symboles de module à rechercher est sélectionnée :

Vous pouvez ajouter un module au filtre à l’aide de l’icône « + ». Les filtres de module prennent en charge la correspondance simple de caractères génériques. Un « * » correspond à n’importe quel groupe de caractères. Par exemple , '*myproduct*' correspond à des fichiers tels que 'myproduct.utilities.dll' et 'entrypoint.myproduct.exe', entre autres.

Il existe plusieurs options supplémentaires pour personnaliser davantage votre expérience :

• Toujours charger des symboles situés à côté des modules indique à Visual Studio de charger les fichiers pdb stockés dans le système de fichiers à côté de leurs fichiers .dll ou .exe correspondants. Cela peut être utile, par exemple, lors de la tentative de débogage d’une application web déployée.

• Chargement automatique de symboles supplémentaires quand nécessaire ordonne à Visual Studio de rechercher des symboles pour effectuer des actions de débogage courantes, telles qu'avancer pas à pas, même si le module que vous voulez explorer n’est pas dans votre projet ou dans le filtre des modules. La façon dont la recherche est déterminée peut être affectée par vos paramètres Just My Code.

Si vous avez sélectionné Rechercher tous les symboles de module sauf exclusion, la boîte de dialogue de filtre de module ressemble à ceci :

Dans cette boîte de dialogue, vous pouvez choisir les modules pour lesquels vous ne souhaitez pas que Visual Studio charge les symboles. Dans ce scénario, Visual Studio tente de charger des symboles pour chaque module de vos processus débogués (y compris les modules par des tiers), sauf si vous ajoutez un filtre correspondant pour les exclure. Le seul autre moyen de modifier ce comportement réside dans vos paramètres Just My Code.

Autres options de symboles pour le débogage

Vous pouvez sélectionner des options de symboles supplémentaires dans Outils>Options>Débogage> Général (ou Débogage>Options>Général) :

• Charger des exportations dll (native uniquement)

  Charge les tables d’exportation DLL pour C/C++. Pour plus d'informations, consultez les tables d’exportation de DLL . La lecture des informations d’exportation DLL implique une surcharge, de sorte que le chargement des tables d’exportation est désactivé par défaut. Vous pouvez également utiliser dumpbin /exports dans une ligne de commande de build C/C++.

• Activer le débogage au niveau de l’adresse et Afficher le désassemblement si la source n’est pas disponible

  Affiche toujours le désassemblement lorsque les fichiers sources ou de symboles sont introuvables.

  Options

• Activer la prise en charge du serveur source

  Utilise le serveur source pour aider à déboguer une application lorsqu’il n’existe aucun code source sur l’ordinateur local, ou que le fichier .pdb ne correspond pas au code source. Le serveur source accepte les demandes de fichiers et retourne les fichiers réels à partir du contrôle de code source. Le serveur source s’exécute à l’aide d’une DLL nommée srcsrv.dll pour lire le fichier .pdb de l’application. Le fichier .pdb contient des pointeurs vers le référentiel de code source, ainsi que des commandes utilisées pour récupérer le code source à partir du référentiel.

  Vous pouvez limiter les commandes que srcsrv.dll pouvez exécuter à partir du fichier .pdb de l’application en répertoriant les commandes autorisées dans un fichier nommé srcsrv.ini. Placez le fichier srcsrv.ini dans le même dossier que srcsrv.dll et devenv.exe.

  Important

  Les commandes arbitraires peuvent être incorporées dans le fichier .pdb d’une application. Veillez donc à placer uniquement les commandes que vous souhaitez exécuter dans un fichier srcsrv.ini . Toute tentative d’exécution d’une commande non dans le fichier srcsvr.ini entraîne l’affichage d’une boîte de dialogue de confirmation. Pour plus d’informations, consultez Avertissement de sécurité : le débogueur doit exécuter une commande non approuvée.

  Aucune validation n’est effectuée sur les paramètres de commande. Soyez donc prudent avec les commandes approuvées. Par exemple, si vous avez répertorié cmd.exe dans votre srcsrv.ini, un utilisateur malveillant peut spécifier des paramètres sur cmd.exe qui le rendent dangereux.

  Sélectionnez cet élément et les éléments enfants souhaités. Autoriser le serveur source pour les assemblies d’approbation partielle (gérés uniquement) et toujours exécuter des commandes de serveur source non approuvées sans demander confirmation peut augmenter les risques de sécurité.

  

Options de symbole du compilateur

Lorsque vous générez un projet depuis l'IDE Visual Studio avec la configuration de build standard Debug, les compilateurs C++ et gérés créent les fichiers de symboles appropriés pour votre code. Vous pouvez également définir des options de compilateur dans le code.

Pour définir les options du compilateur pour vos configurations de build dans Visual Studio, consultez Définir les configurations de débogage et de mise en production.

Options .NET

Générez avec /debug pour créer un fichier .pdb. Vous pouvez créer des applications avec /debug :full ou /debug :pdbonly. La génération avec /debug:full génère du code pouvant être débogué. La génération avec /debug:pdbonly permet d’obtenir des fichiers .pdb, mais ne génère pas le DebuggableAttribute indiquant au compilateur JIT que des informations de débogage sont disponibles. Utilisez /debug:pdbonly si vous souhaitez générer des fichiers .pdb pour une compilation de version de production que vous ne souhaitez pas rendre déboguable. Pour plus d’informations, consultez /debug (options du compilateur C#) ou /debug (Visual Basic).

Options pour C/C++

• Fichiers VC<x>.pdb et <project>.pdb

  Un fichier .pdb pour C/C++ est créé lorsque vous générez avec /ZI ou /Zi. Dans Visual C++, l’option /Fd nomme le fichier .pdb créé par le compilateur. Lorsque vous créez un projet dans Visual Studio à l’aide de l’IDE, l’option /Fd est définie pour créer un fichier .pdb nommé <projet>.pdb.

  Si vous générez votre application C/C++ à l’aide d’un makefile et que vous spécifiez /ZI ou /Zi sans utiliser /Fd pour spécifier un nom de fichier, le compilateur crée deux fichiers .pdb :

  • vc<x>.pdb, où <x> représente la version du compilateur Microsoft C++, par exemple VC11.pdb

    Le fichier VC<x>.pdb stocke toutes les informations de débogage des fichiers objet individuels et réside dans le même répertoire que le makefile du projet. Chaque fois qu’il crée un fichier objet, le compilateur C/C++ fusionne les informations de débogage dans VC<x>.pdb. Ainsi, même si chaque fichier source inclut des fichiers d’en-tête courants tels que <windows.h>, les typesdefs de ces en-têtes ne sont stockés qu’une seule fois, plutôt que dans chaque fichier objet. Les informations insérées incluent des informations de type, mais n’incluent pas d’informations sur les symboles, telles que les définitions de fonction.

  • <projet>.pdb

    Le fichier .pdb du projet<>stocke toutes les informations de débogage pour le fichier .exe du projet et réside dans le sous-répertoire \debug. Le fichier .pdb du projet <> contient des informations de débogage complètes, y compris des prototypes de fonction, pas seulement les informations de type trouvées dans VC<x>.pdb.

  Les fichiers VC<x>.pdb et <projet>.pdb autorisent les mises à jour incrémentielles. L’éditeur de liens incorpore également le chemin d’accès aux fichiers .pdb dans le fichier .exe ou .dll qu’il crée.

• Tables d’exportation DLL

  Utilisez dumpbin /exports pour afficher les symboles disponibles dans la table d’exportation d’une DLL. Les informations symboliques des tables d’exportation DLL peuvent être utiles pour utiliser des messages Windows, des procédures Windows (WindowProcs), des objets COM, un marshaling ou toute DLL pour laquelle vous n’avez pas de symboles. Les symboles sont disponibles pour n’importe quelle DLL système 32 bits. Les appels sont répertoriés dans l’ordre d’appel, avec la fonction actuelle (la plus profondément imbriquée) en haut.

  En lisant la sortie dumpbin /exports, vous pouvez voir les noms de fonction exacts, y compris les caractères non alphanumériques. L’affichage des noms de fonction exacts est utile pour définir un point d’arrêt sur une fonction, car les noms de fonction peuvent être tronqués ailleurs dans le débogueur. Pour plus d’informations, consultez dumpbin /exports.

Applications Web

Définissez le fichier web.config de votre application ASP.NET en mode débogage. Le mode débogage entraîne la génération de symboles ASP.NET pour les fichiers générés dynamiquement et permet au débogueur de s’attacher à l’application ASP.NET. Visual Studio définit cette valeur automatiquement lorsque vous commencez à déboguer, si vous avez créé votre projet à partir du modèle de projets web.

Charger des symboles lors du débogage

Vous pouvez utiliser les fenêtres Modules, Pile des appels, Variables locales, Auto, ou n’importe quelle fenêtre Espion pour charger des symboles ou modifier les options de symboles pendant le débogage. Pour plus d’informations, consultez Familiarisez-vous avec la façon dont le débogueur s’attache à votre application.

Utiliser des symboles dans la fenêtre Modules

Pendant le débogage, la fenêtre Modules affiche les modules de code que le débogueur traite en tant que code utilisateur ou Mon code et leur état de chargement de symboles. Vous pouvez également surveiller l’état de chargement des symboles, charger des symboles et modifier les options de symboles dans la fenêtre modules.

Pour surveiller ou modifier les emplacements ou options des symboles lors du débogage :

1. Pour ouvrir la fenêtre Modules, lors du débogage, sélectionnezDéboguer>Windows>Modules (ou appuyez surCtrl + Alt + U).
2. Dans la fenêtre Modules, cliquez avec le bouton droit sur les en-têtes Statut des symboles ou Fichier de symboles, ou sur n’importe quel module.
3. Dans le menu contextuel, sélectionnez l’une des options suivantes :

Option	Description
Charger les symboles	S’affiche pour les modules avec des symboles ignorés, introuvables ou non chargés. Tente de charger des symboles à partir d’emplacements spécifiés dans la page Options>Débogage>Symboles. Si le fichier de symboles n’est pas trouvé ou n’est pas chargé, lance Explorateur de fichiers afin de pouvoir spécifier un nouvel emplacement à rechercher.
Informations sur le chargement de symboles	Affiche l’emplacement d’un fichier de symboles chargé ou les emplacements qui ont été recherchés si le débogueur ne trouve pas le fichier.
Paramètres des symboles	Ouvre la page Options>Débogage>Symboles, où vous pouvez modifier et ajouter des emplacements de symboles.
Toujours charger automatiquement	Ajoute le fichier de symboles sélectionné à la liste des fichiers qui sont automatiquement chargés par le débogueur.

Utilisez les pages Aucun symbole chargé/ Aucune source chargée

Il existe plusieurs façons pour le débogueur de s’introduire dans un code qui ne dispose pas de fichiers de symboles ou de sources :

• Effectuez un pas à pas détaillé dans le code.
• Interrompez le code à partir d’un point d’arrêt ou d’une exception.
• Basculez vers un autre thread.
• Modifiez le frame de pile en double-cliquant sur un frame dans la fenêtre Pile des appels.

Lorsque cela se produit, le débogueur affiche les pages Aucun symbole chargé ou Aucune source chargée pour vous aider à trouver et charger les symboles ou les sources nécessaires.

page

Pour utiliser la page de document "Aucun symbole chargé" afin de rechercher et charger les symboles manquants :

• Pour modifier le chemin de recherche, sélectionnez un chemin d’accès non sélectionné, ou sélectionnez nouveau chemin d’accès ou nouveau chemin D’accès VSTS, puis entrez ou sélectionnez un nouveau chemin d’accès. Sélectionnez Charger pour rechercher à nouveau les chemins et charger le fichier de symboles s’il est trouvé.
• Pour remplacer les options de symboles et réessayer les chemins de recherche, sélectionnez Parcourir et rechercher <le nom exécutable>. Le fichier de symboles est chargé s'il est trouvé, ou l'Explorateur de fichiers s'ouvre pour que vous puissiez sélectionner manuellement le fichier de symboles.
• Pour ouvrir la page des paramètres de symbole pour configurer le comportement, sélectionnez Modifier les paramètres de symboles (ou choisissez Options>Débogage>Symboles).
• (Avancé) Pour afficher le désassemblement dans une nouvelle fenêtre une seule fois, sélectionnez afficher le désassemblement, ou sélectionnez boîte de dialogue Options pour définir l’option permettant de toujours afficher le désassemblement lorsque les fichiers source ou symbole ne sont pas trouvés. Pour plus d’informations, consultez Afficher le code de désassemblement.
• Pour afficher les emplacements recherchés et le résultat, développez Informations de chargement des symboles.
• Pour le code C#, vous pouvez également choisir de décompiler le code source à partir des pages Aucun symbole chargé ou Aucune source chargée.

Si le débogueur trouve le fichier .pdb après avoir exécuté l’une des options et peut récupérer le fichier source à l’aide des informations contenues dans le fichier .pdb, il affiche la source. Sinon, une page Aucune source chargée s’affiche, décrivant le problème et contenant des liens vers des actions susceptibles de résoudre le problème.

Pour ajouter des chemins de recherche de fichiers sources à une solution :

Vous pouvez spécifier les emplacements où le débogueur recherche des fichiers sources et exclure des fichiers spécifiques de la recherche.

1. Sélectionnez la solution dans l’Explorateur de solutions, puis sélectionnez l’icône Propriétés , appuyez sur Alt+Entrée, ou faites un clic droit, puis sélectionnez Propriétés.

2. Sélectionnez Déboguer les fichiers sources.

   

3. Sous les répertoires contenant du code source, tapez ou sélectionnez des emplacements de code source à rechercher. Utilisez l’icône Nouvelle ligne pour ajouter d’autres emplacements, l’icône flèche vers le haut et l’icône flèche vers le bas pour les réorganiser, ou l’icône X pour les supprimer.

   Note

   Le débogueur recherche uniquement le répertoire spécifié. Vous devez ajouter des entrées pour tous les sous-répertoires que vous souhaitez rechercher.

4. Sous Ne recherchez pas ces fichiers sources, tapez les noms des fichiers sources à exclure de la recherche.

5. Sélectionnez OK ou Appliquer.

Contenu connexe

• Comprendre les fichiers de symboles et les paramètres de symbole Visual Studio