Depurar aplicativos ASP.NET Core

Esse artigo descreve como depurar aplicativos Blazor, incluindo depuração de Blazor WebAssembly aplicativos com ferramentas de desenvolvedor de navegador ou um ambiente de desenvolvimento integrado (IDE).

Blazor Os aplicativos Web podem ser depurados no Visual Studio ou no Visual Studio Code.

Blazor WebAssembly aplicativos podem ser depurados:

• No Visual Studio ou no Visual Studio Code.
• Usando ferramentas de desenvolvedor de navegadores em navegadores baseados em Chromium, incluindo Microsoft Edge, Google Chrome e Firefox.

Os cenários disponíveis para depuração de Blazor WebAssembly incluem:

• Definir e remover pontos de interrupção.
• Executar o aplicativo com suporte de depuração em IDEs.
• Etapa única usando o código.
• Retome a execução de código com um atalho de teclado em IDEs.
• Na janela Locais, observe os valores das variáveis locais.
• Confira a pilha de chamadas, incluindo as cadeias de chamadas entre JavaScript e .NET.
• Use um servidor de símbolos para depuração, configurado pelas preferências do Visual Studio.

Os cenários sem suporte incluem:

• Depure em cenários não locais (por exemplo, WSL (Subsistema do Windows para Linux) ou Codespaces do Visual Studio).
• Depurar no Firefox a partir do Visual Studio ou Visual Studio Code.

Pré-requisitos

Esta seção explica os pré-requisitos para depuração.

Pré-requisitos do navegador

A versão mais recente dos seguintes navegadores:

• Google Chrome
• Microsoft Edge
• Firefox (somente ferramentas de desenvolvedor do navegador)

Verifique se os firewalls ou proxies não estão bloqueando a comunicação com o proxy de depuração (processo NodeJS). Para obter mais informações, confira a seção Configuração de firewall.

Observação

No momento, não há suporte para o Apple Safari no macOS.

Pré-requisitos do IDE

É necessária a versão mais recente do Visual Studio ou do Visual Studio Code.

Pré-requisitos do Visual Studio Code

O Visual Studio Code requer o Kit de Desenvolvimento em C# para o Visual Studio Code (Comece a usar o C# no VS Code). No Marketplace de Extensões do Visual Studio Code, filtre a lista de extensões com "c# dev kit" para localizar a extensão:

A instalação do Kit de Desenvolvimento em C# instala automaticamente as seguintes extensões adicionais:

• Ferramenta de instalação do .NET
• C#
• IntelliCode para Kit de Desenvolvimento em C#

Se encontrar avisos ou erros, você pode abrir um problema (microsoft/vscode-dotnettools repositório GitHub) descrevendo o problema.

Pré-requisitos de configuração do aplicativo

As diretrizes nesta subseção se aplicam à depuração do lado do cliente.

Abra o arquivo Properties/launchSettings.json do projeto de inicialização. Confirme a presença da seguinte propriedade inspectUri em cada perfil de inicialização do nó profiles do arquivo. Se a seguinte propriedade não estiver presente, adicione-a a cada perfil:

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"

A propriedade inspectUri:

• Permite que o IDE detecte que o aplicativo é um aplicativo Blazor.
• Instrui a infraestrutura de depuração de script a se conectar ao navegador por meio do proxy de depuração do Blazor.

Os valores de espaço reservado para o protocolo WebSocket (wsProtocol), host (url.hostname), porta (url.port) e URI do inspetor no navegador iniciado (browserInspectUri) são fornecidos pela estrutura.

Pacotes

BlazorAplicativos Web:Microsoft.AspNetCore.Components.WebAssembly.Server: faz referência a um pacote interno (Microsoft.NETCore.BrowserDebugHost.Transport) para assemblies que compartilham o host de depuração do navegador.

Blazor WebAssembly Autônomo: Microsoft.AspNetCore.Components.WebAssembly.DevServer: servidor de desenvolvimento para uso ao criar aplicativos Blazor. Chama WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internamente para adicionar o middleware para depuração de aplicativos Blazor WebAssembly dentro das ferramentas de desenvolvedor do Chromium.

Observação

Para obter diretrizes sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes no Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas de pacote em NuGet.org.

Depurar um aplicativo web Blazor em um IDE

Visual Studio

O exemplo nesta seção pressupõe que você criou um aplicativo Web Blazor com um modo de renderização interativo Automático (Servidor e WebAssembly) e local de interatividade por componente.

