Depurar remotamente ASP.NET Core num computador IIS remoto no Visual Studio

Para depurar uma aplicação ASP.NET Core que foi implementada no IIS, instale e execute as ferramentas remotas no computador onde implementou a sua aplicação, e depois conecte-a à sua aplicação em execução a partir do Visual Studio.

Componentes do depurador remotoRemote_debugger_components

Este guia explica como configurar e configurar um Visual Studio ASP.NET Core, implementá-lo no IIS e ligar o depurador remoto a partir do Visual Studio. Para depurar remotamente o ASP.NET 4.8, veja Remote Debug ASP.NET num computador IIS. Também podes implementar e depurar no IIS usando o Azure. Para Azure App Service, veja Depuração remota de ASP.NET Core no Azure ou, para Visual Studio Enterprise, use o Snapshot Debugger (é necessário o .NET 4.6.1).

Pré-requisitos

Visual Studio 2019 ou uma versão posterior é necessário para seguir os passos apresentados neste artigo.

Estes procedimentos foram testados nestas configurações de servidor:

• Windows Server 2022 e IIS 10
• Windows Server 2019 e IIS 10
• Windows Server 2016 e IIS 10

Requisitos de rede

Não há suporte para depuração entre dois computadores conectados por meio de um proxy. A depuração através de uma ligação de alta latência ou baixa largura de banda, como a Internet de acesso telefónico, ou através da Internet entre países/regiões não é recomendada e pode falhar ou ser inaceitavelmente lenta. Para obter uma lista completa de requisitos, consulte Requisitos.

O aplicativo já está em execução no IIS?

Este artigo inclui passos para configurar uma configuração básica do IIS no Windows Server e implementar a aplicação a partir do Visual Studio. Essas etapas estão incluídas para garantir que o servidor tenha os componentes necessários instalados, que o aplicativo possa ser executado corretamente e que você esteja pronto para a depuração remota.

• Se o seu aplicativo estiver sendo executado no IIS e você quiser apenas baixar o depurador remoto e iniciar a depuração, vá para Baixar e instalar as ferramentas remotas no Windows Server.

• Se você quiser ajuda para garantir que seu aplicativo esteja configurado, implantado e funcionando corretamente no IIS para que você possa depurar, siga todas as etapas neste artigo.

Crie a aplicação ASP.NET Core no computador Visual Studio

1. Crie uma nova aplicação web ASP.NET Core.

   No Visual Studio, escolhe File>Iniciar janela para abrir a janela Iniciar e depois escolhe Criar um novo project. Na caixa de pesquisa, escreva web app, depois escolha C# como linguagem, depois escolha ASP.NET Core Web Application (Model-View-Controller), e depois escolha Next. No ecrã seguinte, nomeie o project MyASPApp e depois escolha Next.

   Escolha o framework alvo recomendado ou .NET 10, e depois escolha Create. A versão deve corresponder à versão instalada no servidor.

2. Abra o arquivo HomeController.cs na pasta Controllers e defina um ponto de interrupção na instrução no método .

   Em modelos mais antigos, abra o arquivo Privacy.cshtml.cs e defina um ponto de interrupção no método .

Instalar e configurar o IIS no Windows Server

Estas etapas mostram apenas uma configuração básica do IIS. Para informações mais detalhadas ou para instalar num computador de ambiente de trabalho com Windows, consulte Publishing to IIS ou IIS 8.0 Using ASP.NET 3.5 and ASP.NET 4.5.

Para sistemas operativos Windows Server, utilize o assistente Add Roles and Features através do link Manage ou do link Dashboard no Server Manager. Na etapa Funções de Servidor, selecione a caixa de seleção para Servidor Web (IIS).

Captura de tela mostrando a função IIS do Servidor Web selecionada na etapa Selecionar funções de servidor.

(Windows Server 2022) Na caixa de diálogo exibida, escolha Adicionar Recursos para adicionar o Console de Gerenciamento do IIS.

Na etapa Serviços de função, selecione os serviços de função do IIS desejados ou aceite os serviços de função padrão fornecidos. Se você quiser habilitar a implantação usando as configurações de publicação e a Implantação da Web, verifique se os seguintes recursos estão selecionados:

