Compartilhar via

Caminho de símbolos para depuradores Windows

O caminho do símbolo especifica locais em que depuradores do Windows como WinDbg, KD, CDB e NTST procuram arquivos de símbolo.

Início rápido: Use o .symfix comando para configurar um caminho padrão para o servidor de símbolos públicos da Microsoft. Isso funciona bem na maioria dos cenários de depuração.

Configure o caminho do símbolo corretamente para habilitar a depuração eficiente— os depuradores podem localizar e carregar automaticamente os arquivos de símbolo necessários para analisar a execução do código. Este guia mostra como configurar caminhos de símbolo, usar o servidor de símbolos da Microsoft, armazenar símbolos em cache localmente e solucionar problemas comuns. 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 criou o executável 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 dos símbolos para apontar para as localizações dos arquivos de símbolos.

Dica

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

Sintaxe do caminho do símbolo

O caminho de símbolos 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 drive ou um compartilhamento de arquivo 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 busca 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 pesquisará nesta ordem:

  1. C:\Dir1\symbols\dll
  2. C:\Dir1\dll
  3. C:\Dir1

O depurador repete esse processo para cada diretório no caminho do símbolo.

Locais de recurso de reserva final:

  • Diretório atual
  • Diretório atual com ..\dll, ..\exe ou ..\sys anexado (dependendo do tipo binário que está sendo depurado)

Os arquivos de símbolos estão associados a carimbos de data e hora. O depurador sempre procura os símbolos que correspondem à data/hora nos arquivos binários que estão sendo depurados. 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ímbolo não estiverem disponíveis, consulte Nomes de símbolo 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.

Controlar o caminho do símbolo

Para controlar o caminho do símbolo, selecione 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, digite .symfix C:\MyCache.

  • Use o comando .sympath para exibir, definir, alterar ou adicionar 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 acrescentando _NT_SYMBOL_PATH após _NT_ALT_SYMBOL_PATH. Normalmente, você define o caminho 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, use o Arquivo | Caminho do Arquivo de Símbolos ou pressione CTRL+S para exibir, definir, alterar ou adicionar ao caminho de arquivos de símbolos.

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

Armazenar símbolos em cache localmente

Recomendamos armazenar em cache localmente os símbolos para melhorar o desempenho do depurador e reduzir o tráfego de rede. Para armazenar em cache símbolos, inclua cache*; ou cache*localsymbolcache; no caminho do símbolo.

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

.sympath cache*;\\someshare

Se você incluir a string cache*localsymbolcache; no caminho do símbolo, o depurador armazenará os símbolos que ele carregar de qualquer elemento que estiver à direita dessa string no diretório localsymbolcache.

Por exemplo, o comando a seguir instrui o depurador a obter símbolos do \\someshare compartilhamento de rede 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 público de símbolos 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 srv* 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 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 srv*symbolstore cadeia de caracteres

    Se você incluir a cadeia srv*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. Por exemplo, o comando a seguir instrui o depurador a 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 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 instrui o depurador a obter símbolos do servidor de símbolos da Microsofthttps://msdl.microsoft.com/download/symbols e 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 em seu computador em que coloque 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 c:\MyRegularSymbols manualmente e 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.

Combinar cache* e srv*

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

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

Se você incluir a string cache*localsymbolcache; no caminho do símbolo, o depurador armazenará os símbolos que ele carregar de qualquer elemento que estiver à direita dessa string no diretório localsymbolcache.

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

.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 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 que uma quantidade especificada. Essa limpeza de arquivos de cache será útil se o repositório downstream ficar muito grande.

Carregamento preguiçoso de símbolos

O depurador usa o carregamento de símbolo lento por padrão. Esse tipo de carregamento significa que o depurador não carrega símbolos até precisar deles.

Quando você altera o caminho do símbolo, por exemplo, usando o comando .sympath, o depurador recarrega lentamente todos os módulos carregados com símbolos de exportação.

O depurador recarrega preguiçosamente símbolos de módulos com símbolos PDB completos se o novo caminho não incluir mais o caminho original usado para carregar os símbolos PDB. Se o novo caminho ainda incluir o caminho original para o arquivo de símbolos PDB, o depurador não recarrega esses símbolos de forma preguiçosa.

Você pode desativar o carregamento de símbolos lentos 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 do módulo .reload junto com a opção /f .

Artefatos do Azure DevOps Services

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, consulte Depurar com símbolos no WinDbg (Azure Artifacts). Para obter informações gerais sobre símbolos gerados pelo Azure, consulte a visão geral de símbolos (Artefatos do Azure).

Resolução de problemas

Use !sym noisy ou a opção -nWinDbg Command-Line para mostrar detalhes adicionais quando os símbolos são carregados. Para obter estratégias adicionais de solução de problemas, consulte Verificar símbolos.

Próximas etapas

Agora que você configurou o caminho do símbolo, saiba como verificar se os símbolos estão sendo carregados corretamente e solucionar problemas comuns:

Verificando símbolos

Tarefas relacionadas:

Referência de comando:

  • Last updated on