Especifique o símbolo (.pdb) e os arquivos de origem no depurador do Visual Studio (C#, C++, Visual Basic, F#)

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

Quando o utilizador cria um projeto a partir do Visual Studio IDE 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ímbolos
• Carregar 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 Compreender os arquivos de símbolos e as configurações de símbolos do Visual Studio.

Como funcionam os ficheiros de símbolos

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 informações importantes durante a depuração:

• O nome do arquivo de origem e o número da linha a serem exibidos no IDE do Visual Studio
• Onde na aplicação parar para um ponto de paragem

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 arquivos .pdb que correspondam exatamente aos arquivos .pdb criados durante a construção de uma aplicação (ou seja, os arquivos .pdb originais ou cópias). Essa duplicação exata é necessária porque o layout dos aplicativos pode mudar mesmo que o código em si não seja alterado. Para obter mais informações, consulte Por que o Visual Studio exige que os arquivos de símbolo do depurador correspondam exatamente aos arquivos binários com os quais foram criados?

Dica

Para depurar o código fora do código-fonte do projeto, como o código do Windows ou o código de terceiros chamado pelo projeto, você deve especificar o local dos arquivos .pdb do código externo (e, opcionalmente, dos arquivos de origem), que devem corresponder exatamente às compilações em seu aplicativo.

Onde o depurador procura símbolos

Quando se depura um projeto no IDE do Visual Studio, o depurador carrega automaticamente os arquivos de símbolos predefinidos.

Observação

Ao depurar código gerenciado em um dispositivo remoto, todos os arquivos de símbolo devem estar localizados na máquina 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 no seu computador, o vinculador coloca o caminho completo e o nome 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 o arquivo DLL ou .exe .

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

   • Qualquer pasta de cache de símbolos locais.

   • Servidores e locais de rede, Internet ou símbolos locais especificados, como os Servidores de Símbolos da Microsoft, se selecionados. Visual Studio pode transferir ficheiros de símbolos de depuração de servidores de símbolos que implementam o protocolo symsrv. Visual Studio Team Foundation Server e as Ferramentas de Depuração para Windows são duas ferramentas que podem usar servidores de símbolos.

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

     Servidores públicos de símbolos 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 de 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 sua máquina 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 sua própria máquina.

     Servidores de símbolos de terceiros: Provedores terceirizados de aplicativos e bibliotecas do Windows podem fornecer acesso ao servidor de símbolos na Internet.

Advertência

Se você usar um servidor de símbolos diferente dos servidores de símbolos públicos da Microsoft, 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 à segurança.

Configurar a localização de arquivos de símbolos e 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) >Opções, pode aceder às opções de Depuração> Símbolos:

• 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ê deseja ou não que o depurador carregue símbolos automaticamente.
• Altere essas configurações enquanto depura ativamente. Consulte Carregar símbolos durante a depuração.

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

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

2. No painel direito, marque a caixa de seleção para cada servidor desejado: Microsoft Symbol Servers, NuGet.org Symbol Server e assim por diante.

