Déboguer des applications ASP.NET Core

Cet article décrit comment déboguer Blazor des applications, y compris le débogage d’applications Blazor WebAssembly avec des outils de navigateur et un environnement de développement intégré (IDE).

Vous pouvez déboguer les Blazor Web App dans Visual Studio ou Visual Studio Code.

Les applications Blazor WebAssembly peuvent être déboguées :

• Dans Visual Studio ou Visual Studio Code.
• À l’aide des outils de développement de navigateur dans les navigateurs basés sur Chromium, notamment Microsoft Edge, Google Chrome et Firefox.

Les scénarios disponibles pour le débogage Blazor WebAssembly incluent :

• Définissez et supprimez des points d’arrêt.
• Exécutez l’application avec prise en charge du débogage dans les IDE.
• Pas à pas dans le code.
• Reprendre l’exécution du code avec un raccourci clavier dans les IDE.
• Dans la fenêtre Locales, observez les valeurs des variables locales.
• Consultez la pile d’appels, y compris les chaînes d’appels entre JavaScript et .NET.
• Utilisez un serveur de symboles pour le débogage, configuré par les préférences de Visual Studio.

Les scénarios non pris en charge incluent :

• Déboguer dans des scénarios non locaux (par exemple, Sous-système Windows pour Linux (WSL) ou Visual Studio Codespaces).
• Déboguer dans Firefox à partir de Visual Studio ou Visual Studio Code.

Prérequis

Cette section décrit les prérequis pour le débogage.

Prérequis relatifs au navigateur

Vous devez disposer de la dernière version des navigateurs suivants :

• Google Chrome
• Microsoft Edge
• Firefox (outils de développement du navigateur uniquement)

Assurez-vous que les pare-feu ou les proxys ne bloquent pas la communication avec le proxy de débogage (NodeJS processus). Pour plus d’informations, consultez la section Configuration du pare-feu.

Remarque

Apple Safari sur macOS n’est actuellement pas pris en charge.

Prérequis relatifs à l’IDE

Vous devez disposer de la dernière version de Visual Studio ou de Visual Studio Code.

Conditions préalables pour Visual Studio Code

Visual Studio Code nécessite le kit de développement C# pour Visual Studio Code (Prise en main de C# dans VS Code). Dans la Place de marché des extensions de Visual Studio Code, filtrez la liste des extensions avec « c# dev kit » pour localiser l’extension :

L’installation du kit de développement C# installe automatiquement les extensions supplémentaires suivantes :

• .NET Install Tool (Outil d’installation .NET)
• C#
• IntelliCode for C# Dev Kit (Kit de développement IntelliCode pour C#)

Si vous rencontrez des avertissements ou des erreurs, vous pouvez créer un problème (microsoft/vscode-dotnettoolsréférentiel GitHub) et les décrire.

Conditions préalables à la configuration des applications

L’aide contenue dans cette sous-section s’applique au débogage côté client.

Ouvrez le fichierProperties/launchSettings.json du projet de démarrage. Vérifiez la présence de la propriété inspectUri suivante dans chaque profil de lancement du nœudprofilesdu fichier. Si la propriété suivante n’est pas présente, ajoutez-la à chaque profil :

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

La propriété inspectUri :

• Permet à l’IDE de détecter que l’application est une application Blazor.
• Indique à l’infrastructure de débogage de script de se connecter au navigateur via le proxy de débogage de Blazor.

Les valeurs d’espace réservé pour le protocole WebSocket (wsProtocol), l’hôte (url.hostname), le port (url.port) et l’URI de l’inspecteur sur le navigateur lancé (browserInspectUri) sont fournies par l’infrastructure.

Paquets

Blazor Web App : Microsoft.AspNetCore.Components.WebAssembly.Server : référence un package interne (Microsoft.NETCore.BrowserDebugHost.Transport) pour les assemblys qui partagent l’hôte de débogage du navigateur.

Blazor WebAssembly autonome : Microsoft.AspNetCore.Components.WebAssembly.DevServer : serveur de développement à utiliser lors de la création d’applications Blazor. Appelle UseWebAssemblyDebugging en interne pour ajouter un intergiciel (middleware) pour le débogage d’applications Blazor WebAssembly dans Chromium outils de développement.

Remarque

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions du package sur NuGet.org.

Déboguer une application Blazor Web App dans un IDE

Visual Studio

L’exemple de cette section suppose que vous avez créé une application Blazor Web App avec le mode de rendu interactif Auto (Serveur et WebAssembly) et un emplacement d’interactivité par composant.

