Caminho do símbolo para depuradores do Windows

Artigo
12/21/2023

O caminho do símbolo especifica os locais em que os depuradores do Windows, como WinDbg, KD, CDB e NTST, procuram arquivos de símbolo. Para obter mais informações sobre símbolos e arquivos de símbolo, 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 nome de arquivo e caminho, 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ê configure 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 público de símbolos públicos 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 da unidade ou um compartilhamento de rede antes de cada caminho, a menos que você sempre inicie o depurador do mesmo diretório. Também há suporte para compartilhamentos de rede.

Para cada diretório no caminho do símbolo, o depurador examina 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 na 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 examina o diretório atual e, em seguida, no diretório atual com ..\dll acrescentado a ele. O depurador acrescenta ..\dll, ..\exeou ..\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 em cache seus símbolos 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 cache*; de caracteres no caminho do símbolo, os símbolos carregados de qualquer elemento que aparece à direita dessa cadeia de caracteres serão armazenados no diretório de cache de símbolo padrão no computador local. Por exemplo, o comando a seguir informa ao depurador para obter símbolos do compartilhamento de rede chamado \\someshare e armazenar em cache os símbolos no local padrão no computador local.

.sympath cache*;\\someshare

Se você incluir a cadeia de cache*localsymbolcache; caracteres no caminho do símbolo, os símbolos carregados de qualquer elemento que aparece à 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 símbolos no c:\MySymbols 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 público 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* cadeia de caracteres

Se você incluir a cadeia de srv* caracteres 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 cadeia de caracteres

Se você incluir a cadeia de srv*symbolstore caracteres 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 de servidores 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 cadeia de caracteres

Se você incluir a cadeia srv*localcache*symbolstore de caracteres 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 em cache os símbolos em c:\MyServerSymbols.
```
.sympath srv*C:\MyServerSymbols*https://msdl.microsoft.com/download/symbols
```

Se você tiver um diretório no computador em que 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 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 Armazenamentos de símbolos personalizados e servidores de símbolos.

Combinar cache* e srv*

Se você incluir a cadeia cache*; de caracteres no caminho do símbolo, os símbolos carregados de qualquer elemento que aparece à direita dessa cadeia de caracteres serão armazenados no diretório de cache de símbolo padrão no computador local. Por exemplo, o comando a seguir informa ao depurador para obter símbolos do repositório de servidores de símbolos da Microsoft e armazená-los em cache no diretório de cache de símbolo 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 de servidores de símbolos da Microsoft e armazenar em cache os símbolos 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 armazenados 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ímbolo adiado. 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 serã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 em CDB e 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 opção /f .

Azure DevOps Services Artifacts

Um servidor de símbolos está disponível com o Azure Artifacts no Azure DevOps Services. Para saber mais sobre como trabalhar com o Azure Artifacts no WinDbg, confira 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 funciona bem em muitas situações. Para definir um cache local, basta digitar .symfix C:\MyCache.
Use o comando .sympath para exibir, definir, alterar ou acrescentar ao caminho.
Antes de iniciar o depurador, use as _NT_SYMBOL_PATHvariáveis de ambiente e _NT_ALT_SYMBOL_PATH para definir o caminho. O caminho do símbolo é criado acrescentando _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ê tivesse 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 | Comando Caminho do Arquivo de Símbolo ou pressione CTRL+S para exibir, definir, alterar ou acrescentar ao caminho.

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

Solução de problemas

Use !sym barulhento ou a opção -nWinDbg Command-Line 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.