使用 GitHub Copilot 現代化代理進行批次評估

批次評估讓你能在一次執行中分析包含 Java、.NET 和 JavaScript/TypeScript 應用程式組合。您將能全面掌握整個應用程式的現代化全貌。本文將引導您有效評估多個資料庫的過程。此流程同時支援單語言儲存庫，以及包含混合了 Java、.NET 和 JavaScript/TypeScript 專案的 mono-repos。

每個申請都沿著兩條互補的方向進行分析。 問題掃描 會發現你需要修正的問題。程式碼基礎洞察記錄應用程式如何建置，讓你能圍繞它進行規劃。

問題掃描

問題掃描能偵測三個領域的現代化與安全問題。語言覆蓋因領域而異：

升級 — 執行時與框架版本分析。涵蓋 Java 和 .NET。
雲端準備 — Azure目標平台配合與遷移問題。涵蓋 Java 與 .NET。
安全性 — 針對直接與傳遞相依性的 CVE 掃描，以及 依循 ISO 5055 的 CWE 安全問題。 目前僅支援 Java；.NET 與 JavaScript/TypeScript 支援已列入產品路線圖。

程式碼庫洞察

程式碼庫洞察記錄每個應用程式的建置方式。它們是為 Java、.NET 以及 JavaScript/TypeScript 專案所製作的。當你在分析覆蓋度設定中選擇 完整分析 時，這些問題會浮現出來。

架構 — 高階架構圖，包含分層、模組邊界、執行時拓撲及入口點。
API 合約 — 應用程式公開或使用的 REST、gRPC、訊息佇列與 webhook 介面。在遷移前評估整合的影響範圍。
設定 — 設定檔、環境變數、功能標誌、連線字串與秘密。推動將祕密和組態移轉至 Azure Key Vault 和 Azure 應用程式組態。
業務工作流程 ——從程式碼重建的端到端功能流程（例如訂單 →預留→支付→履行）。為回歸範圍與利害關係人溝通奠定基礎。
相依性 — 直接與傳遞相依的函式庫、SDK 和已固定版本的驅動程式。它會提供 Azure 服務的對應關係，並顯示 EOL 或 Beta 標記。
資料模型 ——資料庫、結構、關鍵實體，以及來自 ORM 映射與 DDL 的關聯。推動資料層遷移規劃。

報表

批次評估對於遷移規劃特別有價值，因為它能讓你有效地同時評估各種應用程式的準備度與需求。透過批次評估，您可以同時評估不同的資料庫，並為每個應用程式取得詳細的評估報告。它會產生兩種報告來支持您的遷移規劃：

每個儲存庫報告：提供針對個別儲存庫層級所識別的兩個面向的詳細見解。
彙整報告：呈現所有評估應用的整體觀點，提供摘要見解、Azure服務、目標平台、升級路徑、遷移策略及遷移浪潮的建議。此外，彙總報告還包含方便存取每個資料庫報告的捷徑。

批次評量帶來以下好處：

跨應用程式可見性：
- 彙整報告：全面檢視各應用。
- 跨儲存庫分析：識別應用程式間的共通模式與依賴關係。
- 優先排序洞察：了解哪些應用程式需要立即關注。
規模與效率：
- 平行處理：使用雲端代理同時處理多個儲存庫。
- 自動化工作流程：整合 CI/CD 管線以進行排程評估。
- 節省時間：將總評估時間從數週縮短為數小時。

先決條件

命令列介面的現代化。
存取你想評估的所有資料庫。
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"
    }
  ]
}

每個 repo 項目支援以下欄位：

領域	說明	Required
`name`	一個友好的名稱，用於指稱資料庫（在報告和儀表板中使用）。	是的
`url`	Git 克隆網址，格式為 HTTPS 或 SSH 格式。	`url`或`path`之一
`path`	絕對本地目錄路徑。	`url`或`path`之一
`branch`	克隆後要切換到的分支。	No
`description`	人類易讀的描述。	No