• Scripts e ferramentas de gerenciamento do IIS
• de Gestão de Serviço
• Console de Gerenciamento do IIS

Captura de tela mostrando scripts e ferramentas de Gerenciamento do IIS selecionados.

Prossiga com as etapas de confirmação para instalar a função de servidor Web e os serviços. Uma reinicialização do servidor/IIS não é necessária após a instalação da função Servidor Web (IIS).

Atualizar as configurações de segurança do navegador no Windows Server

Se estiver a utilizar uma versão mais antiga do Windows Server, poderá ter de adicionar alguns domínios como sites fidedignos para lhe permitir transferir alguns dos componentes do servidor Web. Adicione os sites confiáveis acessando Opções da Internet Segurança Sites Confiáveis Sites. Adicione os seguintes domínios.

• microsoft.com
• go.microsoft.com
• download.microsoft.com
• iis.net

Ao baixar o software, você pode receber solicitações para conceder permissão para carregar vários scripts e recursos de sites. Alguns desses recursos não são necessários, mas para simplificar o processo, selecione Adicionar quando solicitado.

Instalar o ASP.NET Core no Windows Server

1. Instale o .NET Core Hosting Bundle no sistema de alojamento. O pacote instala o .NET Core Runtime, a .NET Core Library e o ASP.NET Core Module. Para obter instruções mais detalhadas, consulte Publicar no IIS.

   Para o atual pacote de alojamento .NET Core, instale o ASP.NET Core Hosting Bundle.

   Observação

   Se já instalaste o IIS anteriormente, o Módulo ASP.NET Core IIS é instalado com o ASP.NET Core. Caso contrário, instale manualmente o Módulo ASP.NET Core IIS.

   Para .NET Core 2, instale o .NET Core Windows Server Hosting.

   Observação

   Se o sistema não tiver uma ligação Inte rnet, obtenha e instale o Microsoft Visual C++ 2015 Redistributable antes de instalar o .NET Core Windows Server Hosting bundle.

2. Reinicie o sistema (ou execute net stop was /y seguido por net start w3svc a partir de um prompt de comando para aplicar uma alteração no PATH do sistema).

Escolha uma opção de implantação

Se precisar de ajuda para implantar o aplicativo no IIS, considere estas opções:

• Implemente criando um ficheiro de definição de publicação no IIS e importando as definições no Visual Studio. Em alguns cenários, essa é uma maneira rápida de implantar seu aplicativo. Quando você cria o arquivo de configurações de publicação, as permissões são configuradas automaticamente no IIS.

• Implante publicando em uma pasta local e copiando a saída por um método preferencial para uma pasta de aplicativo preparada no IIS.

(Opcional) Implantar usando um arquivo de configurações de publicação

Podes usar esta opção, criar um ficheiro de publicação de definições e importá-lo para o Visual Studio.

Configurar o site ASP.NET Core

1. No Gestor do IIS, no painel esquerdo, em Ligações , selecione Grupos de Aplicações. Abra DefaultAppPool e defina a versão .NET CLR para No Managed Code. Isto é obrigatório para o ASP.NET Core. O site padrão usa o DefaultAppPool.

2. Pare e reinicie o DefaultAppPool.

Instalar e configurar o Web Deploy no Windows Server

A Web Deploy fornece recursos adicionais de configuração que permitem criar o ficheiro de definições de publicação a partir da interface de utilizador.

1. Se você ainda não instalou Ferramentas e Scripts de Gerenciamento do IIS, instale-o agora.

   Vá para Selecionar funções de servidorServidor Web (IIS)Ferramentas de Gerenciamento, e depois selecione a função Scripts e Ferramentas de Gerenciamento do IIS , clique em Avançar, e depois instale a função.

   instalar scripts e ferramentas de gerenciamento do IIS

   Os scripts e ferramentas são necessários para permitir a geração do arquivo de configurações de publicação.

   Certifique-se também de instalar o do Serviço de Gerenciamento e Console de Gerenciamento do IIS (eles podem já estar instalados).

2. No Windows Server, baixar o Web Deploy 4.0.

