Déboguer une application JavaScript ou TypeScript dans Visual Studio

Vous pouvez déboguer un code JavaScript et TypeScript à l’aide de Visual Studio. Vous pouvez atteindre des points d’arrêt, attacher le débogueur, inspecter des variables, afficher la pile des appels et utiliser d’autres fonctionnalités de débogage.

Conseil

Si vous n’avez pas encore installé Visual Studio, accédez à la page Téléchargements Visual Studio pour l’installer gratuitement. Si vous développez des applications Node.js, vous devez installer la charge de travail Développement Node.js avec Visual Studio.

Déboguer un script côté serveur

1. Une fois votre projet ouvert dans Visual Studio, ouvrez un fichier JavaScript côté serveur (par exemple, server.js), cliquez dans la gouttière pour définir un point d’arrêt :

   

   Les points d'arrêt constituent une fonctionnalité élémentaire et essentielle de toute procédure de débogage fiable. Un point d’arrêt indique l’endroit où Visual Studio doit suspendre votre code en cours d’exécution, afin que vous puissiez examiner les valeurs des variables ou le comportement de la mémoire, ou si une branche du code est en cours d’exécution ou non.

2. Pour exécuter votre application, appuyez sur F5 (Déboguer>Démarrer le débogage).

   Le débogueur s’interrompt au point d’arrêt que vous définissez (IDE met en surbrillance l’instruction en arrière-plan jaune). Désormais, vous pouvez inspecter l’état de votre application en passant le curseur sur les variables en cours, en utilisant des fenêtres de débogage telles que les fenêtresLocals et Espion.

   

3. Appuyez sur F5 pour continuer l’exécution de l’application.

4. Si vous souhaitez utiliser les outils de développement Chrome, appuyez sur F12 dans le navigateur Chrome. À l’aide de ces outils, vous pouvez examiner le DOM ou interagir avec l’application à l’aide de la console JavaScript.

Débogage de script côté client

Visual Studio fournit la prise en charge du débogage côté client uniquement pour Chrome et Microsoft Edge (Chromium). Dans certains scénarios, le débogueur atteint automatiquement les points d’arrêt dans les codes JavaScript et TypeScript et dans les scripts incorporés dans des fichiers HTML.

• Pour le débogage d’un script côté client dans des applications ASP.NET, choisissez Outils>Options>Débogage, puis sélectionnez Activer le débogage JavaScript pour ASP.NET (Chrome, Edge et Internet Explorer).

  Pour obtenir des informations détaillées, consultez le billet de blog relatif au débogage de JavaScript dans Microsoft Edge ainsi que ce billet sur Google Chrome. Pour déboguer TypeScript dans ASP.NET Core, consultez Ajouter TypeScript à une application ASP.NET Core existante.

• Pour les applications Node.js et autres projets JavaScript, suivez les étapes décrites ici.

Notes

Pour ASP.NET et ASP.NET Core, débogage de scripts incorporés dans les fichiers .CSHTML ne sont pas pris en charge. Le code JavaScript doit se trouver dans des fichiers distincts pour activer le débogage.

Préparez votre application en vue de son débogage

Si votre source est minifiée ou créée par un transpileur tel qu’un TypeScript ou Babel, utilisez mappages sources pour une expérience de débogage optimale. Vous pouvez même attacher le débogueur à un script côté client en cours d’exécution sans les cartes sources. Mais vous pourrez seulement définir et atteindre des points d’arrêt dans le fichier minifié ou transpilé, et non dans le fichier source. Par exemple, dans une application Vue.js, le script minifié est passé sous forme de chaîne à une instruction eval, et il n’existe aucun moyen de parcourir ce code efficacement à l’aide du débogueur Visual Studio, à moins d’utiliser des mappages de sources. Dans certains scénarios de débogage complexes, vous pouvez utiliser à la place les outils de développement Chrome ou les outils F12 pour Microsoft Edge.

