Modernize a sua aplicação de mainframe

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Neste guia, vai aprender a usar a extensão Cloud Code para VS Code para modernizar a sua aplicação de mainframe antiga.

A reescrita de código de modernização de mainframe permite uma abordagem iterativa à reescrita de código para clientes e parceiros. Normalmente, é usado após a conclusão de uma avaliação com a Mainframe Assessment Tool (MAT). Esta extensão integra capacidades de IA gen de mainframe para análise de código, especificação, geração de código e geração de testes, oferecendo uma experiência de desenvolvimento interativa.

Antes de começar

Nota: recomendamos a utilização desta funcionalidade para 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 Cloud Code, se ainda não o fez.
2. Instale a CLI Google Cloud, se ainda não o fez.

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

As secções seguintes descrevem como configurar a reescrita de código de modernização de mainframe. Primeiro, tem de ativar a reescrita de código de modernização de mainframe no seu IDE e, em seguida, associá-lo ao Vertex AI.

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

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

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

2. Selecione o comando Preferences: Open User Settings (JSON).

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

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

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

Ligue a reescrita de código de modernização de mainframe ao Vertex AI

Para ligar a reescrita de código de modernização de mainframe à Vertex AI, siga estes passos:

1. Numa janela do terminal, execute o seguinte comando:

   gcloud auth application-default login
   

2. Siga as instruções no ecrã na janela do navegador de Internet recém-aberta.

3. Siga as instruções para iniciar sessão no Google Cloud.

4. Selecione o projeto que quer usar.

5. Execute o comando Developer: Reload Window.

Após a configuração, pode abrir qualquer espaço de trabalho ou pasta que inclua código de mainframe e executar os comandos Gerar resumo das especificações e Gerar código modernizado em COBOL, JCL, Easytrieve e HLASM.

Gere o resumo das especificações

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

Pode aceder a um resumo das especificações a partir da paleta de comandos ou da vista do explorador:

Paleta de comandos

1. No editor, selecione o ficheiro de origem que quer usar para o tornar o ficheiro ativo.

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

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

É apresentado um resumo das especificações junto ao código.

Explorador

1. Na barra de atividade, clique em Explorador ou prima Ctrl/Cmd+Shift+E.

2. Clique com o botão direito do rato no ficheiro de origem preferido e selecione Gerar resumo das especificações.

É apresentado um resumo das especificações junto ao código.

Anote o código antigo do mainframe

Para orientar o processo de geração do resumo das especificações, pode anotar o código antigo adicionando comentários. Para anotar uma tarefa JCL ou um programa COBOL, procure o botão adicionar Adicionar junto à linha de definição da tarefa/programa:

Tarefa JCL



Programa COBOL



1. Para abrir uma vista do CMS incorporada que lhe permite anotar o seu trabalho/programa, clique em adicionar Adicionar. Depois de adicionar o comentário, clique em Criar nota para o guardar.

2. Quando a anotação é guardada, use o comando Gerar resumo das especificações para gerar uma especificação para a sua tarefa/programa, com base no seu comentário.

   Em seguida, pode editar a anotação para refinar as orientações fornecidas ou eliminá-la, se já não quiser que o modelo a tenha em consideração.

Gere código modernizado

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

Idiomas de origem suportados: COBOL, JCL, Easytrieve e HLASM.

Idiomas de destino suportados: Java, C#, Python e SQL.

Pode aceder a este comando a partir da paleta de comandos ou da vista do explorador:

Paleta de comandos

1. No editor, selecione o ficheiro de origem que quer usar para o tornar o ficheiro ativo.

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

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

4. Selecione o idioma de destino no qual quer que o código modernizado seja gerado.

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

Explorador

1. Na barra de atividade, clique em Explorador ou prima Ctrl/Cmd+Shift+E.

2. Clique com o botão direito do rato no ficheiro de origem para o qual quer gerar código modernizado e selecione Gerar código modernizado.

3. Selecione o idioma de destino no qual quer que o código modernizado seja gerado.

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

