Valutazione batch con l'agente di modernizzazione GitHub Copilot

La valutazione batch consente di analizzare un portfolio di applicazioni Java, .NET e JavaScript/TypeScript in un'unica esecuzione. È possibile ottenere una panoramica completa del panorama della modernizzazione nelle applicazioni. Questo articolo illustra il processo di valutazione efficiente di più repository. Il processo supporta sia repository a linguaggio singolo che mono-repos che contengono una combinazione di progetti Java, .NET e JavaScript/TypeScript.

Ogni applicazione viene analizzata lungo due tracce complementari. L'analisi dei problemi rileva i problemi che è necessario risolvere. Codebase insights documenta come viene compilata l'applicazione in modo da poterla pianificare.

Analisi dei problemi

L'analisi dei problemi rileva problemi di modernizzazione e sicurezza in tre domini. La copertura del linguaggio varia in base al dominio:

• Aggiornamento : analisi della versione del runtime e del framework. Tratta Java e .NET.
• Preparazione al cloud — idoneità della piattaforma di destinazione di Azure e problemi di migrazione. Comprende Java e .NET.
• Sicurezza : CVE analizza le dipendenze dirette e transitive, oltre ai problemi di sicurezza CWE guidati da ISO 5055 . Solo Java al momento; il supporto per .NET e JavaScript/TypeScript è previsto nella roadmap.

Informazioni dettagliate sulla codebase

Codebase insights documenta come viene compilata ogni applicazione. Vengono prodotti per progetti Java, .NET e JavaScript/TypeScript. Vengono visualizzati quando si seleziona Analisi completa nell'impostazione Analisi coverage.

• Architettura : diagramma dell'architettura di alto livello con livelli, limiti del modulo, topologia di runtime e punti di ingresso.
• Contratti API — interfacce REST, gRPC, message-queue e webhook che l'app espone o utilizza. Dimensioni del raggio di esplosione di integrazione prima della migrazione.
• Configurazione : file di configurazione, variabili di ambiente, flag di funzionalità, stringhe di connessione e segreti. Determina la migrazione dei segreti e della configurazione a Azure Key Vault e Configurazione app di Azure.
• Flussi di lavoro aziendali : flussi funzionali end-to-end ricostruiti dal codice (ad esempio, ordinare → riservare → pagare → soddisfare). Definisce l'ambito della regressione e la comunicazione con gli stakeholder.
• Dipendenze — librerie dirette e transitive, SDK e driver con versioni bloccate. Alimenta la mappatura dei servizi Azure ed evidenzia versioni EOL o beta bloccate.
• Modello di dati : database, schemi, entità chiave e relazioni da mapping ORM e DDL. Guida la pianificazione della migrazione del livello dati.

Reports

La valutazione batch è particolarmente utile per la pianificazione della migrazione perché consente di valutare in modo efficiente la conformità e i requisiti di varie applicazioni contemporaneamente. Usando la valutazione batch, è possibile valutare contemporaneamente repository diversi e ottenere report di valutazione dettagliati per ogni applicazione. Produce due tipi di report per supportare la pianificazione della migrazione:

• Report per repository: fornisce informazioni dettagliate sui due aspetti identificati a livello di singolo repository.
• report Aggregated report: presenta una prospettiva complessiva di tutte le applicazioni valutate, che offre informazioni dettagliate di riepilogo, raccomandazioni su servizi Azure, piattaforme di destinazione, percorsi di aggiornamento, strategie di migrazione e onde di migrazione. Inoltre, il report aggregato comprende collegamenti rapidi per accedere facilmente a ogni report per repository.

La valutazione batch offre i vantaggi seguenti:

• Visibilità tra applicazioni:

  • Report aggregati: ottenere una visualizzazione completa tra le applicazioni.
  • Analisi tra più repository: Identificare modelli e dipendenze comuni tra applicazioni.
  • Informazioni dettagliate sulla definizione delle priorità: comprendere quali applicazioni necessitano di attenzione immediata.

• Scalabilità ed efficienza:

  • Elaborazione parallela: usare gli agenti cloud per elaborare più repository contemporaneamente.
  • Flussi di lavoro automatizzati: integrazione con pipeline CI/CD per la valutazione pianificata.
  • Risparmio di tempo: ridurre il tempo totale di valutazione da settimane a ore.

Prerequisiti

• Modernizzare la CLI.
• Accesso a tutti i repository da valutare.
• L'autenticazione di GitHub è configurata (gh auth login).

Configurare gli archivi

L'agente di modernizzazione supporta diversi modi per specificare i repository da valutare:

