使用GitHub Copilot现代化代理进行批量评估

通过批处理评估，可以在单个运行中分析 Java、.NET 和 JavaScript/TypeScript 应用程序组合。你可以全面了解应用程序的现代化布局。本文指导你完成高效评估多个存储库的过程。此过程同时支持单语言存储库和 mono-repos，其中包含混合Java、.NET和 JavaScript/TypeScript 项目。

每个应用程序都沿着两个互补轨道进行分析。 问题扫描可发现你需要修复的问题。 代码库见解 记录应用程序的生成方式，以便你可以围绕它进行规划。

问题扫描

问题扫描可检测三个域中的现代化和安全问题。语言覆盖范围因域而异：

升级 - 运行时和框架版本分析。涵盖 Java 和 .NET。
Cloud Readiness — Azure目标平台适合和迁移问题。涵盖 Java 和 .NET。
安全性 — 针对直接和传递依赖项的 CVE 扫描，以及基于 ISO 5055 指导的 CWE 安全问题。目前仅支持Java；.NET 和 JavaScript/TypeScript 支持已列入路线图。

代码库见解

代码库见解记录每个应用程序的生成方式。它们针对 Java、.NET 和 JavaScript/TypeScript 项目生成。在“分析覆盖率”设置中选择 “完全分析 ”时，它们将浮出水面。

体系结构 - 具有分层、模块边界、运行时拓扑和入口点的高级体系结构关系图。
API 契约 — 应用对外提供或调用的 REST、gRPC、消息队列和 Webhook 接口。在迁移之前调整集成爆炸半径的大小。
配置 - 配置文件、环境变量、功能标志、连接字符串和机密。推动将机密和配置迁移到 Azure 密钥保管库和 Azure 应用程序配置。
业务工作流 - 从代码重建的端到端功能流（例如 ，订单→预留→支付→履行）。定位点回归范围和利益干系人通信。
依赖项 - 具有固定版本的直接和可传递库、SDK 和驱动程序。提供 Azure 服务映射，并显示 EOL 或 beta 固定版本。
数据模型 - 来自 ORM 映射和 DDL 的数据库、架构、关键实体和关系。推动数据层级迁移规划。

报表

批处理评估对于迁移规划尤其有用，因为它使你能够一次性有效地评估各种应用程序的准备情况和要求。通过使用批处理评估，可以同时评估不同的存储库，并为每个应用程序获取详细的评估报告。它生成两种类型的报告来支持迁移规划：

按存储库划分的报告：提供针对各个存储库层面已识别出的两个方面的详细分析。
汇总报告：提供所有已评估应用程序的整体视图，并提供汇总见解，以及有关 Azure 服务、目标平台、升级路径、迁移策略和迁移批次的建议。此外，聚合报表还包括用于轻松访问每个存储库报表的快捷方式。

批处理评估具有以下优势：

跨应用程序可见性：
- 聚合报表：跨应用程序获取全面视图。
- 跨存储库分析：确定应用程序之间的常见模式和依赖关系。
- 优先级见解：了解哪些应用程序需要立即注意。
规模和效率
- 并行处理：使用云代理同时处理多个存储库。
- 自动化工作流：与用于计划评估的 CI/CD 管道集成。
- 节省时间：将总评估时间从数周减少到数小时。

先决条件

现代化命令行界面 (CLI)
访问要评估的所有存储库。
GitHub身份验证已配置（gh auth login）。

配置存储库

现代化代理支持多种方法来指定要评估的存储库：

当前文件夹：评估当前工作目录中的项目。
手动输入：直接输入本地目录路径或远程 Git URL。
存储库配置文件：使用列出所有存储库的 JSON 配置文件。

存储库配置文件

对于跨多个存储库的批处理操作，请创建 JSON 配置文件以列出所有存储库。例如，在工作目录中创建它 .github/modernize/repos.json ，或提供自定义路径。

请确保你对存储库具有适当的权限，或为其创建分支。

简单格式 （存储库数组）：

[
  {
    "name": "PhotoAlbum-Java",
    "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git"
  },
  {
    "name": "PhotoAlbum",
    "url": "https://github.com/Azure-Samples/PhotoAlbum.git"
  },
  {
    "name": "eShopOnWeb",
    "url": "https://github.com/dotnet-architecture/eShopOnWeb.git"
  }
]

