Путь к символам для отладчиков Windows

Статья
12/13/2024

Путь к символам указывает расположения, в которых отладчики Windows, такие как WinDbg, KD, CDB и NTST, ищут файлы символов. Для получения дополнительной информации о символах и файлах символов см. .

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

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

Совет

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

Синтаксис пути к символам

Путь к символу отладчика — это строка, состоящая из нескольких путей каталога, разделенных точкой с запятой. Например, C:\Dir1;C:\Dir2\DirA;C:\Dir2\DirB.

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

Для каждого каталога в пути к символам отладчик ищет в трех каталогах. Например, если путь к символам включает C:\Dir1 и отладчик ищет сведения о символах для библиотеки DLL, отладчик ищет сведения о символах в следующих каталогах, указанных в порядке:

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

Затем отладчик повторяет этот процесс для каждого каталога в пути символов. Наконец, отладчик ищет в текущем каталоге, а затем в текущем каталоге, к которому добавлен ..\dll. Отладчик добавляет ..\dll, ..\exeили ..\sysв зависимости от того, какие двоичные файлы он отлаживает.

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

Одним из способов задать путь символа является ввод команды .sympath. Другие способы задать путь к символам см. в разделе Управление путем к символам далее в этом разделе.

Кэшировать символы локально

Вы должны кэшировать символы локально. Одним из способов локального кэширования символов является включение cache*; или cache*localsymbolcache;* в путь к символам.

Если вы включаете строку cache*; в путь к символам, символы, загруженные из любого элемента, который отображается справа от этой строки, хранятся в каталоге кэша символов по умолчанию на локальном компьютере. Например, следующая команда сообщает отладчику получить символы из сетевой общей папки с именем \\someshare и кэшировать символы в расположении по умолчанию на локальном компьютере.

.sympath cache*;\\someshare

Если вы включаете строку cache*localsymbolcache; в путь к символам, символы, загруженные из любого элемента, который отображается справа от этой строки, хранятся в каталоге localsymbolcache.

Например, следующая команда сообщает отладчику получать символы из сетевого общего ресурса \\someshare и кэшировать символы в каталоге c:\MySymbols.

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

Использование сервера символов: srv*

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

Строка srv*

Если вы включите строку srv* в путь к символам, отладчик будет использовать сервер символов для получения их из хранилища по умолчанию. Например, следующая команда сообщает отладчику получить символы из хранилища символов по умолчанию. Эти символы не кэшируются на локальном компьютере.
```
.sympath srv*
```
Строка srv*symbolstore

Если вы включаете строку srv*symbolstore в путь к символам, отладчик использует сервер символов для получения символов из . Например, следующая команда указывает отладчику получить символы из хранилища сервера символов Microsoft . Эти символы не кэшируются на локальном компьютере.
```
.sympath srv*https://msdl.microsoft.com/download/symbols
```
Строка srv*localsymbolcache*symbolstore

Если вы включаете строку srv*localcache*symbolstore в путь к символам, то отладчик использует сервер символов для получения символов из хранилища символов и сохраняет их в локальном каталоге кэша localcache. Например, следующая команда сообщает отладчику получать символы с сервера символов Майкрософт—https://msdl.microsoft.com/download/symbols и кэшировать символы в c:\MyServerSymbols.
```
.sympath srv*C:\MyServerSymbols*https://msdl.microsoft.com/download/symbols
```

Если у вас есть каталог на компьютере, где вы вручную помещаете символы, не используйте этот каталог в качестве кэша для символов, полученных с сервера символов. Вместо этого используйте два отдельных каталога. Например, можно вручную поместить символы в c:\MyRegularSymbols, а затем назначить c:\MyServerSymbols в качестве кэша для символов, полученных с сервера. В следующем примере показано, как указать оба каталога в пути к символам.

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

Дополнительные сведения о серверах символов и хранилищах символов см. в разделе Пользовательские хранилища символов и серверы символов.

Объединение кэша* и srv*

Если вы включаете строку cache*; в путь к символам, символы, загруженные из любого элемента, который отображается справа от этой строки, хранятся в каталоге кэша символов по умолчанию на локальном компьютере. Например, следующая команда сообщает отладчику получить символы из сервера символов Майкрософт хранить и кэшировать их в каталоге кэша символов по умолчанию.

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

Например, следующая команда сообщает отладчику получать символы из сервера символов Microsoft хранить и кэшировать символы в каталоге c:\MySymbols.

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

Использование AgeStore для уменьшения размера кэша

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

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

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

При изменении пути к символам, например, с помощью команды .sympath, все загруженные модули с символами экспорта лениво перезагружаются.

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

Вы можете отключить отложенную загрузку символов в CDB и KD с помощью параметра командной строки -s. Вы также можете принудительно загружать символы с помощью команды загрузки символов или команды .reload модуля с использованием параметра /f.

Артефакты Azure DevOps Services

Сервер символов доступен в Azure DevOps Services с Артефактами Azure . Сведения о работе с артефактами Azure в WinDbg см. в статье Отладка с символами вWinDbg (Azure Artifacts). Общие сведения о символах, созданных Azure, см. в обзоре символов (Azure Artifacts).

Контроль пути к символам

Чтобы контролировать путь к символам, можно выбрать один из следующих методов:

Используйте команду .symfix set symbol store path, чтобы задать путь по умолчанию к общедоступному серверу символов Майкрософт, который хорошо работает во многих ситуациях. Чтобы задать локальный кэш, просто введите .symfix C:\MyCache.
Используйте команду .sympath для отображения, установки, изменения или добавления пути.
Перед запуском отладчика используйте переменные среды _NT_SYMBOL_PATH и _NT_ALT_SYMBOL_PATHсреды, чтобы задать путь. Путь к символу создается путем добавления _NT_SYMBOL_PATH после _NT_ALT_SYMBOL_PATH. Как правило, путь устанавливается через _NT_SYMBOL_PATH. Однако может потребоваться использовать _NT_ALT_SYMBOL_PATH для переопределения этих параметров в особых случаях, например, если у вас есть частные версии общих файлов символов. При попытке добавить недопустимый каталог с помощью этих переменных среды отладчик игнорирует этот каталог.
При запуске отладчика используйте параметр командной строки -y, чтобы задать путь.
Только в WinDbg можно использовать команду "File | Symbol File Path" или нажмите CTRL+S, чтобы отобразить, задать, изменить или добавить к пути.

Если вы используете параметр командной строки -sins, отладчик игнорирует переменную среды символов.

Устранение неполадок

Используйте !sym verbose или параметр -nWinDbg Command-Line для отображения дополнительных сведений в виде символов. Для получения дополнительных стратегий устранения неполадок см. раздел Проверка символов.