Spécifiez les fichiers de symbole (.pdb) et de 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 avec la configuration de build 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 :

• Configurez 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

Comment fonctionnent les fichiers de symboles

Le fichier .pdb contient des informations sur le débogage et l’état du projet qui permettent de lier de manière incrémentielle 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 :

• Le nom du fichier source et le numéro de ligne à afficher dans l’IDE Visual Studio.
• Où dans l’application 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 Why does Visual Studio require debugger symbol files to *exactly* match the binary files that they were built with?

Conseil

Pour déboguer du code en dehors du code source de votre projet, tel que le code Windows ou le code tiers que votre projet appelle, 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.

Notes

Lors du débogage du code géré 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. L’emplacement qui est spécifié dans la DLL ou le fichier exécutable (.exe).

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

3. Le 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 local.

   • 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 des 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 pourriez utiliser comprennent :

     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 en tant que cache pour les symboles provenant de sources externes. Vous pouvez avoir un serveur de symboles sur votre propre ordinateur.

     Serveurs de symboles tiers : Les fournisseurs tiers des applications et des 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 publics Microsoft, assurez-vous que le serveur de symboles et son chemin d’accès sont dignes de confiance. Étant donné que les fichiers de symboles peuvent contenir du code exécutable arbitraire, vous pouvez être exposé à des menaces de sécurité.

Configurez 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.
• Indiquez les modules pour lesquels vous voulez ou ne voulez pas que le débogueur charge automatiquement les symboles.
• Modifiez ces paramètres pendant que vous déboguez activement. Consultez Symboles de chargement lors du débogage.

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

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

2. Sous les emplacements des fichiers de symboles (.pdb),

   • Pour utiliser les serveurs de symboles Microsoft ou le serveur de symboles de 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.

     

     Note

     Seul le dossier spécifié est recherché. Vous devez ajouter des entrées pour tous les sous-dossiers à explorer.

   • 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, consultez Ajouter un 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.

   Notes

   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.

   Notes

   Pour les projets C++, si vous avez défini la variable d’environnement _NT_SYMBOL_PATH, elle remplacera la valeur définie sous les 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 Charger tous les modules, sauf s’ils sont exclus (valeur par défaut) pour charger tous les symboles de tous les modules à l’emplacement du fichier de symboles, à l’exception des modules que vous excluez spécifiquement. Pour exclure certains modules, sélectionnez Spécifier les modules exclus, sélectionnez l’icône +, tapez les noms des modules à exclure, puis sélectionnez OK.

   • Pour charger uniquement les modules que vous spécifiez à partir des emplacements du fichier de symboles, sélectionnez Charger uniquement les modules spécifiés. Sélectionnez Spécifier les modules inclus, sélectionnez l’icône +, tapez les noms des modules à inclure, puis sélectionnez OK. Les fichiers de symboles d'autres modules ne sont pas chargés.

5. Sélectionnez OK.

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 les exportations de dll (Natif uniquement)

  Charge les tables d’exportation DLL pour C/C++. Pour plus d’informations, consultez les tables d’exportation DLL. La lecture des informations d’exportation DLL implique une certaine 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++.

• Activez le débogage au niveau de l’adresse et montrez le désassemblage si la source n’est pas disponible

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

  

• 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 prend les demandes de fichiers et renvoie les fichiers réels du contrôle de la 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 peut 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 ne se trouvant pas dans le fichier srcsvr.ini provoque l’apparition d’une boîte de dialogue de confirmation. Pour plus d'informations, consultez Security Warning: Debugger Must Execute Untrusted Command.

  Aucune validation n’est effectuée sur les paramètres de commande, soyez donc prudent avec les commandes de confiance. Par exemple, si vous avez listé cmd.exe dans votre fichier srcsrv.ini, un utilisateur malveillant pourrait spécifier des paramètres sur cmd.exe qui le rendraient dangereux.

  Sélectionnez cet élément et les éléments enfants souhaités. Autoriser le serveur source pour les assemblys de confiance partielle (géré uniquement) et Toujours exécuter les commandes de serveur source non fiables sans demander de confirmation peuvent augmenter les risques de sécurité.

  

Options de symbole du compilateur

Lorsque vous construisez un projet à partir de l'IDE Visual Studio avec la configuration de build Débogage standard, C++ et les compilateurs 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 générer 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 voulez générer des fichiers .pdb pour une version Release sans qu’elle puisse être déboguée. Pour plus d’informations, consultez /debug (Options du compilateur C#) ou /debug (Visual Basic).