3. Executa o programa de instalação do Web Deploy e certifique-se de selecionar instalação completa em vez de uma instalação típica.

   Com uma instalação completa, você obtém os componentes necessários para gerar um arquivo de configurações de publicação. (Se você escolher personalizado, poderá ver a lista de componentes, conforme mostrado na ilustração a seguir.)

   Captura de tela mostrando os componentes do Web Deploy 4.0

4. (Opcional) Verifique se o Web Deploy está a correr corretamente abrindo Control Panel > System and Security > Windows Tools > Services, e depois certifique-se de que:

   • Serviço do Agente de Implantação Web está em execução (o nome do serviço é diferente em versões anteriores).

   • O Serviço de Gestão da Web está em execução.

   Se um dos serviços do agente não estiver em execução, reinicie o Web Deployment Agent Service.

   Se o Web Deployment Agent Service não estiver presente, vá a Control Panel > Programas > Desinstalar um programa, encontrar Microsoft Web Deploy <version>. Escolha a opção para Alterar a instalação e certifique-se de selecionar que será instalado no disco rígido local para os componentes de implantação da Web. Conclua as etapas da alteração de instalação.

Criar o arquivo de configurações de publicação no IIS no Windows Server

1. Feche e reabra o Console de Gerenciamento do IIS para mostrar opções de configuração atualizadas na interface do usuário.

2. No IIS, clique com o botão direito do rato no Web Site Padrão, escolha ImplementarConfigurar Publicação do Web Deploy.

   Configurar a configuração do Web Deploy

   Se não vires o menu Implementar, consulta a seção anterior para verificar se o Web Deploy está em execução.

3. Na caixa de diálogo Configurar Publicação 'Web Deploy', examine as configurações.

4. Clique em Configuração.

   No painel Results, a saída mostra que os direitos de acesso são concedidos ao utilizador especificado e que um ficheiro com extensão de ficheiro .publishsettings foi gerado na localização mostrada na caixa de diálogo.

   <?xml version="1.0" encoding="utf-8"?>
   <publishData>
     <publishProfile
       publishUrl="https://myhostname:8172/msdeploy.axd"
       msdeploySite="Default Web Site"
       destinationAppUrl="http://myhostname:80/"
       profileName="Default Settings"
       publishMethod="MSDeploy"
       userName="myhostname\myusername" />
   </publishData>
   

   Dependendo da configuração do Windows Server e do IIS, você verá valores diferentes no arquivo XML. Aqui estão alguns detalhes sobre os valores que você vê:

   • O arquivo msdeploy.axd referenciado no atributo é um arquivo manipulador HTTP gerado dinamicamente para Web Deploy. (Para fins de teste, geralmente funciona também.)

   • A porta é definida como porta 8172, que é o padrão para Web Deploy.

   • A porta é definida como porta 80, que é o padrão para o IIS.

   • Se, em etapas posteriores, não conseguir ligar-se ao host remoto a partir do Visual Studio usando o nome do host, teste o endereço IP do servidor em vez do nome do host.

     Observação

     Se estiveres a publicar para IIS a correr numa VM Azure, tens de abrir uma porta de entrada para Web Deploy e IIS no grupo Network Security. Para informações detalhadas, veja Abrir portas para uma máquina virtual.

5. Copie este ficheiro para o computador onde está a correr o Visual Studio.

Importa as definições de publicação no Visual Studio e implementa

1. No computador onde tem o projeto ASP.NET aberto no Visual Studio, clique com o botão direito no projeto no Solution Explorer e escolha Publicar.

   Se você configurou anteriormente quaisquer perfis de publicação, o painel Publicar será exibido. Clique Novo ou Criar novo perfil.

2. Selecione a opção para importar um perfil.

   Na caixa de diálogo Publicar, clique em Importar perfil.

   Escolha Publicar

3. Navegue até o local do arquivo de configurações de publicação que você criou na seção anterior.

4. Na caixa de diálogo Importar Arquivo de Configurações de Publicação, navegue até o perfil que criou na seção anterior e clique em Abrir.

   Clique Concluir para salvar o perfil de publicação e, em seguida, clique em Publicar.

   O Visual Studio inicia o processo de implementação, e a janela de Saída mostra o progresso e os resultados.

   Se você receber algum erro de implantação, clique em Mais açõesEditar para editar as configurações. Modifique as configurações e clique em Validar para testar novas configurações. Se o nome do host não for encontrado, tente o endereço IP em vez do nome do host nos campos URL do servidor e do destino .

   Configurações de edição na ferramenta Publicar

