Procedure consigliate per la modernizzazione GitHub Copilot

Seguire queste linee guida per ottenere risultati ottimali dalla modernizzazione GitHub Copilot durante l'aggiornamento e la migrazione di progetti .NET.

Prima di iniziare

Preparare i progetti prima di avviare un aggiornamento per ottenere i risultati migliori.

Verifica che la compilazione della soluzione sia completata e che i test siano superati.

L'agente convalida le modifiche apportate eseguendo compilazioni e test. Se la soluzione è già interrotta prima dell'avvio, l'agente non può distinguere gli errori preesistenti dai problemi introdotti.

Documentare eventuali errori di test noti in scenario-instructions.md in modo che l'agente sappia ignorarli.

Eseguire il commit o salvare temporaneamente il lavoro non ancora confermato

Inizia con una directory di lavoro pulita per evitare di mescolare le modifiche non salvate con quelle dell'agente. Una linea di base pulita semplifica la revisione o il ripristino delle modifiche.

git stash
git status

Eseguire il backup di repository non-Git

L'agente funziona anche con le cartelle che non sono sotto il controllo del codice sorgente. Se il progetto non si trova in un repository Git, l'agente ignora le operazioni di branch e commit. In tal caso, eseguire il backup della cartella del progetto prima di iniziare in modo da poterla ripristinare, se necessario.

Prendere in considerazione l'inizializzazione di un repository Git locale prima di avviare l'aggiornamento, anche se non si esegue il push in un provider di servizi cloud. Un repository Git locale consente di:

• È possibile ripristinare le singole modifiche con git revert.
• Tenere traccia dello stato di avanzamento dell'aggiornamento passo dopo passo nella cronologia dei commit.
• Controllare le modifiche da mantenere o rimuovere.
• Mantieni il codice originale al sicuro sul ramo principale mentre l'agente lavora su un ramo separato.

cd your-project-folder
git init
git add .
git commit -m "Baseline before upgrade"

Esaminare la copertura dei test

L'agente si basa sui test per verificare che le modifiche non interrompano il comportamento. I progetti con una buona copertura di test ottengono aggiornamenti con maggiore attendibilità.

Iniziare in piccolo

Se è la prima volta che si usa l'agente, selezionare un piccolo progetto a basso rischio come progetto pilota. Una libreria di classi o un progetto di utilità è ideale. L'avvio di piccole dimensioni consente di comprendere il flusso di lavoro, creare confidenza e individuare eventuali problemi specifici del repository prima di affrontare l'applicazione principale.

Durante l'aggiornamento

Seguire queste linee guida mentre l'agente esegue l'aggiornamento.

Usare la modalità guidata per il primo aggiornamento

L'agente supporta sia le modalità guidate che automatiche. In modalità guidata, l'agente si ferma in punti decisionali chiave per la revisione e l'approvazione. Iniziare con la modalità guidata per comprendere cosa fa l'agente e perché. Passare alla modalità automatica quando si ha familiarità con il flusso di lavoro.

Esaminare attentamente la valutazione

La valutazione è la migliore opportunità per intercettare i problemi prima che l'agente inizi a apportare modifiche. Cercare:

• I progetti che l'agente potrebbe aver perso o identificato erroneamente.
• Le dipendenze che si conoscono sono problematiche.
• Qualcosa di insolito sulla soluzione che l'agente dovrebbe conoscere.

Se si individua qualcosa, indicare all'agente in chat o aggiungere le informazioni a scenario-instructions.md. È anche possibile modificare assessment.md direttamente per aggiungere il contesto, correggere i progetti identificati in modo errato o contrassegnare i problemi prima che l'agente proceda alla pianificazione.

Dedicare tempo alla fase di pianificazione

L'agente genera un piano in base alla valutazione. Esaminare il piano prima di procedere:

• L'ordine ha senso per la codebase?
• L'agente potrebbe non conoscere le dipendenze?
• I progetti devono essere esclusi o gestiti in modo diverso?

