Especificar o símbolo (.pdb) e os arquivos 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ímbolos, mapeiam identificadores e instruções no código-fonte do projeto para identificadores e instruções correspondentes em aplicativos compilados. Esses arquivos de mapeamento vinculam o depurador ao código-fonte, o que permite a depuração.

Quando você constrói um projeto na IDE do Visual Studio com a configuração padrão de compilação Debug, o compilador cria os arquivos de símbolo apropriados. Este artigo descreve como gerenciar 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 do compilador para símbolos

Para obter uma explicação detalhada dos arquivos de símbolo, consulte Entenda 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 estado de projeto e de depuração que permitem a vinculação incremental de uma configuração de depuração do seu aplicativo. O depurador do Visual Studio usa arquivos de .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 colocar um ponto de interrupção no aplicativo

Os arquivos de símbolo também mostram o local dos arquivos de origem e, opcionalmente, o servidor do qual recuperá-los.

O depurador carrega apenas os arquivos .pdb que correspondem exatamente aos arquivos .pdb criados quando um aplicativo foi desenvolvido (ou seja, os arquivos .pdb originais ou cópias). Essa duplicação exata é necessária porque o layout dos aplicativos pode ser alterado mesmo se o próprio código não for alterado. Para obter mais informações, consulte Por que o Visual Studio requer arquivos de símbolo de depurador para corresponder exatamente aos arquivos binários com os quais eles foram criados?

Dica

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

Onde o depurador procura símbolos

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

Nota

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, na ordem especificada:

1. A pasta do projeto.

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

   Por padrão, se você tiver criado uma DLL ou um arquivo .exe em seu computador, o vinculador colocará o caminho completo e o nome de arquivo do arquivo .pdb associado no arquivo DLL ou .exe. O depurador verifica se o arquivo de símbolo existe nesse local.

3. A mesma pasta que a DLL ou o 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ímbolos Públicos da Microsoft: Para depurar uma falha que ocorre durante uma chamada para uma DLL do sistema ou para uma biblioteca de terceiros, você geralmente precisa dos arquivos .pdb do sistema . Os arquivos .pdb do sistema contêm símbolos para DLLs do Windows, arquivos .exe e drivers de dispositivo. Você pode obter símbolos para sistemas operacionais Windows, MDAC, IIS, ISA e .NET dos Servidores de Símbolos públicos da Microsoft.

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

     servidores de símbolos de terceiros: provedores de terceiros de aplicativos e bibliotecas do Windows podem fornecer acesso ao servidor de símbolos na Internet.

Aviso

Se você usar um servidor de símbolos diferente dos Servidores de Símbolos da Microsoft públicos, verifique se o servidor de símbolos e seu caminho são confiáveis. Como os arquivos de símbolo podem conter código executável arbitrário, você pode ser exposto a 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. Para obter mais informações, consulte Onde o depurador procura símbolos.

No menu Ferramentas (ou Depuração), > você pode acessar as opções de Símbolos de Depuração:

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

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

1. Abra o painel Opções de Ferramentas (ou >), e expanda a seção Todas as Configurações, Depuração, >, Símbolos, >.

2. No painel direito, marque a caixa de seleção para cada servidor desejado: Servidores de Símbolos da Microsoft, NuGet.org Servidor de Símbolos e assim por diante.

3. Adicione um novo local do servidor de símbolos selecionando + Adicionar na barra de ferramentas para o grupo de caixa Locais do arquivo de símbolo (.pdb).

   Insira a URL (http), o compartilhamento de rede ou o caminho local do servidor de símbolos ou do local do símbolo no campo de texto. O preenchimento de instruções ajuda você a localizar o formato correto.

   

   Nota

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

   Selecione a caixa de seleção Habilitada e, em seguida, selecione Salvar.

4. Adicione um novo local do Servidor de Símbolos do Azure DevOps selecionando o link Novo local do Servidor de Símbolos do Azure DevOps.

   Na caixa de diálogo Conectar ao Servidor de Símbolos do Azure DevOps , selecione um servidor de símbolos disponível e, em seguida, selecione Conectar.

   

   Para obter mais informações, consulte Adicionar servidor de símbolos do Azure Artifacts.

   • Para alterar a ordem de carregamento dos locais de símbolo, use Ctrl + Para Cima e Ctrl + Para Baixo ou selecione Mover para cima e Mover para baixo.
   • Para editar uma URL ou caminho, clique duas vezes na entrada ou realce a entrada e selecione Editar.
   • Para remover uma entrada, realce a entrada e selecione Remover.

5. (Opcional) Melhore o desempenho de carregamento de símbolos especificando um caminho de pasta local para símbolos copiados.

   Para os símbolos de Cache nesta opção de diretório, insira um caminho de pasta local para o qual os servidores de símbolos podem copiar símbolos.

   Nota

   • Não coloque o cache de símbolo local em uma pasta protegida, como C:\Windows ou uma subpasta. Em vez disso, use uma pasta de leitura e gravação.

   • Se a variável de ambiente _NT_SYMBOL_PATH for definida, o valor substituirá os símbolos de Cache nesse valor de diretório .