完整格式及應用程式分組 （可選，用於有組織的報告）：

你可以新增一個 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"
      }
    }
  ]
}

每個應用程式條目支援：

領域	說明	Required
`identifier`	應用程式唯一的顯示名稱。	是的
`description`	人類易讀的描述。	No
`repos`	屬於這個應用程式的倉庫名稱清單。	是的
`output`	生成後，該將此應用程式的評估報告分發在哪裡。	No

該 output 場支援以下分布類型：

類型	說明	必填欄位
`local`	將報告複製到本地目錄。	`path`
`git`	把報告推送到 Git 倉庫。網址格式為 `https://github.com/org/repo.git#branch:path`。	`url`

小提示

只要你有權限，你可以包含不同組織的資料庫，並使用不同的認證方法。

現代化代理程式會在你選擇「repos.json進入互動模式時自動偵測該.github/modernize/repos.json檔案。你也可以提供自訂路徑。

執行批次評估

有兩種執行模式可供選擇：

本地執行：現代化代理會依序在你的本地機器上處理一個又一個的儲存庫。此模式最適合較小的應用群或初期測試。支援 Git URL 及本地路徑儲存庫。
Cloud agent delegation：現代化代理會將任務提交給GitHub Copilot雲端代理，以便在雲端進行平行處理。此模式在多倉庫場景中速度更快。

這很重要

雲端代理委派要求儲存庫擁有 GitHub（github.com）儲存庫 URL。本地路徑倉庫和非 GitHub 提供者（GitLab、Azure DevOps）不支援雲端委派。使用本地執行來處理那些儲存庫。

小提示

透過使用 Cloud agent 委派，你可以在所有儲存庫間實現平行執行。此方法大幅縮短大型投資組合的總評估時間。

互動模式（本地評估）

執行現代化代理程式：
```
modernize
```
從主選單選擇評估。
選擇如何指定你的目標倉庫。選擇 從設定檔 中使用 repos.json 檔案。

小提示

你也可以選擇 手動輸入 直接輸入本地路徑或遠端 Git 網址，或選擇 Current 資料夾 來評估你目前目錄中的專案。
如果 repos.json 檔案在預設位置被偵測到，代理會自動填補。否則，輸入你的設定檔路徑並按 Enter。
預設會選擇所有儲存庫。取消選擇你想跳過的儲存庫，然後按 Enter 鍵確認你的選擇。
- 用方向鍵 導航，按 空白 鍵切換各個倉庫。
選擇要分析的評估領域。 Upgrade 與 Cloud Readiness 可在倉庫中的 Java 與 .NET 專案上執行。 Security預設未勾選，僅在Java專案上執行;選擇它以掃描 CVE 漏洞及 ISO 5055 指引的 CWE 問題。
檢視並設定評估選項。設定頁面顯示依語言與領域分組的選項：
- 一般/分析報導：
  - 僅問題（預設）：偵測原始碼中的現代化和安全性問題。最快的選擇。
  - 全面分析：偵測問題，並額外產生涵蓋應用程式六個面向的 程式碼庫洞察 —— 架構、 API 合約、設定、 業務工作流程、相依性與 資料模型。比單純議題分析花更長時間。
- Java / UPGRADE：目標執行時（OpenJDK 11、17、21 或 25）。
- Java / 雲端準備：目標運算服務、目標作業系統與容器化。
- Java / SECURITY：最低 CVE 嚴重度（low、medium、high、critical;預設high）。嚴重度較低的數值包含更多發現。 （安全領域目前僅限Java。）
- .NET / UPGRADE：目標框架（.NET 8、9 或 10）。
- .NET / 雲端準備度：目標運算服務。
使用方向鍵導航，按 Enter 更改數值，或選擇繼續以目前設定繼續。

小提示

