Uso avançado do SymSrv

O SymSrv pode fornecer arquivos de símbolo de um repositório de símbolos centralizado. Esse repositório pode conter qualquer número de arquivos de símbolo, correspondente a qualquer número de programas ou sistemas operacionais. O repositório também pode conter arquivos binários (isso é útil ao depurar minidumps).

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

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

Por fim, 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 dá suporte a sites HTTPS protegidos por cartões inteligentes, certificados e logons e senhas regulares. Para obter mais informações, consulte Repositórios de Símbolos HTTP.

Definindo o caminho do símbolo

Para usar esse servidor de símbolos, symsrv.dll deve ser instalado no mesmo diretório que o depurador. O caminho do símbolo pode ser definido conforme mostrado neste código:

set _NT_SYMBOL_PATH = symsrv*ServerDLL*DownstreamStore*\\Server\Share

set _NT_SYMBOL_PATH = symsrv*ServerDLL*\\Server\Share

set _NT_SYMBOL_PATH = srv*DownstreamStore*\\Server\Share

set _NT_SYMBOL_PATH = srv*\\Server\Share

As partes dessa sintaxe são explicadas da seguinte maneira:

symsrv
Essa palavra-chave sempre deve aparecer primeiro. Ele indica ao depurador que esse item é um servidor de símbolos, não apenas um diretório de símbolo normal.

ServerDLL
Especifica o nome da DLL do servidor de símbolos. Se você estiver usando o servidor de símbolos SymSrv, isso sempre será symsrv.dll.

srv
Esta é uma abreviação para symsrv*symsrv.dll.

DownstreamStore
Especifica o repositório downstream. Esse é um diretório local ou compartilhamento de rede que será usado para armazenar em cache arquivos de símbolo individuais.

Você pode especificar mais de um repositório downstream, separado por asteriscos. Vários armazenamentos downstream são explicados em Armazenamentos Downstream em Cascata mais abaixo nesta página.

Se você incluir dois asteriscos em uma linha em que um repositório downstream normalmente seria especificado, o repositório downstream padrão será usado. Esse repositório estará localizado no subdiretório sym do diretório base. O diretório base usa como padrão o diretório de instalação do depurador; isso pode ser alterado usando a extensão !homedir ou definindo a variável de ambiente DBGHELP_HOMEDIR.

Se DownstreamStore especificar um diretório que não existe, o SymStore tentará criá-lo.

Se o parâmetro DownstreamStore for omitido e nenhum asterisco extra for incluído , em outras palavras, se você usar srv com exatamente um asterisco ou symsrv com exatamente dois asteriscos, nenhum repositório downstream será criado. O depurador carregará todos os arquivos de símbolo diretamente do servidor, sem armazená-los em cache localmente.

Nota Se você estiver acessando símbolos de um site HTTP ou HTTPS ou se o repositório de símbolos usar arquivos compactados, um repositório downstream sempre será usado. Se nenhum repositório downstream for especificado, um será criado no subdiretório sym do diretório base.

\\Server\Share
Especifica o servidor e o compartilhamento do repositório de símbolos remoto.

Se um repositório downstream for usado, o depurador procurará primeiro um arquivo de símbolo neste repositório. Se o arquivo de símbolo não for encontrado, o depurador localizará o arquivo de símbolo do Servidor e do Compartilhamento especificados e armazenará em cache uma cópia desse arquivo no repositório downstream. O arquivo será copiado para um subdiretório na árvore em DownstreamStore que corresponde ao seu local na árvore em \\Server\Share.

O servidor de símbolos não precisa ser a única entrada no caminho de símbolos. Se o caminho do símbolo consistir em várias entradas, o depurador verificará cada entrada para os arquivos de símbolo necessários, em ordem (da esquerda para a direita), independentemente de um servidor de símbolo ou um diretório real ser nomeado.

Aqui estão alguns exemplos. Para usar o SymSrv como o servidor de símbolos com um repositório de símbolos em \\mybuilds\mysymbols, defina o seguinte caminho de símbolo:

set _NT_SYMBOL_PATH= symsrv*symsrv.dll*\\mybuilds\mysymbols

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

set _NT_SYMBOL_PATH=symsrv*symsrv.dll*c:\localsymbols*\\mybuilds\mysymbols

Para definir o caminho do símbolo para que o depurador copie arquivos de símbolo do site HTTPS https://www.company.com/manysymbols para um diretório de rede local \\localserver\myshare\mycache, use:

set _NT_SYMBOL_PATH=symsrv*symsrv.dll*\\localserver\myshare\mycache*https://www.company.com/manysymbols

Este último exemplo também pode ser reduzido como tal:

set _NT_SYMBOL_PATH=srv*\\localserver\myshare\mycache*https://www.company.com/manysymbols