1. Ouvrez l’application.
2. Définissez un point d’arrêt sur la ligne currentCount++; dans le Counter composant (Pages/Counter.razor) du projet client (.Client).
3. Avec le projet de serveur sélectionné dans Explorateur de solutions, appuyez sur F5 pour exécuter l’application dans le débogueur.
4. Dans le navigateur, accédez à la page Counter à/counter. Attendez quelques secondes pour que le proxy de débogage se charge et s’exécute. Sélectionnez la touche Cliquer sur moi pour atteindre le point d’arrêt.
5. Dans Visual Studio, inspectez la valeur du champ currentCount dans la fenêtre Locales .
6. Appuyez sur F5 pour poursuivre l’exécution.

Il est également possible que des points d’arrêt soient atteints dans le projet serveur dans les composants côté serveur rendus de manière statique et interactive.

1. Arrêtez le débogueur.
2. Dans l’application serveur, ouvrez le composant rendu Weather statiquement (Components/Pages/Weather.razor) et définissez un point d’arrêt n’importe où dans la OnInitializedAsync méthode.
3. Appuyez sur la touche F5 pour exécuter l’application dans le débogueur.
4. Dans le navigateur, accédez à la page Weather à/weather. Attendez quelques secondes pour que le proxy de débogage se charge et s’exécute. L’exécution de l’application s’arrête au point d’arrêt.
5. Appuyez sur F5 pour poursuivre l’exécution.

Les points d’arrêt ne sont pas atteints au démarrage de l’application avant l’exécution du proxy de débogage. Cela inclut les points d’arrêt dans le fichier Program et les points d’arrêt dans les OnInitialized{Async} méthodes de cycle de vie des composants chargés par la première page demandée à partir de l’application.

Visual Studio Code

L’exemple de cette section suppose que vous avez créé une application Blazor Web App avec un mode de rendu Auto interactif (Serveur et WebAssembly) et un emplacement d’interactivité par composant.

1. Ouvrez l’application dans Visual Studio Code en ouvrant le dossier de la solution, celui-ci contenant les dossiers des projets .Client et serveur.
2. Définissez un point d’arrêt sur la ligne currentCount++; dans le Counter composant (Pages/Counter.razor) du projet client (.Client).
3. Ouvrez le volet Exécuter et déboguer, puis sélectionnez le bouton Exécuter et déboguer. Vous pouvez également appuyer sur F5 (Démarrer le débogage). Sélectionnez le débogueur C# dans la palette de commandes située en haut de l’interface utilisateur. Sélectionnez le profil par défaut pour le projet serveur (par exemple, C#:BlazorSample [Default Configuration]).
4. Dans le navigateur, accédez à la page Counter à/counter. Attendez quelques secondes pour que le proxy de débogage se charge et s’exécute. Sélectionnez la touche Cliquer sur moi pour atteindre le point d’arrêt.
5. Sélectionnez le bouton Continuer dans l’interface utilisateur ou appuyez sur F5 (Continuer) pour poursuivre l’exécution.

Les points d’arrêt peuvent également être atteints dans le projet de serveur.

1. Arrêtez le débogage en sélectionnant le bouton Arrêter ou en appuyant sur Maj+F5 sur le clavier.
2. Dans l’application serveur, ouvrez le composant rendu Weather statiquement (Components/Pages/Weather.razor) et définissez un point d’arrêt n’importe où dans la OnInitializedAsync méthode.
3. Sélectionnez le bouton Démarrer le débogage dans l’interface utilisateur ou appuyez sur F5 (Démarrer le débogage) pour exécuter l’application dans le débogueur.
4. Dans le navigateur, accédez à la page Weather à/weather. Attendez quelques secondes pour que le proxy de débogage se charge et s’exécute. L’exécution de l’application s’arrête au point d’arrêt.
5. Sélectionnez le bouton Continuer dans l’interface utilisateur ou appuyez sur F5 (Continuer) pour poursuivre l’exécution.

Les points d’arrêt ne sont pas atteints au démarrage de l’application avant l’exécution du proxy de débogage. Cela inclut les points d’arrêt dans le fichier Program et les points d’arrêt dans les OnInitialized{Async} méthodes de cycle de vie des composants chargés par la première page demandée à partir de l’application.

Démarrer sans débogage [Ctrl+F5 (Windows) ou ⌘+F5 (macOS)] n’est pas pris en charge. Lorsque l’application est exécutée dans la configuration Débogage, la surcharge de débogage entraîne toujours une légère réduction des performances.

