对大型主机应用进行现代化改造

在本指南中，您将学习如何使用适用于 VS Code 的 Cloud Code 扩展程序来改造旧版大型机应用。

大型主机现代化代码重写功能可为客户和合作伙伴提供迭代式代码重写方法。通常，在使用 Mainframe Assessment Tool (MAT) 完成评估后，便会使用此报告。此扩展程序集成了 Mainframe GenAI 功能，可用于代码分析、规范、代码生成和测试生成，从而提供交互式开发体验。

准备工作

  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.

    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.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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.
  8. 如果您尚未安装 Cloud Code 扩展程序，请安装该扩展程序。
  9. 如果您尚未安装 Google Cloud CLI，请进行安装。

设置大型主机现代化改造代码重写

以下部分介绍了如何设置大型机现代化代码重写。您首先需要在 IDE 中启用大型机现代化代码重写，然后将其连接到 Vertex AI。

启用大型主机现代化改造代码重写

如需启用大型机现代化代码重写，请按以下步骤操作：

  1. 按 Ctrl/Cmd+Shift+P 打开 Command Palette。

  2. 选择 Preferences: Open User Settings (JSON) 命令。

    如需启用大型主机现代化代码重写，请将 "cloudcode.beta.enableMainframeModernization": true 设置添加到 settings.json 文件中：

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

  3. 再次打开 Command Palette（按 Ctrl/Cmd+Shift+P），然后选择 Developer: Reload Window 命令。

将大型主机现代化代码重写连接到 Vertex AI

如需将大型机现代化代码重写连接到 Vertex AI，请按以下步骤操作：

  1. 在终端窗口中，运行以下命令：

    gcloud auth application-default login

  2. 按照新打开的网络浏览器窗口中的说明操作。

  3. 按照提示登录 Google Cloud。

  4. 选择要使用的项目。

  5. 运行 Developer: Reload Window 命令。

设置完成后，您可以打开包含大型机代码的任何工作区或文件夹，并针对 COBOL、JCL、Easytrieve 和 HLASM 执行生成规范摘要和生成现代化代码命令。

生成规范摘要

借助 Cloud Code：为活动文件生成规范摘要命令，您可以为旧版大型机代码创建中性语言规范。支持 COBOL、JCL、Easytrieve 和 HLASM。

您可以通过 Command Palette 或 Explorer 视图访问规范摘要：

命令 Palette

  1. 在编辑器中，选择要使用的源文件，使其成为活动文件。

  2. 如需打开 Command Palette，请按 Ctrl/Cmd+Shift+P。

  3. 搜索并选择 Cloud Code: Generate Specification Summary for Active File 命令。

代码旁边会显示规范摘要。

资源管理器

  1. 在活动栏中，点击 Explorer（资源管理器）或按 Ctrl/Cmd+Shift+E。

  2. 右键点击首选的源文件，然后选择生成规范摘要。

代码旁边会显示规范摘要。

为大型主机旧版代码添加注解

为了引导规范摘要生成流程，您可以通过添加注释来为旧版代码添加注解。如需为 JCL 作业或 COBOL 程序添加注释，请找到作业/程序定义行旁边的添加 Add 按钮：

JCL 作业

为 JCL 作业添加注解

COBOL 程序

为 COBOL 程序添加注释

  1. 如需打开内嵌 CMS 视图以对作业/计划添加注释，请点击添加 添加。添加评论后，点击创建备注保存评论。

  2. 保存注解后，使用生成规范摘要命令，根据您的注释为作业/程序生成规范。

    然后，您可以修改注释以优化所提供的指导，或者删除注释（如果您不想让模型再将其纳入考量）。

生成现代化代码

借助 Cloud Code：为活动文件生成现代化代码命令，您可以根据大型机旧版代码创建现代代码。

支持的源语言：COBOL、JCL、Easytrieve 和 HLASM。

支持的目标语言：Java、C#、Python、SQL。

您可以通过 Command Palette 或 Explorer 视图访问此命令：

命令 Palette

  1. 在编辑器中，选择要使用的源文件，使其成为活动文件。

  2. 按 Ctrl/Cmd+Shift+P 打开 Command Palette。

  3. 搜索并选择 Cloud Code: Generate Modernized Code for Active File 命令。

  4. 选择要生成现代化代码的目标语言。

    生成的现代化代码会在编辑器中显示为新的未命名文件。

资源管理器

  1. 在活动栏中，点击 Explorer（资源管理器）或按 Ctrl/Cmd+Shift+E。

  2. 右键点击要为其生成现代化代码的源文件，然后选择生成现代化代码。

  3. 选择要生成现代化代码的目标语言。

    生成的现代化代码会在编辑器中显示为新的未命名文件。

