Anexar a processos em execução com o depurador do Visual Studio

É possível anexar o depurador do Visual Studio a um processo em execução em um computador local ou remoto. Depois que o processo estiver em execução, selecione Depurar>Anexar ao Processo ou pressione Ctrl+Alt+p no Visual Studio e use a caixa de diálogo Anexar ao Processo para anexar o depurador ao processo.

É possível usar Anexar ao Processo para depurar aplicativos em execução em computadores locais ou remotos, depurar vários processos simultaneamente, depurar aplicativos que não foram criados no Visual Studio ou depurar qualquer aplicativo não iniciado no Visual Studio com o depurador anexado. Por exemplo, se você estiver executando um aplicativo sem o depurador e atingir uma exceção, é possível anexar o depurador ao processo que executa o aplicativo e iniciar a depuração.

Dica

Não tem certeza se deseja usar Anexar ao Processo para o cenário de depuração? Consulte Cenários comuns de depuração.

Anexar a um processo em execução em seu computador local

Para reanexar de forma rápida um processo ao qual você anexou anteriormente, consulte Anexar novamente a um processo.

Para anexar a um processo em seu computador local:

  1. No Visual Studio, selecione Depurar>Anexar ao Processo (ou pressione Ctrl+Alt+P) para abrir a caixa de diálogo Anexar ao Processo.

  2. Verifique o tipo de conexão.

    Na maioria dos casos, é possível usar oPadrão. Alguns cenários podem exigir um tipo de conexão diferente. Para obter mais informações, consulte outras seções neste artigo ou Cenários comuns de depuração.

  3. Defina o Destino da conexão com o nome do computador local.

    Screenshot of the Attach to Process dialog box, with the connection target set to the local machine name.

    Screenshot of the Attach to Process dialog box, with the connection target set to the local machine name.

  4. Na lista Processos disponíveis, localize e selecione o processo ou os processos que você deseja anexar.

    • Para selecionar rapidamente um processo, digite seu nome ou primeira letra na caixa Filtro processos.

    • Se você não souber o nome do processo, navegue pela lista ou veja Cenários comuns de depuração para obter alguns nomes de processo comuns.

    Dica

    Os processos podem iniciar e parar em segundo plano enquanto a caixa de diálogo Anexar ao Processo está aberta, portanto, a lista de processos em execução pode nem sempre estar atualizada. É possível selecionar Atualizar a qualquer momento para visualizar a lista atual.

  5. No campo Anexar a, verifique se o tipo de código que deseja depurar está listado. A configuração automática padrão funciona para a maioria dos tipos de aplicativo.

    Se você estiver usando o tipo de conexão Padrão, é possível selecionar manualmente o tipo de código ao qual deseja anexar. Caso contrário, a opção Selecionar pode estar desabilitada.

    Para selecionar tipos de código manualmente:

    1. Clique em Selecionar.
    2. Na caixa de diálogo Selecionar tipo de código, selecione Depurar estes tipos de código. Se houver uma falha ao tentar anexar a um processo na lista, é possível usar a caixa de diálogo Selecionar tipo de código para ajudar a solucionar o problema.
    3. Selecione os tipos de código que deseja depurar.
    4. Selecione OK.
  6. Selecionar Anexar.

Dica

No cenário em que há vários processos idênticos, use a coluna Linha de Comando ou os detalhes do processo w3wp da coluna Título para identificar o processo certo.

Observação

É possível ser anexado a vários aplicativos para depuração, mas somente um aplicativo está ativo no depurador em um determinado momento. É possível definir o aplicativo ativo na barra de ferramentas Local de Depuração do Visual Studio ou na janela Processos.

Anexar a um processo em um computador remoto

Também é possível selecionar um computador remoto na caixa de diálogo Anexar ao Processo, exibir uma lista de processos disponíveis que estão em execução no computador e anexá-la a um ou mais processos para depuração. O depurador remoto (msvsmon.exe) deve estar em execução no computador remoto. Para obter mais informações, confira Depuração remota.

