Depurar aplicativos ASP.NET ou ASP.NET Core no Visual Studio

Você pode depurar aplicativos de ASP.NET e ASP.NET Core no Visual Studio. O processo difere entre ASP.NET e ASP.NET Core e se você o executa em IIS Express ou em um servidor IIS local.

Observação

As etapas e configurações a seguir se aplicam somente à depuração de aplicativos em um servidor local. A depuração de aplicativos em um servidor IIS remoto usa Anexar ao Processo e ignora essas configurações. Para saber mais e obter instruções sobre a depuração remota de aplicativos ASP.NET no IIS, confira De depuração remota de ASP.NET em um computador IIS ou Depuração remota de ASP.NET Core em um computador IIS remoto.

Os servidores do Kestrel e IIS Express internos estão incluídos no Visual Studio. O Kestrel é o servidor de depuração padrão para projetos de ASP.NET Core e vem pré-configurado. O IIS Express é o servidor de depuração padrão para ASP.NET.

Pré-requisitos para servidor IIS local

Você também pode depurar um aplicativo ASP.NET ou ASP.NET Core em um servidor IIS local (versão 8.0 ou superior) configurado para executar o aplicativo. Para depurar no IIS local, você deve atender aos seguintes requisitos:

• Se ele não estiver instalado, instale o ASP.NET e a carga de trabalho de desenvolvimento na Web. (Execute novamente o Instalador do Visual Studio, selecione Modificar e adicione esta carga de trabalho.)

• Execute o Visual Studio como administrador.

• Instale e configure corretamente o IIS com as versões apropriadas de ASP.NET e/ou ASP.NET Core. Para saber mais sobre como usar o IIS com ASP.NET Core, confira Host ASP.NET Core no Windows com IIS. Para ASP.NET, confira Instalar módulos do IIS e ASP.NET.

• Verifique se o aplicativo é executado no IIS sem erros.

Depurar o ASP.NET Core aplicativos

Um perfil padrão baseado em https ou um com base no nome do projeto pode estar presente, que são configurados para o servidor do Web Kestrel. Caso esteja depurando no IIS local, garanta atender aos pré-requisitos para a depuração do IIS local.

1. Selecione o projeto ASP.NET Core no Gerenciador de Soluções do Visual Studio e clique no ícone Propriedades, pressione Alt+Enter ou clique com o botão direito do mouse e escolha Propriedades.

2. Selecione a guia Depurar e clique no link para abrir a interface do usuário Abrir perfis de inicialização de depuração.

   A interface do usuário apresentada corresponde às configurações no arquivo launchSettings.json do projeto. Para obter mais informações sobre esse arquivo, consulte a seção Desenvolvimento e launchSettings.json em Usar vários ambientes no ASP.NET Core.

3. Selecione o perfil a ser configurado para depuração.

   • Para o kestrel, selecione o perfil https ou o perfil com o nome do projeto.
   • Para IIS Express, selecione IIS Express na lista suspensa.
   • Para o IIS local, selecione Novo e crie um novo perfil do IIS.

4. Verifique se Iniciar navegador está selecionado.

5. Verifique se a URL, a URL do Aplicativo e a URL SSL do Aplicativo estão corretas.

   A URL especifica o local da URL do host para .NET ou .NET Core. Para um perfil nomeado de acordo com o projeto (ou seja, a propriedade commandName em launchSettings.json é Projeto), o servidor Kestrel escuta a porta especificada. Para um perfil do IIS, esse normalmente é o mesmo valor que a URL do Aplicativo. Para obter mais informações, confira a seção Perfil de inicialização do IIS em Configurar o projeto.

   A URL do aplicativo e a URL SSL do aplicativo especificam as URLs do aplicativo. Para um perfil nomeado de acordo com o projeto, essa propriedade especifica as URLs do servidor Kestrel, normalmente https://localhost:5001 e http://localhost:5000. Para IIS Express, a URL do SSL do aplicativo costuma ser http://localhost:44334.

6. Em Variáveis de ambiente, verifique se ASPNETCORE_ENVIRONMENT está presente com um valor de Desenvolvimento. Caso contrário, adicione a variável.

   

   Para saber mais sobre variáveis de ambiente, confira Ambientes.

7. Para depurar o aplicativo, em seu projeto, defina pontos de interrupção em algum código. Na barra de ferramentas do Visual Studio, verifique se a configuração está definida como Depurar.

8. Para iniciar a depuração, selecione o nome do perfil na barra de ferramentas, como as https, IIS Express ou <nome de perfil do IIS> na barra de ferramentas, selecione Iniciar Depuração no menuDepurar ou pressione F5. O depurador faz uma pausa nos pontos de interrupção. Se o depurador não conseguir atingir os pontos de interrupção, confira Solucionar problemas de depuração.

Depurar aplicativos ASP.NET

IIS Express é o padrão e está pré-configurado. Se você estiver depurando no IIS Local, atenda aos requisitos de depuração do IIS local.

1. Selecione o projeto ASP.NET no Visual Studio Gerenciador de Soluções e clique no ícone Propriedades, pressione Alt+Enter ou clique com o botão direito e escolha Propriedades.

2. Selecione a guia Web .

   Se você não vir a guia Web, confira Depurar aplicativos ASP.NET Core. A guia Web aparece apenas para o ASP.NET Framework.

