Usar pontos de interrupção no depurador do Visual Studio

Os pontos de interrupção são uma das técnicas de depuração mais importantes no repertório do desenvolvedor. Defina pontos de interrupção nos pontos em que quiser pausar a execução do depurador. Por exemplo, talvez você queira ver o estado das variáveis de código ou examinar a pilha de chamadas em um determinado ponto de interrupção. Se você estiver tentando resolver um aviso ou problema ao usar pontos de interrupção, confira Solucionar problemas de pontos de interrupção no depurador do Visual Studio.

Observação

Se você souber a tarefa ou o problema que está tentando resolver, mas precisar saber que tipo de ponto de interrupção usar, confira Perguntas frequentes – encontre o seu recurso de depuração.

Definir pontos de interrupção no código-fonte

Você pode definir um ponto de interrupção em qualquer linha de código executável. Por exemplo, no código C# a seguir, você pode definir um ponto de interrupção na linha de código com a atribuição de variável (int testInt = 1), o loop for ou qualquer código dentro do loop for. Não será possível definir um ponto de interrupção em assinaturas de método, declarações para um namespace ou classe ou declarações de variável se não houver nenhuma atribuição e nenhum getter/setter.

Para definir um ponto de interrupção no código-fonte:

• Clique na margem extrema esquerda ao lado de uma linha de código. Você também pode selecionar a linha e pressionar F9, selecionar Depurar>Alternar Ponto de Interrupção ou clicar com o botão direito do mouse e selecionar Ponto de Interrupção>Inserir ponto de interrupção. O ponto de interrupção aparece como um ponto vermelho na margem esquerda.

Para a maioria das linguagens, incluindo C#, o ponto de interrupção e as linhas de execução atuais são realçados automaticamente. Para código C++, você pode ativar o realce do ponto de interrupção e das linhas atuais selecionando Ferramentas (ou Depurar) >Opções>Depuração>Realçar toda a linha de origem para pontos de interrupção e instrução atual (somente C++).

Quando você depura, a execução é pausada no ponto de interrupção, antes que o código nessa linha seja executado. O símbolo de ponto de interrupção mostra uma seta amarela.

No ponto de interrupção no exemplo a seguir, o valor de testInt ainda é 3. Portanto, o valor não foi alterado desde que a variável foi inicializada (definida como um valor de 3) porque a instrução em amarelo ainda não foi executada.

Quando o depurador interrompe o ponto de interrupção, você pode examinar o estado atual do aplicativo, incluindo valores variáveis e a pilha de chamadas.

Aqui estão algumas instruções gerais para trabalhar com pontos de interrupção.

• O ponto de interrupção é uma alternância. Você pode clicar nele, pressionar F9 ou usar Depurar>Alternar Ponto de Interrupção para excluí-lo ou reinseri-lo.

• Para desabilitar um ponto de interrupção sem excluí-lo, passe o mouse sobre ele ou clique com o botão direito do mouse e selecione Desabilitar ponto de interrupção. Pontos de interrupção desabilitados aparecem como pontos vazios na margem esquerda ou na janela Pontos de Interrupção. Para reabilitar um ponto de interrupção, passe o mouse sobre ele ou clique com o botão direito do mouse e selecione Habilitar ponto de interrupção.

• Defina condições e ações, adicione e edite rótulos ou exporte um ponto de interrupção clicando nele com o botão direito do mouse e selecionando o comando apropriado ou passando o mouse sobre ele e selecionando o ícone Configurações.

Ações de ponto de interrupção e pontos de rastreamento

Um tracepoint é um ponto de interrupção que imprime uma mensagem na janela de Saída. Um ponto de rastreamento pode agir como uma instrução de rastreamento temporária na linguagem de programação e não pausa a execução do código. Você cria um ponto de rastreamento definindo uma ação especial na janela Configurações do Ponto de Interrupção. Para obter instruções detalhadas, confira Usar pontos de rastreamento no depurador do Visual Studio.

Condições de ponto de interrupção