Além disso, o caminho do símbolo pode conter vários diretórios ou servidores de símbolo, separados por ponto-e-vírgula. Isso permite que você localize símbolos de vários locais (ou até mesmo vários servidores de símbolos). Se um binário tiver um arquivo de símbolo incompatível, o depurador não poderá localizá-lo usando o servidor de símbolos porque ele verifica apenas os parâmetros exatos. No entanto, o depurador pode encontrar um arquivo de símbolo que não corresponde completamente, mas ainda assim tem o nome correto, utilizando o caminho de símbolo tradicional, e carregá-lo com sucesso. Mesmo que o arquivo tecnicamente não seja o arquivo de símbolo correto, ele pode fornecer informações úteis.

Excluindo o Cache

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

É possível ter um amplo repositório de símbolos que inclui arquivos de símbolo para muitos programas diferentes ou versões do Windows. Se você atualizar a versão do Windows usada em seu 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 uso adicional e, portanto, esse pode ser um bom momento para excluir o cache.

Armazenamentos downstream em cascata

Você pode especificar qualquer número de repositórios downstream, separados por asteriscos. Esses repositórios são conhecidos como repositórios de símbolos em cascata.

Após o srv* ou symsrv*ServerDLL* inicial, cada token subsequente representa um local de símbolo. O token mais distante à esquerda é verificado primeiro. Um token vazio , indicado por dois asteriscos em uma linha ou por um asterisco no final da cadeia de caracteres, representa o repositório downstream padrão.

Aqui está um exemplo de um caminho de símbolos que utiliza dois repositórios downstream para armazenar informações do repositório principal de símbolos em acesso. Eles podem ser chamados de repositório mestre, repositório de nível médio e cache local:

srv*c:\localcache*\\interim\store*https://msdl.microsoft.com/download/symbols

Nesse cenário, o SymSrv primeiro procurará em c:\localcache um arquivo de símbolo. Se encontrado lá, retornará o caminho para ele. Se não for encontrado lá, ele será exibido em \\interim\store. Se o arquivo de símbolo for encontrado lá, o SymSrv o copiará para c:\localcache e retornará o caminho. Se não for encontrado lá, o SymSrv examinará o repositório https://msdl.microsoft.com/download/symbolsde símbolos públicos da Microsoft; se o arquivo for encontrado lá, o SymSrv o copiará para \\interim\store e c:\localcache.

Um comportamento semelhante seria obtido usando o seguinte caminho:

srv**\\interim\store*https://internetsite

Nesse caso, o cache local é o repositório downstream padrão e o repositório mestre é um site da Internet. Um repositório de nível médio de \\interim\store foi especificado para uso entre os outros dois.

Quando o SymSrv processa um caminho que contém repositórios em cascata, ele ignorará qualquer repositório no qual não possa ler ou gravar. Portanto, se um compartilhamento for inoperante, ele copiará o arquivo para o repositório downstream do repositório ausente sem nenhum erro. Um bom efeito colateral desse erro é que o usuário pode especificar mais de um repositório mestre que alimenta um único fluxo de repositórios downstream, desde que os repositórios mestres não sejam graváveis.

Quando um arquivo de símbolo compactado é recuperado do repositório mestre, ele será armazenado em forma compactada em qualquer repositório de nível médio. O arquivo será descompactado no nível mais inferior do armazenamento no caminho.

Trabalhando com caminhos de servidor de símbolos HTTP e SMB

Conforme discutido anteriormente, o encadeamento (ou processo em cascata) refere-se à cópia que ocorre entre cada separador "*" no caminho de símbolos. Os símbolos são pesquisados em uma ordem da esquerda para a direita. Em cada erro, o próximo servidor de símbolos (upstream) é consultado até que o arquivo seja encontrado.

Se encontrado, o arquivo é copiado do servidor de símbolos (upstream) para o servidor de símbolos anterior (downstream). Isso é repetido para cada servidor de símbolos (downstream). Dessa forma, os servidores de símbolos downstream (compartilhados) são preenchidos com os esforços coletivos de todos os clientes usando os servidores de símbolos.

Embora caminhos UNC encadeados possam ser usados sem o prefixo SRV*, recomendamos que o SRV* seja especificado para que o tratamento avançado de erros de symsrv.dll seja usado.

Ao incluir um servidor de símbolos HTTP no caminho, apenas um pode ser especificado (por cadeia) e deve estar no final do caminho (pois ele não pode ser gravado para servir como um cache). Se um repositório de símbolos baseado em HTTP estivesse localizado no meio ou à esquerda da lista de repositórios, não seria possível copiar nenhum arquivo encontrado para ele e a cadeia seria interrompida. Além disso, como o manipulador de símbolos não consegue abrir um arquivo de um site, um repositório baseado em HTTP não deve ser o primeiro da lista ou o único na lista. Se o SymSrv for apresentado com esse caminho de símbolo, ele tentará recuperar copiando o arquivo para o repositório downstream padrão e abri-lo a partir daí, independentemente de o repositório downstream padrão ser indicado no caminho do símbolo ou não.

O HTTP só tem suporte ao usar o prefixo SRV* (implementado pelo manipulador de símbolos symsrv.dll).

Exemplo de cenários de servidor de símbolos de compartilhamento HTTP e SMB