3. No painel Propriedades, em Servidores,

   • Para o Kestrel, selecione https, na lista suspensa.
   • Para IIS Express, selecione IIS Express na lista suspensa.
   • Para o IIS local,
     1. Selecione IIS Local na lista suspensa.
     2. Ao lado do campo URL do Projeto, selecione Criar Diretório Virtual, caso ainda não tenha configurado o aplicativo no IIS.

4. Em Depuradores, selecione ASP.NET.

   

5. Escolha Arquivo>Salvar Itens Selecionados (ou pressione Ctrl+S) para salvar as alterações.

6. Para depurar o aplicativo, em seu projeto, defina pontos de interrupção em algum código. Na barra de ferramentas do Visual Studio, verifique se a configuração está definida como Depuração e se o navegador desejado aparece em IIS Express (<Nome do navegador>) ou IIS Local (<Nome do navegador>) no campo do emulador.

7. Para iniciar a depuração, selecione IIS Express (<Nome do navegador>) ou IIS Local (<Nome do navegador>) na barra de ferramentas, selecione Iniciar Depuração no menu Depurar ou pressione F5. O depurador faz uma pausa nos pontos de interrupção. Se o depurador não conseguir atingir os pontos de interrupção, confira Solucionar problemas de depuração.

Solucionar problemas de depuração

Se a depuração do IIS local não puder progredir para o ponto de interrupção, execute estas etapas para solucionar problemas.

1. Inicie o aplicativo Web do IIS e verifique se ele é executado corretamente. Deixe o aplicativo Web em execução.

2. No Visual Studio, selecione Depurar > Anexar ao Processo ou pressione Ctrl+Alt+P e conecte-se ao processo de ASP.NET ou ASP.NET Core (normalmente w3wp.exe ou dotnet.exe). Para saber mais, confira Anexar ao Processo e Como localizar o nome do processo de ASP.NET.

Se você puder se conectar e atingir o ponto de interrupção usando Anexar ao Processo, mas não usando Depurar>Iniciar Depuração ou F5, uma configuração provavelmente estará incorreta nas propriedades do projeto. Se você usar um arquivo HOSTS, verifique se ele também está configurado corretamente.

Para habilitar a depuração no arquivo web.config

Projetos ASP.NET têm arquivos web.config por padrão, que contêm informações de configuração e inicialização do aplicativo, incluindo configurações de depuração. Os arquivos web.config devem ser configurados corretamente para depuração. As configurações de Propriedades nas seções anteriores atualizam os arquivos web.config, mas você também pode configurá-los manualmente.

Observação

Projetos do ASP.NET Core inicialmente não têm arquivos web.config, mas usam arquivos appsettings.json e launchSettings.json para informações sobre configuração e inicialização de aplicativos. Implantar o aplicativo cria um arquivo ou arquivos web.config no projeto, mas eles não costumam conter informações de depuração.

Dica

Seu processo de implantação pode atualizar as configurações de web.config, portanto, antes de tentar depurar, verifique se web.config está configurado para depuração.

Para configurar manualmente um arquivo web.config para depuração:

1. No Visual Studio, abra o arquivo web.config do projeto ASP.NET.

2. Web.config é um arquivo XML e, assim, contém as seções aninhadas marcadas com tags. Localize a seção configuration/system.web/compilation. (Se o elemento compilation não existir, crie-o.)

3. Verifique se o atributo debug no elemento compilation está definido como true. (Se o elemento compilation não contiver um atributo debug, adicione-o e defina-o como true.)

   Se você estiver usando o IIS local em vez do servidor de IIS Express padrão, verifique se o valor do atributo targetFramework no elemento compilation corresponde à estrutura no servidor IIS.

   O elemento compilation do arquivo web.config deve ser semelhante ao seguinte exemplo:

   Observação

   O exemplo é um arquivo web.config parcial. Geralmente, há seções XML adicionais nos elementos configuration e system.web, e o elemento compilation também pode conter outros atributos e elementos.

   <configuration>
      ...
      <system.web>
          <compilation  debug="true"  targetFramework="4.6.1" ... >
             ...
          </compilation>
      </system.web>
   </configuration>
   

O ASP.NET detecta automaticamente todas as alterações nos arquivos web.config e aplica as novas definições de configuração. Você não precisa reiniciar o computador ou reiniciar o servidor IIS para que as alterações entrem em vigor.

Um site pode conter vários diretórios virtuais e subdiretórios, com arquivos web.config em cada um deles. Os aplicativos ASP.NET herdam as definições de configuração de arquivos web.config em níveis mais altos no caminho da URL. As configurações hierárquicas de arquivo web.config se aplicam a todos os aplicativos ASP.NET abaixo deles na hierarquia. Definir uma configuração diferente em um arquivo web.config inferior na hierarquia substitui as configurações no arquivo superior.

Por exemplo, se você especificar debug="true" em www.microsoft.com/aaa/web.config, qualquer aplicativo na pasta aaa ou em qualquer subpasta de aaa herda essa configuração, exceto se um desses aplicativos substituir a configuração com seu próprio arquivo web.config.

Importante

O modo de depuração reduz consideravelmente o desempenho do aplicativo. Ao implantar um aplicativo de produção ou realizar medidas de desempenho, defina debug="false" no web.config e especifique um build de versão.

Conteúdo relacionado

• Depuração do ASP.NET: requisitos do sistema
• Como executar o processo de trabalho em uma conta de usuário
• Como localizar o nome do processo ASP.NET
• Depurar aplicativos Web implantados
• Como depurar exceções do ASP.NET
• Depurar aplicativos Web: solução de erros e de problemas