Cómo depurar el código ObjectScript con VS Code

Visual Studio Code (VS Code) es el editor de códigos más popular del mercado. Fue creado por Microsoft y distribuido como IDE gratuito. VS Code es compatible con docenas de lenguajes de programación, incluido ObjectScript.

Hasta 2018, Atelier (basado en Eclipse), se consideraba una de las principales opciones para desarrollar los productos de InterSystems. Sin embargo, en diciembre de 2018, cuando la Comunidad de Desarrolladores de InterSystems lanzó el soporte para VSCode, una parte relevante de los profesionales de InterSystems comenzaron a utilizar este editor y lo siguen haciendo desde entonces, especialmente los desarrolladores que trabajan con nuevas tecnologías (Docker, Kubernetes, NodeJS, Angular, React, DevOps, Gitlab, etc.).

Algunas de las mejores características de VSCode son las funciones de depuración. Por eso, en este artículo mostraré en detalle cómo depurar un código ObjectScript, incluido el código de clase y el código %CSP.REST.

 

¿En qué consiste la depuración?

La depuración es un proceso de detección y resolución de "bugs" - errores en el código. Algunos errores son lógicos, no de compilación. Por eso, para comprenderlos en tu lógica de ejecución del código fuente, es necesario ver el programa ejecutándose línea por línea. Esta es la mejor manera de identificar las condiciones o la lógica de la programación y encontrar errores lógicos. Otros errores son de ejecución. Para que podamos depurar este tipo de problemas, es esencial verificar primero los valores de las variables asignadas.

Instalación de las extensiones de InterSystems IRIS para VSCode

En primer lugar, hay que instalar las extensiones de InterSystems IRIS en tu IDE de VSCode. Para hacerlo, ve a Extensiones, busca InterSystems e instala estas extensiones de InterSystems:

La última extensión (InterSystems ObjectScript Extension Pack) debería instalarse la primera, porque es un paquete de extensiones necesarias para conectar, editar, desarrollar y depurar ObjectScript. Las demás extensiones de la lista son opcionales.

Aplicación de muestra