Modificar as definições

A reescrita de código de modernização do mainframe tem as seguintes definições que pode configurar no âmbito do espaço de trabalho ou no âmbito das definições do utilizador (globais).

Para modificar as definições ao nível do espaço de trabalho, prima Ctrl/Cmd+Shift+P para abrir a paleta de comandos e selecione o comando Preferences: Open Workspace Settings (JSON).

Para modificar as definições ao nível das definições globais do utilizador, prima Ctrl/Cmd+Shift+P para abrir a paleta de comandos e selecione o comando Preferences: Open User Settings (JSON).

Segue-se um exemplo de um ficheiro 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."
    ],
}

Ative e desative o Google Analytics

Esta propriedade de configuração ativa ou desativa a recolha de estatísticas de utilização para a extensão.

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

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

• Valor predefinido: true (o Analytics está ativado).

Ative e desative o Cloud Logging

Esta propriedade de configuração controla se o registo está ativado ou não.

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

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

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

Modelo

Quando esta propriedade de configuração está definida, a reescrita de código de modernização de mainframe usa o modelo Gemini especificado na configuração.

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

• Valores de configuração de exemplo: "gemini-1.5-flash", "gemini-1.5-pro", "gemini-2.0-flash", "gemini-2.0-flash-lite" ou "gemini-2.5-pro".

• Valor predefinido: "(default)" (Perguntar sempre).

Idioma de destino

Quando esta propriedade de configuração está definida, o comando Gerar código modernizado deixa de lhe pedir que selecione o idioma de destino quando gera código e usa o idioma definido na propriedade.

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

• Valores de configuração de exemplo: "java", "csharp", "python" ou "pgsql".

• Valor predefinido: null (Perguntar sempre).

Sugestões de pilha tecnológica de geração de código

Quando esta propriedade de configuração está definida, o comando Generate Modernized Code transmite a lista especificada de sugestões de tecnologia como instruções adicionais ao GML quando gera código. Esta configuração pode ser usada como orientação para ajustar a arquitetura, as estruturas e o estilo de código de destino.

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

• Valor de configuração de exemplo:

  [
    "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 predefinido: [] (uma lista vazia; sem sugestões de tecnologia).

Elimine os 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 de mainframe para o espaço de trabalho atual, siga estes passos:

1. Abra o terminal selecionando Ver > Terminal na barra de menu ou premindo o atalho de teclado ⌃.

2. Introduza 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 secção descreve os problemas conhecidos da reescrita de código de modernização de mainframe e fornece passos de resolução de problemas:

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

Se os comandos Generate Specification Summary ou Generate Modernized Code forem executados durante muito tempo e, em seguida, falharem, a API Vertex AI pode não estar ativada ou ter excedido a respetiva quota no projeto selecionado. Para confirmar que este é o problema, clique no botão Aceder ao resultado.

Se o botão Aceder à saída não estiver disponível, siga os passos em Inspeção do canal de saída. No canal de saída, procure uma mensagem de erro que contenha "Vertex.GenerateContent failed". Por exemplo, segue-se uma mensagem de erro causada pela não ativação da API Vertex AI no Google Cloud projeto selecionado:

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

Para resolver este problema, pode:

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

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

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

Se os comandos como Gerar resumo das especificações ou Gerar código modernizado não estiverem disponíveis na paleta de comandos, isto pode indicar que a ferramenta de CLI de modernização do mainframe não foi instalada. Para confirmar se é este o caso, verifique se o seguinte ficheiro executável está em falta:

• 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 este 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: Install or Update Mainframe Modernization Tools.
3. Verifique se o ficheiro executável já não está em falta.
4. Abra novamente a paleta de comandos com Ctrl/Cmd+Shift+P.
5. Selecione o comando Developer: Reload Window.

Inspeção do canal de saída

Para resolver outros erros não listados noutras partes deste guia, experimente inspecionar o canal de saída da extensão. Para abrir o canal de saída, execute as seguintes tarefas:

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.