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 o seguinte:

• Noções básicas sobre arquivos de símbolo e 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 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 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 tiver sido 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:

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. 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 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 a depuração ativa. Confira Carregar os símbolos durante a depuração.

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

Nota

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

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 de + 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 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.

   • 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 caminho, clique duas vezes na entrada ou selecione-a e pressione F2.

   • Para remover uma entrada, selecione-a e 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 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.

Nota

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 Escolher automaticamente os símbolos de módulo a serem procurados (recomendado) para permitir que o Visual Studio decida quais símbolos devem ser procurados e carregados. Por padrão, o Visual Studio carrega automaticamente símbolos criados pela solução aberta e carrega todos os símbolos adicionais necessários para executar operações comuns de depuração. 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 forçar símbolos adicionais a serem carregados clicando no link Especificar filtros de módulo.

   • Selecione Procurar todos os símbolos de módulo, exceto os excluídos para forçar o Visual Studio a carregar todos os símbolos no processo que você está depurando. Isso não é recomendado porque pode tornar sua experiência de depuração mais lenta. 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 os símbolos de módulo a serem procurados e Procurar todos os símbolos de módulo, exceto os excluídos permitem que você tenha um controle mais preciso sobre quais símbolos são pesquisados durante a depuração. Escolha Especificar os filtros do módulo para personalizar sua experiência.

Por padrão, você verá o seguinte diálogo quando Escolher automaticamente os símbolos de módulo a serem procurados estiver selecionado:

Você pode adicionar um módulo ao filtro usando o ícone '+'. Os filtros de módulo oferecem suporte à correspondência simples de coringa. Um '*' corresponde a qualquer grupo de caracteres. Por exemplo, '*myproduct*' corresponderá a arquivos como 'myproduct.utilities.dll' e 'entrypoint.myproduct.exe', entre outros.

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

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

• Carregar automaticamente os símbolos adicionais quando necessário instrui o Visual Studio a procurar os símbolos para executar ações comuns de depuração, como o passo a passo, mesmo que o módulo ao qual você estará realizando o passo a passo não esteja no projeto ou no filtro de módulo. A maneira como a pesquisa é determinada pode ser afetada pelas configurações do Just My Code.

Se você tiver selecionado Procurar todos os símbolos de módulo, exceto os excluídos, a caixa de diálogo de filtro de módulo terá esta aparência:

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

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

Você pode selecionar opções de símbolo adicionais no Tools>Options>Debugging>General (ou Debug>Options>General):

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

  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++.

• Habilitar depuração em nível de endereço e Mostrar desmontagem do código 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.

  Opções /

• Habilitar suporte ao servidor de origem

  Usa o Servidor de Origem para ajudar a depurar um aplicativo quando não há nenhum 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, bem como 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 fará com que uma caixa de diálogo de confirmação apareça. 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 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 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: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, 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.

  • <project>.pdb

    O arquivo .pdb do projeto<>armazena todas as informações de depuração para o arquivo de projeto .exe 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 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 saída dumpbin /exports, você pode ver os nomes exatos de 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, 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 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, iniciará 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 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 que são carregados automaticamente pelo depurador.

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

Existem várias maneiras para o depurador acessar 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 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 ou, se for encontrado, 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 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, 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