Usando o SymSrv

O SymSrv fornece arquivos de símbolos de repositórios de símbolos centralizados. Esses armazenamentos podem conter qualquer número de arquivos de símbolo, correspondendo a qualquer número de programas ou sistemas operacionais. Os armazenamentos também podem conter arquivos binários, que são particularmente úteis ao depurar arquivos minidump.

Os repositórios podem conter o símbolo real e arquivos binários ou simplesmente ponteiros para arquivos de símbolos. Se o armazenamento contiver ponteiros, o SymSrv recuperará os arquivos reais diretamente de suas fontes.

O SymSrv também pode separar um grande repositório de símbolos em um subconjunto menor que é apropriado para uma tarefa de depuração especializada.

Finalmente, o SymSrv pode obter arquivos de símbolo de uma fonte HTTP ou HTTPS usando as informações de logon fornecidas pelo sistema operacional. O SymSrv suporta sites HTTPS protegidos por smartcards, certificados e logins e senhas regulares.

Definindo o caminho do símbolo

Conforme descrito em Caminhos de símbolo, o caminho do símbolo (_NT_SYMBOL_PATH variável de ambiente) pode ser composto de vários elementos de caminho separados por ponto-e-vírgula. Se qualquer um ou mais desses elementos de caminho começar com o texto "srv*", então o elemento é um servidor de símbolos e usará o SymSrv para localizar arquivos de símbolos.

Observação

Se o texto "srv*" não for especificado, mas o elemento de caminho real for um armazenamento de servidor de símbolos, o manipulador de símbolos agirá como se "srv*" fosse especificado. O manipulador de símbolos faz essa determinação pesquisando a existência de um arquivo chamado "pingme.txt" no diretório raiz do caminho especificado.

 

Assim como os caminhos de símbolos são compostos de elementos de caminho de símbolo separados por ponto-e-vírgula, os servidores de símbolos são compostos de elementos de armazenamento de símbolos separados por asteriscos. Pode haver até 10 repositórios de símbolos após o prefixo "srv*". As lojas listadas à esquerda da lista são chamadas de lojas downstream e as lojas à direita são chamadas de lojas upstream.

srv\**SymbolStore* srv\**SymbolStore1*\**SymbolStoreN*

Se apenas um elemento de armazenamento de símbolos estiver incluído no caminho, o SymSrv tentará usar qualquer arquivo solicitado diretamente desse armazenamento.

Se houver dois repositórios de símbolos no caminho, o SymSrv procurará o arquivo de símbolos no repositório de símbolos mais à esquerda. Se o arquivo estiver lá, ele será usado. Se não estiver lá, o SymSrv olha na loja de símbolos imediatamente à direita. Se o arquivo estiver lá, ele será copiado para o armazenamento esquerdo e aberto de lá.

Se houver mais de dois armazenamentos, esse comportamento continuará à direita até que o arquivo seja encontrado ou não haja mais armazenamentos na lista.

O arquivo nunca é aberto de qualquer armazenamento, exceto o armazenamento mais à esquerda. Se o arquivo for encontrado em qualquer outro lugar da cadeia, ele será copiado para todos os repositórios à esquerda dele. Esse processo de cópia é chamado de "cascata" e fornece certos benefícios que serão esclarecidos posteriormente neste documento.

Tipos de Repositórios de Símbolos

A tabela a seguir exibe exemplos dos tipos de repositório de símbolos com suporte.

Tipo de repositório de símbolos	Descrição
\\servidor\compartilhamento	Um caminho UNC totalmente qualificado para um compartilhamento em um servidor remoto.
c:\LocalCache	Um caminho para um diretório no computador cliente.
https://InternetSite	A URL de um site que hospeda os símbolos. Deve ser a loja mais à direita na lista e não deve ser a única loja na lista.
https://SecureInternetSite	A URL para um site seguro que hospeda os símbolos. Isso pode oferecer suporte a senhas, credenciais de logon do Windows, certificados e cartões inteligentes. Deve ser a loja mais à direita na lista e não deve ser a única loja na lista.
<em branco>	Se não houver texto entre dois asteriscos, isso indicará o armazenamento downstream padrão. O local é definido chamando SymSetHomeDirectory. O valor padrão é um diretório chamado "sym" imediatamente abaixo do diretório do programa do aplicativo de chamada. Isso às vezes é chamado de cache local padrão.

 