Para obter instruções mais completas sobre como depurar aplicativos ASP.NET que foram implantados no IIS, consulte Depuração remota ASP.NET em um computador IIS remoto.

Para anexar a um processo em execução em um computador remoto:

  1. No Visual Studio, selecione Depurar>Anexar ao Processo (ou pressione Ctrl+Alt+P) para abrir a caixa de diálogo Anexar ao Processo.

  2. Verifique o tipo de conexão.

    Na maioria dos casos, é possível usar oPadrão. Alguns cenários, como a depuração do Linux ou um aplicativo em contêineres, exigem um tipo de conexão diferente. Para obter mais informações, consulte outras seções neste artigo ou Cenários comuns de depuração.

  3. Na caixa Destino da conexão, selecione o computador remoto usando um dos seguintes métodos:

    • Selecione a seta suspensa ao lado de destino de conexão e selecione o nome do computador na lista suspensa.

    • Insira o nome do computador na caixa Destino da conexão e pressione Enter.

      Verifique se o Visual Studio adiciona a porta necessária ao nome do computador, que aparece no formato: <nome do computador remoto>:porta

      Observação

      Se você não conseguir se conectar usando o nome do computador remoto, tente usar o IP e o endereço da porta (por exemplo, 123.45.678.9:4022). 4026 é a porta padrão para o depurador remoto do Visual Studio 2022. Para outras atribuições de porta do depurador remoto, consulte Atribuições de porta do depurador remoto.

      Observação

      Se você não conseguir se conectar usando o nome do computador remoto, tente usar o IP e o endereço da porta (por exemplo, 123.45.678.9:4022). 4024 é a porta padrão para o depurador remoto do Visual Studio 2019. Para outras atribuições de porta do depurador remoto, consulte Atribuições de porta do depurador remoto.

    • Selecione o botão Localizar ao lado da caixa Destino da conexão para abrir a caixa de diálogo Conexões Remotas. A caixa de diálogo Conexões Remotas lista todos os dispositivos que estão em sua sub-rede local ou conectados diretamente ao computador. Talvez seja necessário abrir a porta UDP 3702 no servidor para encontrar dispositivos remotos. Selecione o computador ou o dispositivo desejado e, depois, clique em Selecionar.

    Observação

    A configuração Tipo de conexão continua entre as sessões de depuração. A configuração Destino de conexãocontinua entre as sessões de depuração somente se uma conexão de depuração bem-sucedida ocorreu com o destino.

  4. Clique em Atualizar para preencher a lista Processos disponíveis.

    Dica

    Os processos podem iniciar e parar em segundo plano enquanto a caixa de diálogo Anexar ao Processo está aberta, portanto, a lista de processos em execução pode nem sempre estar atualizada. É possível selecionar Atualizar a qualquer momento para visualizar a lista atual.

  5. Na lista Processos disponíveis, localize e selecione o processo ou os processos que você deseja anexar.

  6. No campo Anexar a, verifique se o tipo de código que deseja depurar está listado. A configuração automática padrão funciona para a maioria dos tipos de aplicativo.

    Se você estiver usando o tipo de conexão Padrão, é possível selecionar manualmente o tipo de código ao qual deseja anexar. Caso contrário, a opção Selecionar pode estar desabilitada.

    Para selecionar tipos de código manualmente:

    1. Clique em Selecionar.
    2. Na caixa de diálogo Selecionar tipo de código, selecione Depurar estes tipos de código. Se houver uma falha ao tentar anexar a um processo na lista, é possível usar a caixa de diálogo Selecionar tipo de código para ajudar a solucionar o problema.
    3. Selecione OK.
  7. Selecionar Anexar.

Observação

É possível ser anexado a vários aplicativos para depuração, mas somente um aplicativo está ativo no depurador em um determinado momento. É possível definir o aplicativo ativo na barra de ferramentas Local de Depuração do Visual Studio ou na janela Processos.

