Páginas filhas
  • 02 - Instalação VSCode + extensão TOTVS Developer Studio - LGX

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.


INTRODUÇÃO


O editor de código-fonte Visual Studio Code, ou simplesmente VSCode, é ferramenta multiplataforma e amplamente utilizada para desenvolvimento com várias linguagens de programação através da instalação de extensões (plugins).

TOTVS desenvolveu a extensão TOTVS Developer Studio Code para desenvolvimento nas linguagens ADVPL4GL e TLPP, sendo que a linguagem 4GL, utilizada para desenvolvimento do produto LOGIX, está disponível para uso desde o início do 2o semestre de 2020.

A seguir serão apresentados tópicos resumidos envolvendo algumas dicas e procedimentos de instalação e configuração do VSCode e extenão TDS for VSCode, sendo que em alguns pontos serão apenas apontados alguns links de páginas oficiais existentes no site GitHub onde encontram-se as documentações oficiais da ferramenta.


Section
Column
width10%



PASSO A PASSO

Column
width90%

Expandir
titleInstalação VSCode


Se você ainda não tem o editor VSCode instalado, acesse https://code.visualstudio.com/, faça o download para a plataforma desejada e instale conforme passo-a-passo do site oficial.


Dica
titleDICA

Na instalação Windows, o instalador sugere a pasta local do usuário por padrão e recomendamos manter esta sugestão, pois ao instalar na pasta de Arquivos de Programas do Windows, alguns controles de segurança do Windows podem impedir algumas atualizações futuras envolvendo VSCode ou até atualizações de extensões, dependendo do nível de segurança ativo no Windows.



Expandir
titleInstalação plugin TOTVS Developer Studio Code

A partir do editor VSCode, acompanhando a ilustração de itens na imagem abaixo, acesse na barra de ferramentas disponível na lateral esquerda na posição vertical, o atalho de extensões do VSCode, destacado no item (1) abaixo, informe "TDS" na caixa superior de filtro, item (2), selecione a extensão TOTVS Developer Studio for VSCode (AdvPL, TLPP e 4GL) conforme mostra o item(3) e cliquei em INSTALL item (4).



Informações
iconfalse

Para documentação completa sobre a extensão TDS for VSCode acesse https://github.com/totvs/tds-vscode, que contém o passo-a-passo de instalação e várias dicas de configuração.



Expandir
titleConfigurando o ENCODE (formato de edição) de arquivos no VSCode

No Logix o formato de codificação padrão dos códigos fonte é ISO8859-1 ou CP1252 e para que isso seja reconhecido automaticamente no VSCode é preciso configurar a lista de extensões dos arquivos fontes previstos para cada linguagem, sendo que no Logix fazemos uso atualmente de 3 linguagens de desenvolvimento, sendo: 4GL, ADVPL e TLPP, sendo esta última prevista a partir do build Harpia.


Siga o passo a passo abaixo e veja como é simples configurar as extensões de arquivos por linguagem no VSCode e depois indicar o formato de codificação padrão de cada extensão.


No VSCode acesse no menu  File | Preferences | Settings (Arquivo >> Preferências >> Configurações)  e, conforme mostra a imagem abaixo, acesse a aba User item (1), opção Extensions item (2) e a direita acesse o link descrito comoEdit in settings.jsonitem (3) para abrir o arquivo de configurações do usuário do VSCode.


Com o arquivo settings.json aberto para edição inclua as configurações abaixo, verificando sempre se as respectivas chaves já estão informadas, para que não sejam registradas de forma duplicada.

Painel
borderColor#C0C0C0
borderStyledashed

     Losango - ícones de formas grátis  A chave files.encoding é comum já existir e neste caso basta ajustar o seu conteúdo para utf8, conforme mostra o quadro abaixo.

         Losango - ícones de formas grátis  Informe este bloco no final do arquivo e cuide com o delimitador das chaves no arquivo JSON que precisa sempre usar vírgula ( , ) entre uma chave e outra.



