Depuración de aplicaciones ASP.NET Core

En este artículo se muestra cómo depurar aplicaciones Blazor, incluida la depuración de aplicaciones Blazor WebAssembly con las herramientas de desarrollo del explorador o un entorno de desarrollo integrado (IDE).

Las aplicaciones web Blazor se pueden depurar en Visual Studio o en Visual Studio Code.

Las aplicaciones Blazor WebAssembly se pueden depurar:

• En Visual Studio o Visual Studio Code.
• Mediante herramientas de desarrollo del explorador en exploradores basados en Chromium, incluidos Edge, Google Chrome, y Firefox.

Entre los escenarios disponibles para la depuración de Blazor WebAssembly se incluyen:

• Establecimiento y eliminación de puntos de interrupción.
• Ejecute la aplicación con compatibilidad de depuración en IDE.
• Examine el código en un solo paso.
• Reanude la ejecución de código con un método abreviado de teclado en IDE.
• En la ventana Variables locales, observe los valores de las variables locales.
• Vea la pila de llamadas, incluidas las cadenas de llamadas entre JavaScript y .NET.
• Use un servidor de símbolos para la depuración, configurado por las preferencias de Visual Studio.

Entre los escenarios no admitidos se incluyen:

• Depure en escenarios no locales; por ejemplo, el Subsistema de Windows para Linux (WSL) o Visual Studio Codespaces.
• Depuración en Firefox desde Visual Studio o Visual Studio Code.

Requisitos previos

En esta sección se explican los requisitos previos para la depuración.

Requisitos previos del usuario

La versión más reciente de los siguientes exploradores:

• Google Chrome
• Microsoft Edge
• Firefox (solo para herramientas de desarrollo del explorador)

Asegúrese de que los firewalls o servidores proxy no bloquean la comunicación con el proxy de depuración (proceso NodeJS). Para más información, vea la sección Configuración de firewall.

Nota:

Apple Safari en macOS no se admite actualmente.

Requisitos previos del IDE

Se requiere la versión más reciente de Visual Studio o Visual Studio Code.

Requisitos previos de Visual Studio Code

Visual Studio Code requiere el Kit de desarrollo de C# para Visual Studio Code (Cómo empezar con C# en VS Code). En Marketplace de extensiones de Visual Studio Code, filtre la lista de extensiones con "c# dev kit" para buscar la extensión:

La instalación del Kit de desarrollo de C# instala automáticamente las siguientes extensiones adicionales:

• Herramienta de instalación de .NET
• C#
• IntelliCode para el kit de desarrollo de C#

Si encuentra advertencias o errores, puede abrir una incidencia (microsoft/vscode-dotnettools repositorio de GitHub) describiendo el problema.

Requisitos previos de configuración de aplicaciones

La guía de esta subsección se aplica a la depuración del lado cliente.

Abra el archivo Properties/launchSettings.json del proyecto de inicio. Confirme la presencia de la siguiente propiedad inspectUri en cada perfil de inicio del nodo profiles del archivo. Si la propiedad siguiente no está presente, agréguela a cada perfil:

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

La propiedad inspectUri:

• Permite que el IDE detecte que la aplicación es una aplicación Blazor.
• Indica a la infraestructura de depuración de scripts que se conecte al explorador a través del proxy de depuración de Blazor.

El marco de trabajo proporciona los valores de marcador de posición para el protocolo WebSocket (wsProtocol), el host (url.hostname), el puerto (url.port) y el identificador URI del inspector en el explorador iniciado (browserInspectUri).

Paquetes

Aplicaciones web Blazor: Microsoft.AspNetCore.Components.WebAssembly.Server: hace referencia a un paquete interno (Microsoft.NETCore.BrowserDebugHost.Transport) para ensamblados que comparten el host de depuración del explorador.

Blazor WebAssembly independiente: Microsoft.AspNetCore.Components.WebAssembly.DevServer: servidor de desarrollo para su uso al crear aplicaciones Blazor. Llama a WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internamente a para agregar middleware para depurar aplicaciones Blazor WebAssembly dentro de las herramientas de desarrollo de Chromium.

Nota:

Para obtener instrucciones sobre cómo agregar paquetes a aplicaciones .NET, consulte los artículos de Instalación y administración de paquetes en Flujo de trabajo de consumo de paquetes (NuGet documentación). Confirme las versiones correctas del paquete en NuGet.org.

Depuración de una aplicación web Blazor en un IDE

Visual Studio

