Débogage du code ObjectScript à l'aide de VSCode

Visual Studio Code (VSCode) est l'éditeur de code le plus populaire du marché. Il a été créé par Microsoft et distribué en tant qu'IDE gratuit. VSCode supporte des dizaines de langages de programmation, y compris ObjectScript, Until 2018, Atelier (basé sur Eclipse). Il était considéré comme l'une des principales options pour développer les produits InterSystems. Cependant, en décembre 2018, lorsque la communauté des développeurs d'InterSystems a lancé le support de VSCode, une partie pertinente des professionnels d'InterSystems a commencé à utiliser cet éditeur et ne cesse de le faire depuis, en particulier les développeurs aui travaillent avec de nouvelles technologies (Docker, Kubernetes, NodeJS, Angular, React, DevOps, Gitlab, etc.). Certaines des meilleures fonctionnalités de VSCode sont les capacités de débogage. C'est pourquoi cet article démontrera en détail comment déboguer le code ObjectScript, y compris le code de classe et le code %CSP.REST.
 

Qu'est-ce que le débogage ?

Le débogage est un processus qui consiste à détecter et à résoudre les "bugs", c'est-à-dire les erreurs dans votre code ObjectScript. C'est pourquoi pour les comprendre dans la logique d'exécution de votre code source, vous devez voir le programme s'exécuter ligne par ligne. C'est la meilleure façon d'identifier les conditions ou la logique de programmation et de trouver les erreurs logiques. Les autres erreurs sont des erreurs d'exécution. Pour pouvoir déboguer ce type de problème, il est essentiel de vérifier d'abord les valeurs des variables assignées.

Installation des extensions InterSystems IRIS pour VSCode

Tout d'abord, il faut installer les extensions IRIS d'InterSystems dans votre IDE VSCode. Pour ce faire, allez dans Extensions, cherchez InterSystems et installez les extensions InterSystems suivantes :

La dernière extension (InterSystems ObjectScript Extension Pack) doit être installée en premier, car il s'agit d'un paquet d'extensions nécessaires pour connecter, éditer, développer et déboguer ObjectScript. Les autres extensions listées sont optionnelles.

Application modèle