Bloco de código
languagegroovy
themeMidnight
titleChaves a serem definidas no arquivo settings.json do usuário no VSCode
    "files.encoding": "utf8",
    "files.associations": {
        "*.ini": "advpl",
        "*.pro": "4gl",
        "*.4gl": "4gl",
        "*.cnv": "4gl",
        "*.xml": "4gl",
        "*.per": "4gl",
        "*.msg": "4gl",
        "*.prw": "advpl",
        "*.apw": "advpl",
        "*.prg": "advpl",
        "*.prx": "advpl",
        "*.tlpp": "advpl",
        "*.ppp": "advpl",
        "*.ppx": "advpl",
        "*.apl": "advpl",
        "*.aph": "advpl",
        "*.ahu": "advpl",
        "*.tres": "advpl",
        "*.res": "advpl",
        "*.txt": "advpl"
    },
    "[4gl]": {
        "files.encoding": "iso88591"
    },
    "[advpl]": {
        "files.encoding": "windows1252",
    }


Salve o arquivo e a partir de agora seu editor VSCode já irá abrir cada fonte desenvolvido no LOGIX respeitando o formato de codificação (ENCODE) correto para não gerar problemas durante a execução do produto após compilação dos fontes, onde podem ser exibidas os textos em telas e mensagens contendo caracteres estranhos, por terem sido salvos com ENCODE incorreto.

Caso surja mais alguma extensão de arquivo que não esteja na lista acima, pode ser adicionada, desde que respeitando o formato e delimitadores das chaves e valores no arquivo settings.json.



Expandir
titleCriando nova workspace de desenvolvimento

Para criar um espaço de trabalho (Workspace) para desenvolvimento no LOGIX, a exemplo do TDS (Totvs Developer Studio) podíamos indicar uma pasta para armazenar todas as configurações desejadas, onde tínhamos um projeto com a lista de fontes em formato de árvore (TreeView) e também era possível configurar a lista de pastas de includes para o projeto (utilizados para compilação de fontes ADVPL).

Para o VSCode isso não muda, pois também é possível abrir tanto um único arquivo como uma pasta completa e no caso de abertura de uma pasta o VSCode entende que estamos definindo um novo espaço de trabalho (Workspace), onde então ele cria automaticamente uma subpasta chamada .vscode\ onde irá armazenar todos os arquivos das configurações utilizadas.

Toda vez que uma pasta nova é aberta a partir do VSCode e consequentemente uma nova Workspace é criada, por padrão será apresentada uma tela de Boas Vindas conforme imagem abaixo:



Nesta tela você deverá:


Informar o atalho completo do Smartclient que será utilizado para execução.

Por padrão a extensão TDS VSCode traz o atalho como "c:/totvs/bin/smartclient/smartclient.exe", mas basta acionar o botão e selecionar o caminho correto do executável do smartclient que será utilizado. 

Dica
iconfalse

É possível criar novos atalhos para Smartclients localizados em outras pastas quando for necessário, mas isso será citado em outro tópico adiante.


Informar as pastas de localização dos arquivos de INCLUDES.

Estas pastas são utilizadas para compilação de fontes desenvolvidos na linguagem ADVPL, sendo as pastas separadas por ponto e vírgula.

No caso de fontes 4GL não é necessário informar este campo.


A janela de Boas Vindas não aparece?

Para ativar ou desativar a exibição da janela de Boas Vindas é preciso mudar a configuração Totvs Language Server: Welcome Page (File | Preferences | Settings | Extensions | TOTVS | Welcome Page) conforme mostra o vídeo abaixo:



Expandir
titleConfigurando atalhos do Smartclient (Launchers)

Para ajustar configurações de um atalho existente d do Smartclient é possível acionar a partir da lista de comandos no VsCode o comando TOTVS:Configure Launchers.

Pressione o atalho CTRL+SHIFT+P e informe o filtro do comando como "TOTVS" conforme imagem abaixo e selecione TOTVS:Configure Launchers


Selecione a opção TOTVS:Configure Launchers


Será apresentada esta janela para configurar um novo atalho (Launcher) para o Smartclient desejado.


Selecione em Choose launcher o atalho do Smartclient que deseja alterar as configurações e ajuste as configurações necessárias. 

É recomendado sempre marcar as OPÇÕES e ARGUMENTOS acima já sinalizados, pois auxiliam no processo de DEBUG, permitem execução paralela com outras seções de Smartclient em execução e ajustam a qualidade de escala de interface.

