Modernize seu aplicativo de mainframe

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas 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 da fase de lançamento.

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

A reescrita de código de modernização de mainframe permite uma abordagem iterativa para reescrever o código de clientes e parceiros. Ela geralmente é 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, especificação, geração de código e testes, oferecendo uma experiência de desenvolvimento interativa.

Antes de começar

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

Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

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 role (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 role (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 tiver feito isso.
2. Instale a Google Cloud CLI, se ainda não tiver 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 de modernização de mainframe. Primeiro, ative a reescrita de código de modernização de mainframe no seu ambiente de desenvolvimento integrado e, em seguida, conecte-o à 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 "cloudcode.beta.enableMainframeModernization": true configuração ao seu settings.json arquivo:

   {
       "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 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 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.

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

Gerar resumo de 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 de mainframe legado. COBOL, JCL, Easytrieve e HLASM são compatíveis.

É possível acessar um resumo de 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 de especificação para arquivo ativo.

Um resumo de 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 de especificação.

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

Anotar código legado de mainframe

Para orientar o processo de geração de resumo de especificação, você pode anotar seu código legado adicionando comentários. Para anotar um job JCL ou um programa COBOL, procure o adicionar Adicionar botão 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 job/programa, clique em adicionar Adicionar. Depois de adicionar o comentário, clique em Criar nota para salvá-lo.

2. Quando a anotação for salva, use o comando Gerar resumo de especificação para gerar uma especificação para seu job/programa, orientada pelo comentário.

   Em seguida, 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 um código moderno com base no seu código legado de 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-alvo 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 um código modernizado e selecione Gerar código modernizado.

3. Selecione o idioma-alvo 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 de modernização de mainframe tem as seguintes configurações que podem ser definidas no escopo do espaço de trabalho ou no escopo de 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 de configurações globais do usuário, pressione Ctrl/Cmd+Shift+P para abrir a paleta de comandos e selecione o Preferências: abrir configurações do usuário (JSON) comando.

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 Cloud 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 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-alvo

Quando essa propriedade de configuração é definida, o comando Gerar código modernizado não pede 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

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

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

Dicas de conjunto de tecnologias de 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 o código. Essa configuração pode ser usada como orientação para ajustar a arquitetura de destino, as estruturas 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 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 Visualizar > Terminal na barra de menus ou pressionando o atalho de teclado ⌃.

2. Insira os comandos a seguir 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 de modernização de mainframe e fornece etapas de solução de problemas:

Vertex AI não disponível em Google Cloud projeto

Se os comandos Gerar resumo de especificação ou Gerar código modernizado forem executados por muito tempo e falharem, a API Vertex AI poderá não estar ativada ou ter excedido a cota no projeto selecionado. Para confirmar se esse é 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 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 comandos como Gerar resumo de especificação ou Gerar código modernizado não estiverem disponíveis na paleta de comandos, isso poderá indicar que a ferramenta de CLI de modernização de mainframe não foi instalada. Para confirmar se esse é o caso, verifique se o arquivo executável a seguir 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 ausente.
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 em outro lugar neste guia, tente inspecionar o canal de saída da extensão. Para abrir o canal de saída, realize 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.