Em alguns casos, quando você depura em uma sessão da Área de Trabalho Remota (Serviços de Terminal), a lista Processos Disponíveis não exibirá todos os processos disponíveis. Se você estiver executando o Visual Studio como um usuário que tem uma conta de usuário limitada, a lista Processos disponíveis não mostrará os processos em execução na Sessão 0. A sessão 0 é usada para serviços e outros processos de servidor, incluindo w3wp.exe. É possível solucionar o problema executando o Visual Studio em uma conta de administrador ou executando o Visual Studio de console do servidor em vez de uma sessão de Serviços de Terminal.

Se nenhuma dessas soluções alternativas é possível, uma terceira opção é anexar ao processo executando vsjitdebugger.exe -p <ProcessId> na linha de comando do Windows. É possível determinar a ID do processo usando tlist.exe. Para obter tlist.exe, baixe e instale as Ferramentas de Depuração para o Windows, disponíveis em downloads de WDK e WinDbg.

Anexar a um processo do .NET Core em execução no Serviço de Aplicativo do Azure (Windows)

Se estiver publicando no Serviço de Aplicativo do Azure (Windows), consulte ASP.NET Core de depuração remota no Azure ou Depuração dos Serviço de Aplicativo do Azure para obter instruções.

Anexar a um processo do .NET Core em execução no Serviço de Aplicativo do Azure (Windows)

Se estiver publicando no Serviço de Aplicativo do Azure (Windows), você encontrará a opção Anexar Depurador no menu ... em Hospedagem no perfil de publicação. O Visual Studio tenta anexar o depurador remoto à instância do Serviço de Aplicativo do Azure (Windows) na qual o perfil está publicando.

Screenshot of the Attach Debugger option from within the Publish summary page.

Anexar a um processo do .NET Core em execução no Linux usando SSH

Para obter mais informações, consulte Depuração remota do .NET Core em execução no Linux usando SSH.

Anexar a um processo em execução em um contêiner do Docker

A partir do Visual Studio 2019, você pode anexar o depurador do Visual Studio a um processo em execução em um contêiner do Docker. Para um contêiner do Docker do .NET Core do Linux, consulte Anexar a um processo em execução em um contêiner do Docker do Linux. Para um contêiner do Docker do Windows, consulte Anexar a um processo em execução em um contêiner do Docker do Windows.

Reanexar ao processo

Você pode reanexar rapidamente aos processos aos quais foi anexado anteriormente escolhendo Depurar>Reanexar ao Processo (Shift+Alt+P). Depois de escolher esse comando, o depurador tentará anexar imediatamente aos últimos processos anexados, primeiro tentando corresponder à ID do processo anterior e, se não ocorrer, correspondendo ao nome do processo anterior. Se nenhuma correspondência for encontrada ou se vários processos tiverem o mesmo nome, a caixa de diálogo Anexar ao Processo será aberta para que você possa selecionar o processo correto.

Observação

O comando Reanexar ao Processo está disponível a partir do Visual Studio 2017.

Cenários comuns de depuração

Para ajudar você a determinar se deve usar Anexar ao Processo e a qual processo anexar, a tabela a seguir mostra alguns cenários comuns de depuração, com links para mais instruções quando disponíveis. (A lista não é exaustiva.)

Para alguns tipos de aplicativo, como aplicativos UWP (Plataforma Universal do Windows), você não anexa diretamente a um nome de processo, mas usa a opção de menu Depurar Pacote do Aplicativo Instalado no Visual Studio (consulte tabela).

Para que o depurador se anexe ao código escrito em C++, o código precisa emitir DebuggableAttribute. Você pode adicionar isso ao seu código automaticamente vinculando à opção do vinculador /ASSEMBLYDEBUG.