O Argumento é indicado utilizar para manter a escala de tamanho de textos e imagens das telas em 100%, pois quando a escala configurada no monitor estiver superior a 100% as imagens tendem a perder qualidade de exibição e as letras podem ficar desproporcionais, gerando um pouco de desconforto para o usuário.


É possível também registrar alterações dos atalhos do Smartclient diretamente no arquivo de configuração de forma manual no arquivo /.vscode/launch.json existente na pasta de workspace aberta no VsCode.

Para isso a partir do editor VSCode, acompanhando a ilustração de itens na imagem abaixo, acesse na barra de ferramentas disponível na lateral esquerda na posição vertical, o atalho de excução "Run and Debug", destacado no item (1) abaixo, em seguida selecione o atalho do smartclient desejado item (2)  e em seguida clique sobre o botão de configurações ao lado item (3) para que seja possível abrir para edição o arquivo launch.json correto, já que para cada Workspace criada no TDS-VSCode existirá um arquivo launch.json diferente com a configuração de atalhos de Smartclient.





Veja que no conteúdo do arquivo launch.json, existe um conjunto de chaves para cada configuração de atalho de Smartclient já criado e que é apresentado para uso no ambiente item (2).


No quadro representado pelo item (4), ajuste o valor das chaves desejadas, como:

  • Caminho do executável do Smartclient (smartclientBin).
  • Título para exibição do atalho para seleção (name).
  • Permitir execução de múltiplas sessões de Smartclient (isMultiSession).  Recomedado manter como TRUE para não bloquear execução com outra execução de Smartclient em uso.
  • Permitir execução MultiThread (enableMultiThread). Recomendado manter como TRUE para que a depuração de fontes linha a linha esteja acessível.


Para criar um novo atalho de Smartclient, basta copiar o bloco completo de uma configuração de smartclient e logo abaixo colar como um novo bloco e realizar as alterações necessárias para o novo atalho, como Nome, Caminho do Smartclient, etc.



(aviso) Atente para não esquecer de colocar uma vírgula após o fechamento do bloco, após o "}" (fechamento de chaves) para não invalidar o formato JSON do arquivo de configuração. (aviso)




Expandir
titleCriando conexão com AppServer


Painel
bgColoryellow
borderStylesolid
titlePRÉ-REQUISITOS ANTES DE CRIAR CONEXÃO COM APPSERVER NO VSCODE
  • BUILD 7.00.131227A (32 bits) → Utilizar revisão 13.1.3.53 ou superior
  • BUILD 7.00.210324P (64 bits - HARPIA) → Utilizar revisão atualizada disponível para desenvolvimento 20.3.0.xx ou superior
  • Extensão TDS-VSCode sempre atualizada → Versão 1.3.12 ou superior
  • Manter versão do VSCode atualizada
  • Ter um RPO Logix válido pacote 12.1.29 ou superior já disponível na pasta configurada no ambiente Logix do arquivo INI do AppServer, pois será feita requisição de usuário e senha Logix para realizar autenticação e ter acesso ao RPO.



Para criar uma conexão com um novo AppServer para desenvolvimento no LOGIX, a partir do editor VSCode, acompanhando a ilustração de itens na imagem abaixo, acesse na barra de ferramentas disponível na lateral esquerda na posição vertical, o atalho TOTVS AppServer  , destacado no item (1) abaixo, depois clique no na opção  na caixa superior de filtro, item(2).

Nota
titleATENÇÃO

NÃO DEIXE DE EXECUTAR TODAS INSTRUÇÕES ANTERIORES para que não tenha problemas na conexão com AppServer, ou seja, além de instalar o VSCode e a extensão TDS for VSCode, precisa já ter a Workspace definida para desenvolvimento.





Nesta tela você deverá:



Preencher os campos da tela com os dados conforme descrito em vermelho.




Expandir
titleConectando AppServer

Após conexão do AppServer já ter sido criada, deve-se registrar os ambientes de execução ou Environment, que já estão configurados no arquivo INI do AppServer.

Diferentemente de como os ambientes do AppServer eram acessados no TDS, onde ao conectar um AppServer já tínhamos disponíveis todos os ambientes para uso já registrados no AppServer, via TDS for VSCode deve-se registrar os ambientes um a um, baseados nos ambientes já registrados no arquivo INI do AppServer