Déboguer une application Blazor WebAssembly dans un IDE

Visual Studio

1. Ouvrez l’application.
2. Définissez un point d'arrêt sur la ligne currentCount++; dans le Counter composant (Pages/Counter.razor).
3. Appuyez sur la touche F5 pour exécuter l’application dans le débogueur.
4. Dans le navigateur, accédez à la page Counter à/counter. Attendez quelques secondes pour que le proxy de débogage se charge et s’exécute. Sélectionnez la touche Cliquer sur moi pour atteindre le point d’arrêt.
5. Dans Visual Studio, inspectez la valeur du champ currentCount dans la fenêtre Locales .
6. Appuyez sur F5 pour poursuivre l’exécution.

Les points d’arrêt ne sont pas atteints au démarrage de l’application avant l’exécution du proxy de débogage. Cela inclut les points d’arrêt dans le fichier Program et les points d’arrêt dans les OnInitialized{Async} méthodes de cycle de vie des composants chargés par la première page demandée à partir de l’application.

Visual Studio Code

1. Ouvrez le dossier de l’application dans Visual Studio Code.
2. Définissez un point d'arrêt sur la ligne currentCount++; dans le Counter composant (Pages/Counter.razor).
3. Ouvrez le volet Exécuter et déboguer, puis sélectionnez le bouton Exécuter et déboguer. Vous pouvez également appuyer sur F5 (Démarrer le débogage). Sélectionnez le débogueur C# dans la palette de commandes située en haut de l’interface utilisateur. Sélectionnez le profil par défaut (par exemple, C#:BlazorSample [Default Configuration]).
4. Appuyez sur la touche F5 pour exécuter l’application dans le débogueur.
5. L’application autonome est lancée et un navigateur de débogage est ouvert.
6. Dans le navigateur, accédez à la page Counter à/counter. Attendez quelques secondes pour que le proxy de débogage se charge et s’exécute. Sélectionnez la touche Cliquer sur moi pour atteindre le point d’arrêt.
7. Appuyez sur F5 pour poursuivre l’exécution.

Les points d’arrêt ne sont pas atteints au démarrage de l’application avant l’exécution du proxy de débogage. Cela inclut les points d’arrêt dans le fichier Program et les points d’arrêt dans les OnInitialized{Async} méthodes de cycle de vie des composants chargés par la première page demandée à partir de l’application.

Démarrer sans débogage [Ctrl+F5 (Windows) ou ⌘+F5 (macOS)] n’est pas pris en charge. Lorsque l’application est exécutée dans la configuration Débogage, la surcharge de débogage entraîne toujours une légère réduction des performances.

Joindre à une session de débogage Visual Studio Code existante

Pour joindre une application Blazor en cours d’exécution, ouvrez le fichier .vscode/launch.json et remplacez l’espace réservé {URL} par l’URL où l’application est en cours d’exécution :

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

Options de lancement de Visual Studio Code

Les options de configuration de lancement dans le tableau suivant sont prises en charge pour le type de débogage blazorwasm (.vscode/launch.json).

Option	Description
browser	Navigateur à lancer pour la session de débogage. Définissez edge sur chrome. La valeur par défaut est edge.
cwd	Répertoire de travail sous lequel lancer l’application.
request	Utilisez launch pour lancer et attacher une session de débogage à une application Blazor WebAssembly ou attach pour attacher une session de débogage à une application déjà en cours d’exécution.
timeout	Nombre de millisecondes à attendre pour que la session de débogage soit attachée. La valeur par défaut est de 30 000 millisecondes (30 secondes).
trace	Utilisé pour générer des journaux à partir du débogueur JS. Définissez sur true pour générer des journaux.
url	URL à ouvrir dans le navigateur lors du débogage.
webRoot	Spécifie le chemin absolu du serveur web. Doit être défini si une application est servie à partir d’un sous-itinéraire.

Déboguer Blazor WebAssembly avec Google Chrome ou Microsoft Edge

Les conseils de cette section s’appliquent aux applications de débogage Blazor WebAssembly dans :

• Google Chrome s’exécute sur Windows ou macOS.
• *Microsoft Edge s’exécutant sur Windows.

1. Utilisez l’application dans un interpréteur de commandes avec dotnet watch (ou dotnet run).

2. Lancez un navigateur et accédez à l’URL de l’application.