Nous allons utiliser une application de mon référentiel GitHub (https://github.com/yurimarx/debug-objectscript.git) pour les exemples de débogage dans cet article. Donc, suivez les étapes ci-dessous pour obtenir, exécuter et déboguer l'application dans VSCode :
1.    Créez un répertoire local et récupérez le code source du projet dans ce répertoire :

$ git clone https://github.com/yurimarx/debug-objectscript.git

2.    Ouvrez le terminal dans ce répertoire (répertoire iris-rest-api-template) et exécutez :

$ docker-compose up -d --build

3.    Ouvrez VSCode dans le répertoire iris-rest-api-template en utilisant $code . ou clic-droit sur le dossier et sélectionnez Open with Code.
4.    Dans le pied de page, cliquez sur ObjectScript pour ouvrir les options configurées dans .vscode/launch.json :

5.    Sélectionnez Toggle Connection pour activer la connexion actuelle :

6.    Après avoir activé cette connexion, vous obtiendrez la connexion indiquée ci-dessous :

7.    Si vous n'êtes pas connecté avec IRIS dans VSCode, vous ne pourrez pas déboguer le code ObjectScript. Vérifiez donc votre connexion en cliquant sur l'extension ObjectScript VSCode :

8.    Ouvrez Person.cls, allez à la ligne numéro 25 et pointez la souris sur le chiffre 25 à votre gauche.

9.    Maintenant, pointez la souris sur la ClassMethod supérieure et cliquez sur "Debug this method" (Débugger cette méthode) :

10.    VSCode ouvrira une boîte de dialogue pour vous permettre de définir les valeurs des paramètres, alors définissez les valeurs comme indiqué ci-dessous, et cliquez sur Entrée :

11.    VSCode va interrompre l'exécution du code à la ligne 25 :

12.    Maintenant, en haut à gauche, vous pouvez voir les valeurs actuelles des variables.  

13.    En bas à gauche, vous pouvez maintenant voir la liste des points d'arrêt et la pile d'appels pour le point d'arrêt actuel.  

14.    En haut à droite, vous pouvez voir le code source avec le point d'arrêt et une série de boutons pour contrôler l'exécution du débogage.  

15.    Si vous avez besoin d'utiliser la console de débogage pour y taper quelque chose, tapez : Name_",""_Title pour voir la concaténation des variables en utilisant la Debug Console :

16.    Sélectionnez la variable de résultat, cliquez sur le bouton droit de la souris et sélectionnez "Add to Watch" (Ajouter à la liste) :

17.    Vous pouvez maintenant surveiller ou modifier la valeur actuelle de la variable de résultat dans la section WATCH :

18.    Enfin, la barre de bas de page est orange, et elle indique le débogage :

Utilisation de la console de débogage

La console de débogage vous permet d'écrire des expressions pendant le débogage, de sorte que vous pouvez vérifier les valeurs de différentes variables (de type simple ou de type objet) ou valider la valeur actuelle et d'autres conditions. Elle peut exécuter tout ce qui peut retourner des valeurs, donc $zv fonctionnera également. Suivez ces étapes pour voir quelques options :

1.    Écrire Nom_", "_Title_" à partir de "_Company" sur l'invite du terminal de débogage et voyez les valeurs concaténées de Nom, Titre et Société en sortie :

 ou valider la valeur actuelle et d'autres conditions. Elle peut exécuter tout ce qui peut retourner des valeurs, donc $zv fonctionnera également. Suivez ces étapes pour voir quelques options :).png)

Utilisation de la barre d'outils de débogage

La barre d'outils de débogage vous permet de contrôler l'exécution du débogage. Découvrez les fonctions des boutons ici :

1.    Bouton Continuer (F9) : poursuit l'exécution jusqu'au prochain point d'arrêt. S'il n'y a pas de point d'arrêt à atteindre, le programme continue jusqu'à la fin.
2.    Step Over (F8) : passe à la ligne suivante sans entrer dans le code source d'une méthode interne (ne pas entrer dans la méthode Populate).
3.    Step Into (F7) : aller à la ligne suivante à l'intérieur du code source de la méthode interne (aller à la première ligne de la méthode Populate).
4.    Step Out (Shift + F8) : aller à la ligne courante du code source de l'appelant d'une méthode.
5.    Redémarrer (Crtl + Shift + F5) : relancer le débogage.
6.    Stop : arrête la session de débogage.  

Déboguer les méthodes de la classe %CSP.REST

Pour déboguer les méthodes des classes REST, il est nécessaire d'appliquer une petite astuce révélée par Fábio Gonçalves (voir l'article ici https://community.intersystems.com/post/atelier-debugging-attach-process). Il est nécessaire d'ajouter un HANG (ma recommandation est entre 20 et 30 secondes). Il suffit de suivre les étapes suivantes :

1.    Ouvrez le fichier src\dc\Sample\PersonREST.cls et allez à la méthode GetInfo(), ajoutez HANG 30 (ceci est nécessaire pour obtenir le temps, 30 secondes, pour commencer le débogage de cette méthode) :

2.    Fixez des points d'arrêt sur les lignes de version HANG et SET (cercles rouges) :

3.    Ouvrez un client HTTP pour appeler une méthode REST (je vais appeler GetInfo de la classe PersonREST) :

4.    Définissez Basic Auth sur Authorization (nom d'utilisateur _SYSTEM et mot de passe SYS) :

5.    Envoyer un GET http://localhost:52773/crud/.
6.    Cliquez sur ObjectScript Attach dans la barre de bas de page :

7.    Sélectionnez Attachement ObjectScript :

8.    Sélectionnez le processus PersonREST :

9.    Attendez quelque temps (environ 30 secondes) pour que VSCode interrompe l'exécution en cours sur le point d'arrêt :

Remarque 1 : supprimez le HANG 30 lorsque vous avez terminé votre débogage, car le HANG met l'exécution en pause.

Remarque 2 : si le processus PersonREST n'apparaît pas, redémarrez votre VSCode, et réessayez.

10.    Maintenant vous pouvez procéder au débogage.

Modification du point d'arrêt

Vous pouvez faire un clic droit sur le point d'arrêt pour supprimer ou configurer les points d'arrêt conditionnels (rupture sur le point d'arrêt avec la condition "true"). La commande de rupture intégrée directement dans le code sera également prise en compte par le débogueur. Vous pouvez également essayer cette fonction.

1.    Faites un clic droit sur le point d'arrêt et sélectionnez Edit Breakpoint :

2.    Saisissez l'expression mentionnée ci-dessous et appuyez sur Entrée :

Remarque : essayez la version = 1.0.5 pour voir le point d'arrêt faux et 1.0.6 pour voir le point d'arrêt vrai.

 

Configuration de l'option de débogage sur le fichier .vscode/launch.json

Le fichier Launch.json est utilisé pour configurer les options de débogage pour votre projet. Pour voir les alternatives, allez dans le fichier suivant :

Pour ce modèle, nous avons deux options à choisir pour le débogage :

1.    Nous pouvons lancer le débogage sur la classe configurée sur l'attribut programme directement avec un programme (dans cet exemple le débogueur va démarrer dans la classe PackageSample.ObjectScript, méthode Test().
2.    Nous pouvons attacher PickProcess au processus du programme sélectionné que nous voulons déboguer. Dans cet exemple, le débogueur ouvrira en haut une liste de processus pour sélectionner le processus (chaque programme a son processus) qui sera débogué. La deuxième option est Le fichier Launch.json, qui est utilisé pour configurer les options de débogage pour votre projet. Pour voir les alternatives, allez dans le fichier suivant : more common.

D'une manière générale, ces attributs sont obligatoires pour toute configuration de débogage (source : https://intersystems-community.github.io/vscode-objectscript/rundebug/):

• "type" - Identifie le type de débogueur à utiliser. Dans ce cas, objectcript est fourni par l'extension InterSystems ObjectScript.
• "request" - Identifie le type d'action pour cette configuration de lancement. Les valeurs possibles sont "launch" et "attach".
• "name" - Un nom arbitraire pour identifier la configuration. Ce nom apparaît dans la liste déroulante Start Debugging.

En outre, pour une configuration de lancement ObjectScript, vous devez fournir l'attribut program, qui spécifie la routine ou la ClassMethod à exécuter lors du lancement du débogueur, comme le montre l'exemple suivant :

"launch": {
    "version": "0.2.0",
    "configurations": [
       {
        "type": "objectscript",
        "request": "launch",
        "name": "ObjectScript Debug HelloWorld",
        "program": "##class(Test.MyClass).HelloWorld()",
      },
      {
        "type": "objectscript",
        "request": "launch",
        "name": "ObjectScript Debug GoodbyeWorld",
        "program": "##class(Test.MyOtherClass).GoodbyeWorld()",
      },
   ]
}

Pour une configuration d'attachement ObjectScript, vous pouvez fournir les attributs suivants :

• "processId" - Spécifie l'ID du processus à attacher à une chaîne ou un nombre. La valeur par défaut est "${command:PickProcess}" pour fournir une liste déroulante d'ID de processus à attacher au moment de l'exécution.
• "system" - Spécifie si les pièces jointes doivent être autorisées ou non dans le processus système. La valeur par défaut est "false".

L'exemple suivant montre plusieurs configurations d'attachement ObjectScript valides :

"launch": {
    "version": "0.2.0",
    "configurations": [
        {
            "type": "objectscript",
            "request": "attach",
            "name": "Attach 1",
            "processId": 5678
        },
        {
            "type": "objectscript",
            "request": "attach",
            "name": "Attach 2",
            "system": true
        },
    ]
}

Maintenant, vous pouvez sélectionner une configuration de débogage dans la liste que VS Code fournit dans le champ Run and Debug en haut de la barre latérale de débogage (source : https://intersystems-community.github.io/vscode-objectscript/rundebug/):

Si vous cliquez sur la flèche verte, la configuration de débogage actuellement sélectionnée sera exécutée.
Lorsque vous lancez une session de débogage ObjectScript, assurez-vous que le fichier contenant le programme que vous déboguez est ouvert dans votre éditeur et se trouve dans l'onglet actif. VS Code lancera une session de débogage avec le serveur du fichier dans l'éditeur actif (l'onglet sur lequel l'utilisateur est concentré). Ceci s'applique également aux sessions de débogage ObjectScript attachées.
Cette extension utilise WebSockets pour communiquer avec le serveur InterSystems pendant le débogage. Si vous rencontrez des problèmes lorsque vous essayez de lancer une session de débogage, vérifiez si le serveur Web d'InterSystems autorise les connexions WebSocket.
Les commandes de débogage et les éléments du menu "Run" fonctionnent à peu près de la même manière que pour les autres langues prises en charge par VS Code. Pour plus d'informations sur le débogage de VS Code, consultez les ressources documentaires mentionnées au début de cette section.

Définition de la synchronisation entre un code source local et un code source serveur (dans IRIS Server)

Il est également important de disposer d'une structure de dossiers pour le code source, qui peut être adoptée par les paramètres "objectcript.export". Cette information sera utilisée pour convertir les noms de classes du serveur en fichiers locaux. Si elle est incorrecte, il est possible que les classes soient ouvertes en mode lecture seule même si elles n'existent que localement.
1.    Ouvrez le fichier .vscode\settings.json et configurez objectcript.export :

2.    Passez la souris sur le dossier, et ajoutez la catégorie et d'autres paramètres pour voir la documentation correspondante.

Autres techniques pour compléter le processus de débogage

En plus du débogage de votre programme, n'oubliez pas de bien documenter votre code source, de consigner les opérations effectuées par le code important et d'effectuer des tests unitaires et des outils d'analyse statique du code source. De cette façon, la qualité de vos programmes sera beaucoup plus élevée, ce qui réduira le temps et le coût de la maintenance et des ajustements.

Plus d'informations

Vous pouvez en savoir plus sur le débogage d'ObjectScript sur VSCode si vous révisez les ressources suivantes :
1.    https://www.youtube.com/watch?v=diLHwA0rlGM
2.    https://intersystems-community.github.io/vscode-objectscript/rundebug/
3.    https://code.visualstudio.com/docs/introvideos/debugging
4.    https://code.visualstudio.com/docs/editor/debugging
5.    https://docs.intersystems.com/iris20221/csp/docbook/Doc.View.cls?KEY=TOS_VSCode