Para depuração de script do lado do cliente, a depuração de script deve ser habilitada no navegador. Para depurar o script do lado do cliente no Chrome, escolha JavaScript ou TypeScript como o tipo de código e, dependendo do tipo de aplicativo, talvez seja necessário fechar todas as instâncias do Chrome e iniciar o navegador no modo de depuração (digite chrome.exe --remote-debugging-port=9222 de uma linha de comando).

Para depuração de script do lado do cliente, a depuração de script deve ser habilitada no navegador. Para depurar o script do lado do cliente no Chrome, escolha JavaScript (Chrome) ou JavaScript (Microsoft Edge – Chromium) como o tipo de código e, dependendo do tipo de aplicativo, talvez seja necessário fechar todas as instâncias do Chrome e iniciar o navegador no modo de depuração (digite chrome.exe --remote-debugging-port=9222 de uma linha de comando). Em versões anteriores do Visual Studio, o depurador de scripts para Chrome era o web kit.

Para selecionar rapidamente um processo em execução para anexar, no Visual Studio, digite Ctrl+Alt+P e digite a primeira letra do nome do processo.

Cenário Método Depurar Nome do processo Notas e links
ASP.NET Core – Depuração remota no servidor IIS Usar ferramentas remotas e Anexar ao Processo w3wp.exe ou dotnet.exe A partir do .NET Core 3, o processo dew3wp.exe é usado para o modelo de hospedagem no aplicativo padrão. Para implantação de aplicativo, consulte Publicar no IIS. Para obter informações mais detalhadas, consulte Depuração remota ASP.NET Core em um computador IIS remoto
ASP.NET Core - Depurar no computador local depois de iniciar o aplicativo sem o depurador Usar Anexar ao processo msedge.exe Pode ser útil para que seu aplicativo seja carregado mais rapidamente, como (por exemplo) ao criar perfil.
ASP.NET 4 ou 4.5 – Depuração remota em um servidor IIS Usar ferramentas remotas e Anexar ao Processo w3wp.exe Consulte Depuração remota do ASP.NET em um computador IIS remoto
Script do lado do cliente – Depurar em um servidor IIS local para tipos de aplicativo com suporte Usar Anexar ao processo chrome.exe ou msedge.exe A depuração de script deve ser habilitada. Para o Chrome, você também deve executar o Chrome no modo de depuração (digite chrome.exe --remote-debugging-port=9222 de uma linha de comando) e selecionar JavaScript ou TypeScript no campo Anexar ao.
Aplicativo C#, Visual Basic ou C++ - Depurar no computador local Usar a depuração padrão (F5) ou Anexar ao Processo <appname>.exe Na maioria dos cenários, use a depuração padrão e não Anexar ao Processo.
Aplicativo da área de trabalho do Windows – Depuração remota Ferramentas remotas N/D Consulte Depurar remotamente um aplicativo C# ou Visual Basic ou Depurar remotamente um aplicativo C++
Depuração do .NET Core no Linux Usar Anexar ao processo dotnet.exe ou um nome de processo exclusivo Para usar SSH, consulte Depuração remota do .NET Core em execução no Linux usando SSH. Para aplicativos em contêineres, consulte Anexar a um processo em execução em um contêiner do Docker.
Aplicativo em contêineres – Depurar Usar Anexar ao processo dotnet.exe ou um nome de processo exclusivo Consulte Anexar a um processo em execução em um contêiner do Docker
Python no Linux – Depuração remota Usar Anexar ao processo debugpy Consulte Anexar remotamente por meio das Ferramentas Python
Outros tipos de aplicativo com suporte – Depurar em um processo de servidor Se o servidor for remoto, use ferramentas remotas e Anexar ao Processo chrome.exe, msedge.exe ou outros processos Se necessário, use o Monitor de Recursos para ajudar a identificar o processo. Confira Depuração remota.
Plataforma Universal do Windows Universal do Windows (UWP), OneCore, HoloLens ou aplicativo IoT – Depuração remota Depurar pacote do aplicativo instalado N/D Consulte Depurar um pacote de aplicativo instalado em vez de usar Anexar ao Processo
Plataforma Universal do Windows (UWP), OneCore, HoloLens ou IoT – Depurar um aplicativo não iniciado no Visual Studio Depurar pacote do aplicativo instalado N/D Consulte Depurar um pacote de aplicativo instalado em vez de usar Anexar ao Processo