3. Démarrez le débogage à distance en appuyant sur:

   • Maj+Alt+d sur Windows.
   • Shift+⌘+d sur macOS.

   Le navigateur doit être en cours d’exécution avec le débogage à distance activé, ce qui n’est pas la valeur par défaut. Si le débogage à distance est désactivé, une page d’erreur Impossible de trouver l’onglet de navigateur pouvant être déboguée est affichée avec des instructions pour lancer le navigateur avec le port de débogage ouvert. Suivez les instructions de votre navigateur.

   Une fois que vous avez suivi les instructions pour activer le débogage à distance, l’application s’ouvre dans une nouvelle fenêtre de navigateur. Démarrez le débogage à distance en appuyant sur la combinaison de touches d’accès rapide dans la nouvelle fenêtre du navigateur :

   • Maj+Alt+d sur Windows.
   • Shift+⌘+d sur macOS.

   L’onglet du navigateur des outils de développement s’ouvre dans une nouvelle fenêtre et affiche une image fantôme de l’application.

   Remarque

   Si vous avez suivi les instructions pour ouvrir un nouvel onglet de navigateur avec le débogage à distance activé, vous pouvez fermer la fenêtre du navigateur d’origine pour ne garder que la deuxième fenêtre ouverte, celle-ci exécutant l’application sous le premier onglet et le débogueur sous le deuxième.

4. Après un instant, l’onglet Sources affiche une liste des assemblys .NET et des pages de l’application.

5. Ouvrez le nœud file://. Dans le code du composant (fichiers .razor) et les fichiers de code C# (.cs), les points d’arrêt que vous définissez sont atteints lorsque le code s’exécute sous l’onglet du navigateur de l’application (l’onglet initial ouvert après le démarrage du débogage à distance). Une fois qu’un point d’arrêt est atteint, exécutez pas à pas le code (F10) ou reprenez normalement l’exécution du code sous l’onglet de débogage (F8).

Pour le débogage de navigateurs basés sur Chromium, Blazor fournit un proxy de débogage qui implémente le protocole Chrome DevTools et augmente le protocole avec .NET Informations spécifiques. Lorsque vous appuyez sur le raccourci clavier du débogage, Blazor pointe Chrome DevTools vers le proxy. Le proxy se connecte à la fenêtre de navigateur que vous souhaitez déboguer (d’où la nécessité d’activer le débogage à distance).

Déboguer une application Blazor WebAssembly avec Firefox

Les conseils de cette section s’appliquent aux applications de débogage Blazor WebAssembly dans Firefox sur Windows.

Le débogage d’une application Blazor WebAssembly avec Firefox nécessite la configuration du navigateur pour le débogage à distance et la connexion au navigateur à l’aide des outils de développement de celui-ci via le proxy de débogage WebAssembly .NET.

Remarque

Le débogage dans Firefox à partir de Visual Studio n’est pas pris en charge pour le moment.

Voici comment déboguer une application Blazor WebAssembly dans Firefox pendant le développement :

1. Configurez Firefox :
   • Ouvrir about:config dans un nouvel onglet de navigateur. Lisez et ignorez l’avertissement qui s’affiche.
   • Activez devtools.debugger.remote-enabled en définissant sa valeur sur True.
   • Activez devtools.chrome.enabled en définissant sa valeur sur True.
   • Désactivez devtools.debugger.prompt-connection en définissant sa valeur sur False.
2. Fermez toutes les instances Firefox.
3. Utilisez l’application dans un interpréteur de commandes avec dotnet watch (ou dotnet run).
4. Relancez le navigateur Firefox et accédez à l’application.
5. Ouvrir about:debugging dans un nouvel onglet de navigateur. Laissez cet onglet ouvert.
6. Revenez à l’onglet où l’application est en cours d’exécution. Démarrez le débogage à distance en appuyant sur Maj+Alt+d.
7. Dans l’onglet Debugger, ouvrez le fichier source de l’application que vous souhaitez déboguer sous le nœud file:// et définissez un point d’arrêt. Par exemple, définissez un point d’arrêt sur la ligne currentCount++; dans la méthode IncrementCount du composant Counter (Pages/Counter.razor).
8. Accédez à la page du composant Counter (/counter) sous l’onglet du navigateur de l’application et sélectionnez le bouton compteur pour atteindre le point d’arrêt.
9. Appuyez sur F5 pour poursuivre l’exécution sous l’onglet de débogage.

Arrêter sur les exceptions non gérées

Le débogueur ne s’arrête pas sur les exceptions non gérées, car Blazor intercepte les exceptions qui ne sont pas gérées par le code du développeur.

Pour arrêter sur les exceptions non gérées :