6. Especifique os módulos para o depurador carregar dos locais do arquivo de símbolo (.pdb) ao iniciar.

   1. Altere para a seção Todas as Configurações>Depuração>Gerais>Símbolos>Pesquisa e Carregamento.

   2. Use a lista suspensa para definir o valor da opção Pesquisa Automática de Símbolos:

      • Escolha automaticamente quais símbolos de módulo procurar (recomendado): permita que o Visual Studio decida quais símbolos pesquisar e carregar. Por padrão, o Visual Studio carrega automaticamente símbolos criados pela solução aberta e carrega todos os outros símbolos necessários para executar operações comuns de depuração. Essa opção reduz o número de arquivos que devem ser pesquisados e carregados pelo Visual Studio, o que melhora o desempenho do depurador. Você pode forçar outros símbolos a serem carregados criando a lista de módulos incluídos.

        

      • Pesquise todos os símbolos de módulo, exceto certos excluídos: Forçar o Visual Studio a carregar todos os símbolos em seu processo depurado. Essa opção não é recomendada porque pode diminuir sua experiência de depuração. Você pode forçar o Visual Studio a ignorar determinados símbolos criando a lista de módulos Excluídos.

        

Especificar filtros de módulo

As opções Escolher automaticamente... e Pesquisar todas... permitem controlar quais símbolos são pesquisados durante a depuração.

Para a opção Escolher automaticamente quais símbolos de módulo procurar, especifique a lista de pesquisa criando a lista de módulos incluídos.

1. Selecione + Adicionar na barra de ferramentas da lista.

2. Na caixa de diálogo Adicionar Item , insira o Nome do Módulo, selecione a caixa de seleção Habilitada e, em seguida, selecione Salvar.

3. Adicione mais itens à lista, conforme necessário.

Os filtros de módulo oferecem suporte à correspondência simples de curingas. O asterisco * corresponde a qualquer grupo de caracteres. Por exemplo, *myproduct* corresponde a arquivos como myproduct.utilities.dll e entrypoint.myproduct.exe, entre outros.

Você pode configurar outras opções para personalizar sua experiência:

• Sempre carregue símbolos localizados ao lado de módulos: o Visual Studio carrega arquivos .pdb armazenados no sistema de arquivos com seus correspondentes arquivos .dll ou .exe. Essa abordagem pode ser útil, como ao tentar depurar um aplicativo Web implantado.

• Carregue automaticamente símbolos adicionais quando necessário: o Visual Studio pesquisa símbolos para executar ações comuns de depuração, como etapas, mesmo que o módulo no qual você está pisando não esteja no projeto ou no filtro de módulos. A maneira como a pesquisa é determinada pode ser afetada pelas configurações do Just My Code .

Para a opção Pesquisar todos os símbolos de módulo, a menos que excluídos, especifique a lista de pesquisa criando a lista de módulos excluídos.

1. Selecione + Adicionar na barra de ferramentas da lista.

2. Na caixa de diálogo Adicionar Item , insira o Nome do Módulo, selecione a caixa de seleção Habilitada e, em seguida, selecione Salvar.

3. Adicione mais itens à lista, conforme necessário.

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

Você pode selecionar mais opções de símbolo de depuração no menu Opções de Ferramentas (ou Depuração>).

As configurações a seguir estão disponíveis na seção Todas as Configurações>Depuração>Geral.

• Carregar exportações de dll (somente nativo): carrega tabelas de exportação de DLL para C/C++. Para detalhes, consulte as tabelas de exportação de DLL . A leitura de informações de exportação de DLL envolve alguma 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 C/C++.

• Habilite a depuração no nível do endereço e mostre a desmontagem se a origem não estiver disponível: sempre mostra a desmontagem quando os arquivos de origem ou símbolo não são encontrados.

• Habilitar o suporte ao servidor de origem: usa o Servidor de Origem para ajudar a depurar um aplicativo quando não há código-fonte no computador local ou o arquivo .pdb não corresponde ao código-fonte. O Servidor de Origem aceita solicitações de arquivos e retorna os arquivos reais do controle do código-fonte. O Source Server é executado usando uma DLL chamada srcsrv.dll para ler o arquivo .pdb do aplicativo. O arquivo .pdb contém ponteiros para o repositório de código-fonte e comandos usados para recuperar o código-fonte do repositório.

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

  Importante

  Comandos arbitrários podem ser inseridos no arquivo .pdb de um aplicativo, portanto, coloque apenas os comandos que você deseja executar em um arquivo srcsrv.ini. Qualquer tentativa de executar um comando que não está no arquivo srcsvr.ini dispara uma caixa de diálogo de confirmação. Para obter mais informações, confira Aviso de segurança: o depurador deve executar um comando não confiável.

  Nenhuma validação é executada em parâmetros de comando, portanto, tenha cuidado com comandos confiáveis. Por exemplo, se você listou cmd.exe em seu srcsrv.ini, um usuário mal-intencionado pode especificar parâmetros em cmd.exe que podem torná-lo perigoso.

  Selecione as preferências de suporte desejadas. Tenha em mente que as opções Permitir servidor de origem para assemblies de confiança parcial (somente gerenciados) e Sempre executar comandos de servidor de origem não confiáveis sem solicitar confirmação podem aumentar os riscos de segurança.

