评估 .NET 应用以进行现代化改造

本页介绍了如何使用 Google Cloud Modernization Hub 评估 ASP.NET 和 .NET Framework 应用，以确定是否适合将它们容器化为 Linux 容器，并现代化改造为跨平台 .NET 版本。

许多企业 .NET 应用依赖于特定于 Windows 的 API、IIS 服务器配置或旧版 .NET Framework 库，这会阻止直接部署到 Linux 容器。Modernization Hub 中的自动化评估功能会分析您的源代码，以识别阻碍因素、评估 NuGet 软件包兼容性，并为 Cloud Run 或 Google Kubernetes Engine 推荐重构路径。

何时使用 .NET 应用评估

如果您计划执行以下任何现代化改造任务，请运行 .NET 应用评估：

  • 重新平台化为 Linux 容器：在将应用容器化以用于 Cloud Run 或 GKE 之前，请先确定仅限 Windows 的依赖项（例如 Windows 注册表访问权限、System.Drawing 或 Active Directory 集成）。
  • 升级 .NET Framework 版本：评估从 .NET Framework 4.x 迁移到现代的跨平台 .NET 版本（.NET 10 或更高版本）时的工作量和兼容性差距。
  • 解耦单体式架构：发现紧密耦合的 WCF 服务、Windows 服务或需要重构为云原生微服务的旧版 Web 表单。

准备工作

在开始 .NET 评估作业之前，请启用必需的 API，验证您的项目 Identity and Access Management (IAM) 权限，注册工作区设置存储桶，并将源代码归档上传到 Cloud Storage。

启用必需的 API

如需使用 Modernization Hub，请在项目中启用所需的 Google Cloud服务 API：

gcloud services enable \
    aiplatform.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    cloudresourcemanager.googleapis.com \
    compute.googleapis.com \
    logging.googleapis.com \
    storage.googleapis.com \
    --project=PROJECT_ID

请将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

所需的角色

使用 Cloud Build 和 Gemini Enterprise Agent Platform 运行评估需要为两个身份授予不同的 IAM 权限：

  • 经过身份验证的控制台用户（启动作业和访问存储桶）：
    • Storage Admin (roles/storage.admin)
    • Service Account User (roles/iam.serviceAccountUser)
    • Cloud Build Editor (roles/cloudbuild.builds.editor)
  • 服务账号（执行评估容器）：
    • Agent Platform User (roles/aiplatform.user)
    • Storage Object User (roles/storage.objectUser) 或 Storage Admin (roles/storage.admin)