1. abra o aplicativo.
2. Defina um ponto de interrupção na linha currentCount++; no componente Counter (Pages/Counter.razor) do projeto cliente (.Client).
3. Pressione F5 para executar o aplicativo no depurador.
4. No navegador, navegue até a página Counter em /counter. Aguarde alguns segundos para que o proxy de depuração seja carregado e executado. Selecione o botão Clique em mim para atingir o ponto de interrupção.
5. No Visual Studio, inspecione o valor do campo currentCount na janela Locais.
6. Pressione F5 para continuar a execução.

Os pontos de interrupção também podem ser atingidos no projeto do servidor em componentes do lado do servidor renderizados estaticamente e renderizados interativamente.

1. Pare o depurador.

2. Adicione o seguinte componente ao aplicativo de servidor. O componente aplica o modo de renderização do Servidor Interativo (InteractiveServer).

   Components/Pages/Counter2.razor:

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. Defina um ponto de interrupção na linha currentCount++; no componente Counter2.

4. Pressione F5 para executar o aplicativo no depurador.

5. No navegador, navegue até a página Counter2 em /counter-2. Aguarde alguns segundos para que o proxy de depuração seja carregado e executado. Selecione o botão Clique em mim para atingir o ponto de interrupção.

6. Pressione F5 para continuar a execução.

Os pontos de interrupção não são atingidos durante a inicialização do aplicativo, antes que o proxy de depuração esteja em execução. Isso inclui pontos de interrupção no arquivo Program e pontos de interrupção nos OnInitialized{Async}métodos de ciclo de vida de componentes que são carregados pela primeira página solicitada do aplicativo.

Visual Studio Code

O exemplo nesta seção pressupõe que você tenha criado um aplicativo Web Blazor com um modo de renderização automático interativo (Servidor e WebAssembly) e um local de interatividade por componente.

1. Abra o aplicativo no Visual Studio Code abrindo a pasta da solução, que é a pasta que contém as pastas do servidor e do projeto .Client.
2. Defina um ponto de interrupção na linha currentCount++; no componente Counter (Pages/Counter.razor) do projeto cliente (.Client).
3. Abra o painel Executar e depurar e selecione o botão Executar e depurar. Como alternativa, pressione F5 (Iniciar depuração). Selecione o depurador C# na paleta de comandos na parte superior da interface do usuário. Selecione o perfil padrão para o projeto do servidor (por exemplo, C#:BlazorSample [Default Configuration]).
4. No navegador, navegue até a página Counter em /counter. Aguarde alguns segundos para que o proxy de depuração seja carregado e executado. Selecione o botão Clique em mim para atingir o ponto de interrupção.
5. Selecione o botão Continuar na interface do usuário ou pressione F5 (Continuar) para continuar a execução.

Pontos de interrupção também podem ser atingidos no projeto do servidor.

1. Interrompa a depuração selecionando o botão Parar ou pressione Shift+F5 no teclado.

2. Adicione o seguinte componente ao aplicativo de servidor. O componente adota o modo de renderização do Servidor Interativo (InteractiveServer).

   Components/Pages/Counter2.razor:

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. Defina um ponto de interrupção na linha currentCount++; no componente Counter2.

4. Selecione o botão Iniciar depuração na interface do usuário ou pressione F5 (Iniciar depuração) para executar o aplicativo no depurador.

5. No navegador, navegue até a página Counter2 em /counter-2. Aguarde alguns segundos para que o proxy de depuração seja carregado e executado. Selecione o botão Clique em mim para atingir o ponto de interrupção.

6. Selecione o botão Continuar na interface do usuário ou pressione F5 (Continuar) para continuar a execução.

Os pontos de interrupção não são atingidos durante a inicialização do aplicativo, antes que o proxy de depuração esteja em execução. Isso inclui pontos de interrupção no arquivo Program e pontos de interrupção nos OnInitialized{Async}métodos de ciclo de vida de componentes que são carregados pela primeira página solicitada do aplicativo.

Não há suporte para Iniciar sem Depuração [Ctrl+F5 (Windows) ou ⌘+F5 (macOS)]. Quando o aplicativo é executado na configuração de Depuração, a sobrecarga de depuração sempre resulta em uma pequena redução de desempenho.

Depurar um aplicativo Blazor WebAssembly em um IDE

Visual Studio

