评估 .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 的重构路径。

如需通过本地计算机运行评估或使用独立的 codmod CLI 自定义报告部分，请参阅创建应用现代化改造评估。

何时使用 .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)
  • 用户 - 将专用服务账号附加到作业：Service Account User (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（删除临时文件）

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

配置工作区设置存储桶

在 Modernization Hub > 设置页面上注册一个指定的 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 代码库打包为不包含构建输出的 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 页面。

    前往 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。

后续步骤