Modernize seu aplicativo de mainframe

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Neste guia, você vai aprender a usar a extensão Cloud Code para VS Code para modernizar seu aplicativo mainframe legado.

A reescrita de código de modernização de mainframe permite uma abordagem iterativa para a reescrita de código para clientes e parceiros. Geralmente, ela é usada após a conclusão de uma avaliação com a Mainframe Assessment Tool (MAT). Essa extensão integra os recursos do Mainframe GenAI para análise de código, especificação, geração de código e geração de teste, oferecendo uma experiência de desenvolvimento interativa.

Antes de começar

Observação: recomendamos usar esse recurso em espaços de trabalho limitados a um máximo de 5 milhões de linhas de código no total.

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Vertex AI API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Vertex AI API.

   Enable the API

8. Instale a extensão do Cloud Code, caso ainda não tenha feito isso.
9. Instale a CLI do Google Cloud, caso ainda não tenha feito isso.

Configurar a reescrita de código para a modernização de mainframe

As seções a seguir descrevem como configurar a reescrita de código para modernização de mainframe. Primeiro, ative a reescrita de código de modernização de mainframe no seu ambiente de desenvolvimento integrado e, depois, conecte-a à Vertex AI.

Ativar a reescrita de código de modernização de mainframe

Para ativar a reescrita de código de modernização de mainframe, siga estas etapas:

1. Abra a paleta de comandos com Ctrl/Cmd+Shift+P.

2. Selecione o comando Preferências: abrir configurações do usuário (JSON).

   Para ativar a reescrita de código de modernização de mainframe, adicione a configuração "cloudcode.beta.enableMainframeModernization": true ao arquivo settings.json:

   {
       "cloudcode.updateChannel": "Insiders",
       "cloudcode.beta.enableMainframeModernization": true
   }
   

3. Abra a paleta de comandos novamente (pressione Ctrl/Cmd+Shift+P) e selecione o comando Developer: Reload Window.

Conectar a reescrita de código de modernização de mainframe à Vertex AI

Para conectar a reescrita de código de modernização de mainframe à Vertex AI, siga estas etapas:

1. Em uma janela de terminal, execute o comando a seguir:

   gcloud auth application-default login
   

2. Siga as instruções na tela na janela do navegador da Web que foi aberta.

3. Siga as instruções para fazer login no Google Cloud.

4. Selecione o projeto que você quer usar.

5. Execute o comando Developer: Reload Window.

Depois de configurar, você pode abrir qualquer espaço de trabalho ou pasta que inclua código de mainframe e executar os comandos Generate Specification Summary e Generate Modernized Code em COBOL, JCL, Easytrieve e HLASM.

Gerar resumo da especificação

O comando Cloud Code: Generate Specification Summary for Active File permite criar uma especificação de linguagem neutra para seu código de mainframe legada. COBOL, JCL, Easytrieve e HLASM são compatíveis.

É possível acessar um resumo da especificação na Paleta de comandos ou na visualização do Explorer:

Paleta de comandos

1. No editor, selecione o arquivo de origem que você quer usar para torná-lo o arquivo ativo.

2. Para abrir a paleta de comandos, pressione Ctrl/Cmd+Shift+P.

3. Pesquise e selecione o comando Cloud Code: Generate Specification Summary for Active File.

Um resumo da especificação aparece ao lado do código.

Explorador

1. Na barra de atividades, clique em Explorer ou pressione Ctrl/Cmd + Shift + E.

2. Clique com o botão direito do mouse no arquivo de origem desejado e selecione Gerar resumo de especificação.

Um resumo da especificação aparece ao lado do código.

Anotar o código legado do mainframe

Para orientar o processo de geração de resumo de especificação, adicione comentários ao seu código legado. Para anotar um job JCL ou um programa COBOL, procure o botão add Add ao lado da linha de definição do job/programa:

Job do JCL

Programa COBOL

1. Para abrir uma visualização inline do CMS que permite anotar seu trabalho/programa, clique em adicionar Adicionar. Depois de adicionar o comentário, clique em Criar nota para salvar.

2. Quando a anotação for salva, use o comando Generate Specification Summary para gerar uma especificação para seu job/programa, guiada pelo seu comentário.

   Você pode editar a anotação para refinar a orientação fornecida ou excluí-la se não quiser mais que o modelo a considere.

Gerar código modernizado

O comando Cloud Code: Generate Modernized Code for Active File permite criar um código moderno a partir do código legado do mainframe.

