Caminho de símbolos para depuradores Windows

Artigo
07/08/2024

O caminho do símbolo especifica locais em que os depuradores Windows, como WinDbg, KD, CDB e NTST, procuram arquivos de símbolo. Para obter mais informações sobre símbolos e arquivos de símbolos, consulte Símbolos.

Alguns compiladores, incluindo o Microsoft Visual Studio, colocam arquivos de símbolo no mesmo diretório que os arquivos binários. Os arquivos de símbolo e os arquivos binários verificados contêm informações de caminho e nome de arquivo, o que permite que o depurador localize os arquivos de símbolo automaticamente. Se você depurar um processo de modo de usuário no computador em que o executável foi criado e se os arquivos de símbolo estiverem em seu local original, o depurador poderá localizar os arquivos de símbolo sem que você defina o caminho do símbolo.

Na maioria das outras situações, você precisa definir o caminho do símbolo para apontar para os locais do arquivo de símbolo.

Dica

Use .symfix para definir um caminho padrão para o servidor de símbolos público da Microsoft que funciona bem em muitas situações.

Sintaxe do caminho do símbolo

O caminho do símbolo do depurador é uma cadeia de caracteres que consiste em vários caminhos de diretório separados por ponto-e-vírgula. Por exemplo, C:\Dir1;C:\Dir2\DirA;C:\Dir2\DirB.

Caminhos relativos são compatíveis. No entanto, você deve adicionar uma letra de unidade ou um compartilhamento de rede antes de cada caminho, a menos que você sempre inicie o depurador no mesmo diretório. Também há suporte para compartilhamentos de rede.

Para cada diretório no caminho do símbolo, o depurador procura em três diretórios. Por exemplo, se o caminho do símbolo incluir C:\Dir1 e o depurador estiver procurando informações de símbolo para uma DLL, o depurador procurará informações de símbolo nos seguintes diretórios, listados em ordem:

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

Em seguida, o depurador repete esse processo para cada diretório no caminho do símbolo. Por fim, o depurador procura no diretório atual e, em seguida, no diretório atual com ..\dll anexado a ele. O depurador acrescenta ..\dll, ..\exe, ou ..\sys, dependendo de quais binários ele está depurando.

Os arquivos de símbolo têm carimbos de data e hora. O depurador sempre procura os símbolos que correspondem ao carimbo de data/hora nos arquivos binários que ele está depurando. Você não precisa se preocupar com o depurador usando os símbolos errados que ele encontra primeiro nesta sequência. Para obter mais informações sobre respostas quando os arquivos de símbolos não estão disponíveis, consulte Nomes de símbolos correspondentes.

Uma maneira de definir o caminho do símbolo é inserindo o comando .sympath. Para obter outras maneiras de definir o caminho do símbolo, consulte Controlar o caminho do símbolo mais adiante neste tópico.

Símbolos de cache localmente

Você deve armazenar seus símbolos em cache localmente. Uma maneira de armazenar símbolos em cache localmente é incluir cache*; ou cache*localsymbolcache;* no caminho do símbolo.

Se você incluir a cadeia de caracteres cache*; no caminho do símbolo, os símbolos carregados de qualquer elemento que apareça à direita dessa cadeia de caracteres serão armazenados no diretório de cache de símbolos padrão no computador local. Por exemplo, o comando a seguir informa ao depurador para obter símbolos do compartilhamento de rede nomeado \\someshare e armazenar em cache os símbolos no local padrão no computador local.

.sympath cache*;\\someshare

Se você incluir a cadeia de caracteres cache*localsymbolcache; no caminho do símbolo, os símbolos carregados de qualquer elemento que apareça à direita dessa cadeia de caracteres serão armazenados no diretório localsymbolcache .

Por exemplo, o comando a seguir informa ao depurador para obter símbolos do compartilhamento \\someshare de rede e armazenar em cache os c:\MySymbols símbolos no diretório.

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

Usando um servidor de símbolos: srv*

Se você estiver conectado à Internet ou a uma rede corporativa, a maneira mais eficiente de acessar símbolos é usar um servidor de símbolos, como o servidor de símbolos público da Microsoft. Você pode usar um servidor de símbolos usando uma das seguintes cadeias de caracteres no caminho do símbolo.

A srv* string

Se você incluir a cadeia de caracteres srv* no caminho do símbolo, o depurador usará um servidor de símbolos para obter símbolos do repositório de símbolos padrão. Por exemplo, o comando a seguir informa ao depurador para obter símbolos do repositório de símbolos padrão. Esses símbolos não são armazenados em cache no computador local.
```
.sympath srv*
```
A srv*symbolstore string

Se você incluir a cadeia de caracteres srv*symbolstore no caminho do símbolo, o depurador usará um servidor de símbolos para obter símbolos do repositório de símbolos. Por exemplo, o comando a seguir informa ao depurador para obter símbolos do repositório do servidor de símbolos da Microsoft. Esses símbolos não são armazenados em cache no computador local.
```
.sympath srv*https://msdl.microsoft.com/download/symbols
```
A srv*localsymbolcache*symbolstore string