Chiedere all'agente di riordinare le attività, ignorare i progetti o modificarne l'approccio. Si conosce meglio la codebase rispetto all'agente, quindi usare tale conoscenza. Modificare il file direttamente per modificare l'ordine plan.md delle attività, aggiungere attività o rimuovere attività.

Inviare immediatamente commenti e suggerimenti

L'agente apprende dalle tue correzioni all'interno di una sessione. Se l'agente fa una scelta che non è d'accordo con:

• Dimmi subito: "Non usare questo modello, usare invece X".
• Aggiungere indicazioni persistenti a scenario-instructions.md in modo che l'agente ricordi tra attività e sessioni.

Rimanere coinvolti durante l'esecuzione

L'esecuzione non è automatica. Prima di indicare all'agente di iniziare, esaminare tasks.md:

• L'ordine delle attività ha senso per la codebase?
• Ci sono attività che vuoi saltare o riordinare?
• Sono presenti attività mancanti?

Chiedere all'agente di modificare l'elenco di attività o modificare tasks.md direttamente prima dell'inizio dell'esecuzione. Una volta avviata l'esecuzione, se l'agente effettua una cattiva chiamata durante l'attività, indicarla immediatamente; applicherà la correzione da quel momento in poi.

Si conosce meglio la codebase rispetto all'agente, quindi usare tali conoscenze in ogni fase.

Inconvenienti comuni

Esaminare questi problemi comuni che possono rallentare o complicare un aggiornamento.

Soluzioni di grandi dimensioni con oltre 50 progetti

L'agente funziona in base al progetto, quindi le soluzioni di grandi dimensioni richiedono tempo. Siate pazienti e monitorate lo stato di avanzamento. Si suggerisce di iniziare con un progetto rappresentativo end-to-end prima di impegnarsi nell'implementazione completa. Un progetto pilota singolo presenta presto problemi sistemici.

Feed NuGet privati

Per i feed NuGet privati, eseguire l'autenticazione prima di avviare l'aggiornamento, ad esempio tramite il provider di credenziali o la configurazione del feed dell'organizzazione. Senza l'autenticazione, gli errori di ripristino del pacchetto bloccano lo stato di avanzamento.

Destinazioni e importazioni di MSBuild personalizzate

Le personalizzazioni di compilazione complesse, ad esempio file personalizzati .targets , importazioni condizionali o logica di compilazione non standard, possono confondere la valutazione e causare errori di compilazione imprevisti. Se la soluzione include queste personalizzazioni, menzionarle nella chat o in scenario-instructions.md modo che l'agente possa tener conto di loro.

Timeout di sessione

Gli aggiornamenti a esecuzione prolungata possono estendersi su più sessioni. L'agente tiene traccia dello stato di avanzamento nei file del flusso di lavoro (in .github/upgrades/), in modo che possa riprendere da dove aveva interrotto. Quando si avvia una nuova sessione, menzionare dove ci si trovava: "Continuare l'aggiornamento .NET 10. Ero al centro del progetto Data.Access."

Collaborare in modo efficace

La qualità dell'interazione influisce direttamente sulla qualità dei risultati.

Specificare l'ambito

Più si è specifici, migliori sono le prestazioni dell'agente.

Condividi i tuoi vincoli

Comunicare all'agente fin dall'inizio i vincoli del mondo reale.

• "Non è possibile interrompere la compatibilità con le versioni precedenti per l'API pubblica".
• "Abbiamo una scadenza di rilascio in due settimane, quindi assegnare priorità ai progetti Web".
• "Il modulo di creazione di report legacy deve essere escluso da questo aggiornamento".

Spiega la tua architettura

L'agente analizza la struttura del codice, ma non conosce il modello mentale del team. Aiutare l'agente a comprendere:

• "Project A è la nostra libreria condivisa. B, C e D dipendono tutti da esso."
• "Il progetto WebApi è l'API pubblica; Internal.Api è solo per i servizi interni."
• "Il progetto Models viene generato automaticamente dalla specifica OpenAPI. Non modificarlo direttamente."

