Debugando código ObjectScript usando VSCode

O Visual Studio Code (VSCode) é o editor de código mais popular do mercado. Foi criado pela Microsoft e distribuído como um IDE gratuito. O VSCode suporta dezenas de linguagens de programação, incluindo ObjectScript, até 2018, Atelier (baseado no Eclipse). Foi considerado como uma das principais opções para desenvolver produtos InterSystems. No entando, em Dezembro de 2018, quando a Comunidade de Desenvolvedores InterSystems lançou suporte para o VSCode, uma porção relevante dos profissionais InterSystems começaram a realmente utilizar esse editor e isso tem sido feito desde então, especialmente os desenvolvedores trabalhando com novas tecnologias (Docker, Kubernetes, NodeJS, Angular, React, DevOps, Gitlab etc.). Algumas das melhores características do VSCode são os recursos de Debug. É por isso que esse artigo vai demonstrar em detalhes como debugar um código ObjectScript, incluindo código de classe e código de %CSP.REST.

O que é debugar?

Debugar é um processo de detectar e resolver "bugs" - erros no seu código ObjectScript. Alguns erros são lógicos, não de compilação. É por isso que para entendê-los na lógica de execução do seu código fonte, você precisa ver o programa rodar linha por linha. Esse é o melhor jeito de identificar condições ou lógica de programação e achar erros lógicos. Outros erros são os de tempo de execução. Para nós conseguirmos debugar esse tipo de problema, é essencial checar os valores das variáveis atribuídas primeiro.

Instalar todas as extensões de InterSystems IRIS para VSCode 

Antes de tudo, você deve instalar as extensões de InterSystems IRIS para o o seu IDE VSCode. Para isso, vá em Extensões, pesquise por InterSystems e instale essas extensões:

A última extensão (InterSystems ObjectScript Extension Pack) deve ser instalada primeiro, porque é um pacote de extensões requiridas para conectar, editar, desenvolver e debugar ObjectScript. As outras extensões são opcionais.

Aplicação de exemplo