• Cartella corrente: Valuta il progetto nella tua attuale directory di lavoro.
• Inserimento manuale: immettere direttamente i percorsi delle directory locali o gli URL Git remoti.
• File di configurazione del repository: usare un file di configurazione JSON che elenca tutti i repository.

File di configurazione del repository

Per le operazioni batch in molti repository, creare un file di configurazione JSON per elencare tutti i repository. Ad esempio, crealo nella directory di lavoro .github/modernize/repos.json oppure specifica un percorso personalizzato.

Assicurarsi di avere le autorizzazioni appropriate per i repository o crearne una copia tramite fork.

Formato semplice (matrice di repository):

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

Formato completo (con rami e percorsi locali):

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

Ogni voce del repository supporta i campi seguenti:

Formato completo con raggruppamento di app (facoltativo, per la creazione di report organizzati):

È possibile aggiungere una apps[] sezione per raggruppare i repository in applicazioni logiche. Quando vengono definite le app, il report aggregato organizza i risultati in base all'applicazione e supporta la distribuzione dei report in destinazioni esterne.

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

Ogni voce nell’app supporta:

Il output campo supporta i tipi di distribuzione seguenti:

L'agente di modernizzazione rileva automaticamente il repos.json file in .github/modernize/repos.json quando si seleziona Da un file di configurazione in modalità interattiva. È anche possibile fornire un percorso personalizzato.

Eseguire la valutazione batch

Sono disponibili due modalità di esecuzione:

• Esecuzione locale: l'agente di modernizzazione elabora i repository uno dopo l'altro nel computer locale. Questa modalità funziona meglio per un set più piccolo di applicazioni o per i test iniziali. Supporta sia gli URL Git sia i repository di percorsi locali.
• Delega agli agenti cloud: l'agente di modernizzazione invia attività agli agenti cloud di GitHub Copilot per l'elaborazione parallela nel cloud. Questa modalità è più veloce per scenari multi-repo.

Modalità interattiva (valutazione locale)

1. Eseguire l'agente di modernizzazione:

   modernize
   

2. Selezionare Valutare dal menu principale.

   

3. Scegliere come specificare i repository di destinazione. Selezionare Da un file di configurazione per usare un repos.json file.

   

   Suggerimento

   È anche possibile selezionare Input manuale per digitare direttamente percorsi locali o URL Git remoti oppure Cartella corrente per valutare il progetto nella tua directory attuale.

4. Se il repos.json file viene rilevato nel percorso predefinito, l'agente lo riempie automaticamente. In caso contrario, immettere il percorso del file di configurazione e premere INVIO.

5. Tutti i repository sono selezionati per impostazione predefinita. Deselezionare tutti i repository da ignorare e quindi premere INVIO per confermare la selezione.

   • Usare i tasti di direzione per spostarsi e premere Spazio per attivare o disattivare singoli repository.

   

6. Selezionare i domini di valutazione da analizzare. Upgrade e Cloud Readiness vengono eseguiti su progetti Java e .NET nel repository. Security è deselezionato per impostazione predefinita e viene eseguito solo nei progetti Java. Selezionarlo per cercare vulnerabilità CVE e problemi CWE guidati da ISO 5055.

   

7. Esaminare e configurare le opzioni di valutazione. La pagina di configurazione mostra le opzioni raggruppate per lingua e dominio:

   • Copertura generale/analisi:
     • Solo problema (impostazione predefinita): rileva problemi di modernizzazione e sicurezza nel codice sorgente. Opzione più veloce.
     • Analisi completa: rileva i problemi e genera informazioni dettagliate sulla codebase in sei aspetti dell'applicazione: architettura, contratti API, configurazione, flussi di lavoro aziendali, dipendenze e modello di dati. L'esecuzione richiede più tempo rispetto all'analisi dei soli problemi.
   • Java/UPGRADE: Runtime di destinazione (OpenJDK 11, 17, 21 o 25).
   • Java/CLOUD READINESS: Servizi di calcolo di destinazione, Sistema operativo di destinazione e Containerizzazione.
   • Java/SECURITY: gravità minima CVE (low, medium, high, critical; valore predefinito high). I valori di gravità inferiori includono più risultati. (Il dominio di sicurezza è attualmente solo per Java.)
   • .NET/UPGRADE: Framework di destinazione (.NET 8, 9 o 10).
   • .NET/CLOUD READINESS: Servizi di calcolo mirati.

   Usare i tasti di direzione per spostarsi, premere INVIO per modificare un valore o selezionare Continua per continuare con le impostazioni correnti.

   

   Suggerimento

   Le impostazioni predefinite consigliate funzionano per la maggior parte degli scenari. È necessario modificare queste impostazioni solo se si hanno requisiti specifici, ad esempio la destinazione di una determinata versione JDK, uno specifico servizio di calcolo Azure o una soglia di gravità CVE diversa.