完整格式 （包含分支和本地路径）：

{
  "repos": [
    {
      "name": "PhotoAlbum-Java",
      "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git",
      "branch": "main"
    },
    {
      "name": "local-project",
      "path": "/absolute/path/to/project"
    }
  ]
}

每个存储库条目支持以下字段：

领域	说明	必需
`name`	存储库的友好名称（用于报表和仪表板）。	是的
`url`	HTTPS 或 SSH 格式的 Git 克隆 URL。	其中之一`url`或`path`
`path`	绝对本地目录路径。	其中之一`url`或`path`
`branch`	克隆后要签出的分支。	否
`description`	人工可读说明。	否

应用分组的完整格式 （可选，用于有组织的报告）：

可以添加一个 apps[] 部分，将存储库组织到逻辑应用程序中。定义应用后，聚合报表按应用程序组织结果，并支持将报表分发到外部目标。

{
  "repos": [
    {
      "name": "PhotoAlbum-Java",
      "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git",
      "branch": "main"
    },
    {
      "name": "PhotoAlbum",
      "url": "https://github.com/Azure-Samples/PhotoAlbum.git"
    }
  ],
  "apps": [
    {
      "identifier": "photo-app",
      "description": "Photo management application",
      "repos": ["PhotoAlbum-Java"],
      "output": {
        "type": "local",
        "path": "/path/to/reports/photo-app"
      }
    }
  ]
}

每个应用条目都支持：

领域	说明	必需
`identifier`	应用程序的唯一显示名称。	是的
`description`	人工可读说明。	否
`repos`	属于此应用的存储库名称列表。	是的
`output`	在哪里分发应用程序的评估报告生成后的版本。	否

该 output 字段支持以下分布类型：

类型	说明	必填字段
`local`	将报表复制到本地目录。	`path`
`git`	将报表推送到 Git 存储库。 URL 格式为 `https://github.com/org/repo.git#branch:path`.	`url`

小窍门

你可以包括来自不同组织的存储库，只要你有权访问，就可以使用不同的身份验证方法。

在互动模式下选择repos.json时，新式化代理会自动检测.github/modernize/repos.json位于的文件。还可以提供自定义路径。

运行批量评估

有两种执行模式可用：

本地执行：现代化代理在本地计算机上逐个处理存储库。此模式最适合一组较小的应用程序或初始测试。支持 Git URL 和本地路径存储库。
云代理委派：现代化代理将任务提交到 GitHub Copilot 云代理，以便在云端并行处理。对于多存储库方案，此模式更快。

重要

云代理委派要求存储库具有 GitHub （github.com）存储库 URL。云委派不支持本地路径存储库和非GitHub提供程序（GitLab、Azure DevOps）。对这些存储库使用本地执行。

小窍门

通过使用云代理委派，可以跨所有存储库启用并行执行。此方法大大减少了大型投资组合的总评估时间。

交互模式（在本地评估）

运行现代化工具：
```
modernize
```
从主菜单中选择 “评估 ”。
选择如何指定目标存储库。 从配置文件中选择以使用repos.json文件。

小窍门

还可以选择 “手动输入 ”以直接输入本地路径或远程 Git URL，或者 选择“当前”文件夹 来评估当前目录中的项目。
repos.json如果在默认位置检测到该文件，代理会自动填充该文件。否则，请输入配置文件的路径，然后按 Enter。
默认情况下，所有存储库均处于选中状态。取消选择想要跳过的任何存储库，然后按 Enter 确认选择。
- 使用箭头键 进行导航，然后按 空格 键切换单个存储库。
选择要分析的评估域。 Upgrade 和 Cloud Readiness在存储库中的Java和.NET项目上运行。默认情况下，Security处于未选中状态，仅在Java项目上运行;选择它以扫描 CVE 漏洞和 ISO 5055 引导的 CWE 问题。
查看和配置评估选项。配置页显示按语言和域分组的选项：
- 常规/分析覆盖范围：
  - 问题（ 默认值）：检测源代码中的现代化和安全问题。最快选项。
  - 完整分析：检测问题，并额外生成应用程序六个方面 的代码库见解 - 体系结构、 API 协定、配置、 业务工作流、 依赖项和数据模型。运行时间比仅问题分析要长。
