Applicare istruzioni di aggiornamento personalizzate per gli aggiornamenti .NET

Le istruzioni di aggiornamento personalizzate sono file Markdown che guidano la modernizzazione di GitHub Copilot per applicare trasformazioni specifiche durante un aggiornamento. Creare questi file per automatizzare le modifiche ripetitive, ad esempio sostituendo una libreria con un'altra o applicando un aggiornamento api specifico.

Questo articolo illustra come creare e strutturare un file di istruzioni di aggiornamento personalizzato, testarlo in isolamento e integrarlo nella fase di valutazione di un flusso di lavoro di aggiornamento.

Prerequisiti

Configurare la modernizzazione di GitHub Copilot nell'ambiente di sviluppo prima di creare delle istruzioni personalizzate. Per i passaggi di installazione, vedere Installazione della modernizzazione di GitHub Copilot.

Comprendere le istruzioni di aggiornamento personalizzate

La modernizzazione di GitHub Copilot recupera le istruzioni di aggiornamento personalizzate su richiesta come file Markdown durante le fasi di valutazione e pianificazione di un aggiornamento. Le istruzioni di aggiornamento personalizzate differiscono da copilot-instructions.md nel senso che sono:

  • Destinato all'automazione delle modifiche al codice e alle dipendenze.
  • Recuperata solo quando è rilevante per la valutazione o il piano di aggiornamento corrente.
  • Riutilizzabile tra le soluzioni quando viene copiato in ogni repository.

Strutturare i file di istruzione con:

  • Titolo breve che descrive l'azione. Ad esempio, "sostituire Newtonsoft.Json con System.Text.Json".
  • Una sezione concisa del problema o prerequisito.
  • Logica di passaggio esplicita ("Se viene trovata X, do Y"). Evitare un linguaggio vago.
  • (Scelta consigliata) Uno o più esempi diff acquisiti da modifiche locali effettive per guidare le trasformazioni.

Oltre alle istruzioni di aggiornamento personalizzate, è possibile estendere la modernizzazione di GitHub Copilot tramite il sistema standard di competenza e istruzioni. Le competenze aggiungono funzionalità all'agente e ai file di istruzioni (ad esempio copilot-instructions.md) forniscono indicazioni globali.

Creare un'istruzione di aggiornamento personalizzata

Seguire questa procedura per generare e perfezionare un nuovo file di istruzioni. Queste sezioni si concentrano sulla sostituzione Newtonsoft.Json con System.Text.Json come esempio.

  1. Nella finestra Esplora soluzioni fare clic con il pulsante destro del mouse sul solution>Modernize.

    oppure

    Aprire il pannello Copilot chat e digitare @Modernize per avviare una conversazione con l'agente.

    Annotazioni

    Questi passaggi si applicano a Visual Studio. In Visual Studio Code e in altri ambienti richiamare l'agente modernize-dotnet direttamente dal pannello di chat Copilot. In Visual Studio l'agente è denominato Modernize.

  2. Nella chat digitare : I want to generate a custom upgrade instruction.

  3. Quando richiesto, fornisci uno scenario come I want to replace Newtonsoft with System.Text.Json affinché Copilot crei il file.

  4. Quando Copilot crea il nuovo file, ad esempio replace_newtonsoft_with_system_text_json.md, esaminare il contenuto e perfezionarlo nella chat. Ad esempio, chiedere Copilot di "chiarire i criteri di rilevamento" o "aggiungere una sezione prerequisiti."

    Suggerimento

    Aggiungere il file alla soluzione per la visibilità, se non è già incluso.

  5. Rafforzare l'istruzione con esempi reali di 'diff'.

    1. Apportare manualmente le modifiche al codice desiderate in un progetto. Ad esempio, "rimuovere il pacchetto Newtonsoft.Json, aggiornare le direttive di utilizzo e sostituire il codice JsonConvert con JsonSerializer".
    2. Nella chat, con il file di istruzioni aperto, digitare : Check my git changes and add diffs as examples to my instruction file.
    3. Confermare che Copilot ha usato un diff git e ha accodato un blocco diff delimitato o un esempio strutturato al file Markdown.

Suggerimenti per la creazione

Seguire queste linee guida per scrivere istruzioni di aggiornamento personalizzate chiare ed efficaci che Copilot possono interpretare in modo affidabile:

  • Usare la formulazione condizionale chiara: If code references X, then do Y.
  • Mantenere una trasformazione per ogni file; usare i prerequisiti quando più file devono essere eseguiti in sequenza.
  • Fornire almeno un esempio concreto, come una diff o un frammento prima e dopo, al fine di migliorare l'accuratezza della trasformazione.
  • Evitare verbi ambigui come "migliorare" o "fix"; usare azioni esplicite come "replace", "remove" e "update".

Testare un'istruzione di aggiornamento personalizzata (esecuzione una tantum)

Prima di eseguire l'istruzione durante un aggiornamento, convalidarla in isolamento. I test isolati consentono di perfezionare il rilevamento e verificare le modifiche al codice.

  1. Nella finestra Esplora soluzioni fare clic con il pulsante destro del mouse sul solution>Modernize.

    Annotazioni

    Questi passaggi si applicano a Visual Studio. In Visual Studio Code e in altri ambienti richiamare l'agente modernize-dotnet direttamente dal pannello di chat Copilot.

  2. Nella chat richiamare l'istruzione con parole simili al nome del file. Ad esempio: replace Newtonsoft with System.Text.Json.

  3. Verificare nella finestra della chat che Copilot recuperato il file di istruzioni:

    > Getting instructions for 'replace Newtonsoft with System.Text.Json'.

