Usando o SymSrv

O SymSrv fornece arquivos de símbolos de lojas centralizadas de símbolos. Essas lojas podem conter qualquer número de arquivos de símbolo, correspondentes 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 os símbolos efetivos e ficheiros binários ou simplesmente apontadores para ficheiros de símbolos. Se a loja contiver ponteiros, o SymSrv recuperará os arquivos reais diretamente de suas fontes.

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

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

Definindo o caminho do símbolo

Conforme descrito em Caminhos de Símbolo, o caminho do símbolo (variável de ambiente _NT_SYMBOL_PATH) pode ser composto por 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á 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*" tivesse sido especificado. O manipulador de símbolos faz essa determinação procurando 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 constituídos por elementos de caminho de símbolos separados por ponto-e-vírgula, os servidores de símbolos são constituídos por elementos de armazenamento de símbolos separados por asteriscos. Pode haver até 10 lojas de símbolos após o prefixo "srv*". As lojas listadas à esquerda da lista são chamadas lojas a jusante e as lojas à direita são chamadas lojas a montante.

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 é usado. Se não estiver lá, o SymSrv procura no repositório de símbolos imediatamente à direita. Se o ficheiro estiver lá, é copiado para o armazém esquerdo e aberto a partir daí.

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

O arquivo nunca é aberto a partir de qualquer loja, exceto da loja mais à esquerda. Se o arquivo for encontrado em qualquer outro lugar da cadeia, ele será copiado para todas as lojas à esquerda dele. Esse processo de cópia é chamado de "cascata" e fornece certos benefícios que serão esclarecidos mais adiante neste documento.

Tipos de Armazenamento de Símbolos

A tabela a seguir exibe exemplos dos tipos de armazenamento de símbolos suportados.

Tipo de armazenamento de símbolos	Descrição
\\servidor\partilha	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	O URL para 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	O URL para um site seguro que hospeda os símbolos. Isso pode suportar senhas, credenciais de login 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 indica 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 chamador. Isso às vezes é chamado de cache local padrão .

 

Como um repositório de símbolos baseado em HTTP não pode ser gravado, deve ser o último repositório na lista. Se um repositório de símbolos baseado em HTTP estivesse localizado no meio ou à esquerda da lista de lojas, 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 consegue abrir um ficheiro de um site, um local de armazenamento baseado em HTTP não deve ser o primeiro nem o único armazenamento 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 abrindo-o a partir daí, independentemente de o armazenamento downstream padrão ser 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ímbolos 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 dos símbolos para que o depurador copie os ficheiros de símbolos de um armazenamento de símbolos em \\mybuilds\mysymbols para o armazenamento downstream padrão (normalmente c:\debuggers\sym), utilize:

definir _NT_SYMBOL_PATH=srv**\\mybuilds\mysymbols

Para usar um repositório em cascata, defina o seguinte caminho de símbolo:

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

Neste exemplo, 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 ele for encontrado lá, o SymSrv copia o arquivo para c:\localsymbols e retorna um caminho para o arquivo; se não for encontrado, o SymSrv procura o arquivo em https://DistantServere, se ele for encontrado lá, o SymSrv copia o arquivo para \\NearbyServer\store, depois 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ê pode configurar um servidor comum com um armazenamento 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 para \\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 significativo e largura de banda de rede.

Loja de Símbolos da Microsoft

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

O servidor de símbolos da Internet é abastecido com uma variedade de símbolos do Windows para sistemas operacionais Microsoft Windows, incluindo hot fixes, Service Packs, pacotes cumulativos de segurança e lançamentos comerciais. Os símbolos também estão disponíveis no servidor para Betas atuais e Release Candidates para produtos 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 de lá.

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 de armazenamento 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 mais detalhes, consulte Usando o SymStore.

Quando em cascata, os ficheiros não são descompactados, a não ser que o armazenamento de destino seja o mais à esquerda no percurso. Se houver apenas um repositório 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 repositório downstream padrão não esteja indicado no caminho do símbolo.

DbgHelp 6.1 e anteriores.: Se os arquivos no repositório mestre forem compactados, você deverá usar um repositório downstream. O SymSrv descompactará todos os ficheiros 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 uma vasta loja 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 de qualquer utilidade adicional 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 algoritmos de data de corte e 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, chamar a função SymSetOptions com SYMOPT_FLAT_DIRECTORY (o que também define a opção SSRVOPT_FLAT_DEFAULT_STORE em SymSrv). Certifique-se de ligar para SymSetHomeDirectory antes de o fazer; caso contrário, os ficheiros de símbolos podem ser gravados no diretório do programa.

Arquivos de ponteiro

SymStore pode criar e usar arquivos que apontam para um arquivo de destino em vez do arquivo de destino em si. 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 repositório. Para configurar um repositório para que o arquivo de ponteiro seja copiado em vez do arquivo para o qual 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 Utilização da biblioteca DbgHelp.