Você pode controlar quando e onde um ponto de interrupção é executado definindo condições. A condição pode ser qualquer expressão válida que seja reconhecida pelo depurador. Para obter mais informações sobre expressões válidas, confira Expressões no depurador.

Para definir uma condição de ponto de interrupção:

1. Clique com o botão direito do mouse no símbolo do ponto de interrupção e selecione Condições (ou pressione Alt + F9, C). Ou passe o mouse sobre o símbolo do ponto de interrupção, selecione o ícone Configurações e, em seguida, selecione Condições na janela Configurações do Ponto de Interrupção.

   Você também pode clicar com o botão direito do mouse na margem esquerda ao lado de uma linha de código e selecionar Inserir Ponto de Interrupção Condicional no menu de contexto para definir um novo ponto de interrupção condicional.

   Você também pode definir condições na janela Pontos de Interrupção clicando com o botão direito do mouse em um ponto de interrupção e selecionando Configurações e selecionando Condições

   

2. Na lista suspensa, selecione Expressão Condicional, Contagem de Ocorrências ou Filtro e defina o valor adequadamente.

3. Selecione Fechar ou pressione Ctrl+Enter para fechar a janela Configurações de Ponto de Interrupção. Ou, na janela Pontos de Interrupção, selecione OK para fechar a caixa de diálogo.

Os pontos de interrupção com condições definidas aparecem com um símbolo + no código-fonte e nas janelas Pontos de Interrupção.

Criar uma expressão condicional

Ao selecionar Expressão Condicional, você pode escolher entre duas condições: É verdadeiro ou Quando alterado. Escolha É verdadeiro se quiser interromper quando a expressão for satisfeita ou escolha Quando alterado se quiser interromper quando o valor da expressão for alterado.

No seguinte exemplo, o ponto de interrupção é atingido somente quando o valor de testInt é 4:

No seguinte exemplo, o ponto de interrupção é atingido somente quando o valor de testInt é alterado:

Se você definir uma condição de ponto de interrupção com sintaxe inválida, uma mensagem de aviso aparecerá. Se você especificar uma condição de ponto de interrupção com sintaxe válida mas semântica inválida, uma mensagem de aviso aparecerá na primeira vez em que o ponto de interrupção for atingido. Em ambos os casos, o depurador é interrompido quando atinge o ponto de interrupção inválido. O ponto de interrupção é ignorado somente se a condição é válida e avaliada como false.

Observação

Para o campo Quando alterado, o depurador não considera a primeira avaliação da condição como uma alteração, portanto, não atinge o ponto de interrupção na primeira avaliação.