Depois que o aplicativo for implantado com êxito, ele deve ser iniciado automaticamente.

• Se o aplicativo não iniciar após a implantação, inicie o aplicativo no IIS para verificar se ele é executado corretamente.
• Para ASP.NET Core, certifique-se de que o campo do pool de aplicações para o DefaultAppPool está definido como No Managed Code.

Quando estiver pronto, mude para uma configuração de depuração.

(Opcional) Implantar publicando em uma pasta local

Você pode usar essa opção para implantar seu aplicativo se quiser copiar o aplicativo para o IIS usando PowerShell, RoboCopy ou se quiser copiar manualmente os arquivos.

Configure o site do ASP.NET Core no computador Windows Server

1. Abra o Explorador do Windows e crie uma nova pasta, C:\Publish, para usar na implementação do ASP.NET Core project.

2. Se ainda não estiver aberto, abra o Gerenciador dos Serviços de Informações da Internet (IIS). (No painel esquerdo de Server Manager, selecione IIS. Clique com o botão direito do mouse no servidor e selecione Gerenciador dos Serviços de Informações da Internet (IIS).)

3. Em Conexões no painel esquerdo, vá para Sites.

4. Selecione o Site Web Padrão, escolha Definições Básicase defina o Caminho Físico para C:\Publish.

5. Clique com o botão direito do mouse no nó Site Padrão e selecione Adicionar Aplicação.

6. Defina o campo Alias como MyASPApp , aceite o Pool de Aplicativos padrão (DefaultAppPool) e defina o Caminho físico como C:\Publish.

7. Em Connections, selecione Application Pools. Abra DefaultAppPool e defina o campo do pool de aplicações para Sem Código Gerenciado.

8. Clique com o botão direito no novo site no Gestor IIS, escolha Editar Permissões, e certifique-se de que o IUSR, IIS_IUSRS ou o utilizador configurado para o acesso à aplicação web é um utilizador autorizado com direitos de Leitura e Execução.

   Se não vir nenhum destes utilizadores com acesso, siga os passos para adicionar o IUSR como utilizador com permissões de Leitura e Execução.

Publique e implemente a aplicação publicando numa pasta local a partir do Visual Studio

Você também pode publicar e implantar o aplicativo usando o sistema de arquivos ou outras ferramentas.

1. No Solution Explorer, clique com o botão direito no nó project e selecione Publicar (para Formulários Web, Publicar Aplicação Web).

   Se você configurou anteriormente quaisquer perfis de publicação, o painel Publicar será exibido. Clique em Novo perfil.

2. Na caixa de diálogo Publicar, selecione Pasta, clique em Procurare crie uma nova pasta C:\Publish.

   

   Clique Concluir para guardar o perfil de publicação.

3. Alterne para uma configuração de depuração.

   Escolha Editar para editar o perfil e, em seguida, escolha Configurações. Escolha uma configuração de de depuração e, em seguida, escolha Remover arquivos adicionais no destino nas opções de publicação de arquivo .

   Captura de ecrã do separador Definições na caixa de diálogo Publicar. A configuração é definida como Depurar e o botão Publicar é selecionado.

   Observação

   Se você usar uma compilação de versão, desativará a depuração no arquivo web.config quando publicar.

4. Clique Publicar.

   A aplicação publica a configuração Debug do projeto na pasta local. O progresso é exibido na janela Saída.

5. Copie o diretório ASP.NET project do computador Visual Studio para o diretório local configurado para a aplicação ASP.NET (neste exemplo, C:\Publish) no computador Windows Server. Neste tutorial, assumimos que você está copiando manualmente, mas pode usar outras ferramentas como PowerShell, Xcopy ou Robocopy.

   Atenção

   Se precisar fazer alterações no código ou reconstruir, publique novamente e repita esta etapa. O executável copiado para a máquina remota deve corresponder exatamente à origem e aos símbolos locais. Se não o fizer, receberá um aviso cannot find or open the PDB file em Visual Studio quando tentar depurar o processo.