- Java/UPGRADE：目标运行时（OpenJDK 11、17、21 或 25）。
- Java/CLOUD READINESS：目标计算服务、目标操作系统和容器化。
- Java/ SECURITY：最小 CVE 严重性（low、medium、high、critical; 默认high）。较低的严重性值对应更多发现。 （安全域目前仅Java。
- .NET/UPGRADE：目标框架（.NET 8、9 或 10）。
- .NET/CLOUD READINESS：目标计算服务。
使用箭头键进行导航，按 Enter 更改值，或选择 “继续 ”继续执行当前设置。

小窍门

建议的默认值适用于大多数方案。仅当有特定要求（例如针对特定 JDK 版本、特定Azure计算服务或不同的 CVE 严重性阈值）时，才需要更改这些设置。
选择执行模式。选择“ 在本地评估”。
输入评估结果的输出路径，或按 Enter 接受默认值。
代理自动：
- 克隆远程存储库（直接使用本地路径存储库）。
- 逐个对每个存储库运行评估。
- 生成单个评估报告。
- 创建聚合报表。
评估完成后，代理会自动打开聚合报表。

交互模式（委派给云代理）

首先，在每个应用程序存储库中配置云代理。若要配置云代理，请分叉示例存储库。

.NET 应用程序的配置

配置为在 Windows 上运行 .NET Framework 应用程序

默认情况下，Copilot云代理在 Ubuntu Linux 环境中运行。对于 .NET Framework 应用程序，需要一个Windows环境。若要启用它，请在应用程序代码仓库的.github/workflows/copilot-setup-steps.yaml分支中配置main，如以下示例所示：

# Windows-based Copilot Setup Steps for .NET tasks
# Note: Windows runners have firewall limitations that may affect some network operations
# Use this workflow for .NET projects that require Windows-specific tooling

name: "Copilot Setup Step (Windows)"

on:
  workflow_dispatch:

jobs:
  copilot-setup-steps:
    runs-on: windows-latest
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

详细了解：通过Copilot设置步骤自定义Copilot的开发环境

禁用防火墙

在存储库设置中禁用Copilot云代理的集成防火墙，如下图所示：

MCP 服务器

如以下示例所示，在仓库设置的 Cloud 代理 部分中配置 GitHub Copilot Modernization MCP 服务器：

{
  "mcpServers": {
   "AppModDotNetUpgrade": {
        "type": "local",
        "command": "dotnet",
        "args": [
          "dnx",
          "Microsoft.GitHubCopilot.Modernization.Mcp",
          "--prerelease",
          "--yes",
          "--source",
          "https://api.nuget.org/v3/index.json"
        ],
        "env": {
          "APPMOD_CALLER_TYPE": "modernize-cli"
        },
        "tools": ["*"]
    }
  }
}

Java应用程序的配置

在仓库设置的 Cloud agent 部分中配置 GitHub Copilot Modernization MCP 服务器，如以下示例中所示：

{
  "mcpServers": {
    "app-modernization": {
      "type": "local",
      "command": "npx",
      "tools": [
        "*"
      ],
      "args": [
        "-y",
        "@microsoft/github-copilot-app-modernization-mcp-server"
      ]
    }
  }
}

步骤

云委派的交互流程与 本地评估 在源、存储库、域和配置步骤中相同。唯一的区别是执行模式选择以及之后会发生什么。

运行现代化工具：
```
modernize
```
从主菜单中选择“ 评估 ”，选择源（配置文件、手动输入或当前文件夹）、选择存储库、选择 评估域并查看配置。这些步骤与交互模式（本地评估）中所述完全相同。
选择执行模式。选择 委托到云代理。
输入评估结果的输出路径，或按 Enter 接受默认值。
代理会自动将每个存储库的评估任务委托给云代理，并在云中并行执行它们。

代理将每个应用评估结果拉回本地，并在本地生成聚合报表。
评估完成后，代理会自动打开聚合报表。

非交互模式（CLI）

还可以通过直接指定命令参数来使用非交互式模式。使用 modernize assess 命令：

使用存储库配置文件在本地评估：

modernize assess --source .github/modernize/repos.json

通过直接指定源来评估多个存储库：

modernize assess --source https://github.com/org/repo1 --source https://github.com/org/repo2

通过委托给云代理进行评估：

modernize assess --source .github/modernize/repos.json --delegate cloud --wait