Uma implantação típica baseada apenas em UNC envolve um escritório central que armazena todos os arquivos (\\MainOffice\Symbols), filiais que armazenam em cache um subconjunto (\\BranchOfficeA\Symbols) e desktops (C:\Symbols) que armazenam em cache os arquivos que são referenciados.

srv*C:\Symbols*\\BranchOfficeA\Symbols*\\MainOffice\Symbols

Quando o compartilhamento SMB é o repositório de símbolos primário (upstream), é necessária a permissão de leitura.

srv*C:\Symbols*\\MachineName\Symbols

Quando o compartilhamento SMB é um repositório de símbolos intermediário (downstream), é necessário ter permissão de leitura/alteração. O cliente copiará o arquivo do repositório de símbolos primário para o compartilhamento SMB e, em seguida, do compartilhamento SMB para a pasta local.

srv*C:\Symbols*\\MachineName\Symbols*https://msdl.microsoft.com/download/symbols
srv*C:\Symbols*\\MachineName\Symbols*\\MainOffice\Symbols

Quando o compartilhamento SMB é um repositório de símbolos intermediário (downstream) em uma implantação do SymProxy, somente leitura é necessária. O Filtro ISAPI SymProxy executará as gravações, não o cliente.

srv*C:\Symbols*\\MachineName\Symbols*https://SymProxyName/Symbols

Vários cenários de cache de servidor de símbolos de compartilhamento HTTP e SMB

É possível especificar várias cadeias de servidores de símbolos e locais de cache, separados por um ponto e vírgula ";". Se os símbolos estiverem localizados na primeira cadeia, a segunda cadeia não será percorrida. Se os símbolos não estiverem localizados na primeira cadeia, a segunda cadeia será percorrida e, se os símbolos estiverem localizados na segunda cadeia, eles serão armazenados em cache no local especificado. Essa abordagem permitirá que um servidor de símbolos primário normalmente seja usado, com um servidor secundário sendo usado apenas se os símbolos não estiverem disponíveis no servidor de símbolos primário especificado na primeira cadeia.

srv*C:\Symbols*\\Machine1\Symbols*https://SymProxyName/Symbols;srv*C:\WebSymbols*https://msdl.microsoft.com/download/symbols

cache*localsymbolcache

Outra maneira de criar um cache local de símbolos é usando a cache*localsymbolcache cadeia de caracteres no caminho do símbolo. Isso não faz parte do elemento do servidor de símbolos, mas é um elemento separado no seu caminho de símbolos. O depurador usará o diretório especificado localsymbolcache para armazenar qualquer símbolo carregado de qualquer elemento que apareça no caminho do símbolo à direita dessa cadeia de caracteres. Isso permite que você use um cache local para símbolos baixados de qualquer local, não apenas aqueles baixados por um servidor de símbolos.

Por exemplo, o caminho do símbolo a seguir não armazenará em cache símbolos tirados de \\someshare. Ele usará c:\mysymbols para armazenar em cache símbolos tirados de \\anothershare, pois o elemento que começa com \\anothershare aparece à direita do elemento cache*c:\mysymbols . Ele também usará c:\mysymbols para armazenar em cache símbolos retirados do repositório de símbolos públicos da Microsoft, devido à sintaxe usual usada pelo servidor de símbolos (srv com dois ou mais asteriscos). Além disso, se você usar posteriormente o comando .sympath+ para adicionar locais adicionais a esse caminho, esses novos elementos também serão armazenados em cache, pois eles serão acrescentados ao lado direito do caminho.

_NT_SYMBOL_PATH=\\someshare\that\cachestar\ignores;srv*c:\mysymbols*https://msdl.microsoft.com/download/symbols;cache*c:\mysymbols;\\anothershare\that\gets\cached

Como o SymSrv localiza arquivos

O SymSrv cria um caminho UNC totalmente qualificado para o arquivo de símbolo desejado. Esse caminho começa com o caminho para o repositório de símbolos registrado na variável de ambiente _NT_SYMBOL_PATH. A rotina SymbolServer é usada para identificar o nome do arquivo desejado; esse nome é acrescentado ao caminho como um nome de diretório. Outro nome de diretório, consistindo na concatenação dos parâmetros id, dois e três passados para SymbolServer, é adicionado. Se qualquer um desses valores for zero, eles serão omitidos.

O diretório resultante é pesquisado para o arquivo de símbolo ou um arquivo de ponteiro do repositório de símbolos.

Se essa pesquisa for bem-sucedida, SymbolServer passará o caminho para o chamador e retornará TRUE. Se o arquivo não for encontrado, SymbolServer retornará FALSE.

Usando o AgeStore para reduzir o tamanho do cache

A ferramenta AgeStore pode ser usada para excluir arquivos armazenados em cache que são mais antigos do que uma data especificada ou para reduzir o conteúdo do cache abaixo de um tamanho especificado. Isso pode ser útil se o armazenamento downstream for muito grande. Para obter detalhes, consulte AgeStore.