Pour obtenir de l’aide sur la génération de mappages sources, consultez Générer des mappages sources pour le débogage.

Préparez le navigateur pour le débogage

Pour ce scénario, utilisez Microsoft Edge (Chromium) ou Chrome.

1. Fermez toutes les fenêtres du navigateur cible.

   D’autres instances de navigateur peuvent empêcher l’ouverture du navigateur avec le débogage activé. (Les extensions de navigateur étant en cours d’exécution et interceptant le mode de débogage complet, vous devrez peut-être ouvrir le Gestionnaire des tâches pour rechercher et fermer des instances inattendues de Chrome.)

   Pour de meilleurs résultats, arrêtez toutes les instances de Chrome, même si vous utilisez Microsoft Edge (Chromium). Les deux navigateurs utilisent la même base de code chromium.

2. Démarrez votre navigateur avec le débogage activé.

   À partir de Visual Studio 2019, vous pouvez définir l’indicateur --remote-debugging-port=9222 au lancement du navigateur en sélectionnant Naviguer avec...> dans la barre d’outils Déboguer.

   

   Si vous ne voyez pas la commande Naviguer avec... dans la barre d’outils Déboguer, sélectionnez un autre navigateur, puis réessayez.

   Dans la boîte de dialogue Naviguer avec, choisissez Ajouter, puis définissez l’indicateur dans le champ Arguments. Utilisez un autre nom convivial pour le navigateur, comme Edge avec débogage ou Chrome avec débogage. Pour plus d’informations, consultez les notes de publication.

   

   Vous pouvez également ouvrir la commande Exécuter à partir du bouton Démarrer de Windows (faites un clic droit et choisissez Exécuter), puis entrez la commande suivante :

   msedge --remote-debugging-port=9222

   ou

   chrome.exe --remote-debugging-port=9222

   Cela démarre votre navigateur avec le débogage activé.

   L’application n’est pas encore en cours d’exécution. Vous obtenez donc une page de navigateur vide.

Attachez le débogueur à un script côté client

Pour attacher le débogueur à partir de Visual Studio et atteindre les points d’arrêt dans le code côté client, vous devez l’aider à identifier le processus approprié. Voici une façon de l’activer.

1. Basculez vers Visual Studio, puis définissez un point d’arrêt dans votre code source, qui peut être un fichier JavaScript, un fichier TypeScript ou un fichier JSX. (Définissez le point d’arrêt dans une ligne de code qui autorise les points d’arrêt, tels qu’une instruction return ou une déclaration var.)

   

   Pour rechercher le code spécifique dans un fichier transpilé, utilisez Ctrl+F (Modifier rechercher>Trouver et remplacer>Recherche rapide).

   Pour le code côté client, atteindre un point d’arrêt dans un fichier TypeScript, .vue ou JSX nécessite généralement l’utilisation de mappages sources. Une carte source doit être configurée correctement pour prendre en charge le débogage dans Visual Studio.

2. Sélectionnez votre navigateur cible comme cible de débogage dans Visual Studio, puis appuyez sur Ctrl+F5 (Déboguer>Démarrer sans débogage) pour exécuter l’application dans le navigateur.

   Si vous avez créé une configuration de navigateur avec un nom convivial, choisissez-le comme cible de débogage. L’application s’ouvre dans un nouvel onglet du navigateur.

3. Choisissez Déboguer>Attacher au processus.

   Conseil

   À partir de Visual Studio 2017, une fois que vous vous êtes attaché au processus la première fois en suivant ces étapes, vous pouvez rapidement vous rattacher au même processus en choisissant Déboguer>Rattacher au processus.

4. Dans la boîte de dialogue Attacher au processus, obtenez une liste filtrée des instances de navigateur auxquelles vous pouvez attacher. Choisissez le débogueur approprié pour votre navigateur cible, JavaScript (Chrome) ou JavaScript (Microsoft Edge - Chromium) dans le champ Attacher à, tapez chrome ou edge dans la zone de filtre pour filtrer les résultats de la recherche.