3. Adicione um novo local do servidor de símbolos selecionando + Adicionar na barra de ferramentas do grupo Locais de ficheiros de símbolos (.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 da declaração ajuda-o a encontrar o formato correto.

   

   Observação

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

   Marque a caixa de seleção Habilitado e, em seguida, selecione Salvar.

4. Adicione a localização 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 selecione Conectar.

   

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

   • Para alterar a ordem de carregamento dos locais dos símbolos, use Ctrl + para cima e Ctrl + para baixo ou selecione Mover para cima e Mover para baixo.
   • Para editar um 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 a opção Símbolos de cache neste diretório , insira um caminho de pasta local para o qual os servidores de símbolos possam copiar símbolos.

   Observação

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

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

6. Especifique os módulos que o depurador deverá carregar a partir dos locais dos arquivos de símbolos (.pdb) ao iniciar.

   1. Mude para a seção Todas as Configurações>Depuração>Geral>Símbolos>Pesquisar e Carregar.

   2. Use a lista suspensa para definir o valor da opção de pesquisa automática de símbolos :

      • Escolha automaticamente quais símbolos de módulo pesquisar (recomendado): Permita que o Visual Studio decida quais símbolos procurar e carregar. Por padrão, o Visual Studio carrega automaticamente os símbolos criados pela solução aberta e carrega quaisquer outros símbolos necessários para executar operações de depuração comuns. 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 o carregamento de outros símbolos criando a lista de módulos incluídos.

        

      • Procure todos os símbolos de módulo, a menos que estejam excluídos: Força o Visual Studio a carregar todos os símbolos no seu processo depurado. Essa opção não é recomendada porque pode retardar 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 Procurar por todos ... permitem controlar quais símbolos são pesquisados durante a depuração.

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

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

2. Na caixa de diálogo Adicionar Item , digite o Nome do Módulo, marque a caixa de seleção Habilitado e selecione Salvar.

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

Os filtros de módulo suportam correspondência curinga simples. O asterisco * corresponde a qualquer grupo de caracteres. Por exemplo, *myproduct* corresponde a ficheiros 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 arquivos .dll ou .exe correspondentes. Essa abordagem pode ser útil, como ao tentar depurar um aplicativo Web implantado.

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

Para a opção Pesquisar todos os símbolos de módulos, a menos que sejam 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 , digite o Nome do Módulo, marque a caixa de seleção Habilitado e selecione Salvar.

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

Outras opções de símbolos 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 obter detalhes, consulte 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 compilação C/C++.

• Habilitar a depuração no nível de endereço e Mostrar desmontagem se a fonte 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 na máquina local ou o arquivo .pdb não corresponde 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 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 a partir 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 incorporados no arquivo .pdb de um aplicativo, portanto, certifique-se de colocar apenas os comandos que você deseja executar em um arquivo srcsrv.ini . Qualquer tentativa de executar um comando que não esteja no arquivo srcsvr.ini dispara uma caixa de diálogo de confirmação. Para obter mais informações, consulte Aviso de segurança: Depurador deve executar 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. Lembre-se de que as opções Permitir servidor de origem para assemblies de confiança parcial (somente gerenciado) e Sempre executar comandos de servidor de origem não confiáveis sem avisar podem aumentar os riscos de segurança.

Opções de símbolos do compilador

Quando cria um projecto na IDE do Visual Studio com a configuração de compilação de depuração padrão, os compiladores C++ e de código gerido criam os arquivos de símbolo apropriados para o seu código. Você também pode definir opções do compilador no código.

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

Opções do .NET

Construa com /debug para gerar um ficheiro .pdb. Você pode criar aplicativos com /debug:full ou /debug:pdbonly. Construir com /debug:full gera código depurável. Construir com /debug:pdbonly gera ficheiros .pdb, mas não gera o DebuggableAttribute que indica ao compilador JIT que as informações de depuração estão disponíveis. Use /debug:pdbonly se pretender gerar ficheiros .pdb para uma compilação de lançamento que não seja passível de depuração. Para obter mais informações, consulte /debug (opções do compilador C#) ou /debug (Visual Basic).

Opções C/C++

• <Ficheiros 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 <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 Microsoft C++, por exemplo VC11.pdb

    O arquivo VC<x.pdb> armazena todas as informações de depuração para os arquivos de objeto individuais e reside no mesmo diretório que o makefile do projeto. Cada vez que cria um ficheiro objeto, o compilador C/C++ funde informações de depuração no VC<x.pdb>. Portanto, mesmo que cada arquivo de origem inclua arquivos de cabeçalho comuns, como <windows.h>, os typedefs desses cabeçalhos são armazenados apenas uma vez, em vez de 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.

  • <projeto.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 <ficheiro project.pdb> contém informações de depuração completas, incluindo protótipos de funções, não apenas as informações de tipo encontradas no VC<x.pdb>.

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

• tabelas de exportação 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 de 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.

  Ao ler a dumpbin /exports saída, você pode ver os nomes exatos das funções, incluindo caracteres não alfanuméricos. Ver nomes exatos de funções é útil para definir um ponto de interrupção numa função, já que os nomes das funções podem ser truncados em outros lugares no depurador. Para obter mais informações, consulte dumpbin /exports.

Aplicações Web

Definir o arquivo web.config da sua aplicação ASP.NET para o modo de depuração. O modo de depuração faz com que 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ê começa a depurar, se você criou seu projeto a partir do modelo de projetos da Web.

Carregar símbolos durante a depuração

Você pode usar os Módulos, Pilha de chamadas, Locais, Automáticos ou qualquer janela Watch para carregar símbolos ou alterar opções de símbolos durante a depuração. Para obter mais informações, consulte Familiarize-se com a forma como o depurador se conecta 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 de usuário, ou Meu código, e seu status de carregamento de símbolo. Você também pode monitorar o status de carregamento de símbolos, carregar símbolos e alterar opções de símbolos na janela Módulos .

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

1. Para abrir a janela Módulos, durante a depuração, selecione Depurar>Módulos do> (ou pressione Ctrl + Alt + U).

2. Na janela Módulos , clique com o botão direito do mouse nos cabeçalhos Status do 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 no painel Ferramentas>Opções nas seções Todas as Configurações>,Depuração>,Símbolos>,Pesquisar e Carregar ou Pesquisar Locais. 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 conseguir encontrar o arquivo.
   Configurações do símbolo	Abre o painel Ferramentas>Opções na secção Todas as Configurações>Debugging>Símbolos>Locais de Pesquisa, onde pode-se editar e adicionar locais de símbolos.
   Sempre carregue automaticamente	Adiciona o arquivo de símbolo selecionado à lista de arquivos que são carregados automaticamente pelo depurador.
   Descompilar o código-fonte para o arquivo de símbolo	Para código .NET, você pode escolher essa opção e seguir as instruções em Gerar e incorporar fontes para um assembly.

Use as páginas Sem símbolos carregados/Sem fonte carregada

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

• Mergulhe no código.
• Interrompa a execução do código a partir de um ponto de interrupção ou exceção.
• Mude para um thread diferente.
• Altere o quadro da pilha clicando duas vezes em um quadro na janela Pilha de chamadas .

Quando isso acontece, o depurador exibe as páginas Sem símbolos carregados ou Sem fonte carregada para ajudá-lo a encontrar e carregar os símbolos ou a fonte necessários.

Para usar a página do documento Sem Símbolos Carregados 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 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 quaisquer opções de símbolo e repetir os caminhos de pesquisa, selecione Procurar e encontrar <nome do executável>. O arquivo de símbolo é carregado se for encontrado, ou o Explorador de Arquivos é aberto para que você possa selecionar manualmente o arquivo de símbolo.

• Para abrir a página de configurações de símbolos para configurar o comportamento, selecione Alterar configurações de símbolo (ou abra o painelOpções de> e vá para a seção Todas as configurações>,depuração> desímbolos>,pesquisa e carregamento ou locais de pesquisa).

• (Avançado) Para mostrar a desmontagem em uma nova janela uma vez, selecione exibir desmontagem ou selecione a caixa de diálogo Opções para definir a opção de sempre mostrar a desmontagem quando os arquivos de origem ou de símbolo não forem encontrados. Para obter mais informações, consulte Exibir código de desmontagem.

• Para mostrar os locais pesquisados​​ e os resultados, expanda Informações de carregamento de símbolos.

• Para o código C#, você também pode optar por descompilar o código-fonte das páginas No Symbols Loaded ou No Source Loaded .

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 fonte. Caso contrário, ele exibirá uma página Sem fonte 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 que o depurador procura por arquivos de origem e excluir arquivos específicos da pesquisa.

1. Selecione a solução no Gerenciador de Soluções e, em seguida, 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 mais locais, os ícones de seta para cima e para baixo 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

• Compreender os arquivos de símbolos e as configurações de símbolos do Visual Studio