建議的預設值適用於大多數情境。只有在有特定需求時才需要更改這些設定，例如針對特定 JDK 版本、特定 Azure 運算服務，或不同的 CVE 嚴重度閾值。
選擇執行模式。選擇 「本地評估」。
輸入評量結果的輸出路徑，或按 Enter 接受預設值。
代理程式會自動：
- 克隆遠端儲存庫（本地路徑儲存庫直接使用）。
- 逐一評估每個儲存庫。
- 產生個別評估報告。
- 建立彙整報告。
評估結束後，客服會自動開啟彙整報告。

互動模式（委派給雲端代理）

首先，在每個應用程式儲存庫中設定雲端代理程式。若要設定雲端代理程式，請 Fork 範例存放庫。

.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 伺服器

請在GitHub Copilot儲存庫設定中的 Cloud agent 區塊中配置現代化 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 應用程式的設定

請在GitHub Copilot儲存庫設定中的 Cloud agent 區塊中配置現代化 MCP 伺服器，如下範例所示：

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

Steps

雲端委派的互動流程在原始碼、儲存庫、網域及設定階段與本地評估相同。唯一的差別在於執行模式的選擇以及之後發生的事情。

執行現代化代理程式：
```
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

欲了解更多資訊，請參閱 assess - CLI 指令。

Azure Migrate 整合

你可以直接從 Azure Migrate 專案驅動批次評估，並讓結果報告自動回流到 Azure Migrate。

端到端流程：

從 Azure Migrate 下載一個入門專案repos.json。 Azure Migrate 會產生一個針對你選擇的現代化評估應用程式的 JSON 檔案。檔案中已經包含 apps[] 條目，以及指向你Azure Migrate專案的 output 區塊。
填寫資料庫網址。 編輯下載檔案中每個 repos[] 條目，以新增該應用程式的 GitHub 儲存庫 URL。保留apps[]和output區塊，Azure Migrate產生它們——這些區塊驅動上傳。
進行批次評估。 可在本地執行評估，或依照前述步驟委託給雲端代理。兩種執行模式都尊重 Azure Migrate 的輸出設定。
報告會自動上傳。 評估完成後，現代化代理會將每個應用程式的報告上傳回你的 Azure Migrate 專案。不需要額外的 CLI 標誌——檔案 output.type 中的 repos.json 設定會驅動上傳。

理解彙整報告

彙整報告提供以下評估應用程式的全面概覽：

Dashboard

投資組合健康概況：應用程式總數、需要升級的數量，以及總體阻擋因素和問題數量。
技術分發：使用了哪些框架，以及有多少應用程式共享這些框架。
工作量分配：判斷整體遷移是小型還是大型專案。

建議

Azure 服務：將目前的相依性對應至建議的 Azure 對應服務。跨應用程式的共用依賴是一次性決定的，避免每個應用程式都重新設計。
Target Platform：引導主機選擇，如 Azure 容器應用程式與 AKS，並呈現整合機會。
升級路徑：識別哪些應用程式需要框架升級作為前提，將升級工作與遷移工作區分開來。
成本估算：估算每個應用程式在建議目標上運行的Azure成本，讓你能將支出納入優先排序。
遷移策略：針對每個應用程式建議適合的遷移方式——例如，對於提升並重塑的遷移採用 Replatform，而對於較深度的重構則採用 Rearchitect——讓每個應用程式都能獲得與其就緒程度相符的策略。
遷移波：依照準備度與風險將應用程式排序為不同階段（例如，第一波快速贏出，第二波核心雲，第三波長期投注）。這種方式能實現初步成功，同時準備更複雜的應用程式。

申請評估矩陣

每個應用程式的快速概述，涵蓋框架、目標平台、升級建議、問題分解（強制、潛在、可選）、工作量大小等。
需要時提供個別應用程式報告連結，方便深入分析。

批次評估排除故障

常見問題

儲存庫存取錯誤：

使用 gh auth status 驗證GitHub認證。
確保你能存取 repos.json 中列出的所有儲存庫。

複製失敗：

請確認儲存 repos.json 庫的網址是否正確且可存取。
確保你擁有所有資料庫的正確存取權限。
檢查你的網路連線和 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