Usar IDs de objeto em expressões condicionais (somente C# e F#)

Há momentos em que você deseja observar o comportamento de um objeto específico. Por exemplo, talvez você queira descobrir por que um objeto foi inserido em uma coleção mais de uma vez. Em C# e F#, você pode criar IDs de objeto para instâncias específicas de tipos de referência e usá-las em condições de ponto de interrupção. A ID de objeto gerada pelos serviços de depuração do CLR (Common Language Runtime) e associado ao objeto.

Para criar uma ID de objeto:

1. Defina um ponto de interrupção no código em algum lugar depois que o objeto tiver sido criado.

2. Inicie a depuração e, quando a execução for pausada no ponto de interrupção, selecione Depurar>Janelas>Locais (ou pressione Ctrl + Alt + V, L) para abrir a janela Locais.

   Localize a instância de objeto específica na janela Locais, clique com o botão direito do mouse nela e selecione Criar ID do Objeto.

   Você deverá ver um $ mais um número na janela Locais. Essa é a ID do objeto.

3. Adicione um novo ponto de interrupção no ponto que você deseja investigar; por exemplo, quando o objeto deve ser adicionado à coleção. Clique com o botão direito do mouse no ponto de interrupção e selecione Condições.

4. Use a ID do Objeto no campo Expressão Condicional. Por exemplo, se a variável item for o objeto a ser adicionado à coleção, selecione É verdadeiro e digite item == $<n>, em que <n> é o número da ID do objeto.

   A execução será interrompida no ponto em que esse objeto deve ser adicionado à coleção.

   Para excluir a ID do Objeto, clique com o botão direito do mouse na variável na janela Locais e selecione Excluir ID do Objeto.

Observação

As IDs de objeto criam referências fracas e não impedem que o objeto seja coletado como lixo. Eles são válidos somente para a sessão de depuração atual.

Definir uma condição de contagem de ocorrências

Se você suspeitar que um loop em seu código começa a se comportar mal após um determinado número de iterações, você pode definir um ponto de interrupção para interromper a execução após esse número de ocorrências, em vez de ter que pressionar F5 repetidamente para alcançar essa iteração.

Em Condições, na janela Configurações do Ponto de Interrupção, selecione Contagem de Ocorrências e especifique o número de iterações. No seguinte exemplo, o ponto de interrupção é definido para ser atingido em todas as outras iterações:

Definir uma condição de filtro

Você pode restringir um ponto de interrupção para disparar somente em dispositivos especificados ou em processos e threads especificados.

Em Condições, na janela Configurações do Ponto de Interrupção, selecione Filtrar e insira uma ou mais das seguintes expressões:

• MachineName = "nome"
• ProcessId = valor
• ProcessName = "nome"
• ThreadId = valor
• ThreadName = "nome"

Coloque valores de cadeia de caracteres entre aspas duplas. Você pode combinar cláusulas usando & (AND), || (OR), ! (NOT) e parênteses.

Definir pontos de interrupção de função

Você pode interromper a execução quando uma função é chamada. Isso é útil, por exemplo, quando você sabe o nome da função, mas não a localização dela. Também será útil se você tiver funções com o mesmo nome e quiser interromper todas elas (como funções sobrecarregadas ou funções em projetos diferentes).

Para definir um ponto de interrupção de função:

1. Selecione Depurar>Novo Ponto de Interrupção>Ponto de Interrupção da Função ou pressione Ctrl + K, B.

   Você também pode selecionar Novo>Ponto de Interrupção de Função na janela Pontos de Interrupção.

2. Na caixa de diálogo Novo Ponto de Interrupção de Função, insira o nome da função na caixa Nome da Função.

   Para restringir a especificação da função:

   • Use o nome da função totalmente qualificada.

     Exemplo: Namespace1.ClassX.MethodA()

   • Adicione os tipos de parâmetro de uma função sobrecarregada.

     Exemplo: MethodA(int, string)

   • Use o símbolo '!' para especificar o módulo.

     Exemplo: App1.dll!MethodA

   • Use o operador de contexto em C++ nativo.

     {function, , [module]} [+<line offset from start of method>]

     Exemplo: {MethodA, , App1.dll}+2

3. Na lista suspensa Linguagem de programação, escolha a linguagem de programação da função.

4. Selecione OK.

Definir um ponto de interrupção de função usando um endereço de memória (somente C++ nativo)

Você pode usar o endereço de um objeto para definir um ponto de interrupção de função em um método chamado por uma instância específica de uma classe. Por exemplo, dado um objeto endereçável do tipo my_class, você pode definir um ponto de interrupção de função no método que a instância my_method chama.

1. Defina um ponto de interrupção em algum lugar depois que a instância da classe for instanciada.

2. Localize o endereço da instância (por exemplo, 0xcccccccc).

3. Selecione Depurar>Novo Ponto de Interrupção>Ponto de Interrupção da Função ou pressione Ctrl + K, B.

4. Adicione o conteúdo a seguir à caixa Nome da Função e selecione a linguagem C++.

   ((my_class *) 0xcccccccc)->my_method
   

Definir pontos de interrupção de dados (.NET Core 3.x ou .NET 5+)

Os pontos de interrupção de dados interrompem a execução quando a propriedade de um objeto específico é alterada.

Para definir um ponto de interrupção de dados:

1. Em um projeto .NET Core ou .NET 5+, inicie a depuração e aguarde até que um ponto de interrupção seja atingido.

2. Na janela Automáticos, Inspeção ou Locais, clique com o botão direito do mouse em uma propriedade e selecione Interromper quando o valor for alterado no menu de contexto.

   

Os pontos de interrupção de dados para .NET Core e .NET 5+ não funcionarão para:

• Propriedades que não podem ser expandidas na janela dica de ferramenta, Locais, Automáticos ou Inspeção
• Variáveis estáticas
• Classes com o atributo DebuggerTypeProxy
• Campos dentro de structs

Para obter o número máximo que você pode definir, confira Llimites de hardware do ponto de interrupção de dados.

Definir pontos de interrupção de dados (somente C++ nativo)

Os pontos de interrupção de dados interrompem a execução quando um valor armazenado em um endereço de memória especificado é alterado. Se o valor for lido mas não gravado, a execução não será interrompida.

Para definir um ponto de interrupção de dados:

1. Em um projeto C++, inicie a depuração e aguarde até que um ponto de interrupção seja atingido. No menu Depurar, escolha Novo Ponto de Interrupção>Ponto de Interrupção de Dados.

   Você também pode selecionar Novo>Ponto de Interrupção de Dados na janela Pontos de Interrupção ou clicar com o botão direito do mouse em um item na janela Autos, Inspeção ou Locais e selecionar Interromper quando o valor for alterado no menu de contexto.

2. Na caixa Endereço, digite um endereço de memória ou uma expressão que seja avaliada como um endereço de memória. Por exemplo, digite &avar para interromper quando o conteúdo da variável avar for alterado.

3. Na lista suspensa Contagem de Bytes, selecione o número de bytes que deseja que o depurador inspecione. Por exemplo, se você selecionar 4, o depurador examinará os quatro bytes que começam em &avar e interromperá se qualquer um desses bytes mudar de valor.

Pontos de interrupção não funcionam nestas condições:

• Um processo que não estiver sendo depurado grava na localização da memória.
• A localização de memória é compartilhada entre dois ou mais processos.
• Se o local da memória for atualizado no kernel. Por exemplo, se a memória for passada à função ReadFile do Windows de 32 bits, a memória será atualizada do modo kernel, então a atualização não causará interrupção do depurador.
• Em que a expressão de inspeção é maior que 4 bytes em hardware de 32 bits e 8 bytes em hardware de 64 bits. Essa é uma limitação da arquitetura x86.

Observação

• Os pontos de interrupção de dados dependem de endereços de memória específicos. O endereço de uma variável muda de uma sessão de depuração para a próxima, portanto, os pontos de interrupção de dados são desabilitados automaticamente no final de cada sessão de depuração.

• Se você definir um ponto de interrupção de dados em uma variável local, o ponto de interrupção permanecerá habilitado quando a função terminar, mas o endereço de memória não será mais aplicável, portanto, o comportamento do ponto de interrupção será imprevisível. Ao definir um ponto de interrupção de dados em um variável local, a prática recomendada é remover ou desabilitar o ponto de interrupção antes que a função termine.

Limites de hardware do ponto de interrupção de dados

O kernel do Windows e o hardware subjacente têm os seguintes limites ao definir pontos de interrupção de dados. O limite refere-se ao número máximo de pontos de interrupção de dados que você pode definir.

Arquitetura do processador	Limite do ponto de interrupção de dados
x64 e x86	4
ARM64	2
ARM	1

Definir um ponto de interrupção dependente

Os pontos de interrupção dependentes interromperão a execução somente se outro ponto de interrupção for atingido primeiro. Portanto, em um cenário complexo, como a depuração de um aplicativo multi-threaded, você pode configurar os pontos de interrupção adicionais depois que outro ponto de interrupção for atingido. Isso pode facilitar muito a depuração de código em caminhos comuns, como um loop de jogo ou uma API de utilitário, pois um ponto de interrupção nessas funções pode ser configurado para habilitar somente se a função for invocada de uma parte específica do seu aplicativo.

Para definir um ponto de interrupção dependente:

1. Passe o mouse sobre o símbolo do ponto de interrupção, escolha o ícone Configurações e selecione Habilitar somente quando o ponto de interrupção a seguir for atingido na janela Configurações do Ponto de Interrupção.

2. Na lista suspensa, selecione o ponto de interrupção de pré-requisito do qual você deseja que o ponto de interrupção atual seja dependente.

Escolha Fechar ou pressione Ctrl+Enter para fechar a janela Configurações do Ponto de Interrupção. Ou, na janela Pontos de Interrupção, escolha OK para fechar a caixa de diálogo.

Você também pode usar o menu de contexto acionado com o botão direito do mouse para definir um ponto de interrupção dependente.

1. Clique com o botão direito do mouse na margem à extrema esquerda ao lado de uma linha de código e selecione Inserir Ponto de Interrupção Dependente no menu de contexto.

   

• Os pontos de interrupção dependentes não funcionarão se houver apenas um ponto de interrupção em seu aplicativo.
• Os pontos de interrupção dependentes serão convertidos em um ponto de interrupção de linha normal se o ponto de interrupção de pré-requisito for excluído.

Definir um ponto de interrupção temporário

Esse ponto de interrupção permite que você interrompa o código apenas uma vez. Ao depurar, o depurador do Visual Studio pausa apenas o aplicativo em execução uma vez para esse ponto de interrupção e o remove imediatamente após ele ser atingido.

Para definir um ponto de interrupção temporário:

1. Passe o mouse sobre o símbolo do ponto de interrupção, escolha o ícone Configurações e, em seguida, selecione Remover ponto de interrupção uma vez atingido na janela Configurações do Ponto de Interrupção.

2. Escolha Fechar ou pressione Ctrl+Enter para fechar a janela Configurações do Ponto de Interrupção. Ou, na janela Pontos de Interrupção, escolha OK para fechar a caixa de diálogo.

   

Você também pode usar o menu de contexto acionado com o botão direito do mouse para adicionar um ponto de interrupção.

1. Clique com o botão direito do mouse na margem esquerda ao lado de uma linha de código e selecione Inserir Ponto de Interrupção Temporário no menu de contexto.

   

Ou simplesmente use o atalho F9 + Shift + Alt, T e defina o ponto de interrupção temporário na linha desejada.

Gerenciar pontos de interrupção na Janela de Pontos de Interrupção

Você pode usar a janela Pontos de Interrupção para ver e gerenciar todos os pontos de interrupção em sua solução. Esse local centralizado é especialmente útil em uma solução grande ou em cenários complexos de depuração em que os pontos de interrupção são críticos.

Na janela Pontos de Interrupção, você pode pesquisar, classificar, filtrar, habilitar/desabilitar ou excluir pontos de interrupção. Você também pode definir condições e ações ou adicionar uma nova função ou ponto de interrupção de dados.

Para abrir a janela Pontos de Interrupção, selecione Depurar>Janelas>Pontos de Interrupção ou pressione Ctrl+Alt+B.

Para selecionar as colunas a serem exibidas na janela Pontos de Interrupção, selecione Mostrar Colunas. Selecione um cabeçalho de coluna para classificar a lista de pontos de interrupção por essa coluna.

Rótulos de ponto de interrupção

Você pode usar rótulos para classificar e filtrar a lista de pontos de interrupção na janela Pontos de Interrupção.

1. Para adicionar um rótulo a um ponto de interrupção, clique com o botão direito do mouse no ponto de interrupção no código-fonte ou na janela Pontos de Interrupção e selecione Editar rótulos. Adicione um novo rótulo ou escolha um existente e selecione OK.
2. Classifique a lista de pontos de interrupção na janela Pontos de Interrupção selecionando os cabeçalhos Rótulos, Condições ou outros cabeçalhos de coluna. Você pode selecionar as colunas a serem exibidas selecionando Mostrar Colunas na barra de ferramentas.

Grupos de pontos de interrupção

Para cenários de depuração complexos, talvez você queira criar grupos de pontos de interrupção para organizar seus pontos de interrupção. Isso permite que você habilite e desabilite rapidamente os agrupamentos lógicos de pontos de interrupção com base no cenário atual que você está tentando depurar.

Você pode criar pontos de interrupção na janela Pontos de Interrupção selecionando Novo > Grupo de Pontos de Interrupção e fornecendo um nome para o grupo. Para adicionar um ponto de interrupção a um grupo existente, clique com o botão direito do mouse no ponto de interrupção e escolha Adicionar ao Grupo de Pontos de Interrupção><nome do grupo>. Ou arraste e solte seus pontos de interrupção no grupo desejado.

Para definir um grupo de pontos de interrupção padrão, clique com o botão direito do mouse em um grupo e selecione Definir como Grupo de Pontos de Interrupção padrão. Quando você define um grupo de pontos de interrupção padrão, os pontos de interrupção recém-criados são adicionados automaticamente ao grupo.

Importar e exportar pontos de interrupção

Para salvar ou compartilhar o estado e o local dos pontos de interrupção, você pode exportá-los ou importá-los.

A partir do Visual Studio 2022 versão 17.12 Versão Prévia 3, os grupos de pontos de interrupção também são incluídos nos pontos de interrupção exportados e importados.

• Para exportar um único ponto de interrupção para um arquivo XML, clique com o botão direito do mouse no ponto de interrupção no código-fonte ou na janela Pontos de Interrupção e selecione Exportar ou Exportar selecionado. Selecione um local de exportação e, em seguida, selecione Salvar. O local padrão é a pasta da solução.
• Para exportar vários pontos de interrupção, na janela Pontos de Interrupção, selecione as caixas ao lado dos pontos de interrupção ou insira critérios de pesquisa no campo Pesquisar. Selecione o ícone Exportar todos os pontos de interrupção correspondentes aos critérios de pesquisa atuais e salve o arquivo.
• Para exportar todos os pontos de interrupção, desmarque todas as caixas e deixe o campo Pesquisar em branco. Selecione o ícone Exportar todos os pontos de interrupção correspondentes aos critérios de pesquisa atuais e salve o arquivo.
• Para importar pontos de interrupção, na janela Pontos de Interrupção, selecione o ícone Importar pontos de interrupção de um arquivo, navegue até o local do arquivo XML e selecione Abrir.

Definir pontos de interrupção das janelas do depurador

Você também pode definir pontos de interrupção nas janelas Pilha de Chamadas e Desmontagem do depurador.

Definir um ponto de interrupção na janela Pilha de Chamadas

Para interromper a execução na instrução ou na linha que uma função de chamada retorna, defina um ponto de interrupção na janela Pilha de Chamadas.

Para definir um ponto de interrupção na janela Pilha de Chamadas:

1. Para abrir a janela Pilha de Chamadas, você precisa estar em pausa durante a depuração. Selecione Depurar>Janelas>Pilha de Chamadas ou pressione Ctrl+Alt+C.

2. Na janela Pilha de Chamadas, clique com o botão direito do mouse na função de chamada e selecione Ponto de Interrupção>Inserir Ponto de Interrupção ou pressione F9.

   Um símbolo de ponto de interrupção aparece ao lado do nome da chamada de função na margem esquerda da pilha de chamadas.

O ponto de interrupção da pilha de chamadas aparece na janela Pontos de Interrupção como um endereço, com um local de memória que corresponde à próxima instrução executável na função.

O depurador é interrompido na instrução.

Para obter mais informações sobre a pilha de chamadas, consulte como: Use a janela Pilha de Chamadas.

Para rastrear visualmente os pontos de interrupção durante a execução do código, confira Mapear métodos na pilha de chamadas durante a depuração.

Definir um ponto de interrupção na janela Desmontagem

1. Para abrir a janela Desmontagem, você precisa estar em pausa durante a depuração. Selecione Depurar>Janelas>Desmontagem ou pressione Ctrl+Alt+D.

2. Na janela Desmontagem, clique na margem esquerda da instrução na qual você deseja interromper. Você também pode selecioná-la e pressionar F9 ou clicar com o botão direito do mouse e selecionar Ponto de Interrupção>Inserir Ponto de Interrupção.

Conteúdo relacionado

• O que é depuração?
• Escreva melhor em código C# usando o Visual Studio
• Primeira olhada na depuração
• Solucionar problemas de pontos de interrupção no depurador do Visual Studio