Usando o SymStore
SymStore (symstore.exe) é uma ferramenta para criar repositórios de símbolos. Ele está incluído no pacote Ferramentas de Depuração para Windows .
O SymStore armazena símbolos em um formato que permite que o depurador procure os símbolos com base no carimbo de data/hora e no tamanho da imagem (para um arquivo .dbg ou executável) ou assinatura e idade (para um arquivo .pdb). A vantagem do armazenamento de símbolos sobre o formato tradicional de armazenamento de símbolos é que todos os símbolos podem ser armazenados ou referenciados no mesmo servidor e recuperados pelo depurador sem qualquer conhecimento prévio de qual produto contém o símbolo correspondente.
Observe que várias versões dos arquivos de símbolo .pdb (por exemplo, versões públicas e privadas) não podem ser armazenadas no mesmo servidor, pois cada uma contém a mesma assinatura e idade.
Transações SymStore
Cada chamada para a SymStore é registrada como uma transação. Existem dois tipos de transações: adicionar e excluir.
Quando o repositório de símbolos é criado, um diretório, chamado "000admin", é criado sob a raiz do servidor. O diretório 000admin contém um arquivo para cada transação, bem como os arquivos de log Server.txt e History.txt. O arquivo Server.txt contém uma lista de todas as transações que estão atualmente no servidor. O arquivo History.txt contém um histórico cronológico de todas as transações.
Cada vez que o SymStore armazena ou remove arquivos de símbolos, um novo número de transação é criado. Em seguida, um arquivo, cujo nome é esse número de transação, é criado em 000admin. Esse arquivo contém uma lista de todos os arquivos ou ponteiros que foram adicionados ao repositório de símbolos durante essa transação. Se uma transação for excluída, o SymStore lerá seu arquivo de transação para determinar quais arquivos e ponteiros ele deve excluir.
As opções add e del especificam se uma transação add ou delete deve ser executada. Incluir a opção /p com uma operação add especifica que um ponteiro deve ser adicionado, omitindo a opção /p especifica que o arquivo de símbolo real deve ser adicionado.
Também é possível criar o repositório de símbolos em duas etapas separadas. No primeiro estágio, você usa o SymStore com a opção /x para criar um arquivo de índice. No segundo estágio, você usa o SymStore com a opção /y para criar o armazenamento real de arquivos ou ponteiros a partir das informações no arquivo de índice.
Esta pode ser uma técnica útil por uma variedade de razões. Por exemplo, isso permite que o repositório de símbolos seja facilmente recriado se o repositório for de alguma forma perdido, desde que o arquivo de índice ainda exista. Ou talvez o computador que contém os arquivos de símbolo tenha uma conexão de rede lenta com o computador no qual o armazenamento de símbolos será criado. Nesse caso, você pode criar o arquivo de índice na mesma máquina que os arquivos de símbolo, transferir o arquivo de índice para a segunda máquina e, em seguida, criar o armazenamento na segunda máquina.
Para obter uma lista completa de todos os parâmetros do SymStore, consulte Opções de linha de comando do SymStore.
Observação
A SymStore não suporta transações simultâneas de vários usuários. Recomenda-se que um usuário seja designado "administrador" do repositório de símbolos e seja responsável por todas as transações add e del .
Exemplos de transações
Aqui estão dois exemplos de SymStore adicionando ponteiros de símbolo para a compilação 3790 do Windows Server 2003 para \\sampledir\symsrv:
symstore add /r /p /f \\BuildServer\BuildShare\3790free\symbols\*.*
/s \\sampledir\symsrv /t "Windows Server 2003" /v "Build 3790 x86 free"
/c "Sample add"
symstore add /r /p /f \\BuildServer\BuildShare\3790Chk\symbols\*.*
/s \\sampledir\symsrv /t "Windows Server 2003" /v "Build 3790 x86 checked"
/c "Sample add"
No exemplo a seguir, o SymStore adiciona os arquivos de símbolo reais de um projeto de aplicativo em \\largeapp\appserver\bins a \\testdir\symsrv:
symstore add /r /f \\largeapp\appserver\bins\*.* /s \\testdir\symsrv
/t "Large Application" /v "Build 432" /c "Sample add"
Aqui está um exemplo de como um arquivo de índice é usado. Primeiro, o SymStore cria um arquivo de índice com base na coleção de arquivos de símbolo em \\largeapp\appserver\bins\. Nesse caso, o arquivo de índice é colocado em um terceiro computador, \\hubserver\hubshare. Use a opção /g para especificar que o prefixo do arquivo "\\largeapp\appserver" pode ser alterado no futuro:
symstore add /r /p /g \\largeapp\appserver /f
\\largeapp\appserver\bins\*.*
/x \\hubserver\hubshare\myindex.txt
Agora suponha que você mova todos os arquivos de símbolo para fora da máquina \\largeapp\appserver e coloque-os em \\myarchive\appserver. Em seguida, você pode criar o próprio repositório de símbolos a partir do arquivo de índice \\hubserver\hubshare\myindex.txt da seguinte maneira:
symstore add /y \\hubserver\hubshare\myindex.txt
/g \\myarchive\appserver /s \\sampledir\symsrv /p
/t "Large Application" /v "Build 432" /c "Sample Add from Index"
Finalmente, aqui está um exemplo de SymStore excluindo um arquivo adicionado por uma transação anterior. Consulte a seção a seguir para obter uma explicação de como determinar o ID da transação (neste caso, 0000000096).
symstore del /i 0000000096 /s \\sampledir\symsrv
Arquivos compactados
O SymStore pode ser usado com arquivos compactados de duas maneiras diferentes.
- Use o SymStore com a opção /p para armazenar ponteiros para os arquivos de símbolos. Após a conclusão do SymStore, compacte os arquivos aos quais os ponteiros se referem.
- Use o SymStore com a opção /x para criar um arquivo de índice. Após a conclusão do SymStore, compacte os arquivos listados no arquivo de índice. Em seguida, use o SymStore com a opção /y (e, se desejar, a opção /p) para armazenar os arquivos ou ponteiros para os arquivos no repositório de símbolos. (O SymStore não precisará descompactar os arquivos para executar essa operação.)
Seu servidor de símbolos será responsável por descompactar os arquivos quando eles forem necessários.
Se você estiver usando o SymSrv como seu servidor de símbolos, qualquer compactação deve ser feita usando a ferramenta compress.exe que é distribuída com o Microsoft Windows Software Development Kit (SDK). 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 SymSrv.
Os arquivos server.txt e history.txt
Quando uma transação é adicionada, vários itens de informações são adicionados a server.txt e history.txt para recursos de pesquisa futuros. Veja a seguir um exemplo de uma linha no server.txt e history.txt para uma transação de adição:
0000000096,add,ptr,10/09/99,00:08:32,Windows XP,x86 fre 1.156c-RTM-2,Added from \\mybuilds\symbols,
Esta é uma linha separada por vírgula. Os campos são definidos da seguinte forma.
| Campo | Descrição |
|---|---|
| 0000000096 | Número de ID da transação, conforme criado pela SymStore. |
| add | Tipo de transação. Este campo pode ser add ou del. |
| ptr | Se arquivos ou ponteiros foram adicionados. Este campo pode ser file ou ptr. |
| 10/09/99 | Data em que a transação ocorreu. |
| 00:08:32 | Hora em que a transação começou. |
| Windows XP | Produto. |
| x86 fre | Versão (opcional). |
| Adicionado de | Comentário (opcional) |
| Não usado | (Reservado para uso posterior.) |
Aqui estão algumas linhas de exemplo do arquivo de transação 0000000096. Cada linha registra o diretório e o local do arquivo ou ponteiro que foi adicionado ao diretório.
canon800.dbg\35d9fd51b000,\\mybuilds\symbols\sp4\dll\canon800.dbg
canonlbp.dbg\35d9fd521c000,\\mybuilds\symbols\sp4\dll\canonlbp.dbg
certadm.dbg\352bf2f48000,\\mybuilds\symbols\sp4\dll\certadm.dbg
certcli.dbg\352bf2f1b000,\\mybuilds\symbols\sp4\dll\certcli.dbg
certcrpt.dbg\352bf04911000,\\mybuilds\symbols\sp4\dll\certcrpt.dbg
certenc.dbg\352bf2f7f000,\\mybuilds\symbols\sp4\dll\certenc.dbg
Se você usar uma transação del para desfazer as transações add originais, essas linhas serão removidas do server.txt e a seguinte linha será adicionada a history.txt:
0000000105,del,0000000096
Os campos para a transação de exclusão são definidos da seguinte maneira.
| Campo | Descrição |
|---|---|
| 0000000105 | Número de ID da transação, conforme criado pela SymStore. |
| del | Tipo de transação. Este campo pode ser add ou del. |
| 0000000096 | Transação que foi excluída. |
Formato de armazenamento de símbolos
O SymStore usa o próprio sistema de arquivos como um banco de dados. Ele cria uma grande árvore de diretórios, com nomes de diretório baseados em coisas como carimbos de data/hora do arquivo de símbolos, assinaturas, idade e outros dados.
Por exemplo, depois que vários arquivos acpi.dbg diferentes foram adicionados ao servidor, os diretórios podem ter a seguinte aparência:
Directory of \\mybuilds\symsrv\acpi.dbg
10/06/1999 05:46p <DIR> .
10/06/1999 05:46p <DIR> ..
10/04/1999 01:54p <DIR> 37cdb03962040
10/04/1999 01:49p <DIR> 37cdb04027740
10/04/1999 12:56p <DIR> 37e3eb1c62060
10/04/1999 12:51p <DIR> 37e3ebcc27760
10/04/1999 12:45p <DIR> 37ed151662060
10/04/1999 12:39p <DIR> 37ed15dd27760
10/04/1999 11:33a <DIR> 37f03ce962020
10/04/1999 11:21a <DIR> 37f03cf7277c0
10/06/1999 05:38p <DIR> 37fa7f00277e0
10/06/1999 05:46p <DIR> 37fa7f01620a0
Neste exemplo, o caminho de pesquisa para o arquivo de símbolo acpi.dbg pode ter a seguinte aparência: \\mybuilds\symsrv\acpi.dbg\37cdb03962040.
Três arquivos podem existir dentro do diretório de pesquisa:
- Se o arquivo foi armazenado, então acpi.dbg existirá lá.
- Se um ponteiro foi armazenado, um arquivo chamado file.ptr existirá e conterá o caminho para o arquivo de símbolo real.
- Um arquivo chamado refs.ptr, que contém uma lista de todos os locais atuais para acpi.dbg com esse carimbo de data/hora e tamanho de imagem que estão atualmente adicionados ao repositório de símbolos.
A exibição da listagem de diretórios de \\mybuilds\symsrv\acpi.dbg\37cdb03962040 fornece o seguinte:
10/04/1999 01:54p 52 file.ptr
10/04/1999 01:54p 67 refs.ptr
O arquivo file.ptr contém a cadeia de texto "\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg". Como não há nenhum arquivo chamado acpi.dbg nesse diretório, o depurador tentará localizar o arquivo em \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg.
O conteúdo de refs.ptr é usado apenas pelo SymStore, não pelo depurador. Esse arquivo contém um registro de todas as transações que ocorreram nesse diretório. Uma linha de exemplo de refs.ptr pode ser:
0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg
Isso mostra que um ponteiro para \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg foi adicionado com a transação "0000000026".
Alguns arquivos de símbolo permanecem constantes através de vários produtos ou compilações ou um produto específico. Um exemplo disso é o arquivo msvcrt.pdb. Fazer um diretório de \\mybuilds\symsrv\msvcrt.pdb mostra que apenas duas versões do msvcrt.pdb foram adicionadas ao servidor de símbolos:
Directory of \\mybuilds\symsrv\msvcrt.pdb
10/06/1999 05:37p <DIR> .
10/06/1999 05:37p <DIR> ..
10/04/1999 11:19a <DIR> 37a8f40e2
10/06/1999 05:37p <DIR> 37f2c2272
No entanto, fazer um diretório de \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2 mostra que refs.ptr tem vários ponteiros.
Directory of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2
10/05/1999 02:50p 54 file.ptr
10/05/1999 02:50p 2,039 refs.ptr
O conteúdo de \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2\refs.ptr é o seguinte:
0000000001,ptr,\\mybuilds\symbols\x86\2137\symbols\dll\msvcrt.pdb
0000000002,ptr,\\mybuilds\symbols\x86\2137.chk\symbols\dll\msvcrt.pdb
0000000003,ptr,\\mybuilds\symbols\x86\2138\symbols\dll\msvcrt.pdb
0000000004,ptr,\\mybuilds\symbols\x86\2138.chk\symbols\dll\msvcrt.pdb
0000000005,ptr,\\mybuilds\symbols\x86\2139\symbols\dll\msvcrt.pdb
0000000006,ptr,\\mybuilds\symbols\x86\2139.chk\symbols\dll\msvcrt.pdb
0000000007,ptr,\\mybuilds\symbols\x86\2140\symbols\dll\msvcrt.pdb
0000000008,ptr,\\mybuilds\symbols\x86\2140.chk\symbols\dll\msvcrt.pdb
0000000009,ptr,\\mybuilds\symbols\x86\2136\symbols\dll\msvcrt.pdb
0000000010,ptr,\\mybuilds\symbols\x86\2136.chk\symbols\dll\msvcrt.pdb
0000000011,ptr,\\mybuilds\symbols\x86\2135\symbols\dll\msvcrt.pdb
0000000012,ptr,\\mybuilds\symbols\x86\2135.chk\symbols\dll\msvcrt.pdb
0000000013,ptr,\\mybuilds\symbols\x86\2134\symbols\dll\msvcrt.pdb
0000000014,ptr,\\mybuilds\symbols\x86\2134.chk\symbols\dll\msvcrt.pdb
0000000015,ptr,\\mybuilds\symbols\x86\2133\symbols\dll\msvcrt.pdb
0000000016,ptr,\\mybuilds\symbols\x86\2133.chk\symbols\dll\msvcrt.pdb
0000000017,ptr,\\mybuilds\symbols\x86\2132\symbols\dll\msvcrt.pdb
0000000018,ptr,\\mybuilds\symbols\x86\2132.chk\symbols\dll\msvcrt.pdb
0000000019,ptr,\\mybuilds\symbols\x86\2131\symbols\dll\msvcrt.pdb
0000000020,ptr,\\mybuilds\symbols\x86\2131.chk\symbols\dll\msvcrt.pdb
0000000021,ptr,\\mybuilds\symbols\x86\2130\symbols\dll\msvcrt.pdb
0000000022,ptr,\\mybuilds\symbols\x86\2130.chk\symbols\dll\msvcrt.pdb
0000000023,ptr,\\mybuilds\symbols\x86\2129\symbols\dll\msvcrt.pdb
0000000024,ptr,\\mybuilds\symbols\x86\2129.chk\symbols\dll\msvcrt.pdb
0000000025,ptr,\\mybuilds\symbols\x86\2128\symbols\dll\msvcrt.pdb
0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\dll\msvcrt.pdb
0000000027,ptr,\\mybuilds\symbols\x86\2141\symbols\dll\msvcrt.pdb
0000000028,ptr,\\mybuilds\symbols\x86\2141.chk\symbols\dll\msvcrt.pdb
0000000029,ptr,\\mybuilds\symbols\x86\2142\symbols\dll\msvcrt.pdb
0000000030,ptr,\\mybuilds\symbols\x86\2142.chk\symbols\dll\msvcrt.pdb
Isso mostra que o mesmo msvcrt.pdb foi usado para várias compilações de símbolos armazenados em \\mybuilds\symsrv.
Aqui está um exemplo de um diretório que contém uma mistura de adições de arquivo e ponteiro:
Directory of E:\symsrv\dbghelp.dbg\38039ff439000
10/12/1999 01:54p 141,232 dbghelp.dbg
10/13/1999 04:57p 49 file.ptr
10/13/1999 04:57p 306 refs.ptr
Neste caso, refs.ptr tem o seguinte conteúdo:
0000000043,file,e:\binaries\symbols\retail\dll\dbghelp.dbg
0000000044,file,f:\binaries\symbols\retail\dll\dbghelp.dbg
0000000045,file,g:\binaries\symbols\retail\dll\dbghelp.dbg
0000000046,ptr,\\sampledir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\sampledir2\bin\symbols\retail\dll\dbghelp.dbg
Assim, as transações 43, 44 e 45 adicionaram o mesmo arquivo ao servidor, e as transações 46 e 47 adicionaram ponteiros. Se as transações 43, 44 e 45 forem excluídas, o arquivo dbghelp.dbg será excluído do diretório. O diretório terá, então, o seguinte conteúdo:
Directory of e:\symsrv\dbghelp.dbg\38039ff439000
10/13/1999 05:01p 49 file.ptr
10/13/1999 05:01p 130 refs.ptr
Agora file.ptr contém "\\sampledir2\bin\symbols\retail\dll\dbghelp.dbg" e refs.ptr contém
0000000046,ptr,\\sampledir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\sampledir2\bin\symbols\retail\dll\dbghelp.dbg
Sempre que a entrada final em refs.ptr for um ponteiro, o arquivo file.ptr existirá e conterá o caminho para o arquivo associado. Sempre que a entrada final em refs.ptr for um arquivo, nenhum file.ptr existirá neste diretório. Portanto, qualquer operação de exclusão que remova a entrada final em refs.ptr pode resultar em file.ptr sendo criado, excluído ou alterado.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de