1. abra o aplicativo.
2. Defina um ponto de interrupção na linha currentCount++; no componente Counter (Pages/Counter.razor).
3. Pressione F5 para executar o aplicativo no depurador.
4. No navegador, navegue até a página Counter em /counter. Aguarde alguns segundos para que o proxy de depuração seja carregado e executado. Selecione o botão Clique em mim para atingir o ponto de interrupção.
5. No Visual Studio, inspecione o valor do campo currentCount na janela Locais.
6. Pressione F5 para continuar a execução.

Os pontos de interrupção não são atingidos durante a inicialização do aplicativo, antes que o proxy de depuração esteja em execução. Isso inclui pontos de interrupção no arquivo Program e pontos de interrupção nos OnInitialized{Async}métodos de ciclo de vida de componentes que são carregados pela primeira página solicitada do aplicativo.

Visual Studio Code

1. Abra a pasta do aplicativo no Visual Studio Code.
2. Defina um ponto de interrupção na linha currentCount++; no componente Counter (Pages/Counter.razor).
3. Abra o painel Executar e depurar e selecione o botão Executar e depurar. Como alternativa, pressione F5 (Iniciar depuração). Selecione o depurador C# na paleta de comandos na parte superior da interface do usuário. Selecione o perfil padrão (por exemplo, C#:BlazorSample [Default Configuration]).
4. Pressione F5 para executar o aplicativo no depurador.
5. O aplicativo autônomo será iniciado e um navegador de depuração será aberto.
6. No navegador, navegue até Counter página em /counter. Aguarde alguns segundos para que o proxy de depuração seja carregado e executado. Selecione o botão Clique em mim para atingir o ponto de interrupção.
7. Pressione F5 para continuar a execução.

Os pontos de interrupção não são atingidos durante a inicialização do aplicativo, antes que o proxy de depuração esteja em execução. Isso inclui pontos de interrupção no arquivo Program e pontos de interrupção nos OnInitialized{Async}métodos de ciclo de vida de componentes que são carregados pela primeira página solicitada do aplicativo.

Não há suporte para Iniciar sem Depuração [Ctrl+F5 (Windows) ou ⌘+F5 (macOS)]. Quando o aplicativo é executado na configuração de Depuração, a sobrecarga de depuração sempre resulta em uma pequena redução de desempenho.

Suporte ao depurador

A depuração está habilitada para o runtime quando o suporte ao depurador está habilitado com <DebuggerSupport>{VALUE}</DebuggerSupport>, em que o espaço reservado {VALUE} é preenchido com true ou false.

Por padrão, a estrutura Blazordesabilita o suporte ao depurador para todas as configurações que não sejam de depuração. Para habilitar o suporte ao depurador para uma configuração que não seja de depuração, adicione uma propriedade <DebuggerSupport> ao arquivo de projeto do aplicativo.

No exemplo a seguir, o suporte ao depurador está habilitado para a configuração personalizada "DebugCustom":

<DebuggerSupport Condition="'$(Configuration)' == 'DebugCustom'">true</DebuggerSupport>