有关详细信息，请参阅评估 - CLI 命令。

Azure Migrate 集成

可以直接从Azure Migrate项目驱动批量评估，并让生成的报表自动流回到Azure Migrate。

端到端流程：

从 Azure Migrate 下载入门 repos.json。 Azure Migrate生成一个 JSON 文件，该文件的范围限定为你为现代化评估选择的应用程序。该文件已包含 apps[] 条目以及指回你的 Azure Migrate 项目的 output 块。
填写存储库 URL。 编辑下载文件中的每个 repos[] 条目，以添加应用程序的GitHub存储库 URL。将 apps[] 和 output 块保持为 Azure Migrate 生成时的原样 - 这些块用于控制上传过程。
运行批量评估。 在本地运行评估，或通过按照前面的步骤委托给云代理来运行评估。这两种执行模式都遵循Azure Migrate输出配置。
报表自动上传。 评估完成后，现代化代理会将每个应用程序的报表上传回Azure Migrate项目。不需要额外的 CLI 参数——repos.json 文件中的 output.type 设置会控制上传。

了解聚合报表

聚合报表提供跨评估应用程序的综合视图，如下所示：

仪表板

项目组合健康状况概况：应用总数、需要升级的数量，以及总括阻塞问题和问题数量统计。
技术分发：正在使用哪些框架以及有多少应用共享它们。
工作量分配：总体迁移是一项小型或大型迁移。

建议

Azure Services：将当前依赖项映射到建议的等效Azure依赖项。跨应用的共享依赖项仅需决定一次，因此可以避免每个应用的重复工作。
Target Platform：指导托管选择，例如Azure 容器应用与 AKS，并呈现整合机会。
升级路径：确定哪些应用需要框架升级作为先决条件，将升级工作与迁移工作分开。
Cost Estimate：估计在每个应用程序的建议目标上运行每个应用程序的Azure成本，以便可以考虑将支出纳入优先级。
迁移策略：为每个应用程序推荐相应的迁移方案——例如，对于提升并重塑类迁移可采用 Replatform，对于需要更深层次重构的情况可采用 Rearchitect——从而确保每个应用都能获得与其就绪程度相匹配的策略。
迁移波：按准备情况和风险对应用进行排序（例如，第 1 波快速胜出、第 2 波核心云、第 3 波长期投注）。方法使得在准备更复杂的应用程序的同时取得初步成功。

应用程序评估矩阵

有关框架、目标平台、升级建议、问题细分（必需、潜在、可选）、工作量调整等各方面的应用程序的快速概述。
指向各个应用报表的链接，以便在需要时深入查看。

批处理评估疑难解答

常见问题

存储库访问错误：

使用 gh auth status 验证GitHub身份验证。
请确保有权访问列出的 repos.json所有存储库。

克隆失败：

验证存储库 repos.json URL 是否正确且可访问。
请确保对所有存储库具有正确的访问权限。
检查网络连接和 VPN 设置。

评估失败：

检查存储库是否包含有效的Java、.NET或 JavaScript/TypeScript 项目。
验证是否存在生成文件，例如pom.xml、build.gradle、*.csproj、*.sln或*.slnxpackage.json。
查看控制台输出中的错误消息。非致命警告（例如，子模块中缺少的生成文件）现在直接显示到 CLI 输出 - 在将报表视为最终版本之前查看它们。

云代理委派问题：

云代理委派仅接受 https://github.com/... 存储库 URL。本地路径和非 GitHub 提供方（GitLab、Azure DevOps）会在一开始就被拒绝，并提示明确的错误信息。对这些存储库使用本地执行。
请确保拥有创建GitHub Actions工作流的正确权限。
检查组织的 GitHub Actions 权限和配额限制。
对于 .NET Framework 应用，请确保正确设置Windows运行程序配置。
检查 MCP 服务器配置。

后续步骤

完成批次评估后，您可以：

继续现代化工作流：

跨存储库运行批处理升级 - 根据评估结果应用一致的升级。

了解详细信息：

提供反馈

您的输入非常重要！如果对批处理评估或现代化代理有任何反馈，在 github-copilot-appmod 存储库中中创建问题，或使用 GitHub Copilot现代化反馈表单。

反馈

此页面是否有帮助？

Last updated on 2026-06-02