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

预览版

此产品或功能 受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版产品和功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

在本指南中，您将学习如何使用 Cloud Code for VS Code 扩展程序来对旧版大型机应用进行现代化改造。

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

准备工作

注意： 我们建议您将此功能用于代码总行数不超过 500 万行的工作区。

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. 如果您尚未安装 Cloud Code 扩展程序，请安装该扩展程序。
2. 如果您尚未安装 Google Cloud CLI，请进行安装。

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

以下部分介绍了如何设置 Mainframe Modernization Code Rewrite。 您首先需要在 IDE 中启用 Mainframe Modernization Code Rewrite，然后将其连接到 Vertex AI。

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

如需启用 Mainframe Modernization Code Rewrite，请按以下步骤操作：

1. 按 Ctrl/Cmd+Shift+P 打开命令面板。

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

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

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

3. 再次打开命令面板（按 Ctrl/Cmd+Shift+P），然后选择开发者：重新加载窗口命令。

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

如需将 Mainframe Modernization Code Rewrite 连接到 Vertex AI，请按照以下步骤操作：

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

   gcloud auth application-default login
   

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

3. 按照提示登录 Google Cloud。

4. 选择要使用的项目。

5. 运行开发者：重新加载窗口命令。

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

生成规范摘要

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

您可以通过命令面板或“资源管理器”视图访问规范摘要：

命令面板

1. 在编辑器中，选择要用作活动源文件的源文件。

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

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

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

探索器

1. 在活动栏中，点击探索器或按 Ctrl/Cmd+Shift+E。

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

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

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

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

JCL 作业



COBOL 程序



1. 如需打开可用于为作业/计划添加注释的内嵌 CMS 视图，请依次点击添加 添加。添加注释后，点击创建注释即可保存。

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

   然后，您可以修改注解以优化提供的指导，也可以删除注解（如果您不再希望模型考虑该注解）。

生成现代化代码

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

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

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

您可以通过命令面板或“资源管理器”视图访问此命令：

命令面板

1. 在编辑器中，选择要用作活动源文件的源文件。

2. 按 Ctrl/Cmd+Shift+P 打开“Command Palette”（命令面板）。

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

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

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

探索器

1. 在活动栏中，点击探索器或按 Ctrl/Cmd+Shift+E。

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

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

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

修改设置

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

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

如需在全局用户设置级别修改设置，请按 Ctrl/Cmd+Shift+P 打开命令面板，然后选择首选项：打开用户设置 (JSON) 命令。

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

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

启用和停用 Google Analytics

此配置属性用于启用或停用扩展程序的用量分析收集功能。

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

• 配置值示例：false。

• 默认值：true（已启用 Google Analytics）。

启用和停用 Cloud Logging

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

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

• 配置值示例：true。

• 默认值：false（Cloud Logging 已停用）。

型号

设置此配置属性后，大型主机现代化改造代码重写功能会使用配置中指定的 Gemini 模型。

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

• 配置值示例："gemini-1.5-flash"、"gemini-1.5-pro"、"gemini-2.0-flash"、"gemini-2.0-flash-lite" 或 "gemini-2.5-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. 从菜单栏中依次选择查看 > 终端，或按 ⌃ 键盘快捷键，打开终端。

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"

问题排查

本部分简要介绍了 Mainframe Modernization Code Rewrite 的已知问题，并提供了问题排查步骤：

Vertex AI 在 Google Cloud 项目中不可用

如果生成规范摘要或生成现代化代码命令长时间执行后失败，则可能是 Vertex AI API 未启用，或者在所选项目中已超出其配额。如需确认是否存在此问题，请点击前往输出按钮。

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

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

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

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

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

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

如果命令面板中没有 Generate Specification Summary 或 Generate Modernized Code 等命令，则可能表示 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 打开命令面板。
2. 选择 Cloud Code: Install or Update Mainframe Modernization Tools 命令。
3. 验证可执行文件是否不再缺失。
4. 使用 Ctrl/Cmd+Shift+P 再次打开命令选用区。
5. 选择开发者：重新加载窗口命令。

检查输出渠道

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

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