Depurar aplicativos ASP.NET Core

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

É possível depurar Blazor Web Apps no Visual Studio ou no Visual Studio Code.

Blazor WebAssembly aplicações podem ser depuradas:

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

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

• Defina e remova pontos de interrupção.
• Execute a aplicação com suporte para depuração em IDEs.
• Execute o código passo a passo.
• Retome a execução de código com um atalho de teclado em IDEs.
• Na janela Locais, observe os valores das variáveis locais.
• Veja a pilha de chamadas, incluindo sequências 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:

• Depurar em cenários não locais (por exemplo, do Subsistema Windows para Linux (WSL) ou Visual Studio Codespaces).
• 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 (apenas ferramentas de desenvolvimento do navegador)

Certifique-se de que os firewalls ou proxies não bloqueiem a comunicação com o processoNodeJS do proxy de depuração. Para obter mais informações, consulte a seção de configuração do firewall.

Nota

O Apple Safari no macOS não é suportado no momento.

Pré-requisitos do IDE

A versão mais recente do Visual Studio ou Visual Studio Code é necessária.

Pré-requisitos de código do Visual Studio

O Visual Studio Code requer o C# Dev Kit para Visual Studio Code (Introdução ao C# no VS Code). No Visual Studio Code Extensions Marketplace, filtre a lista de extensões com "c# dev kit" para localizar a extensão:

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

• Ferramenta de Instalação do .NET
• C#
• IntelliCode para C# Dev Kit

Se encontrares avisos ou erros, podes abrir um problema (microsoft/vscode-dotnettools repositório GitHub) descrevendo o problema.

Pré-requisitos de configuração do aplicativo

A orientação nesta subseção se aplica à 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:

JSON

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

A propriedade inspectUri:

• Permite que o IDE detete 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 pelo framework.

Pacotes

Blazor Web Apps: Microsoft.AspNetCore.Components.WebAssembly.Server: Faz referência a um pacote interno (Microsoft.NETCore.BrowserDebugHost.Transport) para montagens que partilham o host de depuração do navegador.

Blazor WebAssemblyautônomo : Microsoft.AspNetCore.Components.WebAssembly.DevServer: Servidor de desenvolvimento para uso ao criar aplicativos Blazor. Chama UseWebAssemblyDebugging internamente para adicionar middleware para depuração de aplicativos Blazor WebAssembly nas ferramentas de desenvolvimento do Chromium.

Nota

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

Depurar um Blazor Web App em um IDE

Visual Studio

O exemplo nesta seção pressupõe que você criou um Blazor Web App com um modo de renderização interativo de Auto (Server e WebAssembly) e um 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. Com o projeto de servidor selecionado em Solution Explorer, 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 carregue e seja executado. Selecione o botão Click me para alcançar o ponto de paragem.
5. No Visual Studio, inspecione o valor do campo currentCount na janela Locals.
6. Pressione F5 para continuar a execução.

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

1. Parar o depurador.
2. No aplicativo de servidor, abra o componente Weather renderizado estaticamente (Components/Pages/Weather.razor) e defina um ponto de interrupção em qualquer lugar no método OnInitializedAsync.
3. Pressione F5 para executar o aplicativo no depurador.
4. No navegador, navegue até a página Weather em /weather. Aguarde alguns segundos para que o proxy de depuração carregue e seja executado. A execução do aplicativo para no ponto de interrupção.
5. 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 seja executado. Isso inclui pontos de paragem no arquivo de Program e pontos de paragem nos métodos de ciclo de vida OnInitialized{Async} de componentes que são carregados pela primeira página solicitada pela aplicação.

O exemplo nesta secção pressupõe que criaste um Blazor Web App com um modo de renderização Auto interativo (Server e WebAssembly) e um local de interatividade por componente.

1. Abra a aplicação no Visual Studio Code ao abrir a pasta da solução, que é a pasta que contém o servidor e as pastas 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 (Start Debugging). Selecione o depurador C# na paleta de comandos no topo da interface. Selecione o perfil padrão para o projeto de 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 carregue e seja executado. Selecione o botão Clique aqui para atingir o ponto de interrupção.
5. Selecione o botão Continue na interface do usuário ou pressione F5 (Continue) para continuar a execução.

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