En el ejemplo de esta sección se supone que ha creado una aplicación web Blazor con un modo de representación interactivo de Auto (Servidor y WebAssembly) y la ubicación de interactividad por componente.

1. Abra la aplicación.
2. Establezca un punto de interrupción en la línea currentCount++; del componente Counter (Pages/Counter.razor) del proyecto de cliente (.Client).
3. Presione F5 para ejecutar la aplicación en el depurador.
4. En el explorador, vaya a la página Counter en /counter. Espere unos segundos para que el proxy de depuración se cargue y ejecute. Seleccione el botón Haga clic en mí para alcanzar el punto de interrupción.
5. En Visual Studio, revise el valor del campo currentCount en la ventana Variables locales.
6. Presione F5 para continuar la ejecución.

Los puntos de interrupción también se pueden alcanzar en el proyecto de servidor en componentes del lado servidor representados de forma estática e interactiva.

1. Detén el depurador.

2. Agregue el siguiente componente a la aplicación de servidor. El componente aplica el modo de representación del servidor interactivo (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. Establezca un punto de interrupción en la línea currentCount++; del componente Counter2.

4. Presione F5 para ejecutar la aplicación en el depurador.

5. En el explorador, vaya a la página Counter2 en /counter-2. Espere unos segundos para que el proxy de depuración se cargue y ejecute. Seleccione el botón Haga clic en mí para alcanzar el punto de interrupción.

6. Presione F5 para continuar la ejecución.

Los puntos de interrupción no se alcanzan durante el inicio de la aplicación antes de que se ejecute el proxy de depuración. Esto incluye los puntos de interrupción del archivo Program y los de los OnInitialized{Async} métodos de ciclo de vida de los componentes que se cargan según la primera página solicitada por la aplicación.

Visual Studio Code

En el ejemplo de esta sección se supone que ha creado una aplicación web Blazor con un modo de representación interactivo de Auto (Servidor y WebAssembly) y la ubicación de interactividad por componente.

1. Abra la aplicación en Visual Studio Code abriendo la carpeta de la solución, que es la carpeta que contiene el servidor y las carpetas del proyecto de .Client.
2. Establezca un punto de interrupción en la línea currentCount++; del componente Counter (Pages/Counter.razor) del proyecto de cliente (.Client).
3. Abra el panel Ejecutar y depurar y seleccione el botón Ejecutar y depurar. Como alternativa, presione F5 (Iniciar depuración). Seleccione el depurador C# en la paleta de comandos de la parte superior de la interfaz de usuario. Seleccione el perfil predeterminado para el proyecto de servidor (por ejemplo, C#:BlazorSample [Default Configuration]).
4. En el explorador, vaya a la página Counter en /counter. Espere unos segundos para que el proxy de depuración se cargue y ejecute. Seleccione el botón Haga clic en mí para alcanzar el punto de interrupción.
5. Seleccione el botón Continuar de la interfaz de usuario o presione F5 (Continuar) para continuar la ejecución.

Los puntos de interrupción también se pueden alcanzar en el proyecto de servidor.

1. Detenga la depuración seleccionando el botón Detener o presione Mayús+F5 en el teclado.

2. Agregue el siguiente componente a la aplicación de servidor. El componente adopta el modo de representación del servidor interactivo (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. Establezca un punto de interrupción en la línea currentCount++; del componente Counter2.

4. Seleccione el botón Iniciar depuración en la interfaz de usuario o presione F5 (Iniciar depuración) para ejecutar la aplicación en el depurador.

5. En el explorador, vaya a la página Counter2 en /counter-2. Espere unos segundos para que el proxy de depuración se cargue y ejecute. Seleccione el botón Haga clic en mí para alcanzar el punto de interrupción.

6. Seleccione el botón Continuar de la interfaz de usuario o presione F5 (Continuar) para continuar la ejecución.

Los puntos de interrupción no se alcanzan durante el inicio de la aplicación antes de que se ejecute el proxy de depuración. Esto incluye los puntos de interrupción del archivo Program y los de los OnInitialized{Async} métodos de ciclo de vida de los componentes que se cargan según la primera página solicitada por la aplicación.

No admite Iniciar sin depuración (Ctrl+F5 [Windows] o ⌘+F5 [macOS]). Cuando la aplicación se ejecuta en la configuración de depuración, la sobrecarga de depuración siempre genera una pequeña reducción del rendimiento.

Depuración de una aplicación Blazor WebAssembly en un IDE

Visual Studio

1. Abra la aplicación.
2. Establezca un punto de interrupción en la línea currentCount++; del componente Counter (Pages/Counter.razor).
3. Presione F5 para ejecutar la aplicación en el depurador.
4. En el explorador, vaya a la página Counter en /counter. Espere unos segundos para que el proxy de depuración se cargue y ejecute. Seleccione el botón Haga clic en mí para alcanzar el punto de interrupción.
5. En Visual Studio, revise el valor del campo currentCount en la ventana Variables locales.
6. Presione F5 para continuar la ejecución.

Los puntos de interrupción no se alcanzan durante el inicio de la aplicación antes de que se ejecute el proxy de depuración. Esto incluye los puntos de interrupción del archivo Program y los de los OnInitialized{Async} métodos de ciclo de vida de los componentes que se cargan según la primera página solicitada por la aplicación.

Visual Studio Code

1. Abra la carpeta de la aplicación en Visual Studio Code.
2. Establezca un punto de interrupción en la línea currentCount++; del componente Counter (Pages/Counter.razor).
3. Abra el panel Ejecutar y depurar y seleccione el botón Ejecutar y depurar. Como alternativa, presione F5 (Iniciar depuración). Seleccione el depurador C# en la paleta de comandos de la parte superior de la interfaz de usuario. Seleccione el perfil predeterminado (por ejemplo, C#:BlazorSample [Default Configuration]).
4. Presione F5 para ejecutar la aplicación en el depurador.
5. Se inicia la aplicación independiente y se abre un explorador de depuración.
6. En el explorador, vaya a la página Counter en /counter. Espere unos segundos para que el proxy de depuración se cargue y ejecute. Seleccione el botón Haga clic en mí para alcanzar el punto de interrupción.
7. Presione F5 para continuar la ejecución.

Los puntos de interrupción no se alcanzan durante el inicio de la aplicación antes de que se ejecute el proxy de depuración. Esto incluye los puntos de interrupción del archivo Program y los de los OnInitialized{Async} métodos de ciclo de vida de los componentes que se cargan según la primera página solicitada por la aplicación.

No admite Iniciar sin depuración (Ctrl+F5 [Windows] o ⌘+F5 [macOS]). Cuando la aplicación se ejecuta en la configuración de depuración, la sobrecarga de depuración siempre genera una pequeña reducción del rendimiento.

compatibilidad con el depurador

La depuración está habilitada para el tiempo de ejecución cuando la compatibilidad con el depurador está habilitada con <DebuggerSupport>{VALUE}</DebuggerSupport>, donde el marcador de posición {VALUE} es true o false.

De manera predeterminada, el marco Blazordeshabilita la compatibilidad con el depurador para todas las configuraciones que no son de depuración. A fin de habilitar la compatibilidad del depurador para una configuración que no es de depuración, agregue una propiedad <DebuggerSupport> al archivo del proyecto de la aplicación.

En el ejemplo siguiente, la compatibilidad con el depurador está habilitada para la configuración personalizada "DebugCustom":

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

Para más información, vea Configuración del depurador personalizado Blazor WebAssembly (dotnet/runtime nº 96239).

Asociación a una sesión de depuración de Visual Studio Code existente

Para asociar a una aplicación Blazor en ejecución, abra el archivo .vscode/launch.json y reemplace el marcador de posición {URL} por la dirección URL donde se ejecuta la aplicación:

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

Opciones de inicio de Visual Studio Code

Las opciones de configuración de inicio de la siguiente tabla son compatibles con el tipo de depuración blazorwasm (.vscode/launch.json).

Opción	Descripción
browser	El explorador que se va a iniciar para la sesión de depuración. Se establece en edge o chrome. Tiene como valor predeterminado edge.
cwd	El directorio de trabajo en el que se va a iniciar la aplicación.
request	Use launch para iniciar y adjuntar una sesión de depuración a una aplicación Blazor WebAssembly o attach para adjuntar una sesión de depuración a una aplicación que ya está en ejecución.
timeout	El número de milisegundos que se esperarán para adjuntar la sesión de depuración. El valor predeterminado es 30 000 milisegundos (30 segundos).
trace	Se usa para generar registros desde el depurador de JS. Se establece en true para generar registros.
url	La dirección URL que se va a abrir en el explorador durante la depuración.
webRoot	Especifica la ruta de acceso absoluta del servidor web. Se debe establecer si una aplicación se envía desde una subruta.

Depuración de Blazor WebAssembly con Google Chrome o Microsoft Edge

Las instrucciones de esta sección se aplican a la depuración de aplicaciones Blazor WebAssembly en:

• Google Chrome que se ejecuta en Windows o macOS.
• Microsoft Edge que se ejecuta en Windows.

1. Ejecute la aplicación en un shell de comandos con dotnet run.

2. Inicie un explorador y vaya a la dirección URL de la aplicación.

3. Para iniciar la depuración remota, presione:

   • Mayús+Alt+d en Windows.
   • Mayús+⌘+d en macOS.

   El explorador debe ejecutarse con la depuración remota habilitada, lo cual no es el valor predeterminado. Si la depuración remota está deshabilitada, aparece una página de error que informa de que no se puede encontrar la pestaña del explorador depurable con instrucciones para iniciar el explorador con el puerto de depuración abierto. Siga las instrucciones del explorador.

   Después de seguir las instrucciones para habilitar la depuración remota, la aplicación se abre en una nueva ventana del explorador. Inicie la depuración remota presionando la combinación HotKey en la nueva ventana del explorador:

   • Mayús+Alt+d en Windows.
   • Mayús+⌘+d en macOS.

   Se abre una nueva ventana del explorador de herramientas de desarrollo que muestra una imagen fantasma de la aplicación.

   Nota:

   Si ha seguido las instrucciones para abrir una nueva pestaña del explorador con la depuración remota habilitada, puede cerrar la ventana original del explorador, dejando abierta la segunda ventana con la primera pestaña que ejecuta la aplicación y la segunda pestaña que ejecuta el depurador.

4. Tras unos instantes, en la pestaña Orígenes se mostrará una lista de los ensamblados .NET y páginas de la aplicación.

5. Abre el nodo file://. En el código de componente (archivos .razor) y archivos de código de C# (.cs), los puntos de interrupción que establezca se alcanzan cuando el código se ejecuta en la pestaña del explorador de la aplicación (la pestaña inicial abierta después de iniciar la depuración remota). Después de alcanzar un punto de interrupción, recorra el código paso a paso (F10) o reanude (F8) la ejecución del código normalmente en la pestaña de depuración.

En la depuración del explorador basado en Chromium, Blazor proporciona un proxy de depuración que implementa el protocolo Chrome DevTools y aumenta el protocolo con información específica de .NET. Cuando se presiona el método abreviado de teclado de depuración, Blazor apunta a Chrome DevTools en el proxy. El proxy se conecta a la ventana del explorador que se quiere depurar (de ahí la necesidad de habilitar la depuración remota).

Depuración de una aplicación Blazor WebAssembly con Firefox

Las instrucciones de esta sección se aplican a la depuración de aplicaciones Blazor WebAssembly en una instancia de Firefox que se ejecuta en Windows.

La depuración de una aplicación Blazor WebAssembly con Firefox requiere configurar el explorador para la depuración remota y conectarse al explorador mediante las herramientas de desarrollo del explorador a través del proxy de depuración WebAssembly de .NET.

Nota:

La depuración en Firefox desde Visual Studio no se admite en este momento.

Para depurar una aplicación Blazor WebAssembly en Firefox durante el desarrollo:

1. Configurar Firefox:
   • Abra about:config en una nueva pestaña del explorador. Lea y descarte la advertencia que aparece.
   • Habilite devtools.debugger.remote-enabled estableciendo su valor en True.
   • Habilite devtools.chrome.enabled estableciendo su valor en True.
   • Deshabilite estableciendo devtools.debugger.prompt-connection su valor en False.
2. Cierre todas las instancias de Firefox.
3. Ejecute la aplicación en un shell de comandos con dotnet run.
4. Vuelva a iniciar el explorador Firefox y vaya a la aplicación.
5. Abra about:debugging en una nueva pestaña del explorador. Deje esta pestaña abierta.
6. Vuelva a la pestaña donde se ejecuta la aplicación. Inicie la depuración remota presionando Mayús+Alt+d.
7. En la pestaña Debugger, abra el archivo de código fuente de la aplicación que desea depurar en el nodo file:// y establezca un punto de interrupción. Por ejemplo, establezca un punto de interrupción en la línea currentCount++; del método IncrementCount del componente Counter (Pages/Counter.razor).
8. Navegue hasta la página del componente Counter (/counter) en la pestaña del navegador de la aplicación y seleccione el botón del contador para alcanzar el punto de interrupción.
9. Presione F5 para continuar la ejecución en la pestaña depuración.

Interrumpir las operaciones ante excepciones no controladas

El depurador no se interrumpe en excepciones no controladas de forma predeterminada porque Blazor detecta excepciones no controladas por código de desarrollador.

Interrumpir las operaciones ante excepciones no controladas:

• Abra la configuración de excepciones del depurador (Depurar>Windows>Configuración de excepciones) en Visual Studio.
• Establezca la siguiente configuración de excepciones de JavaScript:
  • Todas las excepciones
  • Excepciones no detectadas

Mapas de origen del explorador

Los mapas de origen del explorador permiten al explorador volver a asignar los archivos compilados a sus archivos de código fuente originales y se suelen usar para la depuración del lado cliente. Sin embargo, en la actualidad Blazor no asigna C# directamente a JavaScript o WASM. En su lugar, Blazor realiza la interpretación de IL en el explorador, por lo que los mapas de origen no son pertinentes.

Configuración de firewall

Si un firewall bloquea la comunicación con el proxy de depuración, cree una regla de excepción de firewall que permita la comunicación entre el explorador y el proceso NodeJS.

Advertencia

La modificación de una configuración de firewall debe realizarse con cuidado para evitar la creación de vulnerabilidades de seguridad. Aplique con cuidado las instrucciones de seguridad, siga las recomendaciones de seguridad y respete las advertencias realizadas por el fabricante del firewall.

Permitir la comunicación abierta con el proceso NodeJS:

• Abre el servidor de Node en cualquier conexión, en función de la configuración y las funcionalidades del firewall.
• Podría ser arriesgado en función de la red.
• Solo se recomienda en los equipos de los desarrolladores.

Si es posible, permita solo la comunicación abierta con el proceso NodeJSen redes privadas o de confianza.

Para obtener instrucciones de configuración del Firewall de Windows, vea Crear una regla de programa o servicio de entrada. Para más información, vea Firewall de Windows Defender con seguridad avanzada y los artículos relacionados en la serie de documentos sobre el Firewall de Windows.

Solucionar problemas

Si se encuentra con errores, las sugerencias siguientes pueden ser útiles:

• Elimine los puntos de interrupción:
  • Google Chrome: en la pestaña Depurador, abra las herramientas de desarrollo del explorador. En la consola, ejecute localStorage.clear() para quitar los puntos de interrupción.
  • Microsoft Edge: en la pestaña Aplicación, abra almacenamiento local. Haga clic con el botón derecho en el sitio y seleccione Borrar.
• Confirme que instaló el certificado de desarrollo HTTPS de ASP.NET Core y que es de confianza. Para más información, vea Aplicación de HTTPS en ASP.NET Core.
• Visual Studio requiere la opción Habilitar depuración de JavaScript para ASP.NET (Chrome y Edge), en Herramientas>Opciones>Depuración>General. Es el valor predeterminado para Visual Studio. Si la depuración no funciona, confirme que la opción está seleccionada.
• Si su entorno usa un proxy HTTP, asegúrese de que localhost esté incluido en la configuración de omisión del proxy. Esto puede hacerse al establecer la variable de entorno NO_PROXY en alguna de las siguientes opciones:
  • Archivo launchSettings.json del proyecto.
  • En el nivel de usuario o de entorno del sistema para que se aplique a todas las aplicaciones. Si usa una variable de entorno, reinicie Visual Studio para que el cambio surta efecto.
• Asegúrese de que los firewalls o servidores proxy no bloquean la comunicación con el proxy de depuración (proceso NodeJS). Para más información, vea la sección Configuración de firewall.

Puntos de interrupción de OnInitialized{Async} no ejecutados

El proxy de depuración del marco de Blazor no se inicia instantáneamente al iniciarse la aplicación, por lo que es posible que no se alcancen los puntos de interrupción de los métodos de ciclo de vida de OnInitialized{Async}. Se recomienda agregar un retraso al principio del cuerpo del método para dar al proxy de depuración un tiempo para que se inicie antes de que se ejecute el punto de interrupción. Puede incluir el retraso según una directiva de compilador if para asegurarse de que el retraso no está presente en una compilación de versión de la aplicación.

OnInitialized:

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

    ...
}

OnInitializedAsync:

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

    ...
}

Tiempo de espera de Visual Studio (Windows)

Si Visual Studio inicia una excepción relacionada con que el adaptador de depuración no ha podido iniciarse en la que se menciona que se ha alcanzado el tiempo de espera, puede ajustar el tiempo de espera con una configuración del Registro:

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

El marcador de posición {TIMEOUT} del comando anterior se expresa en milisegundos. Por ejemplo, un minuto se asigna como 60000.