Depurar aplicativos ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

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 Web Apps 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:

Blazor Server aplicativos 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 navegador em navegadores baseados no Chromium, incluindo Microsoft Edge e Google Chrome.

Os cenários sem suporte para aplicativos 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.
  • Depure em cenários não locais (por exemplo, WSL (Subsistema do Windows para Linux) ou Codespaces do Visual Studio).
  • Usar um servidor de símbolos para depuração.

Blazor Server aplicativos 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 navegador em navegadores baseados no Chromium, incluindo Microsoft Edge e Google Chrome.

Os cenários sem suporte para aplicativos 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.
  • Atingir pontos de interrupção 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.
  • Depure em cenários não locais (por exemplo, WSL (Subsistema do Windows para Linux) ou Codespaces do Visual Studio).
  • Usar um servidor de símbolos para depuração.

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)

A depuração exige a última versão dos seguintes navegadores:

  • Google Chrome (padrão)
  • Microsoft Edge

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:

Kit de Desenvolvimento em C# no Marketplace de Extensões do Visual Studio Code

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

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

Blazor Web Apps :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 Server: 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 UseWebAssemblyDebugging internamente para adicionar o middleware para depuração de aplicativos Blazor WebAssembly dentro das ferramentas de desenvolvedor do Chromium.

Blazor WebAssembly hospedado:

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 Blazor Web App em um IDE

O exemplo nesta seção pressupõe que você criou um Blazor Web App 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. Com o projeto de servidor selecionado no Gerenciador de Soluções, 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. No aplicativo do servidor, abra o componente renderizado Weather estaticamente (Components/Pages/Weather.razor) e defina um ponto de interrupção em qualquer lugar do OnInitializedAsync método.
  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 seja carregado e executado. A execução do aplicativo é interrompida 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 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.

Depurar um aplicativo Blazor Server em um IDE

  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.

Depurar um aplicativo Blazor WebAssembly em um IDE

  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.

Depurar um aplicativo Blazor WebAssembly hospedado em um IDE

  1. Com o projeto Server selecionado no Gerenciador de Soluções, pressione F5 para executar o aplicativo no depurador.

    Ao depurar com um navegador baseado em Chromium, como o Google Chrome ou o Microsoft Edge, uma nova janela do navegador pode ser aberta com um perfil separado para a sessão de depuração, em vez de abrir uma guia em uma janela do navegador existente com o perfil do usuário. Se a depuração com o perfil do usuário for um requisito, adote uma das seguintes abordagens:

  2. No projeto Client, defina um ponto de interrupção na linha currentCount++; no componente Counter (Pages/Counter.razor).

  3. 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.

  4. No Visual Studio, inspecione o valor do campo currentCount na janela Locais.

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

Você também pode depurar o código do servidor no projeto Server:

  1. Defina um ponto de interrupção na página Pages/FetchData.razor em OnInitializedAsync.
  2. Defina um ponto de interrupção em WeatherForecastController no método de ação Get.
  3. Navegue até a página Fetch Data para atingir o primeiro ponto de interrupção no componente FetchData, pouco antes de emitir uma solicitação HTTP para o servidor.
  4. Pressione F5 para continuar a execução e, em seguida, pressione o ponto de interrupção no servidor no WeatherForecastController.
  5. Pressione F5 novamente para permitir que a execução continue e veja a tabela de previsão do tempo renderizada no navegador.

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.

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.

As opções adicionais na tabela a seguir só se aplicam a aplicativos Blazor WebAssembly hospedados .

Opção Descrição
env As variáveis de ambiente a serem fornecidas ao processo iniciado. Aplicável somente se hosted for definido como true.
hosted Deve ser definido como true, se estiver iniciando e depurando um aplicativo Blazor WebAssembly hospedado.
program Uma referência ao executável para executar o servidor do aplicativo hospedado. Deve ser definido se hosted for true.

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 em execução no Windows ou macOS.
  • *Microsoft Edge em 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é 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 watch (ou 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 porque o 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.