Указание файлов символов (PDB) и исходных файлов в отладчике Visual Studio (C#, C++, Visual Basic, F#)

Файлы базы данных программ (PDB) также называются файлами символов и используются для сопоставления идентификаторов и инструкций в исходном коде вашего проекта с соответствующими идентификаторами и инструкциями в скомпилированных приложениях. С помощью этих файлов отладчик связывается с исходным кодом, что позволяет выполнять его отладку.

При создании проекта из интегрированной среды разработки Visual Studio со стандартной конфигурацией отладочной сборки компилятор создает необходимые файлы символов. В этой статье описывается, как управлять файлами символов в интегрированной среде разработки, а именно:

• Настройка расположения файлов символов
• Загрузка символов при отладке
• Параметры компилятора для символов

Подробные сведения о файлах символов см. в следующих статьях:

• Общие сведения о файлах символов и параметрах символов Visual Studio

Принципы использования файлов символов

PDB-файл содержит отладочные данные и сведения о состоянии проекта, позволяющие выполнять инкрементную компоновку отладочной конфигурации приложения. Отладчик Visual Studio использует PDB-файлы для определения двух ключевых элементов информации во время отладки:

• Имя исходного файла и номер строки, которая отображается в интегрированной среде разработки Visual Studio.
• Расположение точки останова в приложении.

В файлах символов также указываются расположение исходных файлов и при необходимости сервер, с которого они будут извлекаться.

Отладчик загружает только те PDB-файлы, которые точно соответствуют PDB-файлам, созданным при построении приложения (то есть исходные PDB-файлы или их копии). Точное дублирование является обязательным, поскольку компоновка приложения может быть изменена даже в том случае, если сам код не изменялся. Дополнительные сведения см. в статье Почему Visual Studio требует, чтобы файлы символов отладчика точно соответствовали двоичным файлам, с которыми они были собраны?

Совет

Если требуется выполнить отладку кода за пределами исходного кода проекта, например кода Windows или стороннего кода, вызываемого проектом, необходимо указать расположение PDВ-файлов (и, если необходимо, исходных файлов) для внешнего кода, причем эти файлы должны точно соответствовать сборкам вашего приложения.

Места, в которых отладчик ищет символы

При отладке проекта в интегрированной среде разработки Visual Studio отладчик автоматически загружает файлы символов, которые он может найти по умолчанию.

Примечание.

При отладке управляемого кода на удаленном устройстве все необходимые файлы символов должны находиться либо на локальном компьютере, либо в расположении, указанном в параметрах отладчика.

Отладчик ищет файлы символов в следующих местах:

1. Папка проекта

2. Расположение, указанное в библиотеке DLL или в исполняемом файле (EXE).

   По умолчанию, если на компьютере производится сборка библиотеки DLL или исполняемого файла (EXE), компоновщик помещает полный путь и имя связанного PDB-файла в библиотеку DLL или в EXE-файл. Отладчик проверяет, присутствует ли файл символов в этом расположении.

3. Папка, в которой располагается сам DLL- или EXE-файл.

4. Любые расположения, указанные в параметрах отладчика для файлов символов. Сведения о добавлении и активации расположений символов см. в разделе Настройка расположения символов и параметров загрузки.

   • Любая папка локального кэша символов.

   • Указанные серверы и расположения символов — локальные, сетевые или в Интернете — такие как серверы символов корпорации Майкрософт, если эта возможность включена. Visual Studio может загружать файлы отладочных символов с серверов символов, которые реализуют протокол symsrv. Visual Studio Team Foundation Server и средства отладки для Windows — это два средства, которые могут использовать серверы символов.

     Возможно использование следующих серверов символов:

     Общедоступные серверы символов Майкрософт: для отладки сбоя, возникающего во время вызова системной библиотеки DLL или в стороннюю библиотеку, часто требуется системные PDB-файлы . Системные PDB-файлы содержат символьные данные для библиотек DLL, EXE-файлов и драйверов устройств Windows. Символы для операционных систем Windows, MDAC, IIS, ISA и .NET можно получить с общедоступных серверов символов корпорации Майкрософт.

     Серверы символов в внутренней сети или на локальном компьютере: ваша команда или компания могут создавать серверы символов для собственных продуктов и в качестве кэша для символов из внешних источников. Можно иметь сервер символов на собственном компьютере.

     Сторонние серверы символов: сторонние поставщики приложений и библиотек Windows могут предоставлять доступ к серверу символов в Интернете.

     Предупреждение

     При использовании сервера символов, отличного от общедоступных серверов корпорации Майкрософт, следует убедиться в том, что сервер и его путь заслуживают доверия. Поскольку файлы символов могут содержать произвольный исполняемый код, возможно возникновение угроз безопасности.

Настройка расположения файлов символов и параметров загрузки

По умолчанию отладчик выполняет поиск в различных расположениях символов. См. раздел Места, в которых отладчик ищет символы.

На странице Сервис>Параметры>Отладка>Символы можно выполнить следующие действия.

• Укажите и выберите пути поиска для файлов символов.
• Укажите серверы символов для Майкрософт, Windows или сторонних компонентов.
• Указать модули, для которых отладчик будет или не будет автоматически загружать символы.
• Эти параметры можно изменять во время выполнения отладки. См. раздел Загрузка символов при отладке.

Указание расположения символов и параметров загрузки:

1. В Visual Studio откройте меню Сервис>Параметры>Отладка>Символы (или Отладка>Параметры>Символы).

2. В разделе Места размещения файлов символов (.pdb):

   • Установите соответствующий флажок, чтобы использовать Серверы символов (Майкрософт) или Сервер символов NuGet.org.

   • Чтобы добавить новое расположение сервера символов:

     1. Щелкните символ + на панели инструментов.
     2. Укажите в текстовом поле URL-адрес (http), сетевую папку или локальный путь к серверу символов или расположению символов. Завершение операторов помогает найти правильный формат.

     

     Примечание.

     Поиск выполняется только в указанной папке. Любые вложенные папки, в которых требуется осуществлять поиск, должны быть внесены в список.

   • Чтобы добавить новое расположение сервера символов Azure DevOps, выполните приведенные действия.

     1. Выберите значок на панели инструментов.

     2. В диалоговом окне Подключение в сервер символов Azure DevOps выберите один из доступных серверов символов и выберите Подключение.

        Дополнительные сведения см. в разделе "Добавление сервера символов артефактов Azure".

   • Чтобы изменить порядок загрузки для расположений символов, используйте клавиши CTRL+СТРЕЛКА ВВЕРХ и CTRL+СТРЕЛКА ВНИЗ либо значки со стрелками вверх и вниз.

   • Чтобы изменить URL-адрес или путь, дважды щелкните элемент или выберите его и нажмите клавишу F2.

   • Чтобы удалить элемент, выделите его и щелкните значок -.

3. Необязательно: чтобы повысить производительность загрузки символов, перейдите в раздел Кэшировать символы в этом каталоге и введите путь к локальной папке, в которую серверы символов могут копировать символы.

   Примечание.

   Не размещайте локальный кэш символов в защищенной папке, такой как C:\Windows или вложенные папки. Вместо этого следует использовать папку, для которой разрешены чтение и запись.

   Примечание.

   Если для проекта C++ задана переменная среды _NT_SYMBOL_PATH, она переопределяет значение, заданное в разделе Кэшировать символы в этом каталоге.

4. Укажите модули, которые отладчик должен загружать из расположений файлов символов (. pdb) при запуске.

   • Выберите Все модули, кроме исключенных (значение по умолчанию), чтобы загружать все символы для всех модулей, кроме тех, что были явно исключены. Чтобы исключить конкретные модули, выберите Укажите исключенные модули, щелкните значок +, введите имена исключаемых модулей и нажмите кнопку ОК.

   • Чтобы загружать из расположений файлов символов только заданные модули, выберите Загружать только указанные модули. Выберите Укажите включенные модули, щелкните значок +, введите имена включаемых модулей и нажмите кнопку ОК. Файлы символов для других модулей не загружаются.

5. Нажмите ОК.

Другие параметры символов для отладки

Для настройки дополнительных параметров символов перейдите в раздел Сервис>Параметры>Отладка>Общие (или Отладка>Параметры>Общие):

• Загружать экспорты из DLL (только машинный код)

  Загружает таблицы экспорта библиотеки DLL для C/C++. Дополнительные сведения см. в разделе Таблицы экспорта библиотеки DLL. Поскольку на чтение данных экспорта для библиотеки DLL затрачиваются определенные ресурсы, по умолчанию загрузка таблиц экспорта отключена. Кроме того, вы можете использовать dumpbin /exports в командной строке сборки C/C++.

• Включить отладку на уровне адреса и Показывать дизассемблированный код, если исходный код недоступен

  Дизассемблированный код отображается во всех случаях, когда исходные файлы или файлы символов не найдены.

  

• Включить поддержку сервера системы управления версиями

  Если исходный код на локальном компьютере отсутствует или PDB-файл не соответствует исходному коду, при отладке приложения используется сервер системы управления версиями. Сервер системы управления версиями принимает запросы на файлы и возвращает сами файлы из этой системы. Сервер системы управления версиями использует для работы библиотеку srcsrv.dll, которая нужна для чтения PDB-файла приложения. Этот PDB-файл содержит указатели на репозиторий исходного кода, а также команды, используемые для получения исходного кода из репозитория.

  Чтобы ограничить набор команд, которые библиотека srcsrv.dll может исполнять из PDB-файла приложения, можно включить список допустимых команд в файл srcsrv.ini. Поместите файл srcsrv.ini в ту же папку, что и файлы srcsrv.dll и devenv.exe.

  Важно!

  В PDB-файл приложения можно внедрять произвольные команды, поэтому убедитесь, что в файл srcsrv.ini включены только те из них, которые требуется выполнять. Любая попытка выполнить команду не из файла srcsvr.ini вызовет диалоговое окно подтверждения. Для получения дополнительной информации см. Security Warning: Debugger Must Execute Untrusted Command.

  Параметры команд не проверяются, поэтому будьте внимательны с доверенными командами. Например, если вы включили команду cmd.exe в файл srcsrv.ini, пользователь-злоумышленник может указать параметры, которые сделают выполнение команды cmd.exe опасным.

  Выберите этот элемент и нужные дочерние элементы. Параметры Разрешить выполнение частично доверенных сборок (только управляемых) на сервере системы управления версиями и Всегда выполнять ненадежные команды исходного сервера без запроса могут повысить риски безопасности, описанные выше.

  

Параметры символов для компилятора

Если при выполнении сборки проекта из интегрированной среды разработки Visual Studio используется стандартная конфигурация сборки Отладка, компилятор C++ и управляемые компиляторы создают соответствующие файлы символов для кода. Параметры компилятора также можно задать в коде.

Сведения о настройке параметров компилятора для конфигураций сборки в Visual Studio см. в статье Настройка конфигураций отладки и выпуска в Visual Studio.

Параметры .NET

Выполните сборку с использованием параметра /debug, чтобы создать PDB-файл. Можно строить приложения с ключом /debug: full или /debug: pdbonly. При построении с ключом /debug:full создается отлаживаемый код. При сборке с ключом /debug:pdbonly создаются PDB-файлы, но не создается DebuggableAttribute, сообщающий JIT-компилятору о доступности отладочной информации. Ключ /debug:pdbonly следует использовать при создании PDB-файла для сборки выпуска, которая не подлежит отладке. Дополнительные сведения см. в разделе /debug (параметры компилятора C#) или /debug (Visual Basic).

Параметры C/C++

• Файлы VC<x>.pdb и <проект>.pdb

  PDB-файл для C/C++ создается при сборке с параметрами /ZI или /Zi. В Visual C++ параметр /Fd присваивает имя PDB-файлу, который создается компилятором. При создании проекта в Visual Studio с использованием интегрированной среды разработки параметр /Fd задается для создания PDB-файла с именем <проект>.pdb.

  Если вы создаете приложение C/C++ с помощью файла makefile и указываете /ZI или /Zi без использования /Fd для указания имени файла, компилятор создает два PDB-файла :

  • VC<x>.pdb, где <x> представляет версию компилятора Microsoft C++, например VC11.pdb.

    Файл VC<x>.pdb хранит все отладочные данные для отдельных объектных файлов и располагается в том же каталоге, что и файл makefile проекта. Каждый раз, создавая объектный файл, компилятор C/C++ добавляет отладочную информацию в файл VC<x>.pdb. Поэтому даже если исходный файл включает общие файлы заголовков, такие как <windows.h>, определения типов (typedef) из этих заголовков сохраняются только один раз, а не включаются в каждый объектный файл. Вставляемая информация включает информацию о типах, но не включает символьную информацию, такую как определения функций.

  • <проект>.pdb

    Файл <проект>.pdb хранит все отладочные данные из EXE-файла проекта и располагается в подкаталоге \debug. Файл <проект>.pdb содержит полные отладочные данные, включая прототипы функций, а не только сведения о типах, содержащиеся в VC<x>.pdb.

  Файлы VC<x>.pdb и <проект>.pdb поддерживают добавочные обновления. Компоновщик также включает путь к PDB-файлам в EXE-файл или DLL-файл, которые он создает.

• Таблицы экспорта библиотеки DLL

  Чтобы посмотреть, какие символы доступны в таблице экспорта для библиотеки DLL, воспользуйтесь командой dumpbin /exports. Символьные данные из таблиц экспорта библиотеки DLL могут быть полезны при работе с сообщениями Windows, процедурами Windows (WindowProcs), объектами COM, при маршалинге или при работе с любой библиотекой DLL, для которой нет символов. Символы доступны для любой 32-разрядной системной библиотеки DLL. Вызовы функций перечисляются в том порядке, в котором эти функции вызываются, при этом текущая функция (наиболее глубоко вложенная) располагается наверху.

  В выходных данных команды dumpbin /exports можно увидеть точное имя функции, включая символы, отличные от буквенно-цифровых. Просмотр точных имен функций полезен для задания точки останова в функции, поскольку в отладчике имена функций могут быть усечены в других местах. Дополнительные сведения см. в разделе dumpbin /exports.

Веб-приложения

Задайте для файла web.config вашего приложения ASP.NET режим отладки. В режиме отладки ASP.NET создает символы для динамически созданных файлов и включает присоединение отладчика к приложению ASP.NET. Если проект создан на основе шаблона веб-проектов, Visual Studio устанавливает этот режим автоматически при запуске отладки.

Загрузка символов при отладке

Для загрузки символов или изменения параметров символов во время отладки можно использовать окна Модули, Стек вызовов, Локальные, Видимые или Контрольные значения. Дополнительные сведения см. в разделе Дополнительные сведения о присоединении отладчика к приложению.

Работа с символами в окне "Модули"

В процессе отладки в окне Модули можно узнать, какие модули будут рассматриваться отладчиком в качестве пользовательского кода (или "моего кода"), а также проверить состояние загрузки символов для них. Кроме того, в окне Модули вы можете отслеживать состояние загрузки символов, загружать символы и изменять параметры символов.

Отслеживание или изменение расположений и параметров символов во время отладки:

1. Чтобы открыть окно Модули во время отладки, выберите Отладка>Окна>Модули (или нажмите клавиши CTRL + ALT + U).
2. В окне Модули щелкните правой кнопкой мыши заголовки Состояние символов или Файл символов либо любой модуль.
3. В контекстном меню выберите один из следующих вариантов:

Параметр	Описание
Загрузить символы	Отображается для модулей с пропущенными, не найденными или не загруженными символами. Пытается загрузить символы из расположений, указанных на странице Параметры>Отладка>Символы. Если файл символов не удается обнаружить или загрузить, запускается Проводник, с помощью которого можно указать новое расположение для поиска.
Сведения о загрузке символов	Отображает сведения о расположении загруженного файла символов или о расположениях, в которых производился поиск, если отладчику не удалось найти файл.
Параметры символов	Открывает страницу Параметры>Отладка>Символы, на которой можно изменять и добавлять расположения символов.
Всегда загружать автоматически	Добавляет выбранный файл символов в список файлов, которые автоматически загружаются отладчиком.

Использование страниц "Символы не загружены" или "Нет исходного кода"

Отладчик может прервать выполнение в коде, для которого отсутствуют файлы символов или исходные файлы, в результате любого из следующих событий:

• Шаг с заходом в код.
• Приостановка выполнения кода из-за точки останова или исключения.
• Переключение на другой поток.
• Изменение кадра стека двойным щелчком по кадру в окне Стек вызовов.

Когда происходит любое из этих событий, отладчик отображает страницу Символы не загружены или Нет исходного кода, чтобы помочь найти и загрузить необходимые символы или исходный код.

Использование страницы "Символы не загружены" для поиска и загрузки отсутствующих символов:

• Чтобы изменить путь поиска, выберите незанятый путь, либо выберите Новый путь или Новый путь VSTS и введите или выберите новый путь. Выберите Загрузить, чтобы повторить поиск в путях и загрузить файл символов, если он будет найден.
• Выберите Обзор и поиск <имя_исполняемого_файла>, чтобы переопределить все параметры символов и повторить поиск по выбранных путям. Если файл символов будет найден, он будет загружен, иначе отобразится Проводник, в котором можно вручную выбрать файл символов.
• Чтобы открыть страницу параметров символов для настройки поведения, выберите Изменить параметры символов (или Параметры>Отладка>Символы).
• (Дополнительно.) Чтобы однократно отобразить дизассемблированный код в новом окне, выберите Просмотреть дизассемблированный код. Чтобы всегда отображать дизассемблированный код, если файл символов или исходный файл не найдены, перейдите в диалоговое окно Параметры и установите соответствующий параметр. Дополнительные сведения см. в статье Просмотр дизассемблированного кода в отладчике Visual Studio (C#, C++, Visual Basic, F#).
• Чтобы отображать расположения, в которых был выполнен поиск, и результаты поиска, разверните элемент Сведения о загрузке символов.
• Для кода C# можно также выполнить декомпиляцию исходного кода из страниц Символы не загружены или Нет исходного кода.

Если отладчик находит PDB-файл после выполнения одного из этих действий и может извлечь исходный файл на основании информации в PDB-файле, отображается исходный код. В противном случае отображается страница Нет исходного кода, на которой описывается проблема и приводятся ссылки на действия, которые могут решить ее.

Добавление путей поиска исходных файлов в решение:

Вы можете указать расположения, в которых отладчик будет искать исходные файлы, а также исключить из поиска определенные файлы.

1. Выберите решение в обозревателе решений и затем щелкните значок Свойства, нажмите клавиши ALT+ВВОД либо щелкните это решение правой кнопкой мыши и выберите пункт Свойства.

2. Выберите Исходные файлы отладки.

   

3. В разделе Каталоги, содержащие исходный код введите или выберите расположения исходного кода для поиска. Щелкните значок Новая строка для добавления дополнительных расположений, значки со стрелками вверх и вниз для изменения их порядка либо значок X для их удаления.

   Примечание.

   Отладчик выполняет поиск только в указанном каталоге. Любые подкаталоги, в которых требуется осуществлять поиск, должны быть внесены в список.

4. В разделе Не выполнять поиск следующих исходных файлов введите имена исходных файлов, исключаемых из поиска.

5. Нажмите кнопку ОК или кнопку Применить.

Связанный контент

• Общие сведения о файлах символов и параметрах символов Visual Studio