Utilizaremos una aplicación de mi repositorio de GitHub (https://github.com/yurimarx/debug-objectscript.git) para los ejemplos de depuración de este artículo. Por lo tanto, sigue los siguientes pasos para obtener, ejecutar y depurar la aplicación en VSCode:

1.    Crea un directorio local e introduce en él el código fuente del proyecto:

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

2.    Abre el terminal en este directorio (directorio iris-rest-api-template) y ejecuta:

$ docker-compose up -d --build

3.    Abre VS Code dentro del directorio iris-rest-api-template usando $code, o haga clic-derecho sobre la carpeta y selecciona Abrir con Code.

4.    Abajo, haz clic en ObjectScript para abrir las opciones configuradas en .vscode/launch.json:

5.    Selecciona Toggle Connection (Alternar conexión) para activar la conexión actual:

6.    Después de habilitar esta conexión, obtendrás la conexión que se muestra a continuación:

7.    Si no estás conectado con IRIS en VSCode, no podrás depurar el código ObjectScript. Así que comprueba tu conexión haciendo clic sobre la extensión ObjectScript VSCode:

8.    Abre Person.cls, ve a la línea número 25 y señala con el ratón el número 25 que aparece a la izquierda.

9.    Ahora, señala con el ratón en ClassMethod arriba y haz clic en Debug this method:

10.    VSCode abrirá un diálogo para establecer los valores de los parámetros - defínelos como se muestra a continuación, y haz clic en Enter:

11.    VSCode interrumpirá la ejecución del código en la línea 25:

12.    Ahora, en la parte superior izquierda, se pueden ver los valores actuales de las variables.  

13.    En la parte inferior izquierda se puede ver la lista de puntos de interrupción y la pila de llamadas para el punto de interrupción actual.  

14.    En la parte superior derecha se puede ver el código fuente con el punto de interrupción y un conjunto de botones para controlar la ejecución de la depuración.  

15.    Si necesitas utilizar la Consola de Depuración (Debug Console) para escribir algo allí, escribe: Name_","_Title para ver la concatenación de variables usando Debut Console:

16.    Selecciona la variable resultante, pulsa el botón derecho del ratón y selecciona Añadir a Watch (Add to Watch):

17.    Ahora puedes controlar o cambiar el valor actual de la variable resultante en la sección WATCH:

18.    Finalmente, la barra que aparece abajo es de color naranja, e indica la depuración:

Uso de la Consola de Depuración

La Consola de Depuración permite escribir expresiones durante la depuración, para que se puedan verificar los valores de diferentes variables (de tipo simple o de tipo objeto) o validar el valor actual y otras condiciones. Puede ejecutar cualquier elemento que pueda devolver algunos valores, por lo que $zv también funcionará. Sigue estos pasos para ver algunas opciones:

1.    Escribe Name_", "_Title_" From "_Company en la línea de comando Debug Terminal y mira los valores concatenados Nombre, Título y Empresa como salida:

Uso de la barra de herramientas de depuración

La barra de herramientas de depuración permite controlar la ejecución de la depuración. Vamos a ver las funciones de los botones:

1.    Botón Continue (F9): continúa la ejecución hasta el siguiente punto de interrupción. Si no hay ningún punto de interrupción al que ir, continuará hasta el final.
2.    Step Over (F8): pasa a la línea siguiente sin entrar en el código fuente de un método interno (no entra en el método Populate).
3.    Step Into (F7): pasa a la siguiente línea dentro del código fuente del método interno (pasa a la primera línea del método Populate).
4.    Step Out (Shift + F8): pasa a la línea actual del código fuente que llama a un método.
5.    Restart (Crtl + Shift + F5): reinicia la depuración.
6.    Stop: detiene la sesión de depuración.  

Depurar los métodos de la clase %CSP.REST

Para depurar métodos de la clase REST, es necesario aplicar un pequeño truco revelado por Fábio Gonçalves (puedes leer el artículo aquí: https://es.community.intersystems.com/post/atelier-depuraci%C3%B3n-adjun...). Es necesario añadir un HANG (mi recomendación es que dure entre 20 y 30 segundos). Solo sigue estos pasos:

1.    Abre el archivo src\dc\Sample\PersonREST.cls y ve al método GetInfo(), añade HANG 30 (esto es necesario para disponer de tiempo, 30 segundos, para iniciar la depuración de este método):

2.    Establece puntos de interrupción en las líneas HANG y SET version (círculos rojos):

3.    Abre un cliente HTTP para llamar a un método REST (llamaré a GetInfo desde la clase PersonREST):

4.    Establece Basic Auth en Autorización (Username _SYSTEM y Contraseña SYS):

5.    Envía un GET http://localhost:52773/crud/.
6.    Haz clic en la opción Adjuntar ObjectScript que se encuentra en parte de abajo:

7.    Selecciona Adjuntar ObjectScript:

8.    Selecciona el proceso PersonREST:

9.    Espera un poco de tiempo (unos 30 segundos) para que VS Code interrumpa la ejecución actual en el punto de interrupción:

Nota 1: Elimina HANG 30 cuando termine la depuración, porque el comando HANG pausará la ejecución.

Nota 2: Si el proceso PersonREST no aparece, reinicia tu VS Code, e inténtalo de nuevo.

10.    Ahora puedes llevar a cabo tu proceso de depuración.

Editar el punto de interrupción

Se puede hacer clic con el botón derecho en el punto de interrupción para eliminar o configurar puntos de interrupción condicionales (la interrupción en el punto de interrupción con una condición es verdadera). El comando break que está embebido en el código también será detectado por el depurador. También se puede hacer esto.

1.    Haz clic con el botón derecho en el punto de interrupción y selecciona Editar punto de interrupción (Edit breakpoint):

2.    Introduce la expresión siguiente y pulsa Enter:

Nota: prueba version = 1.0.5 para ver el breakpoint falso y version 1.0.6 para ver el breakpoint verdadero.

Configurar la opción de depuración en el archivo .vscode/launch.json

El archivo launch.json se utiliza para configurar las opciones de depuración del proyecto. Para ver las alternativas, ve a este archivo:

Para esta muestra, tenemos dos opciones para depurar:

1.    Podemos iniciar la depuración sobre la clase configurada en el atributo program directamente con un programa. En este ejemplo el depurador se iniciará en la clase PackageSample.ObjectScript, método Test().
2.    Podemos adjuntar PickProcess al proceso del programa seleccionado que se quiere depurar. En este ejemplo el depurador abrirá en la parte superior una lista de procesos para seleccionar qué proceso se depurará (cada programa tiene su propio proceso). La segunda opción es más habitual.

De manera general, estos atributos son obligatorios para cualquier configuración de depuración (fuente: https://intersystems-community.github.io/vscode-objectscript/rundebug/):

• type - Identifica el tipo de depurador que se utilizará. En este caso, ObjectScript se suministra mediante la extensión InterSystems ObjectScript.
• request - Identifica el tipo de acción para esta configuración de inicio. Los posibles valores son iniciar (launch) y adjuntar (attach).
• name - Un nombre arbitrario para identificar la configuración. Este nombre aparece en la lista desplegable "Iniciar depuración".

Además, para una configuración de inicio en ObjectScript, es necesario proporcionar el atributo program, que especifica la rutina o Método de clase que se ejecutará al iniciar el depurador, como se muestra en el siguiente ejemplo:

"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()",
      },
   ]
}