Para obter mais informações, consulte Blazor WebAssembly configuração personalizada do depurador (dotnet/runtime #96239).

Anexar a uma sessão de depuração do Visual Studio Code existente

Para anexar a um aplicativo Blazor em execução, abra o arquivo de .vscode/launch.json e substitua o espaço reservado {URL} pela URL em que o aplicativo está sendo executado:

{
  "name": "Attach and Debug",
  "type": "blazorwasm",
  "request": "attach",
  "url": "{URL}"
}

Opções de inicialização do Visual Studio Code

As opções de configuração de inicialização na tabela a seguir são suportadas para o tipo de depuração blazorwasm (.vscode/launch.json).

Opção	Descrição
browser	O navegador a ser iniciado para a sessão de depuração. Definir como edge ou chrome. Assume o padrão de edge.
cwd	O diretório de trabalho no qual o aplicativo deve ser iniciado.
request	Use launch para iniciar e anexar uma sessão de depuração a um aplicativo Blazor WebAssembly ou attach para anexar uma sessão de depuração a um aplicativo já em execução.
timeout	O número de milissegundos para aguardar pela anexação da sessão de depuração. O padrão é de 30.000 milissegundos (30 segundos).
trace	Usado para gerar logs no depurador JS. Defina como true para gerar logs.
url	A URL a ser aberta no navegador durante a depuração.
webRoot	Especifica o caminho absoluto do servidor Web. Deve ser definido se um aplicativo for atendido a partir de uma sub-rota.

Depurar Blazor WebAssembly com o Google Chrome ou Microsoft Edge

A orientação nesta seção aplica depuração de Blazor WebAssembly aplicativos em:

• Google Chrome rodando no Windows ou macOS.
• Microsoft Edge em execução no Windows.

1. Execute o aplicativo em um shell de comando com dotnet run.

2. Inicie um navegador e navegue até a URL do aplicativo.

3. Inicie a depuração remota pressionando:

   • Shift+Alt+d no Windows.
   • Shift+⌘+d no macOS.

   O navegador deve estar em execução com a depuração remota habilitada, o que não é o padrão. Se a depuração remota estiver desabilitada, a página de erro Não é possível localizar a guia do navegador depurável será renderizada com as instruções para iniciar o navegador com a porta de depuração aberta. Siga as instruções para o seu navegador.

   Depois de seguir as instruções para habilitar a depuração remota, o aplicativo será aberto em uma nova janela do navegador. Inicie a depuração remota pressionando a combinação de HotKey na nova janela do navegador:

   • Shift+Alt+d no Windows.
   • Shift+⌘+d no macOS.

   Uma nova guia do navegador de ferramentas do desenvolvedor de janela é aberta mostrando uma imagem fantasma do aplicativo.

   Observação

   Se você seguiu as instruções para abrir uma nova guia do navegador com a depuração remota habilitada, poderá fechar a janela original do navegador, deixando a segunda janela aberta com a primeira guia executando o aplicativo e a segunda guia executando o depurador.

4. Depois de um momento, a guia Fontes mostra uma lista de assemblies e páginas .NET do aplicativo.

5. Abra o nó file://. No código do componente (arquivos .razor) e nos arquivos de código C# (.cs), os pontos de interrupção definidos são atingidos quando o código é executado na guia do navegador do aplicativo (a guia inicial aberta após iniciar a depuração remota). Depois que um ponto de interrupção é atingido, execute a etapa única (F10) no código ou retome a execução do código (F8) normalmente na guia de depuração.

Para depuração de navegador baseado em Chromium, o Blazor fornece um proxy de depuração que implementa o Chrome DevTools Protocol e aumenta o protocolo com informações específicas da NET. Quando o atalho de teclado de depuração é pressionado, Blazor aponta o Chrome DevTools para o proxy. O proxy se conecta à janela do navegador que você está buscando depurar (daí a necessidade de habilitar a depuração remota).

Depurar um aplicativo Blazor WebAssembly com o Firefox

A diretriz nessa seção aplica depuração de Blazor WebAssembly aplicativos no Firefox em execução no Windows.

Depurar um aplicativo Blazor WebAssembly com o Firefox requer configurar o navegador para depuração remota e conectar-se ao navegador usando as ferramentas de desenvolvedor do navegador por meio do proxy de depuração do .NET WebAssembly.

Observação

No momento, não há suporte para depuração no Firefox por meio do Visual Studio.

Para depurar um aplicativo Blazor WebAssembly no Firefox durante o desenvolvimento:

1. Configurar o Firefox:
   • Abra about:config em uma nova guia do navegador. Leia e ignore o aviso que aparece.
   • Habilite devtools.debugger.remote-enabled definindo o seu valor como True.
   • Habilite devtools.chrome.enabled definindo o seu valor como True.
   • Desabilite devtools.debugger.prompt-connection definindo o seu valor como False.
2. Feche todas as instâncias do Firefox.
3. Execute o aplicativo em um shell de comando com dotnet run.
4. Reinicie o navegador Firefox e vá até o aplicativo.
5. Abra about:debugging em uma nova guia do navegador. Deixe essa guia aberta.
6. Volte para a guia em que o aplicativo está em execução. Inicie a depuração remota pressionando Shift+Alt+d.
7. Na guia Debugger, abra o arquivo de origem do aplicativo que deseja depurar sob o nó file:// e defina um ponto de interrupção. Por exemplo, defina um ponto de interrupção na linha currentCount++; no método IncrementCount do componente Counter (Pages/Counter.razor).
8. Navegue até a página do componente Counter (/counter) na guia do navegador do aplicativo e selecione o botão de contador para acessar o ponto de interrupção.
9. Pressione F5 para continuar a execução na guia de depuração.

Interromper exceções sem tratamento

O depurador não é interrompido em exceções sem tratamento por padrão porque Blazor captura exceções que não são tratadas pelo código do desenvolvedor.

Para interromper exceções sem tratamento:

• Abra as configurações de exceção do depurador (Depurar>Windows>Configurações de Exceção) no Visual Studio.
• Defina as seguintes configurações de Exceções de JavaScript:
  • Todas as Exceções
  • Exceções não Capturadas

Mapas de origem do navegador

Os mapas de origem do navegador permitem que o navegador mapeie os arquivos compilados até os arquivos de origem originais e são comumente usados para depuração do lado do cliente. No entanto, atualmente, Blazor não mapeia o C# diretamente para o JavaScript/WASM. Em vez disso, Blazor faz a interpretação de IL no navegador, portanto, os mapas de origem não são relevantes.

Configuração do firewall

Se um firewall bloquear a comunicação com o proxy de depuração, crie uma regra de exceção de firewall que permita a comunicação entre o navegador e o processo NodeJS.

Aviso

A modificação de uma configuração de firewall deve ser feita com cuidado para evitar a criação de vulnerabilidades de segurança. Aplique cuidadosamente as diretrizes de segurança, siga as melhores práticas de segurança e respeite os avisos emitidos pelo fabricante do firewall.

Permitir a comunicação aberta com o processo NodeJS:

• Abre o servidor Node para qualquer conexão, dependendo dos recursos e da configuração do firewall.
• Pode ser arriscado dependendo da sua rede.
• É recomendado apenas em computadores de desenvolvedor.

Se possível, permita apenas a comunicação aberta com o NodeJS processo em redes confiáveis ou privadas.

Para obter diretrizes de configuração do Firewall do Windows, confira Criar um programa de entrada ou uma regra de serviço. Para obter mais informações, confira Windows Defender Firewall com Segurança Avançada e artigos relacionados no conjunto de documentação do Firewall do Windows.

Solucionar problemas

Se você estiver recebendo erros, as seguintes dicas podem ajudar:

• Remover pontos de interrupção:
  • Google Chrome: na guia do Depurador abra as ferramentas de desenvolvedor em seu navegador. No console, execute localStorage.clear() para remover os pontos de interrupção.
  • Microsoft Edge: na guia Aplicativo, abra armazenamento local. Clique com o botão direito do mouse no site e selecione Limpar.
• Confirme se você instalou e confiou no certificado de desenvolvimento HTTPS do ASP.NET Core. Para saber mais, confira Impor HTTPS no ASP.NET Core.
• O Visual Studio requer a opção Ativar depuração JavaScript para ASP.NET (Chrome e Edge) em Ferramentas>Opções>Depuração>Geral. Essa é a configuração padrão para Visual Studio. Se a depuração não estiver funcionando, confirme se a opção foi selecionada.
• Se o ambiente usar um proxy HTTP, verifique se localhost está incluído nas configurações de bypass de proxy. Isso pode ser feito definindo a variável de ambiente NO_PROXY em:
  • O arquivo launchSettings.json do projeto.
  • No nível de variáveis de ambiente do usuário ou do sistema, para que se aplique a todos os aplicativos. Ao usar uma variável de ambiente, reinicie o Visual Studio para que a alteração entre em vigor.
• Verifique se os firewalls ou proxies não estão bloqueando a comunicação com o proxy de depuração (processo NodeJS). Para obter mais informações, confira a seção Configuração de firewall.

Pontos de interrupção em OnInitialized{Async} não atingidos

O proxy de depuração da estrutura Blazor não é iniciado instantaneamente na inicialização do aplicativo, portanto, os pontos de interrupção nos métodos de ciclo de vidaOnInitialized{Async} podem não ser atingidos. É recomendável adicionar um atraso no início do corpo do método para dar ao proxy de depuração algum tempo para iniciar, antes que o ponto de interrupção seja atingido. Você pode incluir o atraso com base em uma diretiva do compilador if para garantir que o atraso não esteja presente em uma compilação de versão do aplicativo.

OnInitialized:

protected override void OnInitialized()
{
#if DEBUG
    Thread.Sleep(10000);
#endif

    ...
}

OnInitializedAsync:

protected override async Task OnInitializedAsync()
{
#if DEBUG
    await Task.Delay(10000);
#endif

    ...
}

Tempo limite do Visual Studio (Windows)

Se o Visual Studio gerar uma exceção de que o adaptador de depuração não pôde iniciar, mencionando que o tempo limite foi atingido, você poderá ajustar o tempo limite com uma configuração do Registro:

VsRegEdit.exe set "<VSInstallFolder>" HKCU JSDebugger\Options\Debugging "BlazorTimeoutInMilliseconds" dword {TIMEOUT}

O espaço reservado {TIMEOUT} no comando anterior está em milissegundos. Por exemplo, um minuto é atribuído como 60000.