Perfect! I've retrieved the scenario instructions for upgrading from Newtonsoft.Json to System.Text.Json. Now I'll begin the analysis following the scenario-specific instructions.

    Se Copilot non indica che sono state trovate le istruzioni, riprovare con parole chiave dal nome del file, ad esempio le stesse combinazioni verbo e sostantivo.

  4. Esaminare le modifiche proposte (differenze di soluzione, commit in sospeso o modifiche in anteprima) per verificare che l'istruzione di aggiornamento personalizzata si comporti come previsto.

Suggerimenti per la convalida

Se l'esecuzione del test non produce i risultati previsti, usare questi suggerimenti per la risoluzione dei problemi per perfezionare il file di istruzioni:

  • Se Copilot aggiorna solo le versioni del pacchetto anziché sostituire il pacchetto, assicurarsi che l'istruzione indichi esplicitamente di rimuovere o sostituire il pacchetto precedente.
  • Usare nomi coerenti in modo che l'attivazione in linguaggio naturale corrisponda. Ad esempio, avviare il nome del file con replace_ e iniziare la richiesta di chat con "Sostituisci ...".
  • Durante i test, aggiungere eventuali modelli di codice mancanti come esempi per migliorare la copertura.

Applicare istruzioni personalizzate durante un aggiornamento

Usare questi passaggi per incorporare un'istruzione di aggiornamento personalizzata esistente nella fase di valutazione di un aggiornamento.

  1. Nella finestra Esplora soluzioni fare clic con il pulsante destro del mouse sul solution>Modernize.

    Annotazioni

    Questi passaggi si applicano a Visual Studio. In Visual Studio Code e in altri ambienti richiamare l'agente modernize-dotnet direttamente dal pannello di chat Copilot.

  2. Nella chat scegliere Upgrade to a newer version of .NET. Rispondi alle domande di Copilot fino all'avvio della valutazione.

  3. Monitorare la chat per verificare se Copilot recupera automaticamente il file di istruzioni personalizzato durante la valutazione. Cercare un messaggio che indica che è stato aperto il file di istruzioni Markdown.

    Se Copilot non applica automaticamente le istruzioni personalizzate, richiederle in modo esplicito. Usare parole simili al nome del file. Ad esempio: use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment.

  4. Attendere Copilot confermare che il file Markdown sia stato recuperato. Se non viene visualizzato un riferimento al file di istruzioni, riformulare la richiesta usando i verbi chiave del file (sostituire, aggiornare, rimuovere) e i nomi dei pacchetti.

  5. Esaminare il file generato assessment.md nella .github/upgrades cartella . Verificare che la valutazione includa problemi e modifiche identificate dall'istruzione personalizzata.

    Ad esempio, quando si sostituisce Newtonsoft, la valutazione identifica:

    • Progetti che usano Newtonsoft.Json pacchetti.
    • Modelli di codice da ottimizzare per System.Text.Json.
    • Dipendenze da rimuovere o sostituire.

  6. Se necessario, modificare il assessment.md file per aggiungere contesto o regolare i problemi identificati prima di procedere.

  7. Dì a Copilot di continuare alla fase di pianificazione una volta che la valutazione riflette la tua istruzione personalizzata.

  8. Esaminare il file plan.md generato da Copilot. Questo file include strategie per risolvere i problemi della valutazione.

  9. Continuare con la fase di esecuzione dicendo Copilot di procedere. Monitorare il file tasks.md mentre Copilot applica le trasformazioni.

Suggerimenti per una migliore attivazione

La modalità di denominazione e richiamo delle istruzioni di aggiornamento personalizzate influisce sul fatto che Copilot li recuperi automaticamente. Seguire queste linee guida per migliorare l'affidabilità dell'attivazione:

  • Trova la corrispondenza con il verbo del file. Se il nome del file usa replace, usare tale formulazione (non upgrade o fix).
  • Mantenere una trasformazione per ogni file per maggiore chiarezza e riutilizzo. Sequenzia più file elencando i prerequisiti in ogni file.
  • Richiedere istruzioni personalizzate durante la fase di valutazione per ottenere risultati ottimali, anziché attendere fino alla pianificazione o all'esecuzione.
  • Evitare richieste ambigue come "migliorare la valutazione". Essere espliciti: "applicare le istruzioni replace_newtonsoft_with_system_text_json durante la valutazione".

Convalidare le modifiche applicate

Al termine dell'aggiornamento:

  1. Rivedere il file tasks.md in .github/upgrades per vedere lo stato delle attività collegate all'istruzione personalizzata.
  2. Controllare i commit Git creati durante la fase di esecuzione per verificare la presenza di modifiche correlate all'istruzione personalizzata.
  3. Eseguire i test per assicurarsi che il comportamento funzionale rimanga corretto.
  4. Facoltativo: acquisire un esempio diff dalla modifica corretta e aggiungerlo al file di istruzioni per rafforzare l'automazione futura.

Pulire le risorse

Rimuovere o consolidare eventuali file di istruzioni temporanei per evitare trasformazioni sovrapposte negli aggiornamenti futuri.

Contenuti correlati

  • Last updated on