• Ouvrez les paramètres d’exception du débogueur (Déboguer>Fenêtres>Paramètres d’exception) dans Visual Studio.
• Définissez les paramètres Exceptions JavaScript suivants :
  • Toutes les exceptions
  • Exceptions non interceptées

Cartes sources de navigateur

Les cartes sources du navigateur permettent au navigateur de mapper les fichiers compilés à leurs fichiers sources d’origine et sont couramment utilisées pour le débogage côté client. Toutefois, Blazor ne mappe pas C# directement à JavaScript/WASM. Au lieu de cela, Blazor effectue l’interprétation de l’IL dans le navigateur, de sorte que les mappages sources ne sont pas pertinents.

Configuration du pare-feu

Si un pare-feu bloque la communication avec le proxy de débogage, créez une règle d’exception de pare-feu qui autorise la communication entre le navigateur et le processus NodeJS.

Avertissement

La modification d’une configuration de pare-feu doit être effectuée avec précaution pour éviter de créer des failles de sécurité. Appliquez soigneusement les conseils de sécurité, suivez les meilleures pratiques de sécurité et respectez les avertissements émis par le fabricant du pare-feu.

Autorisation d’une communication ouverte avec le processus NodeJS :

• Ouvre le serveur Node à n’importe quelle connexion, en fonction des fonctionnalités et de la configuration du pare-feu.
• Peut être risqué en fonction de votre réseau.
• Est recommandé uniquement sur les ordinateurs de développeur.

Si possible, autorisez uniquement la communication ouverte avec le processus NodeJSsur des réseaux approuvés ou privés.

Pour obtenir des conseils sur la configuration du Pare-feu Windows, consultez Créer un programme de trafic entrant ou une règle de service. Pour plus d’informations, consultez Windows Defender Firewall with Advanced Security et les articles connexes dans l’ensemble de documentation pare-feu Windows.

Résoudre les problèmes

Si vous rencontrez des erreurs, les conseils suivants peuvent vous aider :

• Supprimer les points d'arrêt:
  • Google Chrome: sous l’onglet Débogueur, ouvrez les outils de développement dans votre navigateur. Dans la console, exécutez localStorage.clear() pour supprimer les points d’arrêt.
  • Microsoft Edge : sous l’onglet Application, ouvrez Stockage local. Cliquez avec le bouton droit sur le site et sélectionnez Effacer.
• Vérifiez que vous avez installé et approuvé le certificat de développement HTTPS ASP.NET Core. Pour plus d’informations, consultez Appliquer HTTPS dans ASP.NET Core.
• Visual Studio nécessite l’option Activer le débogage JavaScript pour ASP.NET (Chrome et Edge) dans Outils>Options>Débogage>général. Il s’agit du paramètre par défaut pour Visual Studio. Si le débogage ne fonctionne pas, vérifiez que l’option est sélectionnée.
• Si votre environnement utilise un proxy HTTP, assurez-vous que localhost est inclus dans les paramètres de contournement du proxy. Pour ce faire, définissez la variable d’environnement NO_PROXY dans :
  • Fichier launchSettings.json du projet.
  • Au niveau des variables d’environnement utilisateur ou système pour qu’il s’applique à toutes les applications. Lorsque vous utilisez une variable d’environnement, redémarrez Visual Studio pour que la modification prenne effet.
• Assurez-vous que les pare-feu ou les proxys ne bloquent pas la communication avec le proxy de débogage (NodeJS processus). Pour plus d’informations, consultez la section Configuration du pare-feu.

Points d’arrêt dans OnInitialized{Async} non atteints

Le Blazor lancement du proxy de débogage de l’infrastructure n’a pas lieu dès le démarrage de l’application, de sorte que les points d’arrêt dans les méthodes de OnInitialized{Async} cycle de vie peuvent ne pas être atteints. Nous vous recommandons d’ajouter un délai au début du corps de la méthode pour donner au proxy de débogage un certain temps de lancement avant que le point d’arrêt ne soit atteint. Vous pouvez inclure le délai basé sur une if directive du compilateur pour vous assurer que le délai n’est pas présent pour une version de mise en production de l’application.

OnInitialized:

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

    ...
}

OnInitializedAsync:

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

    ...
}

Délai d’expiration de Visual Studio (Windows)

Si Visual Studio lève une exception que l’adaptateur de débogage n’a pas pu lancer, indiquant que le délai d’expiration a été atteint, vous pouvez ajuster le délai d’expiration avec un paramètre de Registre :

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

L’espace réservé {TIMEOUT} dans la commande précédente est en millisecondes. Par exemple, une minute est affectée en tant que 60000.