Não sabe o que é um Environment ou Ambiente no AppServer?

Um ambiente ou Environment é uma seção do arquivo INI do AppServer onde configuramos o acesso para execução de programas, indicando caminho do repositório de objetos (RPO), banco de dados a ser conectado, pasta raiz do AppServer (ROOTPATH), pasta inicial de trabalhos (STARTPATH), arquivo de SCHEMA de banco de dados utilizado na compilação de fontes 4GL (arquivos com extensão .sch). Veja um exemplo abaixo de um ambiente de conexão no AppServer utilizado para execução do produto Logix:

Bloco de código
languageruby
themeConfluence
[Logix12_ora]
OUTPUTDIR=c:\totvs\logix\lst\
SOURCEPATH=c:\totvs\logix\apo
ROOTPATH=c:\totvs\logix\
STARTPATH=\totvs_data\
RPODB=SQL
RPOLANGUAGE=Portuguese
RPOVERSION=102
RPOPREFIX=lgx
SCROLLCURSORSIZE=100000000
DBALIAS=lgx12_oracle
DBDATABASE=ORACLE
FGLDBPATH=C:\TOTVS\schema\teste

01. Clique com o botão direito do mouse sobre o nome da conexão de AppServer já configurado anteriormente e selecione a opção CONNECT, conforme mostra imagem abaixo. Pode-se também clicar no ícone lateral indicado como , que tem o mesmo objetivo.


Dica
titleDICA IMPORTANTE

Para que a conexão e autenticação de usuário no ambiente do AppServer seja bem sucedido e seja possível realizar as compilações de fontes, extração de PATCH e aplicação de PATCH, já deve-se ter o RPO Logix disponível e válido devidamente configurado no AppServer.
Para não ter problemas de autenticação de usuário ao conectar um ambiente do AppServer Logix, utilize um RPO Logix oficial na versão 12.1.28 ou superior, pois existem pré-requisitos do Framework utilizados nesse processo de autenticação.

Para RPOs Logix anteriores a 12.1.28, deve-se ao menos atualizar os pacotes FIX Framework disponíveis até a versão 12.1.27.FIX01.

02. Durante o processo inicial de conexão, aguarde até que seja solicitado o nome do ambiente (Environment) do AppServer que deseja conectar.

Na primeira conexão, como ainda não existe nenhum ambiente configurado no VSCode, deve-se informar um dos ambientes já configurados no INI do AppServer, confome imagem abaixo, onde neste caso o ambiente é logix12_ora.


03. Informe um usuário Logix para a autenticação no ambiente.

A partir do uso do TDS for VSCode, é exigida autenticação de usuário para cada ambiente do AppServer, pois este dá permissão para realizar as compilações de fontes, extração e aplicação de patches.

No caso do Logix, ainda não existe um bloqueio no repositório de objetos com algum usuário específico, mas isso futuramente será implantado. Com isso pode-se informar um login de usuário qualquer, o que na imagem abaixo está como "user", mas deve  *** OBRIGATORIAMENTE *** ser informado o login de um usuário ADMINISTRADOR do banco Logix configurado para o ambiente que estiver sendo conectado.

Dica
iconfalse

Esta obrigatoriedade de informar um login e senha de usuário Logix administrador é exigida a partir do pacote LOGIX 12.1.2301.


04. Informe a senha de usuário Logix (obrigatório)


05. Após a conclusão das etapas anteriores, o ambiente será conectado com sucesso, quando o seu ícone for apresentado na cor verde, como mostra imagem abaixo.

06. É possível cadastrar mais de um ambiente para uso posterior, no entanto para isso é preciso repetir a etapa 01 e na sequência, quando for solicitado o nome do ambiente (Environment), clique no sinal de  conforme mostra imagem abaixo para cadastrar ambientes novos, ou pode-se apenas selecionar um dos ambientes já apresentados numa lista e que já estão registrados no VSCode para o AppServer.


07. Após clicar no botão anterior, informe o nome de um outro ambiente já pré-configurado no INI do AppServer e que ainda não tenha sido registrado no VSCode para o AppServer selecionado e repita os passos 03 e 04.


08. Quando o cadastro do novo ambiente for realizado com sucesso, o mesmo será apresentado na lista de ambientes do AppServer, como apresentado na imagem abaixo (TOTVS: SERVERS).

