Risolvere i problemi di modernizzazione GitHub Copilot

Questo articolo tratta dei problemi comuni che possono verificarsi durante l'utilizzo di GitHub Copilot per la modernizzazione su .NET, organizzati per categoria. Ogni voce segue un problema, una causa e un formato di soluzione per poter trovare e risolvere rapidamente i problemi.

Problemi del flusso di lavoro

Questi problemi si riferiscono all'individuazione dello scenario, alla ripresa del lavoro e allo stato dell'attività.

Agent indica che non sono stati trovati scenari

Cause: L'agente non riconosce l'area di lavoro come progetto di .NET.

Soluzione:

  1. Verificare che la radice dell'area di lavoro contenga un file .sln, .csproj o .vbproj.
  2. Chiedere all'agente: "Quale soluzione o file di progetto si usa?"
  3. Se la soluzione o il file di progetto si trova in una sottodirectory, aprire tale directory come radice dell'area di lavoro o puntare l'agente al file in modo esplicito.

L'agente non può riprendere il lavoro precedente

Causa: La .github/upgrades/ cartella, in cui l'agente archivia tutto lo stato, è mancante o danneggiata.

Soluzione:

  1. Controllare se la cartella .github/upgrades/ esiste nella directory principale del repository.
  2. Se la cartella è stata eliminata accidentalmente, avviare lo scenario aggiornato. L'agente non può eseguire il ripristino senza i relativi file di stato.
  3. Se la cartella esiste ma i file appaiono danneggiati, chiedere all'agente di "rivalutare e ripianificare" per rigenerarli.

Suggerimento

Effettuare il commit della cartella .github/upgrades/ nel ramo per preservarla tra sessioni e computer.

Attività bloccate in corso

Causa: La sessione precedente è terminata mentre l'agente era a metà attività.

Soluzione:

  1. L'agente rileva automaticamente le attività non aggiornate nella maggior parte dei casi. Indicare all'agente di "riprendere" o "riavviare l'attività corrente".
  2. Se lo stato bloccato persiste, indicare all'agente "contrassegnare l'attività corrente come in sospeso e riavviarla" o "rivaluta e continuare dall'ultimo passaggio completato".
  3. Controllare il file corrispondente progress-details.md per capire dove è stata interrotta la sessione precedente.

Agente continua a suggerire uno scenario sbagliato

Causa: L'analisi dell'agente ha rilevato caratteristiche impreviste del progetto e ha dedotto uno scenario diverso da quello previsto.

Soluzione:

Essere espliciti su ciò che vuoi. Invece di "aggiornare il progetto", dire:

  • "Voglio eseguire l'aggiornamento a .NET 10."
  • "Voglio eseguire l'aggiornamento da Newtonsoft.Json a System.Text.Json."
  • "Converti il mio progetto in formato SDK".

Aggiungere le preferenze dello scenario a scenario-instructions.md per evitare future mancate corrispondenze.

Problemi di creazione e compilazione

Questi problemi si riferiscono a errori di compilazione, problemi di ripristino NuGet e errori di generazione del codice.

Compilazione fallita dopo le modifiche apportate dall'agente

Causa: Gli aggiornamenti possono introdurre modifiche dell'API di rilievo, pacchetti mancanti o modelli di codice incompatibili.

Soluzione:

  1. Comunicare all'agente l'errore. L'agente analizza automaticamente gli errori.
  2. Se l'agente non riesce a risolvere il problema, ripristinare l'ultimo commit (git revert HEAD) e chiedere all'agente di provare un approccio diverso.
  3. Per gli errori complessi, verificare execution-log.md per capire che cosa ha cambiato l'agente e in quale ordine.

Il ripristino NuGet non riesce

Causa: Incompatibilità del pacchetto con il framework di destinazione o gli errori di autenticazione con feed NuGet privati.

Soluzione:

  • Per i feed privati: Eseguire l'autenticazione al feed prima di avviare l'aggiornamento.
  • Per i pacchetti incompatibili: Indicare all'agente quale pacchetto è problematico. L'agente può cercare versioni compatibili o suggerire pacchetti alternativi.
  • Per i problemi di connettività del feed: Verificare che sia possibile eseguire dotnet restore manualmente. Risolvere prima i problemi del feed, quindi lasciare che l'agente riprova.

Agent genera codice che non viene compilato

Causa: Il codice generato dall'intelligenza artificiale può contenere errori, in particolare nei casi perimetrali o con modelli API non comuni.

Soluzione:

  1. L'agente rileva automaticamente gli errori di compilazione. Se l'agente è in difficoltà, fornire indicazioni o correggere manualmente il codice e indicare all'agente di continuare.
  2. Se l'agente ha difficoltà con una correzione specifica dopo più tentativi, modificare il codice manualmente e indicare all'agente: "Ho risolto l'errore di compilazione in MyClass.cs, contrassegna il completamento dell'attività".
  3. L'agente apprende dalla correzione manuale e applica schemi simili quando lo stesso problema si verifica altrove.

Problemi relativi a Git

Annotazioni

