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

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

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

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

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

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

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

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

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

Совет

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

Расположение файлов символов и поведение при загрузке

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

Примечание

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

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

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

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

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

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

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

    • Указанные серверы и расположения символов — локальные, сетевые или в Интернете — такие как серверы символов корпорации Майкрософт, если эта возможность включена. 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), сетевую папку или локальный путь к серверу символов или расположению символов. Завершение операторов помогает найти правильный формат.

      Страница "Сервис - Параметры - Отладка - Символы"

      Примечание

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

    • Добавление нового расположения сервера символов VSTS:

      1. Выберите "Сервис / Параметры / Отладка / Символы" и щелкните значок нового сервера на панели инструментов.
      2. В диалоговом окне Подключение к серверу символов VSTS выберите один из доступных серверов символов и щелкните Подключить.
    • Чтобы изменить порядок загрузки для расположений символов, используйте клавиши 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 вызовет диалоговое окно подтверждения. Дополнительные сведения см. в статье Предупреждение системы безопасности. Отладчик должен выполнить команду без доверия.

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

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

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

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

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

Параметры .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 и <project>.pdb

    PDB-файл для C/C++ создается при сборке с параметрами /ZI или /Zi. В Visual C++ параметр /Fd присваивает имя PDB-файлу, который создается компилятором. При создании проекта в Visual Studio с использованием интегрированной среды разработки используется параметр /Fd с целью создания PDB-файла с именем <project>.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) из этих заголовков сохраняются только один раз, а не включаются в каждый объектный файл. Вставляемая информация включает информацию о типах, но не включает символьную информацию, такую как определения функций.

    • <project>.pdb

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

    Файлы VC<x>.pdb и <project>.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 и введите или выберите новый путь. Выберите Загрузить, чтобы повторить поиск в путях и загрузить файл символов, если он будет найден.
  • Выберите Обзор для поиска <executable-name> , чтобы переопределить все параметры символов и повторить поиск по выбранным путям. Если файл символов будет найден, он будет загружен, иначе отобразится Проводник, в котором можно вручную выбрать файл символов.
  • Чтобы открыть страницу параметров символов для настройки поведения, выберите Изменить параметры символов (или Параметры > Отладка > Символы).
  • (Дополнительно.) Чтобы однократно отобразить дизассемблированный код в новом окне, выберите Просмотреть дизассемблированный код. Чтобы всегда отображать дизассемблированный код, если файл символов или исходный файл не найдены, перейдите в диалоговое окно Параметры и установите соответствующий параметр. Дополнительные сведения см. в статье Просмотр дизассемблированного кода в отладчике Visual Studio (C#, C++, Visual Basic, F#).
  • Чтобы отображать расположения, в которых был выполнен поиск, и результаты поиска, разверните элемент Сведения о загрузке символов.
  • Для кода C# можно также выполнить декомпиляцию исходного кода из страниц Символы не загружены или Нет исходного кода.

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

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

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

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

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

    Страница отладки исходных файлов

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

    Примечание

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

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

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

См. также