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

Ficheiros de base de dados do programa (.pdb), também chamados de ficheiros de símbolos, mapeiam identificadores e instruções no código-fonte do seu projeto para os identificadores e instruções correspondentes em 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ímbolo
• Carregar símbolos durante a depuração
• Opções do compilador para símbolos.

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

• 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 de .pdb contém informações de depuração e estado do projeto que permitem a ligação incremental de uma configuração de depuração do seu aplicativo. O depurador do Visual Studio usa arquivos de .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 definir um ponto de interrupção.

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 tenha sido alterado. Para obter mais informações, consulte Por que o Visual Studio exige arquivos de símbolo do 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 o código do Windows ou o código de terceiros chamado pelo projeto, você deve especificar o local dos arquivos de .pdb .pdb do código externo (e, opcionalmente, os 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:

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 computador, o vinculador colocará o caminho completo e o nome do arquivo de .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 ativar locais de símbolos, veja 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 o Debugging Tools for 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, muitas vezes você precisa de arquivos de .pdb do sistema. Os arquivos de .pdb do System 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. Consulte Onde o depurador procura símbolos.

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

• 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 está a depurar ativamente. Consulte Carregar símbolos ao depurar.

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

Observação

Essas opções foram atualizadas no Visual Studio 2022 Versão 17.12 Preview 1.

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

2. Nos locais do ficheiro de símbolos (.pdb) ,

   • Para utilizar os Microsoft Symbol Servers ou o NuGet.org Symbol Server, selecione a caixa de verificação.

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

     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ímbolos ou do local do símbolo no campo de texto. O preenchimento da declaração ajuda-o a encontrar o formato correto.

   Ferramentas

   Observação

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

   • Para adicionar uma nova localização do Servidor de Símbolos do Azure DevOps:

     1. Selecione o novo ícone do servidor na barra de ferramentas.

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

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

   • Para alterar a ordem de carregamento dos locais dos símbolos, use Ctrl+para cima e Ctrl+para baixo, ou os ícones de seta para cima e para baixo.

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

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

3. (Opcional) Para melhorar o desempenho de carregamento de símbolos, em Símbolos de cache neste diretório, digite 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.

Observação

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 dos locais do arquivo de Symbol (.pdb) quando ele for iniciado.

   • Selecione Escolher automaticamente os símbolos de módulo a procurar (recomendado) para permitir que o Visual Studio decida quais símbolos procurar e carregar. Por padrão, o Visual Studio carrega automaticamente símbolos que foram criados pela solução aberta e carrega quaisquer símbolos adicionais necessários para executar operações de depuração comuns. Isso reduz o número de arquivos que devem ser pesquisados e carregados pelo Visual Studio, o que melhora o desempenho do depurador. Você pode obrigar o carregamento de símbolos adicionais clicando no link Especificar filtros de módulo.

   • Selecione Pesquisar todos os símbolos de módulo, exceto se excluído para forçar o Visual Studio a carregar todos os símbolos no seu processo de depuração. Isso não é recomendado porque pode retardar sua experiência de depuração. Se você selecionar essa opção, poderá forçar o Visual Studio a ignorar determinados símbolos clicando no link Especificar filtros de módulo.

5. Selecione OK.

Especificar filtros de módulo

As opções Escolher automaticamente quais símbolos de módulo procurar e Pesquisar todos os símbolos de módulo, salvo exclusão, permitem-lhe ter um controlo mais preciso sobre quais símbolos são pesquisados durante a depuração. Escolha Especificar os filtros do módulo para personalizar a sua experiência.

Por predefinição, é apresentada a seguinte janela de diálogo quando Escolher automaticamente os símbolos de módulo a procurar está selecionado:

Pode adicionar um módulo ao filtro utilizando o ícone '+'. Os filtros de módulo suportam correspondência curinga simples. Um '*' corresponde a qualquer grupo de caracteres. Por exemplo, '*myproduct*' irá corresponder a ficheiros como 'myproduct.utilities.dll' e 'entrypoint.myproduct.exe', entre outros.

Existem várias opções adicionais para personalizar ainda mais a sua experiência:

• Carregue sempre os símbolos localizados ao lado dos módulos instrui o Visual Studio a carregar os ficheiros pdb que estão armazenados no sistema de ficheiros ao lado dos seus ficheiros .dll ou .exe correspondentes. Isso pode ser útil, por exemplo, ao tentar depurar um aplicativo Web implantado.

• Carregar automaticamente símbolos adicionais quando necessário instrui o Visual Studio a procurar símbolos para executar ações comuns de depuração, como o passo a passo, mesmo que o módulo a que estará a aceder não esteja no seu projeto ou no filtro de módulos. A forma como a pesquisa é determinada pode ser afetada pelas suas apenas o meu código definições.

Se tiver selecionado Pesquisar todos os símbolos de módulo, exceto os excluídos, então a caixa de diálogo do filtro de módulo irá apresentar-se assim:

Nesta caixa de diálogo, você pode escolher para quais módulos você não deseja o Visual Studio carregue símbolos. Nesse cenário, o Visual Studio tenta carregar símbolos para cada módulo em seus processos depurados (incluindo módulos de terceiros), a menos que você adicione um filtro correspondente para excluí-los. A única outra maneira de modificar este comportamento é através das suas configurações de Just My Code.

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

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

• Carregar exportações 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++.

• Ativar a depuração ao nível de endereço e Mostrar desassemblagem 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.

  

• Ativar 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 quando o arquivo de .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, bem como 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 de .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 de .pdb de um aplicativo, portanto, certifique-se de colocar apenas os comandos que deseja executar em um 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 apareça. Para obter mais informações, consulte Aviso de Segurança: O 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 o tornariam perigoso.

  Selecione este item e os itens filho desejados. Permitir que o servidor de origem execute assemblies com confiança parcial (somente gerenciados) e Executar sempre comandos do servidor de origem não confiáveis sem aviso prévio pode aumentar os riscos de segurança.

  

Opções de símbolos do compilador

Quando cria um projeto na IDE do Visual Studio com a configuração de compilação padrão Debug, os compiladores C++ e geridos 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 liberação.

Opções do .NET

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

Opções C/C++

• VC<x>.pdb e arquivos de projeto <>.pdb

  Um ficheiro .pdb para C/C++ é criado quando compilas com /ZI ou /Zi. No Visual C++, a opção /Fd nomeia o arquivo de .pdb que o compilador cria. Quando cria um projeto no Visual Studio usando o IDE, a opção /Fd é definida para criar um arquivo .pdb chamado <projeto>.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 de .pdb:

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

    O ficheiro VC<x>.pdb armazena todas as informações de depuração para os ficheiros objeto individuais e encontra-se no mesmo diretório que o makefile do projeto. Cada vez 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 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>.pdb do projeto<armazena todas as informações de depuração para o arquivo .exe do projeto e reside no subdiretório \debug. O projeto <>arquivo de .pdb contém informações completas de depuração, incluindo protótipos de função, não apenas as informações de tipo encontradas em VC<x>.pdb.

  Tanto o VC<x>.pdb quanto os arquivos de projeto<>.pdb permitem atualizações incrementais. O vinculador também incorpora o caminho para os ficheiros .pdb nos ficheiros .exe ou .dll que 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 saída dumpbin /exports, 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

Defina o arquivo web.config do seu aplicativo 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, a Pilha de Chamadas , os Locais , os Automáticos , ou qualquer janela de Observação 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á a tratar como código de utilizador, ou Meu Código, e o seu estado de carregamento de símbolos. 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 Windows> (ou pressione Ctrl + Alt + U).
2. Na janela Módulos, clique com o botão direito do rato nos cabeçalhos Estado do Símbolo ou Ficheiro 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 a partir 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, iniciará do 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 conseguir encontrar o arquivo.
Configurações de símbolos	Abre a página Opções >Depuração>Símbolos, onde pode editar e adicionar localizações dos símbolos.
Carregar Sempre Automaticamente	Adiciona o arquivo de símbolo selecionado à lista de arquivos que são carregados automaticamente pelo depurador.

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

Há várias maneiras de o depurador quebrar em código que não tem símbolos ou arquivos 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 ao clicar duas vezes em um quadro na janela da pilha de chamadas.

Quando isso acontece, o depurador exibe as páginas No Symbols Loaded ou No Source Loaded para ajudar a encontrar e carregar os símbolos ou o código 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 ignorar quaisquer opções de símbolo e tentar novamente os caminhos de pesquisa, selecione Navegar e localize <nome executável>. O ficheiro de símbolos é carregado se for encontrado, ou Explorador de Ficheiros abre para que possas selecionar manualmente o ficheiro de símbolos.
• Para abrir a página de configurações de símbolos para configurar o comportamento, selecione Alterar configurações de símbolos (ou escolha Opções >Depuração>símbolos).
• (Avançado) Para mostrar a desmontagem uma vez em uma nova janela, selecione mostrar a 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 o resultado, expanda Informações de carregamento do símbolo.
• 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 de .pdb depois de executar uma das opções e puder recuperar o arquivo de origem usando as informações no arquivo de .pdb, ele exibirá a fonte. Caso contrário, ele exibirá uma página No Source Loaded 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+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 efetuar a pesquisa. 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 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

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