5. Sélectionnez le processus de navigateur avec le port (localhost dans cet exemple), puis sélectionnez Attacher.

   Le port (par exemple, 1337) peut également apparaître dans le champ Titre pour vous aider à sélectionner l’instance de navigateur appropriée.

   L’exemple suivant montre comment cela recherche le navigateur Microsoft Edge (Chromium).

   

   Conseil

   Si le débogueur ne s’attache pas et que vous voyez le message « Échec du lancement de l’adaptateur de débogage » ou « Impossible de s’attacher au processus. Une opération n’est pas légale dans l’état actuel. » utilisez le Gestionnaire des tâches Windows pour fermer toutes les instances du navigateur cible avant de démarrer le navigateur en mode débogage. Les extensions de navigateur peuvent être en cours d’exécution et empêcher le mode de débogage complet.

6. Le code avec le point d’arrêt a peut-être déjà été exécuté, actualisez la page de votre navigateur. Si nécessaire, prenez des mesures pour que le code avec le point d’arrêt s’exécute.

   Pendant que l’exécution du débogueur est en pause, vous pouvez examiner l’état de votre application en pointant sur les variables et en utilisant les fenêtres du débogueur. Vous pouvez faire avancer le débogueur en exécutant pas à pas le code (F5, F10 et F11). Pour plus d’informations sur les fonctionnalités de débogage de base, consultez Premier aperçu du débogueur.

   Vous pouvez atteindre le point d’arrêt dans un fichier ..js transpilé ou un fichier source, en fonction du type d’application, des étapes que vous avez suivies précédemment et d’autres facteurs tels que l’état de votre navigateur. De toute façon, vous pouvez exécuter pas à pas le code et examiner les variables.

   • Si vous devez insérer du code dans un fichier source .vue TypeScript, JSX ou .vue et que vous ne pouvez pas le faire, assurez-vous que votre environnement est configuré correctement, comme décrit dans la section Résolution des problèmes.

   • Si vous devez arrêter l’exécution du code dans un fichier JavaScript transpilé (par exemple, app-bundle.js) et que vous n’y parvenez pas, supprimez le fichier de mappage de source, filename.js.map.

Résolution des problèmes liés aux points d’arrêt et aux mappages sources

Si vous devez accéder au code d’un fichier source TypeScript ou JSX et que vous ne parvenez pas à le faire, utilisez Attacher au processus comme décrit dans la section précédente pour attacher le débogueur. Vérifiez que votre environnement est configuré correctement :

• Fermez toutes les instances de navigateur, y compris les extensions Chrome (à l’aide du Gestionnaire des tâches), afin de pouvoir exécuter le navigateur en mode débogage.

• Veillez à démarrer le navigateur en mode débogage.

• Assurez-vous que votre fichier de mappage source inclut le chemin relatif correct de votre fichier source et qu’il n’inclut pas de préfixes non pris en charge, tels que webpack:///, ce qui empêche le débogueur Visual Studio de localiser un fichier source. Par exemple, une référence comme webpack:///.app.tsx peut être corrigée en ./app.tsx. Vous pouvez le faire manuellement dans le fichier de carte source (ce qui est utile pour les tests) ou via une configuration de build personnalisée. Pour plus d’informations, consultez Générer des mappages sources pour le débogage.

Sinon, si vous devez vous décomposer en code dans un fichier source (par exemple, app.tsx) et ne pouvez pas le faire, essayez d’utiliser l’instruction debugger; dans le fichier source ou définissez des points d’arrêt dans les outils de développement Chrome (ou F12 Tools pour Microsoft Edge) à la place.

Générer des mappages de sources pour le débogage