Options C/C++

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

  Un fichier .pdb est créé lors de la génération avec /ZI or /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é<project>.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 pour les fichiers d’objets 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. Par conséquent, même si chaque fichier source inclut des fichiers d'en-tête courants tels que <windows.h>, les typedefs de ces en-têtes ne sont stockés qu'une seule fois, au lieu de l'être pour chaque fichier objet. Les informations insérées incluent les informations de type, mais pas les informations de symbole, comme les définitions de fonctions.

  • <project>.pdb

    Le fichier <project>.pdb stocke toutes les informations de débogage pour le fichier .exedu projet et réside dans le sous-répertoire \debug. Le fichier <project>.pdb contient toutes les informations de débogage, y compris les prototypes de fonction, et non pas seulement les informations de type présentes dans VC<x>.pdb.

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

• Tables d’exportation DLL

  Utilisez dumpbin /exports pour voir les symboles disponibles dans la table d’exportation d’une DLL. Les informations symboliques de tables d'exportation de DLL peuvent être utiles pour travailler avec les messages Windows, des procédures Windows (WindowProcs), des objets COM, le marshaling pour laquelle vous n’avez pas de symboles. Il existe des symboles pour toutes les DLL système 32 bits. Les appels sont répertoriés dans l'ordre chronologique inverse, la fonction en cours (la plus profondément imbriquée) apparaissant en tête de liste.

  En lisant la sortie dumpbin /exports, vous pouvez voir les noms exacts des fonctions, y compris les caractères non alphanumériques. Voir les 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. En mode débogage, ASP.NET génère des symboles pour les fichiers générés dynamiquement et le débogueur peut être attaché à l'application ASP.NET. Visual Studio définit cela automatiquement lorsque vous commencez le débogage, si vous avez créé votre projet à partir du modèle de projets web.

Chargez des symboles lors du débogage

Vous pouvez utiliser les fenêtres Modules, Pile des appels, Locals, Autos, ou n’importe quelle fenêtre d’espion pour charger des symboles ou modifier les options de symboles pendant le débogage. Pour plus d’informations, consultez Obtenir plus d’informations sur la façon dont le débogueur s’attache à votre application.

Travailler avec 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 , faites un clic droit sur les en-têtes d’état du symbole ou de 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 est introuvable ou n’est pas chargé, lancez l’Explorateur de fichiers afin de spécifier un nouvel emplacement à rechercher.
Informations sur le chargement de symboles	Affiche l’emplacement d’un fichier de symboles chargé, ou les emplacements ayant fait l'objet d'une recherche 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 No Symbols Loaded/No Source Loaded

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 :

• Entrez dans le code.
• Entrez dans le code à partir d’un point d’arrêt ou d’une exception.
• Basculez vers un autre thread.
• Modifiez le cadre de pile en double-cliquant sur un cadre 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 sources nécessaires.

Pour utiliser la page Aucun symbole chargé pour aider à trouver 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 VSTS, puis entrez ou sélectionnez un nouveau chemin d’accès. Sélectionnez Charger pour rechercher à nouveau les chemins d'accès 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 afin de pouvoir sélectionner manuellement le fichier de symboles.
• Pour ouvrir la page des paramètres de symboles pour configurer le comportement, sélectionnez Modifier les paramètres de symbole (ou choisissez Options>Débogage>de symboles).
• (Avancé) Pour afficher le désassemblage dans une nouvelle fenêtre une fois, sélectionnez Afficher le désassemblage ou sélectionnez la boîte de dialogue Options pour définir l’option pour toujours afficher le désassemblage lorsque les fichiers sources ou symboles ne sont pas trouvés. Pour plus d’informations, consultez Afficher le code désassemblage.
• Pour afficher les emplacements recherchés et le résultat, développez les informations de chargement des symboles.
• Pour le code C#, vous pouvez également choisir de décomposer 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 qu’il peut récupérer le fichier source à l’aide des informations contenues dans le fichier .pdb , il affiche la source. Sinon, il affiche une page Aucune source chargée qui décrit le problème, avec 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 Répertoires contenant le code source, tapez ou sélectionnez des emplacements de code source à rechercher. Utilisez l’icône Nouvelle ligne pour ajouter d’autres emplacements, les icônes flèche haut et bas pour les réorganiser ou l’icône X pour les supprimer.

   Notes

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

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