Como um repositório de símbolos baseado em HTTP não pode ser gravado, ele deve ser o armazenamento mais à direita na lista. Se um repositório de símbolos baseado em HTTP estivesse localizado no meio ou à esquerda da lista de armazenamento, não seria possível copiar nenhum arquivo encontrado para ele e a cadeia seria quebrada. Além disso, como o manipulador de símbolos não pode abrir um arquivo de um site, um armazenamento baseado em HTTP não deve ser o armazenamento mais à esquerda ou único na lista. Se o SymSrv for apresentado com esse caminho de símbolo, ele tentará recuperar copiando o arquivo para o armazenamento downstream padrão e abri-lo a partir daí, independentemente de o armazenamento downstream padrão estar indicado no caminho do símbolo ou não.

Exemplos

Para usar o SymSrv com um repositório de símbolos em \\mybuilds\mysymbols, defina o seguinte caminho de símbolo:

definir _NT_SYMBOL_PATH= srv*\\mybuilds\mysymbols

Para definir o caminho do símbolo para que o depurador copie arquivos de símbolo de um repositório de símbolos em \\mybuilds\mysymbols para o diretório local c:\localsymbols, use:

Definir _NT_SYMBOL_PATH=SRV*C:\LocalSymbols*\\MyBuilds\MySymbols

Para definir o caminho do símbolo para que o depurador copie arquivos de símbolo de um repositório de símbolos em \\mybuilds\mysymbols para o armazenamento downstream padrão (normalmente c:\debuggers\sym), use:

definir _NT_SYMBOL_PATH=srv**\\mybuilds\mysymbols

Para usar um armazenamento em cascata, defina o seguinte caminho de símbolo:

definir _NT_SYMBOL_PATH = srv*c:\localsymbols*\\NearbyServer\store*https://DistantServer

Neste exemplo, o SymSrv primeiro procura o arquivo em c:\localsymbols. Se ele for encontrado lá, ele retornará um caminho para o arquivo. Caso contrário, o SymSrv procurará o arquivo em \\NearbyServer\store. Se for encontrado lá, o SymSrv copia o arquivo para c:\localsymbols e retorna um caminho para o arquivo; se ele não for encontrado, o SymSrv procurará o arquivo no https://DistantServer, e se ele for encontrado lá, o SymSrv copiará o arquivo para \\NearbyServer\store e, em seguida, para c:\localsymbols.

Este último exemplo mostra como o design criterioso de um caminho de símbolo pode ser usado para otimizar o download de símbolos. Se você tiver um site de trabalho com um grupo de depuradores e todos eles precisarem obter símbolos de um local distante, você poderá configurar um servidor comum com um repositório de símbolos perto de todos os depuradores. Em seguida, configure cada depurador com o caminho do símbolo acima. O primeiro depurador que requer uma determinada versão do foo.pdb irá baixá-lo de https://DistantServer \\NearbyServer\store e, em seguida, para sua própria máquina em c:\localsymbols. O próximo depurador que requer o mesmo arquivo poderá baixá-lo de \\NearbyServer\store porque ele já foi baixado para esse local pelo depurador anterior. Esse cache de vários níveis economiza tempo e largura de banda de rede significativos.

Loja de símbolos da Microsoft

A Microsoft fornece acesso a um servidor de símbolos da Internet que contém arquivos de símbolo para as várias versões do sistema operacional Windows. Este catálogo de símbolos não é garantido para ser completo, mas é extenso. Outros produtos da Microsoft também estão representados.

O servidor de símbolos da Internet é preenchido com uma variedade de símbolos do Windows para sistemas operacionais Microsoft Windows, incluindo hot fixes, Service Packs, pacotes cumulativos de segurança e versões de varejo. Os símbolos também estão disponíveis no servidor para produtos Betas e Release Candidates atuais para Windows, além de uma variedade de outros produtos da Microsoft, como o Microsoft Internet Explorer.

Se você tiver acesso à Internet durante a depuração, poderá configurar o depurador para baixar símbolos conforme necessário durante uma sessão de depuração, em vez de baixar arquivos de símbolos separadamente antes de uma sessão de depuração. Os símbolos são baixados para um local de diretório especificado e, em seguida, o depurador os carrega a partir daí.

A URL do repositório de símbolos da Microsoft é https://msdl.microsoft.com/download/symbols. O exemplo a seguir mostra como definir o caminho do símbolo do depurador (substitua o caminho do repositório downstream por c:\DownstreamStore):

srv*c:\DownstreamStore*https://msdl.microsoft.com/download/symbols

Arquivos compactados

