Especificar arquivos de símbolo (.pdb) e de origem no Depurador do Visual Studio (C#, C++, Visual Basic, F#)

Arquivos de banco de dados de programa (.pdb), também chamados de arquivos de símbolo, identificadores de mapa e instruções no código-fonte do projeto para os identificadores e instruções correspondentes nos aplicativos compilados. Esses arquivos de mapeamento vinculam o depurador ao código-fonte, o que permite a depuração.

Quando você compila um projeto do IDE do Visual Studio com a configuração de build de depuração padrão, o compilador cria os arquivos de símbolo apropriados. Este artigo descreve como gerenciar os arquivos de símbolo no IDE, por exemplo:

• Configurar o local dos arquivos de símbolo
• Carregar os símbolos durante a depuração
• Opções de compilador para símbolos.

Para obter uma explicação detalhada dos arquivos de símbolo, confira o seguinte:

• Entender os arquivos de símbolo e as configurações de símbolo do Visual Studio

Como funcionam os arquivos de símbolo

O arquivo .pdb contém informações de depuração e estado do projeto que permitem a vinculação incremental de uma configuração de Depuração do seu aplicativo. O depurador do Visual Studio usa arquivos .pdb para determinar duas partes principais de informações durante a depuração:

• O nome do arquivo de origem e o número de linha a serem exibidos no IDE do Visual Studio.
• Onde parar no aplicativo para um ponto de interrupção.

Os arquivos de símbolo também mostram o local dos arquivos de origem e, opcionalmente, o servidor em que serão recuperados.

O depurador carrega apenas os arquivos .pdb que correspondem exatamente aos arquivos .pdb criados quando um aplicativo foi compilado (ou seja, os arquivos .pdb ou cópias originais). Essa duplicação exata é necessária porque o layout dos aplicativos pode ser alterado mesmo que o próprio código não tenha sido alterado. Para obter mais informações, confira Por que o Visual Studio exige que os arquivos de símbolo do depurador correspondam exatamente aos arquivos binários com que foram compilados?

Dica

Para depurar códigos fora do código-fonte do projeto, como o código do Windows ou o código de terceiros que seu projeto chama, você deve especificar o local dos arquivos .pdb do código externo (e, opcionalmente, os arquivos de origem), que devem corresponder exatamente aos builds no seu aplicativo.

Onde o depurador procura símbolos

Quando você depura um projeto no IDE do Visual Studio, o depurador carrega automaticamente os arquivos de símbolo que pode encontrar por padrão.

Observação

Ao depurar o código gerenciado em um dispositivo remoto, todos os arquivos de símbolo devem estar localizados no computador local ou em um local especificado nas opções do depurador.

O depurador procura arquivos de símbolo nos seguintes locais:

1. A pasta do projeto.

2. No local especificado dentro da DLL ou do arquivo executável (.exe).

   Por padrão, se você compilou uma DLL ou um arquivo .exe no seu computador, o vinculador coloca o caminho completo e o nome do arquivo associado .pdb dentro da DLL ou do arquivo .exe file. O depurador verifica se o arquivo de símbolo existe nesse local.

3. A mesma pasta da DLL ou do arquivo .exe.

4. Os locais especificados nas opções do depurador para arquivos de símbolo. Para adicionar e habilitar locais de símbolo, confira Configurar locais de símbolo e opções de carregamento.

   • Qualquer pasta de cache de símbolo local.

   • Servidores e locais de símbolo especificados na rede, Internet ou no local, como os Microsoft Symbol Servers, se selecionado. O Visual Studio pode baixar arquivos de símbolo de depuração nos servidores de símbolo que implementam o protocolo symsrv. O Visual Studio Team Foundation Server e as Ferramentas de Depuração para Windows são duas ferramentas que podem usar servidores de símbolo.

     Os servidores de símbolo que você pode usar incluem:

     Servidores de Símbolo Públicos da Microsoft: para depurar uma falha que ocorre durante uma chamada a uma DLL do sistema ou a uma biblioteca de terceiros, geralmente são necessários os arquivos .pdb. Arquivos .pdb do sistema contêm símbolos para DLLs do Windows, arquivos .exe e drivers de dispositivo. Você pode obter símbolos para os sistemas operacionais Windows, MDAC, IIS, ISA e .NET dos Servidores de Símbolo Públicos da Microsoft.

     Servidores de símbolo em uma rede interna ou no seu computador local: sua equipe ou empresa pode criar servidores de símbolo para seus próprios produtos e como um cache para símbolos de fontes externas. Você pode ter um servidor de símbolo no seu próprio computador.

     Servidores de símbolo de terceiros: os provedores de terceiros de aplicativos e bibliotecas do Windows podem fornecer acesso ao servidor de símbolo na Internet.

     Aviso

     Ao usar um servidor de símbolo que não seja um dos servidores de símbolo públicos da Microsoft, verifique se o servidor de símbolo e seu caminho são confiáveis. Como os arquivos de símbolo podem conter códigos executáveis arbitrários, você pode ser exposto às ameaças de segurança.

Configurar o local dos arquivos de símbolo e as opções de carregamento

O depurador verifica vários locais em busca de símbolos por padrão. Confira Onde o depurador procura símbolos.

Na página Ferramentas>Opções>Depuração>Símbolos, você pode fazer o seguinte:

• Especifique e selecione os caminhos de pesquisa para arquivos de símbolo.
• Especifique os servidores de símbolo para componentes da Microsoft, do Windows ou de terceiros.
• Especifique os módulos em que você deseja ou não que o depurador carregue os símbolos automaticamente.
• Altere essas configurações durante a depuração ativa. Confira Carregar os símbolos durante a depuração.

Para especificar os locais de símbolo e as opções de carregamento:

1. No Visual Studio, abra Ferramentas>Opções>Depuração>Símbolos (ou Depurar>Opções>Símbolos).

2. Em Locais do arquivo de símbolo (.pdb),

   • Para usar os Servidores de Símbolo da Microsoft ou o Servidor de Símbolo NuGet.org, marque a caixa de seleção.

   • Para adicionar um novo local de servidor de símbolo,

     1. Selecione o símbolo + na barra de ferramentas.
     2. Digite a URL (http), o compartilhamento de rede ou o caminho local do servidor de símbolo ou do local de símbolo no campo de texto. O preenchimento de instruções ajuda você a localizar o formato correto.

     

     Observação

     Somente a pasta especificada é pesquisada. Você deve adicionar entradas para todas as subpastas que deseja pesquisar.

   • Para adicionar um novo local de Servidor de Símbolo do Azure DevOps:

     1. Selecione o ícone na barra de ferramentas.

     2. Na caixa de diálogo Conectar-se ao Servidor de Símbolo do Azure DevOps, escolha um dos servidores de símbolo disponíveis e selecione Conectar.

        Para obter informações adicionais, confira Adicionar servidor de símbolo do Azure Artifacts.

   • Para alterar a ordem de carregamento para os locais de símbolo, use Ctrl+Up e Ctrl+Down ou os ícones de seta Up e Down.

   • Para editar uma URL ou um caminho, clique duas vezes na entrada ou selecione-o e pressione F2.

   • Para remover uma entrada, selecione-a e o ícone -.

3. (Opcional) Para melhorar o desempenho de carregamento de símbolo, em Símbolos de cache nesse diretório, digite um caminho de pasta local em que os servidores de símbolos podem copiar símbolos.

   Observação

   Não coloque o cache de símbolo local em uma pasta protegida, como C:\Windows ou uma subpasta. Use uma pasta de leitura/gravação.

   Observação

   Para projetos C++, se você tiver a variável de ambiente _NT_SYMBOL_PATH definida, ela substituirá o valor definido em Símbolos de cache neste diretório.

4. Especifique os módulos que você deseja que o depurador carregue nos locais de arquivo de símbolo (.pdb), quando ele for iniciado.

   • Selecione Carregar todos os módulos, a menos que excluídos (o padrão) para carregar todos os símbolos de todos os módulos no local do arquivo de símbolo, exceto os módulos que você excluir especificamente. Para excluir determinados módulos, selecione Especificar módulos excluídos, selecione o ícone +, digite os nomes dos módulos a serem excluídos e selecione OK.

   • Para carregar apenas os módulos especificados nos locais do arquivo de símbolo, selecione Carregar somente módulos especificados. Selecione Especificar módulos incluídos, selecione o ícone +, digite os nomes dos módulos a serem incluídos e selecione OK. Os arquivos de símbolo para outros módulos não serão carregados.

5. Selecione OK.

Outras opções de símbolo para depuração

Você pode selecionar opções de símbolo adicionais em Ferramentas>Opções>Depuração>Geral (ou Depurar>Opções>Geral):

• Carregar exportações de dll (somente Nativas)

  Carrega as tabelas de exportação de DLL para C/C++. Para obter detalhes, confira Tabelas de exportação de DLL. A leitura das informações de exportação de DLL envolve determinada sobrecarga. Portanto, o carregamento de tabelas de exportação é desativado por padrão. Você também pode usar dumpbin /exports em uma linha de comando de build do C/C++.

• Habilitar depuração no nível do endereço e Mostrar desmontagem se a origem não estiver disponível

  Mostra sempre a desmontagem quando os arquivos de origem ou de símbolo não são encontrados.

  

• Habilitar suporte a servidor de origem

  Use o Servidor de Origem para ajudar a depurar uma aplicativo quando não houver código-fonte no computador local ou quando o arquivo .pdb não corresponder ao código-fonte. O Servidor de Origem recebe solicitações de arquivos e retorna os arquivos reais do controle do código-fonte. O Servidor de Origem é executado usando uma DLL chamada srcsrv.dll para ler o arquivo .pdb do aplicativo. O arquivo .pdb contém ponteiros para o repositório do código-fonte, bem como os comandos usados para recuperar o código-fonte do repositório.

  Você pode limitar os comandos que o srcsrv.dll podem executar no arquivo .pdb do aplicativo, listando os comandos permitidos em um arquivo chamado srcsrv.ini. Coloque o arquivo desrcsrv.ini na mesma pasta que o srcsrv.dll e o devenv.exe.

  Importante

  Comandos arbitrários podem ser inseridos em um arquivo .pdb do aplicativo. Portanto, coloque somente aqueles que você deseja executar no arquivo srcsrv.ini. Qualquer tentativa de executar um comando que não esteja no arquivo srcsvr.ini fará com que uma caixa de diálogo de confirmação seja exibida. Para obter mais informações, confira Aviso de segurança: o depurador deve executar um comando não confiável.

  Nenhuma validação é feita em parâmetros do comando. Portanto, tenha cuidado com comandos confiáveis. Por exemplo, se você listou cmd.exe no seu srcsrv.ini, um usuário mal-intencionado pode especificar parâmetros no cmd.exe que o tornariam perigoso.

  Selecione este item e os itens filho desejados. Permitir servidor de código-fonte para assemblies de confiança parcial (somente gerenciados) e Executar sempre comandos não confiáveis do servidor de código-fonte, sem aviso podem aumentar os riscos de segurança.

  

Opções de símbolo do compilador

Quando você compila um projeto no IDE do Visual Studio com a configuração de build padrão Depurar, o C++ e os compiladores gerenciados criam os arquivos de símbolo apropriados para o código. Você também pode definir as opções do compilador no código.

Para definir as opções do compilador para suas configurações de build no Visual Studio, confira Definir configurações de depuração e versão.

Opções do .NET

Compile com /debug para criar um arquivo .pdb. Você pode compilar aplicativos com /debug:full ou /debug:pdbonly. Compilar com /debug:full gera o código depurável. Compilar com /debug:pdbonly gera arquivos .pdb, mas não gera o DebuggableAttribute que informa ao compilador JIT que as informações de depuração estão disponíveis. Use /debug:pdbonlyse desejar gerar arquivos .pdb para um build de versão que você não deseja que seja depurável. Para obter mais informações, confira /debug (opções do compilador C#) ou /debug (Visual Basic).

Opções do C/C++

• Arquivos VC<x>.pdb e <project>.pdb

  Um arquivo .pdb para C/CC++ é criado quando você compila com /ZI ou /Zi. No Visual C++, a opção /Fd nomeia o arquivo .pdb que o compilador cria. Quando você cria um projeto no Visual Studio usando o IDE, a opção /Fd é definida para criar um arquivo .pdb chamado <project>.pdb.

  Se você compilar seu aplicativo C/C++ usando um makefile e especificar /ZI ou /Zi sem usar /Fd para especificar um nome de arquivo, o compilador criará dois arquivos .pdb:

  • VC<x>.pdb, onde <x> representa a versão do compilador do Microsoft C++, por exemplo VC11.pdb

    O arquivo VC<x>.pdb armazena todas as informações de depuração para arquivos OBJ individuais e reside no mesmo diretório que o makefile do projeto. Sempre que um arquivo OBJ é criado, o compilador C/C++ mescla as informações de depuração com o VC<x>.pdb. Assim, mesmo que todos os arquivos de origem incluam arquivos de cabeçalhos comuns, como <windows.h>, os typedefs desses cabeçalhos são armazenados somente uma vez, e não em todos os arquivos de objeto. As informações inseridas incluem informações de tipo, mas não incluem informações de símbolo como definições de função.

  • <project>.pdb

    O arquivo <project.pdb> armazena todas as informações de depuração para o arquivo .exe do projeto e reside no subdiretório \debug. O arquivo <projeto>.pdb contém todas as informações de depuração, incluindo protótipos de função, não apenas as informações de tipo encontradas no VC<x>.pdb.

  Os arquivos VC<x.pdb> e <project.pdb> permitem atualizações incrementais. O vinculador também insere o caminho no arquivo .pdb do arquivo .exe ou .dll que ele cria.

• Tabelas de exportação de DLL

  Use dumpbin /exports para ver os símbolos disponíveis na tabela de exportação de uma DLL. As informações simbólicas das tabelas de exportação de DLL podem ser úteis ao trabalhar com mensagens do Windows, procedimentos do Windows (WindowProcs), objetos COM, marshaling ou qualquer DLL para a qual você não tem símbolos. Os símbolos estão disponíveis para qualquer DLL de 32 bits do sistema. As chamadas são listadas na ordem de chamada, com a função atual (a mais profundamente aninhada) na parte superior.

  Ao ler a saída dumpbin /exports, você pode ver os nomes exatos da função, incluindo caracteres não alfanuméricos. Ver os nomes exatos da função é útil para definir um ponto de interrupção em uma função, pois os nomes da função podem ser truncados em outro lugar no depurador. Para obter mais informações, confira dumpbin /exports.

Aplicativos Web

Defina o arquivo web.config do aplicativo ASP.NET como modo de depuração. O modo de depuração faz com que o ASP.NET gere símbolos para arquivos gerados dinamicamente e permite que o depurador se anexe ao aplicativo ASP.NET. O Visual Studio define isso automaticamente quando você inicia a depuração, caso você tenha criado o projeto do modelo projetos Web.

Carregar os símbolos durante a depuração

Você pode usar as janelas Módulos, Pilha de Chamadas, Locais, Autos ou qualquer janela Inspeção para carregar símbolos ou alterar opções de símbolo durante a depuração. Para obter mais informações, confira Familiarize-se mais com a forma como o depurador se anexa ao seu aplicativo.

Trabalhar com símbolos na janela Módulos

Durante a depuração, a janela Módulos mostra os módulos de código que o depurador está tratando como código do usuário ou Meu Código e o status de carregamento de símbolo. Você também pode monitorar o status de carregamento de símbolos, carregar símbolos e alterar as opções de símbolo na janela Módulos.

Para monitorar ou alterar locais ou opções de símbolo durante a depuração:

1. Para abrir a janela Módulos durante a depuração, selecione Depurar>Windows>Módulos (ou pressione Ctrl + Alt + U).
2. Na janela Módulos, clique com o botão direito do mouse nos cabeçalhos Status de Símbolo ou Arquivo de Símbolo ou em qualquer módulo.
3. No menu de contexto, selecione uma das seguintes opções:

Opção	Descrição
Carregar Símbolos	Aparece para módulos com símbolos ignorados, não encontrados ou não carregados. Tenta carregar símbolos de locais especificados na página Opções>Depuração>Símbolos. Se o arquivo de símbolo não for encontrado ou não for carregado, o Explorador de Arquivos será iniciado para que você possa especificar um novo local para pesquisar.
Informações de Carregamento de Símbolos	Mostra o local de um arquivo de símbolo carregado ou os locais que foram pesquisados se o depurador não puder localizar o arquivo.
Configurações de Símbolo	Abre a página Opções>Depuração>Símbolos, na qual você pode editar e adicionar locais de símbolo.
Sempre Carregar Automaticamente	Adiciona o arquivo de símbolo selecionado à lista de arquivos carregados automaticamente pelo depurador.

Usar as páginas Nenhum Símbolo Carregado/Nenhuma Origem Carregada

Há várias maneiras em que o depurador pode invadir o código que não tem arquivos de símbolo ou de origem disponíveis:

• Intervir no código.
• Invadir o código a partir de um ponto de interrupção ou exceção.
• Mudar para outro thread.
• Alterar o registro de ativação clicando duas vezes em um quadro na janela Pilha de Chamadas.

Quando isso acontece, o depurador exibe as páginas Nenhum Símbolo Carregado ou Nenhuma Origem Carregada para ajudar você a localizar e carregar a origem ou os símbolos necessários.

Para usar a página do documento Nenhum Símbolo Carregado para ajudar a localizar e carregar símbolos ausentes:

• Para alterar o caminho de pesquisa, selecione um caminho não selecionado ou selecione Novo Caminho ou Novo Caminho do VSTS e insira ou selecione um novo caminho. Selecione Carregar para pesquisar novamente e carregar o arquivo de símbolo, caso seja encontrado.
• Para substituir as opções de símbolo e repetir os caminhos de pesquisa, selecione Procurar e localizar <executable-name>. O arquivo de símbolo será carregado, se encontrado, ou o Explorador de Arquivos será exibido para que você selecione manualmente o arquivo de símbolo.
• Para abrir a página de configurações de símbolo para definir o comportamento, selecione Alterar Configurações de Símbolo (ou escolha Opções>Depuração>Símbolos ).
• (Avançado) Para mostrar a desmontagem em uma nova janela uma vez, selecione a desmontagem de exibição ou selecione a caixa de diálogo Opções para definir a opção para sempre mostrar a desmontagem, quando os arquivos de origem ou de símbolo não forem encontrados. Para obter mais informações, confira Exibir código de desmontagem.
• Para mostrar os locais pesquisados e o resultado, expanda Informações de carregamento de símbolo.
• Para código C#, você também pode optar por descompilar o código-fonte das páginas Nenhum Símbolo Carregado ou Nenhuma Origem Carregada.

Se o depurador localizar o arquivo .pdb depois que você executar uma das opções e puder recuperar o arquivo de origem usando as informações no arquivo .pdb, a origem será exibida. Caso contrário, ele exibirá a página Nenhuma Origem Carregada que descreve o problema com links para ações que podem resolver o problema.

Para adicionar caminhos de pesquisa do arquivo de origem a uma solução:

Você pode especificar os locais em que o depurador pesquisa arquivos de origem e excluir arquivos específicos da pesquisa.

1. Selecione a solução no Gerenciador de Soluções e selecione o ícone Propriedades, pressione Alt+Enter ou clique com o botão direito do mouse e selecione Propriedades.

2. Selecione Depurar Arquivos de Origem.

   

3. Em Diretórios que contêm código-fonte, digite ou selecione locais de código-fonte para pesquisar. Use o ícone Nova Linha para adicionar locais, os ícones de seta Up e Down para reordená-los ou o ícone X para excluí-los.

   Observação

   O depurador pesquisa apenas o diretório especificado. Você deve adicionar entradas para todos os subdiretórios que deseja pesquisar.

4. Em Não procurar esses arquivos de origem, digite os nomes dos arquivos de origem a serem excluídos da pesquisa.

5. Selecione OK ou Aplicar.

Conteúdo relacionado

• Entender os arquivos de símbolo e as configurações de símbolo do Visual Studio