8. Scegliere la modalità di esecuzione. Selezionare Valuta localmente.

   

9. Immettere il percorso di output per i risultati della valutazione o premere INVIO per accettare l'impostazione predefinita.

10. L'agente opera automaticamente:

    • Clona i repository remoti (i repository di percorsi locali vengono usati direttamente).

    • Esegue la valutazione in ogni repository uno alla volta.

    • Genera report di valutazione individuali.

      

    • Crea un report aggregato.

      

11. Al termine della valutazione, l'agente apre automaticamente il report aggregato.

    

Modalità interattiva (che delega agli agenti cloud)

Prima di tutto, configurare gli agenti cloud in ogni repository di applicazioni. Per configurare gli agenti cloud, eseguire un fork dei repository di esempio.

Configurazione per le applicazioni .NET

Configurare per l'esecuzione in Windows per le applicazioni .NET Framework

Per impostazione predefinita, l'agente cloud Copilot viene eseguito in un ambiente Ubuntu Linux. Per le applicazioni .NET Framework, è necessario un ambiente Windows. Per abilitarla, configurare .github/workflows/copilot-setup-steps.yaml nel main ramo del repository dell'applicazione, come illustrato nell'esempio seguente:

# 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

Per saperne di più su: Personalizzazione dell'ambiente di sviluppo di Copilot con i passaggi di configurazione di Copilot

Disabilitare il firewall

Disabilita il firewall integrato dell'agente cloud di Copilot nelle impostazioni del repository, come illustrato nell'immagine seguente:

MCP Server

Configura il server MCP Modernization di GitHub Copilot nella sezione Cloud agent nelle impostazioni del repository, come illustrato nell'esempio seguente:

{
  "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": ["*"]
    }
  }
}

Configurazione per le applicazioni Java

Configura il server MCP di modernizzazione di GitHub Copilot nella sezione Cloud agent delle impostazioni del repository, come mostrato nell'esempio seguente:

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

Gradi

Il flusso interattivo per la delega cloud è identico a Valutare localmente tramite i passaggi di origine, repository, dominio e configurazione. L'unica differenza è la scelta in modalità di esecuzione e ciò che accade in seguito.

1. Eseguire l'agente di modernizzazione:

   modernize
   

2. Selezionare Valuta dal menu principale, scegliere l'origine (file di configurazione, input manuale o cartella corrente), selezionare i repository, selezionare i domini di valutazione e rivedere la configurazione. Questi passaggi funzionano esattamente come descritto in modalità interattiva (valutare localmente).

3. Scegliere la modalità di esecuzione. Selezionare Delegare agli agenti cloud.

   

4. Immettere il percorso di output per i risultati della valutazione o premere INVIO per accettare l'impostazione predefinita.

5. L'agente delega automaticamente le attività di valutazione per ogni repository agli agenti cloud e le esegue nel cloud in parallelo.

   

   L'agente recupera i risultati della valutazione per app a livello locale e genera in loco il report aggregato.

   

6. Al termine della valutazione, l'agente apre automaticamente il report aggregato.

Modalità non interattiva (interfaccia della riga di comando)

È anche possibile usare la modalità non interattiva specificando direttamente gli argomenti di comando. Usare il comando modernize assess:

Valutare in locale usando un file di configurazione del repository:

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

Valutare più repository specificando direttamente le origini:

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

Valutare delegando agli agenti cloud:

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

Per altre informazioni, vedere Valutare - Comandi dell'interfaccia della riga di comando.

Integrazione di Azure Migrate

È possibile eseguire la valutazione batch direttamente dal progetto Azure Migrate e riportare automaticamente i report risultanti a Azure Migrate.

Il flusso completo:

1. Scarica un modello iniziale repos.json da Azure Migrate. Azure Migrate genera un file JSON con ambito per le applicazioni selezionate per la valutazione della modernizzazione. Il file contiene già le voci apps[] e il blocco output, che rimanda al progetto Azure Migrate.

2. Inserire gli URL del repository. Modificare ogni voce repos[] nel file scaricato per aggiungere l'URL del repository GitHub per l'applicazione. Mantieni i blocchi apps[] e output così come sono stati generati da Azure Migrate: tali blocchi gestiscono il caricamento.

3. Esegui la valutazione in batch. Esegui la valutazione in locale o delegandola agli agenti cloud seguendo i passaggi precedenti. Entrambe le modalità di esecuzione rispettano la configurazione di output Azure Migrate.