Para adjuntar una configuración en ObjectScript, se pueden proporcionar los siguientes atributos:

• processId - Especifica el ID del proceso para adjuntar a una cadena o un número. El valor predeterminado "${command:PickProcess}" proporciona una lista desplegable de los ID de los procesos para adjuntar durante la ejecución.
• system - Especifica si se permiten o no archivos adjuntos en el proceso del sistema. Establece la configuración predeterminada en falso.

El siguiente ejemplo muestra varias configuraciones válidas para adjuntar ObjectScript:

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

Ahora, puedes seleccionar una configuración de depuración de la lista que VS Code proporciona en el campo Run and Debug en la parte superior de la barra lateral de depuración (fuente: https://intersystems-community.github.io/vscode-objectscript/rundebug/):

Si haces clic en la flecha verde, se ejecutará la configuración de depuración seleccionada en ese momento.
Al iniciar la sesión de depuración de ObjectScript, asegúrate de que el archivo que contiene el programa que estás depurando está abierto en tu editor y se encuentra en la pestaña activa. VS Code iniciará una sesión de depuración con el servidor del archivo en el editor activo (la pestaña en la que está centrado el usuario). Esto también se aplica a las sesiones de depuración ObjectScript adjuntas.
Esta extensión utiliza WebSockets para comunicarse con el servidor de InterSystems durante la depuración. Si tienes problemas al intentar iniciar una sesión de depuración, comprueba que el servidor web de InterSystems permite las conexiones WebSocket.
Los comandos de depuración y los elementos del menú Run funcionan prácticamente igual que en otros lenguajes compatibles con VS Code. Para más información sobre la depuración de VS Code, consulta la documentación enumerada al final de este artículo.

Establecer la sincronización entre un código fuente local y un código fuente del servidor (en IRIS Server)

También es importante tener una estructura de carpetas para el código fuente, que puede adoptarse mediante la configuración de "objectscript.export". Esta información se utilizará para convertir los nombres de clase del servidor en archivos locales. Si es incorrecto, puede abrir clases en el modo de solo lectura aunque solo existan de forma local.
1.    Abre el archivo .vscode\settings.json y configura objectscript.export:

2.    Pasa el ratón por encima de la carpeta y añade Categoría y otros parámetros para ver la documentación sobre ella.

Otras técnicas para complementar el proceso de depuración

Además de depurar tu programa, recuerdaa documentar bien tu código fuente, registrar las operaciones realizadas por el código importante y realizar pruebas unitarias y herramientas de análisis estático en el código fuente. De esta manera, la calidad de tus programas será mucho mejor, reduciendo el tiempo y el coste de ajustes y mantenimiento.

Para saber más

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