Vamos usar uma aplicação do meu repositório GitHub (https://github.com/yurimarx/debug-objectscript.git)  para os exemplos de debug nesse artigo. Então, siga os passos e seguir para obter, rodar e debugar a aplicação em VSCode:
1.    Crie um diretório local e obtenha o código fonte do projeto nesse diretório:

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

2.    Abra o terminal nesse diretório (diretório iris-rest-api-template) e rode:

$ docker-compose up -d --build

3.    Abra o VSCode dentro do diretório de iris-rest-api-template usando $code . ou clique com o botão direito na pasta e selecione Abrir com Code.
4.    No rodapé, clique em ObjectScript para abrir as opções configuradas em .vscode/launch.json:

5.    Selecione Toggle Connection para habilitar a conexão atual:

6.    Após habilitar essa conexão, você a terá mostrada abaixo:

7.    Se você não está conectado em IRIS no seu VSCode, você não poderá debugar seu código ObjectScript. Então cheque sua conexão clicando na extensão ObjectScript VSCode:

8.    Abra Person.cls, vá para a linha número 25 e aponte o mouse para o número 25 à sua esquerda.

9.    Agora, aponte o mouse acima de ClassMethod e clique em Debugar esse método:

10.    O VSCode vai abrir um Diálogo para você setar valores para os parâmetros, então defina os valores como os demonstrados abaixo e clique em Enter:

11.    O VSCode vai quebrar a execução do código na linha 25:

12.    Agora, no topo à esquerda, você pode ver os valores atuais das variáveis.

13.    Abaixo à esquerda, você pode ver a lista de Breakpoints e a pilha de chamadas para o breakpoint atual.

14.     No topo à direita, você pode ver o código fonte com o breakpoint e um conjunto de botões para controlar a execução de debugar.

15.    Se você precisa usar o Console de Debug para escrever algo, digite: Name_","_Title para ver a concatenação das variáveis  usando o Console de Debug:

16.    Selecione a variável de resultado, clique com o botão direito do mouse e selecione Add to Watch:

17.    Agora você pode monitorar ou mudar o valor atual da variável resultante na seção WATCH:

18.    Por fim, a barra de rodapé é laranja e indica o debug:

Usando o Console de Debug

O  Console de Debug permite que você escreva expressões durante o Debug, então você pode checar valores de diferentes variáveis (tipo simples ou tipo objeto) ou validar o valor atual e outras condições. Ele pode executar qualquer coisa que possa retornar alguns valores, então  $zv vai funcionar também. Siga esses passos para ver algumas opções:

1.    Escreva Name_","_Title_" From "_Company no prompt do Terminal de Debug e veja os valores de Name, Title e Company concatenados como output:

Usando a Barra de Ferramentas de Debug

A Barra de Ferramentas de Debug permite que você controle a execução do debug, então cheque as funções dos botões aqui:

1.    Botão de continuar (F9): continua a execução até o próximo ponto de parada. Se não há ponto de parada, segue até o final.
2.    Pular (F8): vá para a próxim alinha sem entrar no código fonte de um método interno (não entre no método Populate)
3.    Entrar (F7): vá para a próxima linha dentro do código fonte do método interno (vá para a primeira linha do método Populate)
4.    Sair (Shift + F8): vá para a linha atual do código fonte chamador do método.
5.    Recomeçar: (Ctrl +Shift + F5): recomece o debug.
6.    Parar: para a sessão de debug.

Debugando métodos de classe de %CSP.REST

Para debugar métodos de classe REST, é necessário aplicar um pequeno truque revelado pelo Fábio Gonçalves (cheque aqui o artigo https://community.intersystems.com/post/atelier-debugging-attach-process). É necessário adicionar um HANG (minha recomendação é entre 20 e 30 segundos). Simplesmente siga esses passos:

1.    Abra o Arquivo src\dc\Sample\PersonREST.cls e vá para o método GetInfo(), adicione HANG 30 (isso é necessário para ganhar tempo, 30 segundos, para começar o debug desse método):

2.    Defina pontos de parada nas linhas do HANG e do SET version (círculos vermelhos):

3.    Abra um client HTTP para chamar um método REST (vou chamar GetInfo da classe PersonREST):

4.    Defina Basic Auth para Authorization (Usuário _SYSTEM e Senha SYS):

5.    Envie um GET http://localhost:52773/crud/.
6.    Clique em ObjectScript Attach na barra de rodapé:

7.    Escolha ObjectScript Attach:

8.    Escolha o processo de PersonREST:

9.    Espere um tempo (cerca de 30 segundos) para o VSCode quebrar a execução atual no ponto de parada:

Nota 1: remova o HANG 30 quando acabar o debug, porque o HANG vai pausar a execução.

Nota 2: se o processo PersonREST não aparecer, reinicie seu VSCode e tente novamente.

10.    Agora você pode fazer seu processo de debug.

Editar ponto de parada

Você pode clicar com o botão direito no ponto de parada para remover ou configurar pontos de parada condicionais (parar no ponto de parada com uma condição verdadeira). O comando de parada integrado no código também será percebido pelo debugger. Você pode tentar isso também.

1.    Clique com o botão direito no ponto de parada e selecione Edit Breakpoint:

2.    Entre na expressão mencionada abaixo e pressione Enter:

Nota: tente versão = 1.0.5 para ver o ponto de parada falso e 1.0.6 para ver o ponto de parada verdadeiro.

Configure opções de debug em .vscode/launch.json

O arquivo Launch.json é usado para configurar opções de debug para o seu projeto. Para ver alternativas, vá para esse arquivo:

Para esse exemplo, temos duas opções para selecionar para debugar:

1.    Podemos lançar o debug na classe configurada no atributo do programa diretamente com um programa (nesse exemplo o debugador vai começar na classe PackageSample.ObjectScript, método Test()).
2.    Podemos anexar PickProcess para o processo do programa selecionado que queira debugar. Nesse exemplo o debugador vai abrir no topo uma lista de processos para selecionar qual processo (cada programa tem seu processo) será debugado. A segunda opção é mais comum.

Em geral, esses atributos são obrigatórios para qualquer configuração de debug (fonte: https://intersystems-community.github.io/vscode-objectscript/rundebug/):

• type - Identifica o tipo de debugador para usar. Nesse caso, objectscript é fornecido pela extensão InterSystems ObjectScript.
• request - Identifica o tipo de ação para essa configuração de lançamento. Possíveis valores são launch e attach.
• name - Um nome arbitrário para identificar a configuração. Esse nome aparece na lista suspensa ao clicar Start Debugging.

Em adição, para uma configuração de lançamento ObjectScript, você precisa fornecer o programa de atributos, que especifica a rotina ou ClassMethod para rodar quando lança o debugador, como mostrado no exemplo:

"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 uma configuração de anexo ObjectScript, você deve fornecer os seguintes atributos:

• processId - Especifica o ID do processo para anexar a uma string ou número. O padrão é "${command:PickProcess}" prove uma lista suspensa de IDs de processo para anexar em tempo de execução.
• system - Especifica se deve ou não permitir anexos para o processo de sistema. O padrão é falso.

O exemplo a seguir mostra múltiplas configurações de anexo ObjectScript válidas:

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

Agora, você pode selecionar uma configuração da lista que o VSCode fornece no campo Run and Debug no topo da barra lateral de debug (fonte: https://intersystems-community.github.io/vscode-objectscript/rundebug/):

Se você clicar na seta verde, a configuração atualmente selecionada irá rodar.

Ao começar um lançamento de sessão de debug ObjectScript, esteja seguro que o arquivo contendo o programa que você está debugando está aberto no seu editor e está na aba ativa. O VS Code vai começar uma sessão de debug com o servidor do arquivo no editor ativo (a aba em que o usuário está focado). Isso também se aplica para sessões de debug ObjectScript anexadas.

Essa extensão usa WebSockets para se comunicar com o servidor InterSystems durante o debug. Se você está tendo problemas quando tenta começar uma sessão de debug, cheque se o servidor web do servidor InterSystems permite conexões WebSocket.

Comandos de debug e itens na menu Run funcionam basicamente da mesma maneira que funcionam para outras linguagens suportadas pelo VS Code. Para informações adicionais no debug do VS Code, veja os recursos da documentação listada no começo dessa seção. 

Definir a sincronização entre um código fonte local e um código fonte do servidor (no servidor IRIS)

Também é importante ter uma estrutura de pastas para o código fonte, que pode ser adotada pelas configurações de "objectscript.export". Essa informação será usada para converter os nomes das classes do servidor para arquivos locais. Se estiver incorreta, pode abrir classes no modo de leitura mesmo se existirem só localmente.
1.    Abra .vscode\settings.json arquivo e configure objectscript.export:

2.    Passe o mouse por cima da pasta e adicione Categoria e outros parâmetros para ver a documentação dela.

Outras técnicas para complementar o processo de debug

Em adição ao seu programa de debug, lembre-se de documentar bem o seu código fonte, logar operações performadas por códigos importantes e performar testes unitários e ferramentas de análise estáticas de códigos fonte. Dessa forma, a qualidade dos seus programas será muito melhor, reduzindo manutenção e tempo de ajuste e custo.

Aprendendo mais

Você pode ler mais sobre debugar ObjectScript no VSCode se olhar esses recursos:
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