Caminho de símbolos para depuradores de Windows

Artigo
12/15/2024

O caminho do símbolo especifica os locais onde 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ímbolos, consulte Symbols.

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 encontre os arquivos de símbolo automaticamente. Se você depurar um processo de modo de usuário no computador onde 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 público de símbolos públicos da Microsoft que funciona bem em muitas situações.

Sintaxe do caminho do símbolo

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

Caminhos relativos são suportados. 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 a partir do mesmo diretório. Compartilhamentos de rede também são suportados.

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. Finalmente, o depurador procura no diretório atual e, em seguida, no diretório atual com ..\dll anexado a ele. O depurador acrescenta ..\dll, ..\exeou ..\sys, dependendo de quais binários está depurando.

Os arquivos de símbolos têm carimbos de data e hora. O depurador procura sempre os símbolos que correspondem à marca temporal nos ficheiros binários que está a depurar. 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.

Armazenar símbolos em 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 incluir a cadeia de caracteres cache*; no caminho dos símbolos, 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 diz 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 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 diz ao depurador para obter símbolos do compartilhamento de rede \\someshare e armazenar em cache os símbolos no diretório c:\MySymbols.

.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úblicos da Microsoft. Você pode usar um servidor de símbolos usando uma das seguintes cadeias de caracteres no caminho do símbolo.

A cadeia de srv*

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 instrui o depurador a 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 cadeia de srv*symbolstore

Se incluíres 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 diz ao depurador para obter símbolos do servidor de símbolos da Microsoft armazenamento. Esses símbolos não são armazenados em cache no computador local.
```
.sympath srv*https://msdl.microsoft.com/download/symbols
```
A cadeia de caracteres srv*localsymbolcache*symbolstore

Se 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 armazenamento de símbolos e os armazenará em cache no diretório localcache . Por exemplo, o comando a seguir indica ao depurador que obtenha símbolos do servidor de símbolos da Microsoft -https://msdl.microsoft.com/download/symbols e guarde 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 onde coloca manualmente os símbolos, não use esse diretório como cache para símbolos obtidos de um servidor de símbolos. Em vez disso, use dois diretórios separados. Por exemplo, pode-se colocar manualmente símbolos no c:\MyRegularSymbols e, 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 Armazenamentos de símbolos personalizados e servidores de símbolos.

Combinar cache* e srv*

Se incluíres a cadeia de caracteres cache*; no teu caminho de símbolos, os símbolos carregados de qualquer elemento que apareça à direita dessa cadeia de caracteres serão armazenados no diretório padrão de cache de símbolos no computador local. Por exemplo, o comando a seguir diz ao depurador para obter símbolos do servidor de símbolos Microsoft armazenar 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 diz ao depurador para obter símbolos do servidor de símbolos Microsoft armazenar e armazenar em cache os símbolos no diretório c:\MySymbols.

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

Use o AgeStore para reduzir o tamanho do cache

Você pode usar a ferramenta AgeStore para excluir arquivos armazenados em cache que são mais antigos do que uma data especificada ou para excluir arquivos antigos suficientes para que o tamanho do cache resultante seja menor do que uma quantidade especificada. Essa limpeza de arquivos de cache é útil se seu armazenamento downstream ficar muito grande.

Carregamento preguiçoso de símbolos

O comportamento padrão do depurador é usar o carregamento preguiçoso de símbolos, também conhecido como o carregamento diferido de símbolos. 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 preguiçosamente.

Símbolos de módulos com símbolos PDB completos são recarregados de forma preguiçosa se o novo caminho já não incluir o caminho original que foi usado para carregar os símbolos do PDB. Se o novo caminho ainda incluir o caminho original para o ficheiro de símbolos PDB, esses símbolos não serão recarregados automaticamente.

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 juntamente com a opção /f.

Artefatos dos Serviços de DevOps do Azure

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

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 público de símbolos 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 acrescentar ao caminho.
Antes de iniciar o depurador, use as variáveis de ambiente _NT_SYMBOL_PATH 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 através do _NT_SYMBOL_PATH. No entanto, convém usar _NT_ALT_SYMBOL_PATH para substituir essas configurações em casos especiais, como se você tiver versões privadas de arquivos de símbolos 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, pode usar o comando Arquivo | Caminho do Arquivo de Símbolos ou pressionar CTRL+S para exibir, definir, alterar ou acrescentar ao caminho.

Se usares a opção -sins da linha de comando, o depurador ignorará a variável de ambiente do caminho de símbolos.

Solução de problemas

Use !sym noisy ou o -nWinDbg Command-Line Option para exibir detalhes adicionais enquanto os símbolos são carregados. Para obter estratégias adicionais de solução de problemas, consulte Verificando símbolos.