Linguagens de origem compatíveis: COBOL, JCL, Easytrieve e HLASM.

Linguagens de destino compatíveis: Java, C#, Python e SQL.

É possível acessar esse comando na Paleta de comandos ou na visualização do Explorer:

Paleta de comandos

1. No editor, selecione o arquivo de origem que você quer usar para torná-lo o arquivo ativo.

2. Abra a paleta de comandos pressionando Ctrl/Cmd+Shift+P.

3. Pesquise e selecione o comando Cloud Code: Generate Modernized Code for Active File.

4. Selecione o idioma de destino em que você quer que o código modernizado seja gerado.

   O código modernizado gerado aparece no editor como um novo arquivo sem título.

Explorador

1. Na barra de atividades, clique em Explorer ou pressione Ctrl/Cmd + Shift + E.

2. Clique com o botão direito do mouse no arquivo de origem para o qual você quer gerar o código modernizado e selecione Generate Modernized Code.

3. Selecione o idioma de destino em que você quer que o código modernizado seja gerado.

   O código modernizado gerado aparece no editor como um novo arquivo sem título.

Modificar configurações

A reescrita de código da modernização de mainframe tem as seguintes configurações que podem ser configuradas no escopo do espaço de trabalho ou no escopo das configurações do usuário (global).

Para modificar as configurações no espaço de trabalho, pressione Ctrl/Cmd+Shift+P para abrir a paleta de comandos e selecione o comando Preferences: Open Workspace Settings (JSON).

Para modificar as configurações no nível global do usuário, pressione Ctrl/Cmd+Shift+P para abrir a paleta de comandos e selecione o comando Preferences: Open User Settings (JSON).

Confira um exemplo de um arquivo settings.json que inclui todas as propriedades de configuração da extensão:

{
    "cloudcode.beta.enableMainframeModernization": true,
    "cloudcode.beta.mainframeModernization.enableGoogleAnalytics": true,
    "cloudcode.beta.mainframeModernization.enableCloudLogging": false,
    "cloudcode.beta.mainframeModernization.model": "gemini-2.0-pro",
    "cloudcode.beta.mainframeModernization.codeGenerationSettings.targetLanguage": "csharp",
    "cloudcode.beta.mainframeModernization.codeGenerationSettings.techStackHints": [
        "Do not print messages directly to the console; use a logging framework instead."
    ],
}

Ativar e desativar o Google Analytics

Essa propriedade de configuração ativa ou desativa a coleta de análises de uso da extensão.

• Nome da propriedade de configuração: cloudcode.beta.mainframeModernization.enableGoogleAnalytics.

• Exemplo de valor de configuração: false.

• Valor padrão: true (o Google Analytics está ativado).

Ativar e desativar o Cloud Logging

Essa propriedade de configuração controla se a geração de registros está ativada ou não.

• Nome da propriedade de configuração: cloudcode.beta.mainframeModernization.enableCloudLogging.

• Exemplo de valor de configuração: true.

• Valor padrão: false (o Cloud Logging está desativado).

Modelo

Quando essa propriedade de configuração é definida, a reescrita de código da modernização do mainframe usa o modelo Gemini especificado na configuração.

• Nome da propriedade de configuração: cloudcode.beta.mainframeModernization.model

• Exemplos de valores de configuração: "gemini-1.5-flash", "gemini-1.5-pro", "gemini-2.0-flash", "gemini-2.0-flash-lite" ou "gemini-2.0-pro".

• Valor padrão: "(default)" (Perguntar sempre).

Idioma de destino

Quando essa propriedade de configuração é definida, o comando Generate Modernized Code não solicita mais que você selecione o idioma de destino ao gerar o código e usa o idioma definido na propriedade.

• Nome da propriedade de configuração: cloudcode.beta.mainframeModernization.codeGenerationSettings.targetLanguage

• Exemplos de valores de configuração: "java", "csharp", "python" ou "pgsql".

• Valor padrão: null (Perguntar sempre).

Dicas de conjunto de tecnologias para geração de código

Quando essa propriedade de configuração é definida, o comando Generate Modernized Code transmite a lista especificada de dicas de stack de tecnologia como instruções adicionais para o LLM ao gerar o código. Essa configuração pode ser usada como orientação para ajustar a arquitetura de destino, os frameworks e o estilo do código.

• Nome da propriedade de configuração: cloudcode.beta.mainframeModernization.codeGenerationSettings.techStackHints