1. Pare a depuração selecionando o botão Parar ou pressione Shift+F5 no teclado.
2. No aplicativo de servidor, abra o componente Weather renderizado estaticamente (Components/Pages/Weather.razor) e defina um ponto de interrupção em qualquer lugar no método OnInitializedAsync.
3. Selecione o botão Iniciar Depuração na interface do usuário ou pressione F5 (Iniciar Depuração) para executar o aplicativo no depurador.
4. No navegador, navegue até a página Weather em /weather. Aguarde alguns segundos para que o proxy de depuração carregue e seja executado. A execução do aplicativo para no ponto de interrupção.
5. Selecione o botão Continue na interface do usuário ou pressione F5 (Continue) 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 seja executado. Isso inclui pontos de interrupção no arquivo de Program e pontos de interrupção nos métodos de ciclo de vida OnInitialized{Async} de componentes que são carregados pela primeira página solicitada ao aplicativo.

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 na /counter. Aguarde alguns segundos para que o proxy de depuração carregue e seja executado. Selecione o botão Clique aqui para atingir o ponto de interrupção.
5. No Visual Studio, inspecione o valor do campo currentCount na janela Locals.
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 seja executado. Isso inclui pontos de interrupção no arquivo de Program e pontos de interrupção nos métodos de ciclo de vida OnInitialized{Async} de componentes que são carregados pela primeira página solicitada ao aplicativo.

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 (Start Debugging). Selecione o depurador C# na paleta de comandos no topo da interface. 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 é iniciado e um navegador de depuração é aberto.
6. No navegador, navegue para a página Counter em /counter. Aguarde alguns segundos para que o proxy de depuração carregue e seja 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 seja executado. Isso inclui pontos de paragem no arquivo Program e pontos de paragem nos métodos de ciclo de vida ,OnInitialized{Async}, dos componentes que são carregados pela página solicitada pela primeira vez ao aplicativo.

Anexar a uma sessão de depuração de código do Visual Studio existente

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

JSON

