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

Статья
12/21/2023

Путь к символу указывает расположения, в которых отладчики 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 в путь к символам отладчик использует сервер символов для получения символов из хранилища символов. Например, следующая команда указывает отладчику получить символы из хранилища сервера символов Майкрософт . Эти символы не кэшируются на локальном компьютере.
```
.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

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

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

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

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

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

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

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

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

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

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

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

Управление путем к символам

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

Используйте команду .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 можно использовать файл | Команда "Путь к файлу символа " или нажмите клавишу CTRL+S , чтобы отобразить, задать, изменить или добавить к нему путь.

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

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

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