6. No Windows Server, verifique se você pode executar o aplicativo corretamente abrindo o aplicativo em seu navegador.

   Se a aplicação não correr corretamente, pode haver uma incompatibilidade entre a versão do ASP.NET instalada no seu servidor e a sua máquina Visual Studio, ou pode haver um problema com a configuração do IIS ou do site. Verifique novamente as etapas anteriores.

Baixe e instale as ferramentas remotas no Windows Server

Descarregue a versão das ferramentas remotas que corresponde à sua versão do Visual Studio.

No dispositivo remoto ou servidor onde pretende depurar, em vez da máquina do Visual Studio, descarregue e instale a versão correta das ferramentas remotas a partir dos links na tabela seguinte.

• Faça o download das ferramentas remotas que tenham a mesma arquitetura da máquina onde as está a instalar. Por exemplo, se você quiser depurar aplicativos x86 em um computador remoto executando um sistema operacional x64, instale as ferramentas remotas x64. Para depurar aplicativos x86, ARM ou x64 em um sistema operacional ARM64, instale as ferramentas remotas ARM64.

Você pode executar o depurador remoto copiando msvsmon.exe para o computador remoto, em vez de instalar as ferramentas remotas. No entanto, o Assistente de Configuração do Depurador Remoto (rdbgwiz.exe) está disponível somente quando você instala as ferramentas remotas. Talvez seja necessário usar o assistente para configuração se quiser executar o depurador remoto como um serviço. Para obter mais informações, consulte (Opcional) Configurar o depurador remoto como um serviço.

Configurar o depurador remoto no Windows Server

1. No computador remoto, localize e inicie o Depurador Remoto no menu Iniciar.

   Se não tiver permissões administrativas no computador remoto, clique com o botão direito do rato na app Depurador Remoto e selecione Executar como administrador. Caso contrário, basta iniciá-lo normalmente.

   Se tencionar ligar-se a um processo que está a ser executado como administrador, ou sob uma conta de utilizador diferente (como o IIS), clique com o botão direito do rato na aplicação Depurador Remoto e selecione Executar como administrador. Para obter mais informações, consulte Executar o depurador remoto como administrador.

2. Na primeira vez que você iniciar o depurador remoto (ou antes de configurá-lo), o assistente de Configuração de Depuração Remota será exibido.

   Na maioria dos cenários, selecione Configurar depuração remota.

   Captura de tela da configuração do depurador remoto.Configuração do Depurador Remoto

   Na maioria dos cenários, escolha Avançar até chegar à página Configurar o Firewall do Windows do assistente.

   Captura de tela da configuração do depurador remoto.Configuração do Depurador Remoto

3. Selecione pelo menos um tipo de rede no qual você deseja usar as ferramentas remotas. Se os computadores estiverem conectados através de um domínio, você deverá escolher o primeiro item. Se os computadores estiverem conectados por meio de um grupo de trabalho ou grupo doméstico, escolha o segundo ou terceiro item conforme apropriado.

   Em seguida, selecione Concluir para iniciar o depurador remoto.

4. Quando a configuração estiver concluída, a janela Remote Debugger será exibida.

   Captura de ecrã da janela do depurador remotojanela do depurador remoto

   Captura de ecrã da janela do depurador remotojanela do depurador remoto

   O depurador remoto está agora à espera de uma ligação. Use o nome do servidor e o número de porta mostrados para definir a configuração da ligação remota no Visual Studio.

Para parar o depurador remoto, selecione ArquivoSair. Você pode reiniciá-lo a partir do menu Iniciar ou da linha de comando:

<Remote debugger installation directory>\msvsmon.exe

Para obter informações sobre como executar o depurador remoto como um serviço, consulte executar o depurador remoto como um serviço.

Liga-se à aplicação ASP.NET Core a partir do computador do Visual Studio

4. Selecione Atualizar.

   Você verá alguns processos aparecerem na janela Processos Disponíveis.

   Se você não vir nenhum processo, tente usar o endereço IP em vez do nome do computador remoto (a porta é necessária). Você pode usar em uma linha de comando para obter o endereço IPv4.

   Se quiser usar o botão Localizar, talvez seja necessário abrir a porta UDP de saída 3702 no servidor.

5. Selecione Mostrar processos de todos os utilizadores.