Caso necessite alterar o ambiente, basta clicar no check do ambiente desejado.

Para alternar a conexão entre ambientes, basta clicar na imagem localizada ao lado do ambiente desejado, conforme mostrado abaixo:



Expandir
titleCompilando programas

Para compilar fontes ADVPL e 4GL, o processo é bem semelhante a antiga ferramenta de desenvolvimento TDS, no entanto no VSCode a compilação dos fontes não irá mais atualizar o RPO padrão do produto, mas sim um RPO customizado, que denominamos RPO CUSTOM. Para mais informações a respeito do conceito de RPO CUSTOM acesse Instalação build HARPIA LOGIX.

Seguem algumas opções de compilação de fontes:

OPÇÃO 1

Compilação de fontes de uma pasta da Workspace em uso.

Clique com o botão direito do mouse sobre a pasta desejada  item (1) e no menu popup apresentado selecione a opção Compile File/Folder item (2).

Veja que existem também as opções:

  •  Compile All Workspace para compilar todos os fontes registrados em toda a Workspace em uso
  •  Compile Open Editors para compilar todos os fontes atualmente abertos no editor.

OPÇÃO 2 

Compilação avulsa de um fonte em edição.

Com o código fonte atualmente em edição e devidamente salvo, pode-se repetir o mesmo processo citado na OPÇÃO 1, no entanto o clique com o botão direito deverá ser realizado sobre o nome do fonte localizado na árvore de arquivos da Workspace e não sobre o nome de uma pasta.

Para um código em edição pode-se também pressionar a tecla de atalho CTRL+F9, como mostra a imagem da OPÇÃO 1, ,




Informações
iconfalse

 

Este processo de compilação de fontes de uma pasta (OPÇÃO 1) irá ignorar a compilação de fontes que forem detectados como já compilados no RPO e que não tenham sido detectadas alterações desde sua última compilação no RPO.


Para realizar a ação de RECOMPILAÇÃO (Recompile) de todos os fontes de uma pasta, Workspace ou dos fontes abertos para edição, conforme as opções do item (2) na imagem a esquerda, deve-se manter a tecla SHIFT pressionada e ai então clicar com o botão direito sobre a pasta desejada.


INFORMAÇÕES:

  • Durante o processo de compilação pode-se acompanhar o sucesso ou falha da compilação na seção OUTPUT conforme exemplo da imagem abaixo:


  • Na ocorrência de erros de compilação será registrada mensagem de alerta na seção OUTPUT e também na seção PROBLEMS, confome pode-se ver no exemplo das imagens abaixo:



Expandir
titleExecutando programas

Para executar um programa já compilado no RPO do ambiente/AppServer conectado é simples. Basta clicar na opção Run and Debug (Ctrl + Shift + D), identificado pela imagem  na barra de ferramentas lateral, conforme mostra imagem do PASSO 1, selecionar o launcher desejado e clicar no botão play.


PASSO 1

Selecione o launcher desejado e clique no play

PASSO 2 

O programa a ser executado dependerá das configurações do launcher (atalho para o Smartclient), onde é possível configurar o caminho do TOTVS Smartclient local que será utilizado para executar o programa no ambiente do AppServer conectado..

Para isto, acesse a seção anterior descrita como "Criando nova workspace de desenvolvimento" e veja como "registrar um novo atalho do SmartClient".


PASSO 3

Ao selecionar o atalho de Smartclient (Launcher) já registrado, será aberta uma tela para informar o nome do programa ou função já compilado no RPO que deseja executar.



Expandir
titleExecutando em modo DEBUG
Informações
titleCONFIGURAÇÃO PARA PERMITIR DEBUG

Existem situações onde é necessário realizar o DEBUG MultiThread e isso é comum quando existem depuração de rotinas acionadas em paralelo, como por exemplo uma requisição REST a partir da ferramenta POSTMAN


Neste caso é preciso que na configuração do atalho do SmartClient (Launcher) seja ativada a opção Multiple Threads e isso pode ser feito da seguinte forma:

  • No VSCode, acione o atalho CTRL+SHIFT+P -> Totvs: configure launchers.

  • Selecione o atalho do Smartclient já configurado (launcher) ou crie um novo conforme item(1) da imagem abaixo.
  • Marque a opção Enable Multi Threads coforme item(2) da imagem abaixo.