如需获得启动评估和执行分析容器所需的权限，请让您的管理员向您授予项目的以下 IAM 角色：

  • 用户 - 管理源归档和存储桶配置： Storage Admin (roles/storage.admin)
  • 用户 - 将专用服务账号附加到作业：服务账号用户 (roles/iam.serviceAccountUser)
  • 用户 - 提交评估作业 (cloudbuild.builds.create) 和查看日志： Cloud Build Editor (roles/cloudbuild.builds.editor)
  • 服务账号 - 执行 codmod 容器： Agent Platform User (roles/aiplatform.user)
  • 服务账号 - 读取源归档文件和写入评估报告：Storage Object User (roles/storage.objectUser) 或 Storage Admin (roles/storage.admin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含启动评估和执行分析容器所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您需要具备以下权限才能启动评估并执行分析容器：

  • 用户（Cloud Storage、Cloud Build 和 IAM）：
    • storage.objects.get（用于下载或读取文件）
    • storage.objects.list（用于列出存储桶中的文件）
    • storage.objects.create（用于上传或创建新文件）
    • storage.objects.update（修改现有文件的元数据）
    • storage.objects.delete（删除或覆盖文件）
    • storage.buckets.get（查看存储桶级配置）
    • cloudbuild.builds.create（用于提交评估作业）
    • iam.serviceAccounts.actAs（将服务账号关联到作业）
  • 服务账号（Agent Platform 和 Cloud Storage）：
    • aiplatform.endpoints.predict（运行 AI 辅助的代码分析）
    • storage.objects.get（用于读取或下载源代码归档文件）
    • storage.objects.list（列出输入文件夹中的文件）
    • storage.objects.create（用于撰写评估报告）
    • storage.objects.delete（用于删除临时文件）

您也可以使用自定义角色或其他预定义角色来获取这些权限。

配置工作区设置存储桶

在现代化中心 > 设置页面上注册指定的 Cloud Storage 存储桶（例如 gs://PROJECT_ID-modernization-hub），以存储工作区二进制状态文件（dotnet_jobs.pb、java_jobs.pb 和 mainframe_jobs.pb）。

查看代码库大小限制

为保持最佳性能和成本效益，codmod 评估引擎会强制执行以下规模和归档准则：

  • 代码库大小上限：每次评估作业大约 600 万行代码 (LOC)。如果您的代码库超过 600 万行代码，请先将代码库拆分为更小的独立解决方案或模块，然后再上传。
  • 干净的归档结构：从 ZIP 文件中排除已编译的二进制文件、软件包缓存和版本控制元数据（例如 bin/、obj/、node_modules/、.vs/ 和 .git/），以便仅分析源文件和 build 配置。

准备并上传 .NET 源归档文件

将 .NET 代码库打包为排除 build 输出的 zip 文件，并将该文件上传到项目中的 Cloud Storage 存储桶。

  1. 在本地机器上，使用以下任一方法创建代码库的 ZIP 文件：

    • 使用 Git（推荐）：

      git archive --format=zip -o repository.zip HEAD

    • 使用 zip CLI：

      zip -r repository.zip . \
    -x "*.git*" "*/bin/*" "*/obj/*" "*/node_modules/*" "*.vs/*"

  2. 使用 Google Cloud CLI 将 ZIP 文件上传到目标 Cloud Storage 存储桶：

    gcloud storage cp repository.zip \
    gs://INPUT_BUCKET/codebase/repository.zip

    将 INPUT_BUCKET 替换为目标 Cloud Storage 存储桶的名称。

运行评估

如需运行评估作业，请按以下步骤操作：

  1. 在控制台中，前往现代化中心页面。

    前往 Modernization Hub

  2. 在着陆页上，找到 .NET 现代化改造卡片，然后点击开始评估。

  3. 在作业名称字段中，为评估作业输入一个唯一的名称。

  4. 在源代码位置字段中，选择包含源代码（以 ZIP 文件形式）的 Cloud Storage 存储桶。

  5. 在报告位置字段中，选择一个 Cloud Storage 存储桶来保存生成的评估报告。

  6. 从现代化方案列表中，选择一个现代化方案。

  7. 从位置列表中，为评估作业选择一个区域。

  8. 在服务账号字段中，选择一个具有所需角色部分中列出的所需 IAM 角色的专用服务账号。 Cloud Build 会在此服务账号下运行评估作业，该服务账号需要 Agent Platform User 和 Cloud Storage 权限。

  9. 点击生成报告。

    控制台会启动一个后台评估容器来分析您的项目。作业状态会显示在评估历史记录表格中。

监控作业状态和查看报告

评估作业通常会在几分钟内完成，具体取决于代码库的大小。后台容器在完成处理后会自动终止。

如需查看评估结果，请按以下步骤操作：

  1. 在 Modernization Hub 页面的评估历史记录表格中，找到您的评估作业。
  2. 当状态列变为已完成时，点击下载报告。
  3. 选择所需的输出格式：
    • HTML 报告：一种互动式摘要，可让您过滤不兼容的 Windows API、检查各个文件的屏蔽列表，以及查看补救建议。
    • Markdown 报告：一种格式化的执行摘要，适合与利益相关者和架构审核委员会分享。

查看评估报告

评估报告会将应用的迁移准备情况分为以下几个方面：

  • 总体兼容性得分：可迁移到跨平台 .NET 而无需修改的源代码行和依赖项所占的百分比。
  • 阻碍因素细分：需要重构的特定 Windows 依赖项，例如：
    • Windows Communication Foundation (WCF) 服务器实现。
    • ASP.NET Web Forms 或 ASP.NET MVC 旧版流水线。
    • Windows 注册表调用 (Microsoft.Win32)。
  • NuGet 依赖项分析：详细列出现有 NuGet 软件包，并指明每个软件包是否支持目标 .NET 版本或是否需要替换。
  • 推荐的操作：建议的代码转换和迁移路径，用于为应用在 Google Cloud上实现容器化做好准备。

使用 Antigravity 重构 .NET 代码

生成评估报告后，您可以将 Antigravity 与专门的 .NET 智能体技能搭配使用，以自动将代码从 .NET Framework 转换为跨平台 .NET。

在运行智能体重构工作流之前，请确保您满足以下前提条件：

  • Antigravity 环境：安装 Antigravity IDE 或 Antigravity CLI (agy)，并使用您的 Google Cloud 项目配置身份验证。
  • 评估制品：下载 codmod 评估报告并将其放置在本地代码库工作区中，以便代理可以参考已识别的阻碍因素和依赖项升级路径。
  • .NET 现代化改造技能：将 codmod .NET 现代化改造技能 (SKILL.md) 加载到 Antigravity 工作区设置中。如需申请预览最新 .NET 现代化智能体技能，请联系 modernization-hub-feedback-external@google.com。

后续步骤