Se você incluir a cadeia de caracteres srv*localcache*symbolstore no caminho do símbolo, o depurador usará um servidor de símbolos para obter símbolos do repositório de símbolos e os armazenará em cache no diretório localcache . Por exemplo, o comando a seguir informa ao depurador para obter símbolos do servidor de símbolos da Microsoft ehttps://msdl.microsoft.com/download/symbols armazenar os símbolos em cache no c:\MyServerSymbols.
```
.sympath srv*C:\MyServerSymbols*https://msdl.microsoft.com/download/symbols
```

Se você tiver um diretório em seu computador onde coloca símbolos manualmente, não use esse diretório como o cache para símbolos obtidos de um servidor de símbolos. Em vez disso, use dois diretórios separados. Por exemplo, você pode colocar símbolos manualmente e c:\MyRegularSymbols , em seguida, designar c:\MyServerSymbols como um cache para símbolos obtidos de um servidor. O exemplo a seguir mostra como especificar ambos os diretórios no caminho do símbolo.

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

Para obter mais informações sobre servidores de símbolos e repositórios de símbolos, consulte Repositórios de símbolos personalizados e servidores de símbolos.

Combine cache* e srv*

Se você incluir a cadeia de caracteres cache*; no caminho do símbolo, os símbolos carregados de qualquer elemento que apareça à direita dessa cadeia de caracteres serão armazenados no diretório de cache de símbolos padrão no computador local. Por exemplo, o comando a seguir informa ao depurador para obter símbolos do repositório do servidor de símbolos da Microsoft e armazená-los em cache no diretório de cache de símbolos padrão.

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

Por exemplo, o comando a seguir informa ao depurador para obter símbolos do repositório do servidor de símbolos da Microsoft e armazenar os símbolos em cache no c:\MySymbols diretório.

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

Usar o AgeStore para reduzir o tamanho do cache

Você pode usar a ferramenta AgeStore para excluir arquivos em cache mais antigos do que uma data especificada ou para excluir arquivos antigos suficientes para que o tamanho do cache resultante seja menor que um valor especificado. Essa limpeza de arquivos de cache será útil se o repositório downstream ficar muito grande.

Carregamento lento de símbolos

O comportamento padrão do depurador é usar o carregamento lento de símbolos, também conhecido como carregamento de símbolos adiados. Esse tipo de carregamento significa que os símbolos não são carregados até que sejam necessários.

Quando o caminho do símbolo é alterado, por exemplo, usando o comando .sympath, todos os módulos carregados com símbolos de exportação são recarregados lentamente.

Os símbolos de módulos com símbolos PDB completos são recarregados lentamente se o novo caminho não incluir mais o caminho original que foi usado para carregar os símbolos PDB. Se o novo caminho ainda incluir o caminho original para o arquivo de símbolo PDB, esses símbolos não serão recarregados lentamente.

Você pode desativar o carregamento lento de símbolos no CDB e no KD usando a opção de linha de comando -s. Você também pode forçar o carregamento de símbolos usando o comando ld load symbols ou usando o comando .reload module junto com a /f opção.

Artefatos do Azure DevOps Services

Um servidor de símbolos está disponível com Azure Artifacts em Azure DevOps Services. Para saber mais sobre como trabalhar com Azure Artifacts no WinDbg, consulte Depurar com símbolos no WinDbg. Para obter informações gerais sobre símbolos gerados pelo Azure, consulte Visão geral de símbolos.

Controlar o caminho do símbolo

Para controlar o caminho do símbolo, você pode selecionar um dos seguintes métodos:

Use o comando .symfix set symbol store path para definir um caminho padrão para o servidor de símbolos público da Microsoft que funcione bem em muitas situações. Para definir um cache local, basta digitar .symfix C:\MyCache.
Use o comando .sympath para exibir, definir, alterar ou anexar ao caminho.
Antes de iniciar o depurador, use as _NT_SYMBOL_PATH variáveis de ambiente e _NT_ALT_SYMBOL_PATH para definir o caminho. O caminho do símbolo é criado anexando _NT_SYMBOL_PATH após _NT_ALT_SYMBOL_PATH. Normalmente, o caminho é definido por meio do _NT_SYMBOL_PATH. No entanto, talvez você queira usar _NT_ALT_SYMBOL_PATH para substituir essas configurações em casos especiais, como se você tiver versões privadas de arquivos de símbolo compartilhados. Se você tentar adicionar um diretório inválido por meio dessas variáveis de ambiente, o depurador ignorará esse diretório.
Ao iniciar o depurador, use a opção de linha de comando -y para definir o caminho.
Somente no WinDbg, você pode usar o arquivo | Caminho do arquivo de símbolo ou pressione CTRL+S para exibir, definir, alterar ou anexar ao caminho.

Se você usar a opção de linha de comando -sinins, o depurador ignorará a variável de ambiente do caminho do símbolo.

Solução de problemas

Use !sym noisy ou a opção de linha de comando -n WinDbg para exibir detalhes adicionais à medida que os símbolos são carregados. Para obter estratégias adicionais de solução de problemas, consulte Verificando símbolos.