L'agente funziona anche con cartelle non Git. Se l'area di lavoro non è un repository Git, l'agente ignora le operazioni Git (diramazione, commit) e applica le modifiche direttamente ai file. Senza Git, eseguire manualmente il backup del progetto prima di iniziare in modo da poter ripristinare se necessario.

L'agente non può creare un ramo

Causa: Le modifiche di cui non è stato eseguito il commit nell'albero di lavoro, un conflitto di denominazione dei rami o Git non vengono inizializzate nell'area di lavoro.

Soluzione:

  1. Effettua il commit o lo stash delle modifiche in sospeso prima di avviare il scenario.
  2. Verificare che Git sia inizializzato eseguendo git status nella radice dell'area di lavoro.
  3. Se esiste già un ramo con il nome previsto dell'agente, eliminare il ramo esistente o chiedere all'agente di usare un nome di ramo diverso.

Annullare tutte le modifiche dell'agente

Causa: L'aggiornamento non è stato pianificato e si vuole ricominciare.

Soluzione:

  1. Tornare al ramo originale con git checkout main (o il ramo di base).
  2. Il ramo di lavoro dell'agente contiene tutte le modifiche isolate dal ramo principale.
  3. Per rimuovere completamente il ramo dell'agente, eseguire git branch -D <agent-branch-name>.
  4. Per mantenere alcune modifiche, seleziona i commit specifici con git cherry-pick <commit-hash>.

Suggerimento

L'agente esegue commit granulari per ogni attività, in modo da poter mantenere selettivamente le modifiche che hanno funzionato.

Problemi di prestazioni

Questi problemi si riferiscono alla velocità di aggiornamento e alla durata della valutazione.

L'agente è lento o richiede molto tempo

Causa: Le soluzioni di grandi dimensioni con molti progetti, grafici delle dipendenze complessi o numerose modifiche di rilievo richiedono naturalmente più tempo.

Soluzione:

Per soluzioni di grandi dimensioni (oltre 50 progetti), è consigliabile eseguire l'aggiornamento in batch. Raggruppare i progetti correlati e aggiornarli insieme.

La valutazione richiede molto tempo

Causa: La valutazione analizza le dipendenze di ogni progetto, i pacchetti NuGet, i framework di destinazione e le modifiche rilevanti applicabili. Per le soluzioni di grandi dimensioni, la valutazione richiede naturalmente più tempo.

Soluzione:

  1. I tempi di valutazione lunghi sono normali per soluzioni di grandi dimensioni. Non è necessaria alcuna azione.
  2. Monitorare lo stato di avanzamento nel pannello Output (selezionare AppModernizationExtension dall'elenco a discesa in Visual Studio).
  3. La valutazione viene eseguita una sola volta per ogni scenario. Le fasi successive usano i risultati memorizzati nella cache.

Problemi di personalizzazione

Questi problemi si riferiscono alle abilità personalizzate e ai file di istruzioni di scenario.

La competenza personalizzata non viene riconosciuta

Causa: Il file di competenza si trova nel percorso errato, contiene metadati mancanti o non validi o ha un formato non corretto.

Soluzione:

  1. Verificare che il file delle skill sia in uno dei percorsi supportati:
    • .github/skills/ (a livello di repository, a livello di team)
    • .github/upgrades/skills/ (a livello di scenario)
    • %UserProfile%/.copilot/skills/ (livello utente, a uso personale)
  2. Verificare che i metadati della competenza includano almeno name e description campi.
  3. Verificare che il discovery campo (se impostato) sia uno di: lazy, preloado scenario.
  4. Verificare che la competenza description corrisponda al tipo di attività a cui si prevede di applicarla. L'agente usa la corrispondenza delle descrizioni per selezionare le abilità.

Le modifiche apportate a scenario-instructions.md non hanno effetto

Causa: L'agente potrebbe non rileggere il file durante la sessione intermedia oppure le modifiche si trovano nella sezione errata.

Soluzione:

  1. Chiedere all'agente di "ricaricare le istruzioni" o avviare una nuova sessione di chat per forzare una rilettura.
  2. Verificare che le modifiche siano presenti nelle sezioni corrette del file:
    • Preferenze utente: Per le preferenze e i vincoli generali.
    • Decisioni chiave: Per registrare decisioni importanti prese durante l'aggiornamento.
    • Istruzioni personalizzate: Per sovrascritture comportamentali specifiche.
  3. Verificare che il file venga salvato e nel percorso previsto: .github/upgrades/{scenarioId}/scenario-instructions.md.

Ottenere assistenza

Quando qualcosa non funziona come previsto:

  1. Chiedere all'agente: Chiedere "Cosa è andato storto con l'ultima attività?" L'agente può spesso spiegare cosa è successo e suggerire i passaggi successivi.
  2. Esaminare il log di esecuzione: Aprire execution-log.md in .github/upgrades/{scenarioId}/. Il log mostra un record cronologico delle operazioni che l'agente ha eseguito, inclusi gli eventuali errori rilevati.
  3. File an issue: Se hai trovato un bug o l'agente continua a fallire in qualcosa, segnala un problema nel repository su GitHub di @modernize-dotnet.

Contenuti correlati

  • Last updated on