Visual Studio permet d’utiliser et de générer des mappages de sources sur les fichiers sources JavaScript. Cela est souvent nécessaire si votre source est minimisée ou créée par un transpiler comme TypeScript ou Babel. Les options disponibles varient selon le type de projet.

• Par défaut, un projet TypeScript dans Visual Studio génère pour vous des mappages de sources. Pour plus d’informations, consultez Configurer des mappages de sources à l’aide d’un fichier tsconfig.json.

• Dans un projet JavaScript, vous pouvez générer des mappages de sources à l’aide d’un bundler comme webpack et d’un compilateur comme TypeScript (ou Babel), que vous pouvez ajouter à votre projet. Pour le compilateur TypeScript, vous devez également ajouter un fichier tsconfig.json et définir l’option de compilateur sourceMap. Pour obtenir un exemple montrant comment procéder à l’aide d’une configuration webpack de base, consultez Créer une application Node.js avec React.

Remarque

Si vous ne connaissez pas les mappages de sources, consultez Présentation des mappages de sources avant de continuer.

Afin de configurer les paramètres avancés pour les mappages de sources, utilisez un fichier tsconfig.json ou les paramètres du projet dans un projet TypeScript, mais pas les deux.

Pour activer le débogage à l’aide de Visual Studio, vous devez vous assurer que les références à votre fichier source dans le mappage source généré sont correctes (cela peut nécessiter des tests). Par exemple, si vous utilisez webpack, les références dans le fichier de mappage source incluent le préfixe webpack:///, ce qui empêche Visual Studio de trouver un fichier source TypeScript ou JSX. Plus précisément, lorsque vous corrigez ce problème à des fins de débogage, la référence au fichier source (par exemple, app.tsx) doit être remplacée par quelque chose comme webpack:///./app.tsx par quelque chose comme ./app.tsx, qui permet le débogage (le chemin d’accès est relatif à votre fichier source). L’exemple suivant montre comment configurer des mappages de sources dans webpack, qui est l’un des bundlers les plus courants, afin qu’ils fonctionnent avec Visual Studio.

(Webpack uniquement) Si vous définissez le point d’arrêt dans un fichier TypeScript de JSX (plutôt qu’un fichier JavaScript transpilé), vous devez mettre à jour votre configuration webpack. Par exemple, dans webpack-config.js, vous devrez peut-être remplacer le code suivant :

  output: {
    filename: "./app-bundle.js", // This is an example of the filename in your project
  },

par ce code :

  output: {
    filename: "./app-bundle.js", // Replace with the filename in your project
    devtoolModuleFilenameTemplate: '[resource-path]'  // Removes the webpack:/// prefix
  },

Il s’agit d’un paramètre de développement uniquement pour activer le débogage du code côté client dans Visual Studio.

Pour les scénarios complexes, les outils de navigateur (F12) fonctionnent parfois mieux pour le débogage, car ils ne nécessitent pas de modification des préfixes personnalisés.

Configurer des mappages de sources à l’aide d’un fichier tsconfig.json

Si vous ajoutez un fichier tsconfig.json à votre projet, Visual Studio traite la racine du répertoire comme un projet TypeScript. Pour ajouter le fichier, faites un clic droit sur votre projet dans l’Explorateur de solutions, puis choisissez Ajouter > Nouvel élément > Fichier de configuration JSON TypeScript. Un fichier tsconfig.json comme ce qui suit est ajouté à votre projet.

{
  "compilerOptions": {
    "noImplicitAny": false,
    "module": "commonjs",
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5"
  },
  "exclude": [
    "node_modules"
  ]
}

Options du compilateur pour le fichier tsconfig.json