Opções de símbolo do compilador

Quando você compila um projeto na IDE do Visual Studio com a configuração padrão de compilação Depurar, o compilador C++ e o compilador gerenciado criam os arquivos de símbolo apropriados para o seu 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 criar 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:pdbonly se você quiser gerar arquivos .pdb para um build de versão que não deseja ser depurável. Para obter mais informações, consulte /depuração (opções do compilador C#) ou /depuração (Visual Basic).

Opções de C/C++

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

  Um arquivo .pdb para C/C++ é criado quando você cria 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 <projeto>.pdb.

  Se você criar 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 de .pdb:

  • VC<x>.pdb, em que <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 os arquivos objeto individuais e está no mesmo diretório que o makefile do projeto. Sempre que cria um arquivo de objeto, o compilador C/C++ mescla informações de depuração em VC<x>.pdb. Portanto, mesmo que cada arquivo de origem inclua arquivos de cabeçalho comuns, como <windows.h>, os typedefs desses cabeçalhos serão armazenados apenas uma vez, em vez de em cada arquivo 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.

  • <projeto.pdb>

    O arquivo .pdb <>armazena todas as informações de depuração para o arquivo de projeto .exe e reside no subdiretório \debug. O arquivo <project>.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 para os arquivos .pdb no 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. Informações simbólicas de tabelas de exportação de DLL podem ser úteis para trabalhar com mensagens do Windows, procedimentos do Windows (WindowProcs), objetos COM, marshaling ou qualquer DLL para a qual você não tenha símbolos. Os símbolos estão disponíveis para qualquer DLL do sistema de 32 bits. As chamadas são listadas na ordem de chamada, com a função atual (a mais profundamente aninhada) na parte superior.

  Lendo a dumpbin /exports saída, você pode ver os nomes de função exatos, incluindo caracteres não numé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, consulte dumpbin /exports.

Aplicativos Web

Defina o arquivo web.config do aplicativo ASP.NET para o modo de depuração. O modo de depuração faz com que ASP.NET gerem símbolos para arquivos gerados dinamicamente e permite que o depurador seja anexado ao aplicativo ASP.NET. O Visual Studio define isso automaticamente quando você começa a depurar, se você criou seu projeto a partir do modelo de 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ímbolos na janela Módulos.

Para monitorar ou modificar a localização ou as opções dos símbolos 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 pulados, não encontrados ou não carregados. Tenta carregar símbolos dos locais especificados no painel Ferramentas>Opções de Todas as Configurações>Depuração>Símbolos nas seções > ou Localizações de Pesquisa. Se o arquivo de símbolo não for encontrado ou não estiver carregado, inicie o Explorador de Arquivos 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 consegue localizar o arquivo.
   Configurações de símbolos	Abre o painel Ferramentas>OpçõesTodas as Configurações>Depuração>Símbolos>Locais de Pesquisa, onde você pode editar e adicionar locais de símbolos.
   Sempre carregar automaticamente	Adiciona o arquivo de símbolo selecionado à lista de arquivos que são carregados automaticamente pelo depurador.
   Descompilar o código-fonte em um arquivo de símbolos	Para o código .NET, você pode escolher essa opção e seguir as instruções em Gerar e inserir fontes para um assembly.

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

Há várias maneiras para o depurador interromper o código que não tenha arquivos de símbolos ou código-fonte 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 os caminhos novamente e carregar o arquivo de símbolo se ele for 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 for encontrado ou o Explorador de Arquivos será aberto para que você possa selecionar manualmente o arquivo de símbolo.

• Para abrir a página de configurações de símbolo para configurar o comportamento, selecione Alterar Configurações de Símbolo (ou abra o painel Ferramentas>Opções e vá para a seção Todas as Configurações>Depuração>Símbolos>Pesquisar e Carregar ou Localização de Pesquisas).

• (Avançado) Para mostrar a desmontagem em uma nova janela uma vez, selecione exibição de desmontagem ou selecione caixa de diálogo Opções para configurar a opção para que a desmontagem seja sempre mostrada quando os arquivos de origem ou símbolo não forem encontrados. Para obter mais informações, veja o 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 encontrar o arquivo .pdb depois de executar uma das opções e puder recuperar o arquivo de origem usando as informações no arquivo .pdb, ele exibirá a origem. 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 de 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 Explorador de Soluções e selecione o ícone Propriedades, pressione Alt+Enterou 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.

   Nota

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

4. Em Não procure 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

• Noções básicas sobre arquivos de símbolo e configurações de símbolo do Visual Studio