6. Digite a primeira letra do nome do processo para localizar rapidamente seu aplicativo.

   • Se você estiver usando o modelo de hospedagem em processo no IIS, selecione o processo de w3wp.exe correto. A partir do .NET Core 3, este processo é o padrão.

   • Caso contrário, selecione o dotnet.exe processo. (Este é o modelo de hospedagem fora do processo.)

   Se tiver vários processos mostrando w3wp.exe ou dotnet.exe, verifique a coluna Nome de Utilizador. Em alguns cenários, a coluna Nome do Utilizador mostra o nome do pool de aplicações, como IIS APPPOOL\DefaultAppPool. Se você vir o Pool de Aplicativos, mas ele não for exclusivo, crie um novo Pool de Aplicativos nomeado para a instância do aplicativo que deseja depurar e, em seguida, poderá encontrá-lo facilmente na coluna Nome de Usuário.

   Captura de ecrã da caixa de diálogo Anexar ao processo.RemoteDBG_AttachToProcess

7. Selecione Anexar.

8. Abra o site do computador remoto. Em um navegador, vá para http://nome do computador remoto.

   Deves ver a página web do ASP.NET.

9. Na aplicação ASP.NET em execução, selecione o link para a página Privacy.

   O ponto de interrupção deve ser atingido no Visual Studio.

   Se não conseguir ligar ou atingir o ponto de interrupção, consulte Resolução de problemas de depuração remota.

Solução de problemas de implantação do IIS

• Se você não conseguir se conectar ao host usando o nome do host, tente o endereço IP.
• Verifique se as portas necessárias estão abertas no servidor remoto.
• Para ASP.NET Core, tens de garantir que o campo do pool de aplicações para o DefaultAppPool está definido para No Managed Code.
• Verifica se a versão do ASP.NET usada na tua aplicação é a mesma que instalaste no servidor. Para a sua aplicação, pode visualizar e definir a versão na página Propriedades. Para definir o aplicativo para uma versão diferente, essa versão deve ser instalada.
• Se o aplicativo tentou abrir, mas você vê um aviso de certificado, escolha confiar no site. Se já encerrou o aviso, pode editar o perfil de publicação, um ficheiro *.pubxml, no seu project e adicionar o seguinte elemento (apenas para teste): <AllowUntrustedCertificate>true</AllowUntrustedCertificate>
• Depois de implantado, inicie o aplicativo no IIS para testar se ele foi implantado corretamente.
• Verifique a janela de Saída no Visual Studio para informações de estado e verifique as suas mensagens de erro.

Abrir portas necessárias no Windows Server

Na maioria das configurações, as portas necessárias são abertas pela instalação do ASP.NET e do depurador remoto. No entanto, talvez seja necessário verificar se as portas estão abertas.

Portas necessárias:

• 80: Necessário para IIS (HTTP).

• UDP 3702: (Opcional) A porta Discovery permite-lhe usar o botão Find ao ligar ao depurador remoto em Visual Studio.

Além disso, estas portas já devem estar abertas pela instalação do ASP.NET:

• 8172: (Opcional) Necessário para o Web Deploy implementar a aplicação a partir do Visual Studio

Abrir uma porta

1. Para abrir uma porta no Windows Server, abra o menu Iniciar, procure pelo Firewall do Windows Defender ou pelo Firewall do Windows com Segurança Avançada.

   Para Firewall do Windows Defender, escolha Configurações avançadas.

2. Em seguida, escolha Regras de entrada Nova regra portae, em seguida, selecione Avançar. (Para UDP 3702, escolha Regras de Saída em vez disso.)

3. Em Portas locais específicas, introduza o número da porta, selecione Seguinte.

4. Selecione Permitir a conexão, selecione Avançar.

5. Selecione um ou mais tipos de rede para habilitar a porta e selecione Avançar.

   O tipo selecionado deve incluir a rede à qual o computador remoto está conectado.

6. Adicione o nome (por exemplo, IIS, Web Deployou msvsmon) para a Regra de Entrada e selecione Concluir.

   Você verá sua nova regra na lista Regras de entrada ou Regras de saída.

   Se quiser obter mais detalhes sobre como configurar o Firewall do Windows, consulte Configurar o Firewall do Windows para Depuração Remota.

7. Crie mais regras para as outras portas necessárias.