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, correspondendo a qualquer número de programas ou sistemas operacionais. O repositório também pode conter arquivos binários (isso é útil ao depurar minidespejos).

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 oferece suporte a sites HTTPS protegidos por cartões inteligentes, certificados e logins 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 forma:

symsrv
Essa palavra-chave deve sempre aparecer primeiro. Ele indica ao depurador que esse item é um servidor de símbolos, não apenas um diretório de símbolos 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 de symsrv*symsrv.dll.

Loja a jusante
Especifica o repositório downstream. Este é 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 repositórios 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 inicial. O diretório inicial é padronizado para 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.

Observação 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 inicial.

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

Se um repositório downstream for usado, o depurador primeiro procurará um arquivo de símbolo nesse 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, em seguida, 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 do símbolo. 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ímbolos 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 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:

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://www.company.com/manysymbols HTTPS 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 abreviado da seguinte forma:

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ímbolos, separados por ponto-e-vírgula. Isso permite que você localize símbolos de vários locais (ou até mesmo de 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 incompatível com o nome correto, usando o caminho de símbolo tradicional, e carregá-lo com êxito. Mesmo que o arquivo não seja tecnicamente o arquivo de símbolo correto, ele pode fornecer informações úteis.

Excluindo o cache

Se você estiver usando um DownstreamStore como 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, todos os arquivos de símbolo armazenados em cache corresponderão à versão anterior. Esses arquivos em cache não terão mais uso 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 armazenamentos são conhecidos como repositórios de símbolos em cascata.

Após o inicial srv* ou symsrv*ServerDLL*, cada token subsequente representa um local de símbolo. O token mais à 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ímbolo que usa dois repositórios downstream para armazenar informações do repositório de símbolos principal que está sendo acessado. 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 for encontrado lá, ele retornará um caminho para ele. Se não for encontrado lá, ele procurará em \\interim\store. Se o arquivo de símbolo for encontrado lá, o SymSrv o copiará para c:\localcache e retornará o caminho. Se ele não for encontrado lá, o SymSrv procurará no repositório de símbolos públicos da Microsoft em https://msdl.microsoft.com/download/symbols; 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 ignora qualquer repositório no qual não pode ler ou gravar. Portanto, se um compartilhamento ficar inativo, 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 formato compactado em qualquer repositório de nível médio. O arquivo será descompactado no repositório mais inferior do caminho.

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

Como discutido anteriormente, o encadeamento (ou cascata) refere-se à cópia que ocorre entre cada separador "*" no caminho do símbolo. Os símbolos são pesquisados em uma ordem da esquerda para a direita. Em cada falha, 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 que usam os servidores de símbolos.

Embora os 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 (já que não pode ser gravado para servir como 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 quebrada. Além disso, como o manipulador de símbolos não pode abrir um arquivo de um site, um repositório baseado em HTTP não deve ser o mais à esquerda ou o único repositório da lista. Se o SymSrv for apresentado com esse caminho de símbolo, ele tentará se recuperar copiando o arquivo para o repositório downstream padrão e abrindo-o a partir daí, independentemente de o repositório downstream padrão ser indicado no caminho do símbolo ou não.

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

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

Uma implantação comum somente UNC envolve um escritório central que hospeda todos os arquivos (\\MainOffice\Symbols), filiais armazenando em cache um subconjunto (\\BranchOfficeA\Symbols) e áreas de trabalho (C:\Symbols) armazenando em cache os arquivos aos quais eles fazem referência.

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

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

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

Quando o compartilhamento SMB é um repositório de símbolos intermediário (downstream), Read/Change é necessário. 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 SymProxy, somente Read é necessário. 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 do 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 seja usado normalmente, 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 caminho do símbolo. O depurador usará o diretório especificado localsymbolcache para armazenar todos os símbolos carregados 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 os símbolos obtidos de \\someshare. Ele usará c:\mysymbols para armazenar em cache os símbolos obtidos 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 os símbolos obtidos do repositório de símbolos público 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 serão anexados 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 é então usada para identificar o nome do arquivo desejado; esse nome é acrescentado ao caminho como um nome de diretório. Outro nome de diretório, que consiste na concatenação dos parâmetros id, two e three passados para SymbolServer, é então acrescentado. Se qualquer um desses valores for zero, eles serão omitidos.

O diretório resultante é pesquisado pelo arquivo de símbolo ou um arquivo de ponteiro de 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, o SymbolServer retornará FALSE.

Usando o AgeStore para reduzir o tamanho do cache

A ferramenta AgeStore pode ser usada para excluir arquivos em cache 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.