修改设置

大型机现代化代码重写有以下设置，您可以在工作区级别或（全局）用户设置级别进行配置。

如需修改工作区级设置，请按 Ctrl/Cmd+Shift+P 打开 Command Palette，然后选择 Preferences: Open Workspace Settings (JSON) 命令。

如需修改全局用户设置级别的设置，请按 Ctrl/Cmd+Shift+P 打开 Command Palette，然后选择 Preferences: Open User Settings (JSON) 命令。

下面是一个包含扩展程序的所有配置属性的 settings.json 文件示例：

{
    "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."
    ],
}

启用和停用 Google Analytics

此配置属性用于启用或停用收集扩展程序使用情况分析数据的功能。

  • 配置属性名称：cloudcode.beta.mainframeModernization.enableGoogleAnalytics。

  • 配置值示例：false。

  • 默认值：true（已启用 Google Analytics [分析]）。

启用和停用 Cloud Logging

此配置属性用于控制日志记录功能是否启用。

  • 配置属性名称：cloudcode.beta.mainframeModernization.enableCloudLogging。

  • 配置值示例：true。

  • 默认值：false（Cloud Logging 处于停用状态）。

型号

设置此配置属性后，Mainframe Modernization Code Rewrite 会使用配置中指定的 Gemini 模型。

  • 配置属性名称：cloudcode.beta.mainframeModernization.model

  • 配置值示例："gemini-1.5-flash"、"gemini-1.5-pro"、"gemini-2.0-flash"、"gemini-2.0-flash-lite" 或 "gemini-2.0-pro"。

  • 默认值："(default)"（每次都询问）。

目标语言

设置此配置属性后，生成现代化代码命令在生成代码时不再要求您选择目标语言，而是使用该属性中设置的语言。

  • 配置属性名称：cloudcode.beta.mainframeModernization.codeGenerationSettings.targetLanguage

  • 配置值示例："java"、"csharp"、"python" 或 "pgsql"。

  • 默认值：null（每次都询问）。

代码生成技术栈提示

设置此配置属性后，生成现代化代码命令会在生成代码时将指定的技术栈提示列表作为额外说明传递给 LLM。此配置可用作调整目标架构、框架和代码样式的指导。

  • 配置属性名称：cloudcode.beta.mainframeModernization.codeGenerationSettings.techStackHints

  • 配置值示例：

    [
  "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"
]

  • 默认值：[]（空列表；无技术栈提示）。

删除大型主机现代化改造代码重写数据

如需移除 Mainframe Modernization Code Rewrite 为当前工作区本地存储的所有数据，请按以下步骤操作：

  1. 从菜单栏中依次选择 View > Terminal 或按 ⌃ 键盘快捷键，打开终端。

  2. 在终端中输入以下命令：

Linux（Bash 或 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"

问题排查

本部分概述了大型机现代化代码重写的已知问题，并提供了问题排查步骤：

Google Cloud 项目中不提供 Vertex AI

如果 Generate Specification Summary 或 Generate Modernized Code 命令执行了很长时间后失败，则表示 Vertex AI API 可能未启用，或者在所选项目中已超出配额。如需确认是否存在此问题，请点击前往输出按钮。

如果前往输出按钮不可用，请按照检查输出渠道中的步骤操作。在输出通道中，查找包含“Vertex.GenerateContent failed”的错误消息。例如，以下错误消息是由所选项目中未启用 Vertex AI API 所致 Google Cloud ：

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

如需解决此问题，请执行以下任一操作：

  • 确认您已在 Google Cloud项目中启用 Vertex AI API。

  • 切换到另一个 Google Cloud 已启用 Vertex AI API 的项目。

大型主机现代化改造代码重写命令不可用

如果命令 Palette 中不提供生成规范摘要或生成现代化代码等命令，则可能表示 Mainframe Modernization CLI 工具安装失败。如需确认是否属于这种情况，请检查是否缺少以下可执行文件：

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

如果是这种情况，请尝试通过执行以下任务来解决问题：

  1. 按 Ctrl/Cmd+Shift+P 打开 Command Palette。
  2. 选择 Cloud Code: Install or Update Mainframe Modernization Tools 命令。
  3. 验证可执行文件是否不再缺失。
  4. 再次按 Ctrl/Cmd+Shift+P 打开 Command Palette。
  5. 选择 Developer: Reload Window 命令。

检查输出渠道

如需排查本指南中未列出的其他错误，请尝试检查扩展程序的输出渠道。如需打开输出渠道，请执行以下任务：

  1. 按 Ctrl/Cmd+Shift+P 打开 Command Palette。
  2. 选择 Output: Show Output Channels 命令。
  3. 选择 Cloud Code Mainframe Modernization 输出渠道。