Chiedi perché

L'agente può spiegarne il ragionamento. Se una decisione non sembra giusta, chiedere:

• "Perché hai scelto l'ordine in basso?"
• "Perché si aggiorna questo pacchetto alla versione X anziché a Y?"
• "Perché l'hai suddivisa in sottoattività?"

Comprendere il ragionamento consente di fornire un feedback migliore.

Salva preferenze in anticipo

Se si hanno preferenze avanzate sullo stile di codifica, i modelli o gli approcci, aggiungerli a scenario-instructions.md nella prima sessione. Questo file persiste tra le sessioni ed è sempre nel contesto dell'agente, rendendolo il modo più affidabile per influenzare il comportamento.

Risoluzione dei problemi

Usare queste strategie quando l'aggiornamento non va come previsto.

Errori di build dopo un'attività

Indicare all'agente: "La compilazione ha esito negativo dopo l'ultima attività". L'agente analizza l'errore e tenta di risolverlo. Se l'agente non riesce a risolvere il problema:

1. Fornire una correzione manuale e indicare all'agente cosa è stato fatto. L'agente apprende dalla correzione.
2. Ripristinare il commit (git revert o reimpostare il commit precedente) e chiedere all'agente di provare un approccio diverso.
3. Ignorare l'attività problematica e tornare in un secondo momento.

Strategia sbagliata scelta

Se l'approccio generale dell'agente non funziona per la codebase, riavviare la fase di pianificazione:

• "Ripetiamo il piano. Voglio aggiornare prima i progetti web anziché dal basso verso l'alto.
• "Modificare la strategia per aggiornare tutte le librerie condivise in un unico batch".

Agente bloccato in un ciclo

Se l'agente ripete la stessa correzione senza avanzamento, pronunciare "Arresta" e descrivere ciò che si sta osservando o arrestare manualmente la sessione. L'agente può reimpostare l'approccio e provare qualcosa di diverso.

Annulla tutte le modifiche

Se è stato usato un ramo Git per l'aggiornamento, annullare tutto passando al ramo originale:

git checkout your-original-branch
git branch -D upgrade-branch

Il codice originale non è stato modificato. Se si lavora senza controllo del codice sorgente, eseguire il ripristino dal backup eseguito prima dell'avvio.

Sicurezza e privacy

• Frammenti di codice: GitHub Copilot li elabora secondo l'informativa sulla privacy di GitHub Copilot e non li memorizza oltre la sessione corrente.
• I file del flusso di lavoro (scenario-instructions.md, le attività personalizzate, le preferenze) rimangono nel repository in .github/upgrades/. GitHub non trasmette questi file a servizi esterni.
• La .github/upgrades/ cartella fa parte del repository. Eseguire il commit della cartella perché contiene il tuo avanzamento e lo stato dell'aggiornamento. L'agente ha bisogno della cartella per riprendere il lavoro tra le sessioni. È possibile rimuoverlo al termine dell'aggiornamento.
• Telemetria: disabilitare tramite le impostazioni di telemetria dell'IDE.

Suggerimenti per le prestazioni

• Chiudere file e schede non necessari: l'agente analizza l'area di lavoro attiva e un minor numero di file aperti significa meno rumore.
• Eseguire l'aggiornamento in fasi per soluzioni molto grandi: anziché aggiornare tutti i progetti contemporaneamente, eseguirne l'invio in batch. Ad esempio, aggiornare prima tutte le librerie, quindi tutti i progetti Web, quindi i test.
• Usare il caching della build: l'agente esegue molte compilazioni incrementali durante la convalida. Le cache di build calde rendono la convalida significativamente più veloce. Evitare di pulire l'output di compilazione tra le attività.

Contenuti correlati

• Che cos'è la modernizzazione di GitHub Copilot?
• Upgrade un'applicazione .NET tramite la modernizzazione con GitHub Copilot
• Concetti fondamentali
• Risoluzione dei problemi della modernizzazione di GitHub Copilot