• inlineSourceMap : émettre un seul fichier avec des mappages sources au lieu de créer un mappage source distinct pour chaque fichier source.
• inlineSources : émettre la source en même temps que les mappages sources dans un seul fichier ; nécessite inlineSourceMap ou sourceMap à définir.
• mapRoot : spécifie l’emplacement où le débogueur doit trouver des fichiers de mappage source (.map) au lieu de l’emplacement par défaut. Utilisez cet indicateur si les fichiers .map à l’exécution doivent se trouver dans un emplacement autre que les fichiers .js. L’emplacement spécifié est incorporé dans le mappage de source pour diriger le débogueur vers l’emplacement des fichiers .map.
• sourceMap : génère un fichier .map correspondant.
• sourceRoot : spécifie l’emplacement où le débogueur doit trouver les fichiers TypeScript au lieu des emplacements sources. Utilisez cet indicateur si les sources runtime doivent se trouver dans un emplacement autre que celui défini au moment de la conception. L’emplacement spécifié est incorporé dans le mappage de source pour diriger le débogueur vers l’emplacement des fichiers sources.

Pour plus d’informations sur les options du compilateur, consultez la page Options du compilateur dans le manuel TypeScript.

Configurez des mappages de sources à l’aide des paramètres du projet (projet TypeScript)

Vous pouvez également configurer les paramètres des mappages de sources à l’aide des propriétés du projet en double-cliquant sur le projet, puis en choisissant Projet > Propriétés > Build TypeScript > Débogage.

Ces paramètres de projet sont disponibles.

• Générer des mappages sources (équivalent à sourceMap dans tsconfig.json) : génère le fichier .map correspondant.
• Spécifier le répertoire racine des mappages sources (équivalent à mapRoot dans tsconfig.json) : spécifie l’emplacement où le débogueur doit trouver les fichiers de cartes au lieu des emplacements générés. Utilisez cet indicateur si les fichiers .map à l’exécution doivent se trouver dans un emplacement autre que les fichiers .js. L’emplacement spécifié est incorporé dans le mappage de source pour diriger le débogueur vers l’emplacement des fichiers de mappages.
• Spécifier le répertoire racine des fichiers TypeScript (équivalent à sourceRoot dans tsconfig.json) : spécifie l’emplacement où le débogueur doit trouver les fichiers TypeScript au lieu des emplacements sources. Utilisez cet indicateur si les fichiers sources runtime doivent se trouver dans un emplacement autre que celui défini au moment de la conception. L’emplacement spécifié est incorporé dans le mappage de source pour diriger le débogueur vers l’emplacement des fichiers sources.

Déboguer JavaScript dans des fichiers dynamiques à l’aide de Razor (ASP.NET)

À partir de Visual Studio 2019, Visual Studio prend en charge le débogage pour Chrome et Microsoft Edge (Chromium) uniquement.

Toutefois, vous ne pouvez pas atteindre automatiquement les points d’arrêt sur les fichiers générés avec la syntaxe Razor (cshtml, vbhtml). Il existe deux approches permettant de déboguer ce type de fichier :

• Placezdebugger; l’instruction là où vous souhaitez l’arrêter : cette instruction entraîne l’arrêt de l’exécution du script dynamique et le démarrage du débogage immédiatement pendant sa création.

• Chargez la page et ouvrez le document dynamique dans Visual Studio : vous devrez ouvrir le fichier dynamique pendant le débogage, définir votre point d’arrêt et actualiser la page pour que cette méthode fonctionne. Selon que vous utilisez Chrome ou Microsoft Edge (Chromium), vous trouverez le fichier à l’aide de l’une des stratégies suivantes :

  • Pour Chrome, accédez à l’Explorateur de solutions > Script Documents (Documents de script) > YourPageName (Nom de votre page).

    Notes

    Quand vous utilisez Chrome, vous pouvez éventuellement recevoir un message indiquant qu’« aucune source n’est disponible entre les balises <script> ». Cela n’est pas un problème, continuez simplement le débogage.

  • Pour Microsoft Edge (Chromium), utilisez la même procédure que Chrome.

Pour plus d’informations, consultez Débogage côté client de projets ASP.NET dans Google Chrome.

Contenu connexe

Propriétés, React, Angular et Vue