4. I report si caricano automaticamente. Al termine della valutazione, l'agente di modernizzazione carica il report di ogni applicazione nel progetto di Azure Migrate. Non è necessario alcun flag CLI aggiuntivo: è l'impostazione output.type nel file repos.json che controlla il caricamento.

Informazioni sul report aggregato

Il report aggregato offre una visualizzazione completa delle applicazioni valutate nel modo seguente:

Dashboard

• Snapshot dell'integrità del portfolio: il numero totale di app, quante necessitano di aggiornamenti, e i conteggi aggregati di blocchi e problemi.
• Distribuzione della tecnologia: quali framework sono in uso e quante app le condividono.
• Distribuzione del lavoro: se la migrazione complessiva è una piccola o grande impresa.

Raccomandazioni

• Azure Services: esegue il mapping delle dipendenze correnti agli equivalenti Azure consigliati. Le dipendenze condivise tra le app vengono decise una sola volta, in modo da evitare la rielaborazione per app.
• Target Platform: guida la scelta dell'hosting, ad esempio tra App contenitore di Azure e AKS, e mette in evidenza le opportunità di consolidamento.
• Percorso di aggiornamento: identifica le app che necessitano di aggiornamenti del framework come prerequisito, separando il lavoro di aggiornamento dal lavoro di migrazione.
• Cost Estimate: stima il costo Azure dell'esecuzione di ogni applicazione nella destinazione consigliata, in modo da poter considerare la spesa per la definizione delle priorità.
• Strategie di migrazione: consiglia un approccio di migrazione per ciascuna applicazione, ad esempio Replatform per migrazioni lift-and-reshape o Rearchitect per refactoring più approfonditi, così che a ogni applicazione venga assegnata una strategia adatta al suo livello di preparazione.
• Ondate di migrazione: organizza le applicazioni in sequenza, in base al livello di preparazione e al rischio, in fasi (ad esempio, Wave 1 risultati rapidi, Wave 2 cloud core, Wave 3 scommesse a lungo termine). Questo approccio consente la vittoria anticipata, mentre le app più difficili vengono preparate in parallelo.

Matrice di valutazione delle applicazioni

• Panoramica rapida per ogni applicazione su aspetti del framework, piattaforma di destinazione, raccomandazione di aggiornamento, scomposizione dei problemi (obbligatorio, potenziale, facoltativo), ridimensionamento e altro ancora.
• Collegamenti a singoli report dell'app per il drill-down quando necessario.

Risoluzione dei problemi relativi all'analisi batch

Problemi comuni

Errori di accesso al repository:

• Verificare l'autenticazione di GitHub usando gh auth status.
• Assicurarsi di avere accesso a tutti i repository elencati in repos.json.

Errori di clonazione:

• Verificare che gli URL del repository in repos.json siano corretti e accessibili.
• Assicurarsi di disporre delle autorizzazioni di accesso appropriate per tutti i repository.
• Controllare la connettività di rete e le impostazioni VPN.

Errori di valutazione:

• Verificare se il repository contiene progetti Java, .NET o JavaScript/TypeScript validi.
• Verificare che i file di compilazione esistano, ad esempio pom.xml, build.gradle*.csproj, *.sln, *.slnx, o package.json.
• Esaminare i messaggi di errore nell'output della console. Gli avvisi non critici (ad esempio, i file di compilazione mancanti in un sottomodulo) vengono ora visualizzati direttamente nell'output della CLI; esaminali prima di considerare il report definitivo.

Problemi di delega dell'agente cloud:

• La delega dell'agente cloud accetta solo https://github.com/... gli URL del repository. I percorsi locali e i provider non GitHub (GitLab, Azure DevOps) vengono rifiutati in anticipo con un errore descrittivo. Usare l'esecuzione locale per tali repository.
• Assicurarsi di disporre delle autorizzazioni appropriate per creare flussi di lavoro GitHub Actions.
• Controlla le autorizzazioni di GitHub Actions e i limiti di quota per l'organizzazione.
• Per le app di .NET Framework, assicurarsi che la configurazione del runner di Windows sia impostata correttamente.
• Controllare la configurazione del server MCP.

Passaggi successivi

Dopo aver completato la valutazione batch, è possibile:

Continuare il flusso di lavoro di modernizzazione:

• Eseguire l'aggiornamento batch tra repository : applicare aggiornamenti coerenti in base ai risultati della valutazione.

Altre informazioni:

• Creare competenze personalizzate per modelli specifici dell'organizzazione.
• Scopri i comandi CLI.

Inviare commenti

L'input è importante. Se si hanno commenti e suggerimenti sulla valutazione batch o sull'agente di modernizzazione, creare un problema nel repository github-copilot-appmod o usare il modulo di feedback sulla modernizzazione GitHub Copilot.