Modernize seu aplicativo de mainframe

Prévia

Este produto ou recurso está sujeitos aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Para mais informações, consulte as descrições das fases de lançamento.

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

A reescrita de código de modernização de mainframe permite uma abordagem iterativa para reescrever o código para clientes e parceiros. Normalmente, ela é usada após a conclusão de uma avaliação com a Mainframe Assessment Tool (MAT). Essa extensão integra recursos de IA generativa para mainframe para análise, especificação, geração e teste de código, 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.

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

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

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

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

Para ativar a reescrita de código da modernização do 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 da modernização do 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 Desenvolvedor: recarregar janela.

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

Para conectar a reescrita de código da 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 recém-aberta.

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

4. Selecione o projeto que você quer usar.

5. Execute o comando Desenvolvedor: recarregar janela.

Depois de configurar, abra qualquer espaço de trabalho ou pasta que inclua código de mainframe e execute os comandos Gerar resumo de especificação e Gerar código modernizado em COBOL, JCL, Easytrieve e HLASM.

Gerar resumo da especificação

O comando Cloud Code: gerar resumo de especificação para arquivo ativo permite criar uma especificação de linguagem neutra para seu código legado de mainframe. 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: gerar resumo da especificação para arquivo ativo.

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 preferido e selecione Gerar resumo da especificação.

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

Anotar código legado de mainframe

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

Job JCL



Programa COBOL



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

2. Quando a anotação for salva, use o comando Gerar resumo da especificação para gerar uma especificação para seu job/programa, com base no seu comentário.

   Depois, 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: gerar código modernizado para arquivo ativo permite criar código moderno com base no código legado do mainframe.

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

Linguagens de destino compatíveis: Java, C#, Python, 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: gerar código modernizado para arquivo ativo.

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

   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 código modernizado e selecione Gerar código modernizado.

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

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

Modificar configurações

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

Para modificar as configurações no nível do espaço de trabalho, pressione Ctrl/Cmd+Shift+P para abrir a paleta de comandos e selecione o comando Preferências: Abrir configurações do espaço de trabalho (JSON).

Para modificar as configurações no nível das configurações globais do usuário, pressione Ctrl/Cmd+Shift+P para abrir a paleta de comandos e selecione o comando Preferências: abrir configurações do usuário (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.5-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 o Logging está ativado 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 de modernização de mainframe usa o modelo do Gemini especificado na configuração.

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

• Exemplo 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.5-pro".

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

Idioma de destino

Quando essa propriedade de configuração é definida, o comando Gerar código modernizado não pede mais que você selecione a linguagem de destino ao gerar código, e usa a linguagem definida na propriedade.

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

• Exemplo 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 Gerar código modernizado transmite a lista especificada de dicas de conjunto de tecnologias como instruções adicionais para o LLM ao gerar código. Essa configuração pode ser usada como uma orientação para ajustar a arquitetura de destino, os frameworks e o estilo de 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 conjunto de tecnologias).

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

Para remover todos os dados armazenados localmente pela reescrita de código de modernização do mainframe no 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

Nesta seção, descrevemos os problemas conhecidos da reescrita de código da modernização do mainframe e fornecemos etapas de solução de problemas:

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

Se os comandos Gerar resumo da especificação ou Gerar código modernizado forem executados por muito tempo e falharem, talvez a API Vertex AI não esteja habilitada ou tenha excedido a cota no projeto selecionado. Para confirmar que este é o problema, clique no botão Acessar saída.

Se o botão Acessar 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 failed". Por exemplo, esta é uma mensagem de erro causada pela API Vertex AI não estar 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 projeto Google Cloud 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 Gerar resumo da especificação ou Gerar código modernizado não estiverem disponíveis na paleta de comandos, isso pode indicar que a ferramenta de linha de comando do Mainframe Modernization 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

Se for esse o 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 faltando.
4. Abra a paleta de comandos novamente com Ctrl/Cmd+Shift+P.
5. Selecione o comando Desenvolvedor: recarregar janela.

Inspecionar o canal de saída

Para resolver outros erros não listados neste guia, tente inspecionar o canal de saída da extensão. Para abrir o canal de saída, faça o seguinte:

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