O SymSrv é compatível com repositórios de símbolos que contêm arquivos compactados, desde que essa compactação tenha sido pré-formada com a ferramenta compress.exe que foi distribuída com o Windows Server 2003 Resource Kit. Os arquivos compactados devem ter um sublinhado como o último caractere em suas extensões de arquivo (por exemplo, module1.pd_ ou module2.db_). Para obter detalhes, consulte Usando o SymStore.

Ao entrar em cascata, os arquivos não são descompactados, a menos que o armazenamento de destino seja o armazenamento mais à esquerda no caminho. Se houver apenas um armazenamento no caminho e ele contiver um arquivo compactado, o SymSrv copiará o arquivo para o armazenamento downstream padrão e o abrirá a partir daí, mesmo que o armazenamento downstream padrão não esteja indicado no caminho do símbolo.

DbgHelp 6.1 e anterior.: Se os arquivos no repositório mestre estiverem compactados, você deverá usar um armazenamento downstream. O SymSrv descompactará todos os arquivos antes de copiá-los para o armazenamento downstream.

Excluindo o cache

Se você estiver usando um armazenamento downstream como um cache, poderá excluir esse diretório a qualquer momento para economizar espaço em disco.

É possível ter um vasto repositório de símbolos que inclui arquivos de símbolos para muitos programas diferentes ou versões do Windows. Se você atualizar a versão do Windows usada no computador de destino, os arquivos de símbolo armazenados em cache corresponderão à versão anterior. Esses arquivos armazenados em cache não serão mais úteis e, portanto, este pode ser um bom momento para excluir o cache.

As Ferramentas de Depuração para Windows vêm com um utilitário chamado agestore.exe que removerá seletivamente os arquivos de uma árvore de diretórios, deixando os arquivos usados mais recentemente. Esta ferramenta foi projetada para remover arquivos não utilizados de repositórios de servidores de símbolos. Ele permite que você controle muitas opções, incluindo data de corte e algoritmos de tamanho de diretório.

Diretório de cache simples

É possível declarar o armazenamento downstream padrão como um diretório simples, em vez de uma estrutura de árvore de símbolos padrão. Para fazer isso, chame a função SymSetOptions com SYMOPT_FLAT_DIRECTORY (isso também define a opção SSRVOPT_FLAT_DEFAULT_STORE no SymSrv). Certifique-se de chamar SymSetHomeDirectory antes de fazê-lo, caso contrário, os arquivos de símbolo podem ser gravados no diretório do programa.

Arquivos de ponteiro

O SymStore pode criar e usar arquivos que apontam para um arquivo de destino em vez do próprio arquivo de destino. Se um repositório de símbolos contiver esse arquivo de ponteiro, o padrão é copiar o arquivo do local indicado no arquivo de ponteiro para o armazenamento. Para configurar um repositório de modo que o arquivo de ponteiro seja copiado em vez do arquivo para o qual ele aponta, crie um arquivo chamado wantsptr.txt na raiz do repositório de destino. O conteúdo do wantsptr.txt não é importante, apenas a presença do arquivo.

Excluindo arquivos da lista de símbolos

Para excluir arquivos de uma pesquisa de símbolos, você pode especificar seus nomes no symsrv.ini ou no Registro. Para especificar os arquivos em symsrv.ini, crie uma seção chamada Exclusões e liste os arquivos. Os nomes de arquivo podem conter curingas, conforme mostrado no exemplo a seguir:

[Exclusions]
dbghelp.pdb
symsrv.*
mso*

Symsrv.ini deve estar localizado no mesmo diretório que symsrv.dll reside. Na maioria das instalações, o arquivo não existe e você precisará criar um novo.

Como alternativa, você pode armazenar os arquivos a serem excluídos no registro. Crie a seguinte chave do Registro: HKEY_LOCAL_MACHINE\Software\Microsoft\Symbol Server\Exclusions. Armazene cada nome de arquivo como um valor de cadeia de caracteres (REG_SZ) dentro dessa chave. O nome do valor da cadeia de caracteres especifica o nome do arquivo a ser excluído. Você pode usar o conteúdo do valor da cadeia de caracteres para armazenar um comentário descrevendo por que o arquivo está sendo excluído.

Instalação

O servidor de símbolos SymSrv (symsrv.dll) está incluído no pacote Ferramentas de Depuração para Windows. Ele deve ser instalado no mesmo diretório que a cópia do dbghelp.dll que você está carregando. Para obter mais detalhes, consulte Chamando a biblioteca DbgHelp.