Dica
titleDICA

Para que possa informar o nome do programa ou function que deseja executar, sempre que for acionar este atalho do Smartclient, clique sobre o campo Program e escolha a opção , pois ai toda vez que for debugar será perguntada qual rotina deseja executar, sempre sugerindo a última informada.


Para executar um programa em modo DEBUG, basta seguir os seguintes passos:


Localize a linha desejada nos fontes e clique somente uma vez ao lado da numeração de linhas do código fonte para inserir um ponto de breakpoint.




Execute a opção Start Debugging

Ou apenas selecione o atalho do Smartclient já registrado e clique em  conforme mostra imagem abaixo:

Utilize normalmente as telas abertas durante a execução. Ao parar num ponto marcado por um breakpoint durante a execução, o processo será automaticamente interrompido para a depuração.

As opções de navegação são apresentadas na barra superior do Visual Code, onde se destacam as principais:

Continue (F5): Pula para o próximo breakpoint

Step Over (F10): Vai para a próxima linha;

Step Into (F11): Entra na função da linha (caso exista).





Expandir
titleGerando ou aplicando PATCH de atualização

As etapas a seguir apresentam uma forma de geração e aplicação de PATCH.


Geração do PATCH

Execute a opção TOTVS: Patch Generation (from RPO)


Será apresentada a tela Patch Generation.

Utilize a opção do filtro para inserir os fontes desejados e clique no botão >> para incluir na lista de geração do PATCH.


Configure os demais campos (directory, name) conforme desejado e clique no botão GENERATE ou GENERATE/CLOSE.


Aplicando PATCH

Execute a opção TOTVS: Patch Apply


Será apresentada a tela de aplicação do Patch, onde é necessário clicar no botão "Escolher arquivos"


Uma janela de seleção de arquivos do Windows será apresentada onde deve-se selecionar o arquivo de Patch desejado.


Após a seleção, utilize as opções de tela conforme desejado e clique no botão APPLY ou APPLY/CLOSE.



Expandir
titleInstalando/Atualizando TDS for VSCode a partir de arquivo .VSIX no VSCode

As atualizações do VSCode podem ser baixadas manualmente do site GITHUB no link (https://github.com/totvs/tds-vscode/releases/), preferencialmente procurando pela revisão descrita como 


Na página de releases do TDS for VSCode, o arquivo com extensão .vsix é utilizado para ser instalação manual da extensão a partir do VSCode  e é exibido na página de releases conforme exemplo na imagem abaixo:

Baixe o arquivo .VSIX e instale-o a partir do VSCode utilizando o passo a passo a seguir:

  1. Acesse a lista de extensões (CTRL+SHIFT+X), ou clique na imagem identificada pelo item(1) na imagem abaixo.
  2. A partir do menu das extensões identificado com conforme indicado pelo item(2), escolha a opção  item(3).
  3. Escolha o arquivo de extensão .VSIX que foi baixado da página de releases do TDS for VSCode no site GitHub e confirme a instalação.



Para confirmar a versão da extensão instalada, basta clicar sobre a extensão TDS for VSCode que já estará sendo exibida na lista de extensões conforme  imagem abaixo:


e na lateral direita conferir a versão da extensão conforme item(1) abaixo:


PRONTO! Sua extensão TDS for VSCode foi instalada/atualizada com sucesso. (grande sorriso)




INFORMAÇÕES COMPLEMENTARES


Para saber mais detalhes de como instalar, configurar e obter dicas de uso do TDS for VSCode, acesse o link https://marketplace.visualstudio.com/items?itemName=totvs.tds-vscode

Este link além de apresentar uma idéia geral a respeito da extensão TDS for VSCode, demonstra o passo-a-passo para instalação e configuração de algumas funcionalidades e também dispõe de link de acesso para alguns vídeos que são recomendados para melhorar a familiarização com esta solução para desenvolvimento do produto Logix.

Para reportar problemas ou até sugerir melhorias relacionadas a extensão TDS for VSCode, acesse a aba ISSUES https://github.com/totvs/tds-vscode/issues e reporte a necessidade, seguindo as orientações descritas de como realizar abertura das novas ISSUES.