{
  "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. Defina como edge ou chrome. O padrão é edge.
cwd	O diretório de trabalho para iniciar o aplicativo em.
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 a aguardar até que a sessão de depuração seja anexada. O padrão é 30.000 milissegundos (30 segundos).
trace	Usado para gerar logs a partir do depurador de JS. Defina como true para gerar logs.
url	O URL a ser aberto no navegador durante a depuração.
webRoot	Especifica o caminho absoluto do servidor Web. Deve ser definido se um aplicativo for servido a partir de uma subrota.

Depurar Blazor WebAssembly com o Google Chrome ou o Microsoft Edge

As orientações nesta secção aplicam-se à depuração de aplicativos Blazor WebAssembly em:

• Google Chromeem execução no Windows ou macOS.
• Microsoft Edgeem execução no Windows.

1. Execute o aplicativo em um shell de comando com dotnet watch (ou dotnet run).

2. Inicie um navegador e navegue até o 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 ativada, o que não é o padrão. Se a depuração remota estiver desativada, uma página de erro Não foi possível encontrar a guia de navegador depurável é renderizada com instruções para lançar o navegador com a porta de depuração aberta. Siga as instruções para o seu navegador.

   Depois de seguir as instruções para ativar a depuração remota, o aplicativo é aberto em uma nova janela do navegador. Inicie a depuração remota pressionando a combinação de teclas de atalho na nova janela do navegador:

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

   Uma nova aba de ferramentas de desenvolvedor é aberta no navegador, exibindo uma imagem fantasma do aplicativo.

   Nota

   Se você seguiu as instruções para abrir uma nova guia do navegador com a depuração remota ativada, você pode 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 de componente (arquivos.razor) e nos arquivos de código C# (.cs), os pontos de interrupção que definir 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 de um ponto de interrupção ser atingido, avance passo a passo (F10) pelo código ou retome a execução do código (F8) normalmente na guia de depuração.

Para a depuração de navegadores baseados no Chromium, o Blazor fornece um proxy de depuração que implementa o Chrome DevTools Protocol e complementa o protocolo com informações específicas do .NET. Quando o atalho de teclado para depuração é pressionado, Blazor direciona as Ferramentas de Desenvolvimento do Chrome para o proxy. O proxy se conecta à janela do navegador que você está procurando depurar (daí a necessidade de habilitar a depuração remota).

Depurar um aplicativo Blazor WebAssembly com o Firefox

As orientações nesta secção aplicam-se à depuração de Blazor WebAssembly aplicativos no Firefox em execução no sistema operativo 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 .NET WebAssembly.

Nota

A depuração no Firefox a partir do Visual Studio não é suportada no momento.

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

1. Configure Firefox:
   • Abra about:config em uma nova guia do navegador. Leia e descarte o aviso que aparece.
   • Habilite devtools.debugger.remote-enabled definindo seu valor como True.
   • Habilite devtools.chrome.enabled definindo seu valor como True.
   • Desative devtools.debugger.prompt-connection definindo seu valor como False.
2. Feche todas as instâncias do Firefox.
3. Execute o aplicativo em um shell de comando com dotnet watch (ou dotnet run).
4. Reinicie o navegador Firefox e navegue até o aplicativo.
5. Abra about:debugging em uma nova guia do navegador. Deixe esta guia aberta.
6. Volte para o separador onde a aplicação está a ser executada. Inicie a depuração remota pressionando Shift+Alt+d.
7. Na guia Debugger, abra o arquivo de origem do aplicativo que você deseja depurar no 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 do contador para atingir o ponto de interrupção.
9. Pressione F5 para continuar a execução na guia Depuração.

Interrupção em exceções não tratadas

O depurador não quebra em exceções não tratadas porque Blazor captura exceções que não são tratadas pelo código do desenvolvedor.

Para interromper exceções não tratadas:

• Abra as configurações de exceção do depurador (Debug>Windows>Exception Settings) no Visual Studio.
• Defina as seguintes configurações de de exceções 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 de volta aos seus arquivos de origem originais e são comumente usados para depuração do lado do cliente. No entanto, Blazor atualmente não mapeia C# diretamente para JavaScript/WASM. Em vez disso, Blazor faz a interpretação de IL dentro do 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 no firewall de forma a permitir a comunicação entre o navegador e o processo de 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 orientações de segurança, siga as melhores práticas de segurança e respeite os avisos emitidos pelo fabricante do firewall.

Permitir uma 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.
• Só é recomendado em máquinas de desenvolvedores.

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

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

Solução de problemas

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

• Remova os pontos de interrupção:
  • Google Chrome: na guia do Depurador, abra as ferramentas de desenvolvedor no seu navegador. No console, execute localStorage.clear() para remover quaisquer pontos de interrupção.
  • Microsoft Edge: na guia Application, 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 ASP.NET Core. Para obter mais informações, consulte Impor HTTPS no ASP.NET Core.
• O Visual Studio requer a opção Ativar depuração JavaScript para ASP.NET (Chrome e Edge) no Tools>Options>Debugging>General. Esta é a configuração padrão para Visual Studio. Se a depuração não estiver funcionando, verifique se a opção está marcada.
• Se o seu ambiente usa um proxy HTTP, certifique-se de que 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 para o projeto.
  • No nível de variáveis de ambiente do usuário ou do sistema para que ele 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.
• Certifique-se de que firewalls ou proxies não bloqueiem a comunicação com o proxy de debug (processoNodeJS). Para obter mais informações, consulte a seção de configuração do 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 vida OnInitialized{Async} podem não ser atingidos. Recomendamos 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 numa diretiva de compilação if para garantir que o atraso não esteja presente numa versão final do aplicativo.

OnInitialized:

C#

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

    ...
}

OnInitializedAsync:

C#

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

    ...
}

Tempo limite do Visual Studio (Windows)

Se o Visual Studio lançar uma exceção de que o adaptador de depuração falhou ao iniciar mencionando que o tempo limite foi atingido, você pode ajustar o tempo limite com uma configuração do Registro:

Console

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

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