Usar recursos do depurador

Para usar os recursos completos do depurador do Visual Studio (como atingir pontos de interrupção) ao anexar a um processo, o aplicativo deve corresponder exatamente à origem e aos símbolos locais. Ou seja, o depurador deve conseguir carregar os arquivos de símbolo (.pdb). corretos. Por padrão, requer um build de depuração.

Para cenários de depuração remota, é preciso ter o código-fonte (ou uma cópia do código-fonte) já aberto no Visual Studio. Os binários de aplicativo compilados no computador remoto devem surgir do mesmo build que no computador local.

Em alguns cenários de depuração local, é possível depurar no Visual Studio sem acesso à origem se os arquivos de símbolo corretos estiverem presentes com o aplicativo. Por padrão, requer um build de depuração. Para obter mais informações, consulte Especificar arquivos de símbolo e de origem.

Solucionar erros de anexo

Em alguns cenários, o depurador pode precisar de ajuda para identificar corretamente o tipo de código a ser depurado. Se os valores de conexão forem definidos corretamente (é possível exibir o processo correto na lista Processos disponíveis), mas o depurador não conseguir anexar, tente selecionar o tipo de conexão mais apropriado na lista Tipo de conexão, o que pode ser necessário, por exemplo, se for feita a depuração de um aplicativo Linux ou Python. Se estiver usando o tipo de conexão Padrão, como alternativa, é possível selecionar o tipo específico de código ao qual se conectar, conforme descrito mais adiante nesta seção.

Quando o depurador se anexa a um processo em execução, o processo pode conter um ou mais tipos de código. Os tipos de código aos quais o depurador pode se anexar são exibidos e selecionados na caixa de diálogo Selecionar Tipo de Código.

Às vezes, o depurador pode ser anexado com êxito a um tipo de código, mas não a outro tipo de código. Normalmente, essa ação ocorre quando:

  • Você tenta anexar a um processo que esteja sendo executado em um computador remoto. O computador remoto pode ter componentes de depuração remota instalados para alguns tipos de código mas não para outros.
  • Você também pode tentar anexar a dois ou mais processos para depuração direta de banco de dados. A depuração de SQL dá suporte à anexação de apenas um único processo.

Se o depurador puder se conectar a alguns, mas não a todos os tipos de código, aparecerá uma mensagem identificando os tipos que não conseguiram estabelecer conexão.

Se o depurador for anexado com êxito a pelo menos um tipo de código, você poderá depurar o processo. Você poderá depurar apenas os tipos de código que foram anexados com êxito. O código não anexado no processo ainda seria executado, mas não será possível definir pontos de interrupção, exibir dados ou executar outras operações de depuração no código.

Se quiser informações mais específicas sobre o motivo do depurador não ser anexado a um tipo de código, tente reanexar somente àquele tipo de código.

Para obter informações específicas sobre o motivo de um tipo de código ter falhado na anexação:

  1. Desanexe do processo. No menu Depurar, selecione Desanexar Tudo.

  2. Reanexe ao processo, selecionando apenas o tipo de código que não foi anexado.

    1. Na caixa de diálogo Anexar ao Processo, selecione o processo na lista Processos Disponíveis.

    2. Selecione Selecionar.

    3. Na caixa de diálogo Tipo de Código Selecionado, selecione Depurar esses tipos de código e o tipo de código que falhou em ser anexado. Desmarque os outros tipos de código.

    4. Selecione OK.

    5. Na caixa de diálogo Anexar ao Processo, clique em Anexar.

    Desta vez, o anexo falhará completamente e você receberá uma mensagem de erro específica.