• Exemplo de valor de configuração:

  [
    "Do not print messages directly to the console; use a logging framework instead.",
    "when generating java code - use Spring Boot version 3 as the framework"
  ]
  

• Valor padrão: [] (uma lista vazia, sem dicas de stack de tecnologia).

Excluir dados de reescrita de código de modernização de mainframe

Para remover todos os dados armazenados localmente pela Reescrita de código de modernização de mainframe para o espaço de trabalho atual, siga estas etapas:

1. Abra o terminal selecionando View > Terminal na barra de menus ou pressionando o atalho de teclado ⌃.

2. Digite os seguintes comandos no terminal:

Linux (Bash ou Zsh)

workspace_id=$(printf %s "$PWD$(stat -c '%i' .)" | md5sum | head -c 32)
workspace_storage_dir="$HOME/.config/Code/User/workspaceStorage/$workspace_id"
rm -r "$workspace_storage_dir/googlecloudtools.cloudcode/mainframe/"

Windows (PowerShell)

$workspacePath = (Get-Location).ToString()

$tempFile = (New-TemporaryFile).FullName
($workspacePath.Substring(0, 1).ToLower() + $workspacePath.Substring(1) +
    (([decimal](Get-Date (Get-ItemProperty . |
        Select-Object -ExpandProperty CreationTimeUtc) -UFormat %s) * 1000) -split '\.')[0]
) | Out-File -FilePath $tempFile -Encoding ascii -NoNewline
$workspaceId = (Get-FileHash -Algorithm MD5 -Path $tempFile).Hash.ToLower()
Remove-Item $tempFile

$workspaceStorageDir = "$env:APPDATA\Code\User\workspaceStorage\$workspaceId"
Remove-Item -Recurse "$workspaceStorageDir\googlecloudtools.cloudcode\mainframe"

Resolver problemas

Esta seção descreve os problemas conhecidos da reescrita de código da modernização do mainframe e oferece etapas de solução de problemas:

A Vertex AI não está disponível no projeto Google Cloud

Se os comandos Generate Specification Summary ou Generate Modernized Code forem executados por muito tempo e falharem, a API Vertex AI pode não estar ativada ou ter excedido a cota no projeto selecionado. Para confirmar se esse é o problema, clique no botão Ir para a saída.

Se o botão Ir para a saída não estiver disponível, siga as etapas em Inspecionar o canal de saída. No canal de saída, procure uma mensagem de erro que contenha "Vertex.GenerateContent falhou". Por exemplo, esta é uma mensagem de erro causada pela API Vertex AI que não está ativada no projeto Google Cloud selecionado:

"generic::unknown: retry budget exhausted (30 attempts): Vertex.GenerateContent failed: 403 Forbidden (403)"

Para resolver esse problema:

• Confirme se a API Vertex AI está ativada no projeto Google Cloud.

• Mude para outro Google Cloud projeto com a API Vertex AI ativada.

Os comandos de reescrita de código da modernização de mainframe não estão disponíveis

Se comandos como Generate Specification Summary ou Generate Modernized Code não estiverem disponíveis na paleta de comandos, isso pode indicar que a ferramenta CLI de modernização de mainframe não foi instalada. Para confirmar se esse é o caso, verifique se o seguinte arquivo executável está ausente:

• No Linux: ~/.cache/cloud-code/mainframe/bin/codegen
• No Windows: %LOCALAPPDATA%\cloud-code\mainframe\bin\codegen.exe
• No macOS: $HOME/Library/Application Support/cloud-code/mainframe/bin/codegen_macos

Nesse caso, tente resolver o problema realizando as seguintes tarefas:

1. Abra a paleta de comandos com Ctrl/Cmd+Shift+P.
2. Selecione o comando Cloud Code: instalar ou atualizar ferramentas de modernização de mainframe.
3. Verifique se o arquivo executável não está mais ausente.
4. Abra a paleta de comandos novamente com Ctrl/Cmd+Shift+P.
5. Selecione o comando Developer: Reload Window.

Inspecionar o canal de saída

Para resolver outros erros não listados em outro lugar neste guia, tente inspecionar o canal de saída da extensão. Para abrir o canal de saída, execute estas tarefas:

1. Abra a paleta de comandos com Ctrl/Cmd+Shift+P.
2. Selecione o comando Output: Show Output Channels.
3. Selecione o canal de saída Modernização de mainframe do Cloud Code.