Aggiornare un'app Windows Forms a .NET usando la modernizzazione con GitHub Copilot

Questo articolo illustra come aggiornare un'app desktop Windows Forms a .NET usando l'agente di modernizzazione GitHub Copilot. L'agente funziona nel tuo editor, analizza il progetto e guida un flusso di lavoro in tre fasi: valutazione, pianificazione ed esecuzione.

L'esempio utilizza il sample Matching Game, una piccola app Windows Forms basata su .NET Framework costituita da un progetto principale e una libreria di classi.

Prerequisiti

Tip

Assicurarsi di disporre di un backup del codice, ad esempio nel controllo del codice sorgente o in una copia, prima di iniziare.

Aprire la soluzione

I progetti Matching Game sono destinati a .NET Framework 4.5. Visual Studio chiede di impostare nuovamente i progetti in una versione supportata di .NET Framework quando si apre la soluzione.

  1. Aprire la soluzione MatchingGame in Visual Studio.
  2. Visual Studio visualizza la finestra di dialogo Framework di destinazione non installato.
  3. Selezionare Aggiorna la destinazione a .NET Framework 4.8 (scelta consigliata) e quindi selezionare Continua.
  4. Aprire la finestra Modifiche Git ed eseguire il commit delle modifiche di reindirizzamento.

Note importanti per Visual Basic

L'agente di modernizzazione GitHub Copilot non supporta completamente i progetti Visual Basic .NET. L'agente include protezioni progettate specificamente per garantire che i progetti C# vengano aggiornati in modo affidabile e tali protezioni interferiscano con l'analisi e l'esecuzione del progetto VB. Se la soluzione contiene progetti VB, usare invece una di queste alternative:

  • GitHub Copilot (agente standard): usare il normale agente Copilot, senza l'agente di modernizzazione, per guidare l'aggiornamento in modo interattivo.
  • Assistente aggiornamenti: uno strumento di migrazione dedicato con supporto per VB.

Tip

Se la soluzione contiene progetti C# e VB, è comunque possibile usare l'agente di modernizzazione per i progetti C#. Aggiornare i progetti VB separatamente usando una delle alternative elencate.

Se si usa manualmente il agente Copilot standard o l'aggiornamento, seguire questa procedura:

  1. Se il progetto è destinato a una versione non supportata di .NET Framework, reindirizzarlo prima a .NET Framework 4.8. Visual Studio chiede di eseguire questa operazione quando si apre la soluzione oppure è possibile modificarla nelle proprietà del progetto.

  2. Aggiornare tutti i pacchetti NuGet obsoleti alle versioni compatibili più recenti.

  3. Creare un nuovo progetto di Windows Forms VB usando un modello di Visual Studio o dotnet new winforms -lang vb. Il modello genera un file di progetto e impostazioni di tipo SDK, che sono state modificate da .NET Framework.

  4. Copiare i .vb file di origine dalla cartella del progetto precedente alla nuova cartella del progetto.

  5. Copiare eventuali file non di codice da cui dipende il progetto, ad esempio app.configfile .settings , immagini, icone e altre risorse incorporate.

  6. Aprire il file di progetto precedente (o packages.config) e prendere nota di ogni riferimento al pacchetto NuGet. Aggiungere gli stessi pacchetti al nuovo progetto usando il Gestione pacchetti NuGet o dotnet add package <name>.

  7. Se il progetto fa riferimento ad altri progetti nella soluzione, aggiungere nuovamente tali riferimenti nel nuovo progetto.

  8. Provare a compilare la soluzione. Non correggere ancora gli errori — l'output della compilazione fornisce a Copilot un elenco concreto di problemi su cui lavorare.

  9. Esegui il commit dello stato corrente nel sistema di controllo del codice sorgente, in modo da avere una baseline pulita prima che Copilot apporti modifiche.

  10. Aprire GitHub Copilot Chat e chiedere di risolvere i problemi rimanenti. Per esempio:

    Questo progetto Visual Basic Windows Forms è stato migrato da .NET Framework 4.8 a .NET 10. Il file di progetto e i file di origine sono disponibili, ma la soluzione non viene compilata. Esaminare gli errori di compilazione e correggere le incompatibilità dell'API, i riferimenti mancanti e eventuali problemi di migrazione della configurazione.

  11. Esaminate le modifiche proposte da Copilot, quindi ricompilate e testate il progetto.

Avviare l'aggiornamento

La soluzione Matching Game contiene l'app MatchingGame e la libreria di classi MatchingGame.Logic. L'agente individua autonomamente il grafico del progetto, quindi avvia l'aggiornamento a livello di soluzione.

  1. In Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione e scegliere Modernize (Modernize).

    Viene visualizzata la finestra di Copilot Chat GitHub e viene avviata una conversazione con l'agente di modernizzazione.

  2. Selezionare un modello con solide funzionalità di ragionamento e codifica.

  3. Dimmi all'agente cosa vuoi fare. Per esempio:

    Aggiornare tutto a .NET 10.

    L'agente segnala lo stato corrente della codebase e le operazioni da eseguire:

    • Framework di destinazione: indica che l'agente aggiorna i progetti a .NET 10.
    • Modalità flusso: l'impostazione predefinita è Automatica. Per le app complesse, chiedere all'agente di passare alla modalità guidata .
    • Controllo del codice sorgente: indica che l'agente crea un nuovo ramo di lavoro.

    L'agente scrive il proprio lavoro in .github/upgrades/scenarios/dotnet-version-upgrade/ nel repository. Se tale cartella esiste già da un tentativo precedente, l'agente chiede se continuare o avviare un nuovo tentativo.

  4. Indicare all'agente start di avviare il processo di aggiornamento.

Esaminare la valutazione

Nella fase di valutazione, l'agente esamina la struttura del progetto, le dipendenze e i modelli di codice per identificare ciò che deve cambiare. Scrive i risultati in assessment.md in .github/upgrades/scenarios/dotnet-version-upgrade/.

Quando Copilot completa la valutazione, rivedi l'output della conversazione. In genere inizia con qualcosa di simile al seguente:

Assessment Complete

I've analyzed the solution and created a full assessment — see .github/upgrades/scenarios/dotnet-version-upgrade/assessment.md.

Solution summary:
• Target: net48 → net10.0
• Projects: 2
• MatchingGame.Logic (Class Library)
• MatchingGame (Windows Forms)
• Issues: 883 (673 mandatory, 210 potential)
• Affected Technologies: Windows Forms (666), GDI+ / System.Drawing (208), Legacy Configuration System (2)

Key concerns:
• Both projects are legacy-format .csproj files — need conversion to SDK-style
• MatchingGame.csproj has API incompatibilities (binary + source) and an incompatible NuGet package
• WinForms remains supported on .NET 10 (Windows-only TFM)
• No reported security vulnerabilities

Suddivisione della valutazione

Copilot apre il .github/upgrades/scenarios/dotnet-version-upgrade/assessment.md file nell'editor Visual Studio. Scorrere verso il basso fino alla MatchingGame\MatchingGame.csproj sezione per visualizzare una tabella dei problemi:

Tecnologia Problemi Percentuale Percorso di migrazione
Sistema di configurazione legacy 2 0.2% Sistema di configurazione basato su XML legacy (app.config/web.config) sostituito da un modello di configurazione più flessibile in .NET Core. Il vecchio sistema era rigido e basato su XML. Eseguire la migrazione a Microsoft. Extensions.Configuration con variabili JSON/di ambiente; usare il pacchetto NuGet System.Configuration.ConfigurationManager come bridge provvisorio, se necessario.
GDI+ / System.Drawing 208 23.7% API System.Drawing per grafica 2D, creazione di immagini e stampa disponibili tramite il pacchetto NuGet System.Drawing.Common. Nota: non consigliato negli scenari server a causa delle dipendenze da Windows; prendere in considerazione alternative multipiattaforma come SkiaSharp o ImageSharp per il nuovo sviluppo.
Windows Forms 621 76.0% Windows Forms API per la creazione di applicazioni desktop Windows con l'interfaccia utente basata su form tradizionale disponibile in .NET su Windows. Abilita il supporto per Windows Forms: Opzione 1 (consigliata): Imposta net10.0-windows come destinazione; Opzione 2: Aggiungi <UseWindowsForms>true</UseWindowsForms>; Opzione 3 (legacy): Usa Microsoft.NET.Sdk.WindowsDesktop SDK.

La maggior parte di questi problemi non sono problemi reali. Consultare la colonna "Percorso di migrazione" per la riga GDI+ che elenca 208 problemi. La valutazione contrassegna queste API perché sono disponibili in .NET Framework, ma non in .NET. La colonna illustra la correzione: aggiungere il System.Drawing.Common pacchetto NuGet per ripristinare le API.

La riga Windows Forms elenca 621 problemi relativi all'API per lo stesso motivo. Le API di Windows Forms non sono disponibili in .NET per impostazione predefinita, ma è possibile renderle nuovamente disponibili scegliendo come destinazione un framework specifico di Windows, ad esempio net10.0-windows, e impostando <UseWindowsForms>true</UseWindowsForms> nel file di progetto. L'opzione 3 suggerisce un'opzione non corretta. Le versioni precedenti di .NET richiedevano un progetto Windows Forms specificamente destinato all'Microsoft.NET.Sdk.WindowsDesktopSDK, ma ora viene fatto automaticamente riferimento quando <UseWindowsForms>true</UseWindowsForms> è impostato.

Tip

Per saperne di più su un'opzione, chiedi a Copilot maggiori informazioni e contesto.

Esaminare le opzioni di aggiornamento

Dopo la valutazione, l'agente presenta le decisioni sulla strategia di aggiornamento upgrade-options.md e le salva in .github/upgrades/scenarios/dotnet-version-upgrade/. Per l'esempio di gioco corrispondente, l'agente seleziona le opzioni seguenti:

Aspect Decisione Ragione
Strategia di aggiornamento Dal basso verso l'alto. L'agente aggiorna MatchingGame.Logic prima di tutto perché MatchingGame dipende da esso, quindi convalida ogni livello prima di procedere.
Approccio al progetto Sul posto. Entrambi i progetti eseguono la migrazione insieme perché non vengono usati da altri progetti di .NET Framework.
Pacchetti non supportati Risolvi in linea. La valutazione ha trovato solo alcuni pacchetti incompatibili, quindi l'agente ricerca le sostituzioni mentre funziona.
Gestione delle API non supportata Correggi in linea. La maggior parte delle modifiche Windows Forms e API GDI+ per .NET sono meccaniche e non richiedono un passaggio di pianificazione separato.
API native di Windows Pacchetto di compatibilità di Windows L'app usa Windows Forms e GDI+ pesantemente ed è intrinsecamente solo Windows.
Tipi di riferimento che ammettono i valori Null Lasciare disabilitato. L'agente considera l'abilitazione di nullable come operazione separata dopo la migrazione.

L'agente segnala anche i rischi che richiedono la tua attenzione. Per l'esempio di gioco corrispondente, l'agente contrassegna i MetroFramework pacchetti perché sono disponibili solo per .NET Framework. Il risultato probabile è la rimozione MetroFramework e il fallback ai controlli Windows Forms standard, che modificano lo stile di visualizzazione dell'app.

Esaminare le opzioni proposte e indicare all'agente cosa si vuole modificare. Ad esempio, indicare all'agente di abilitare i tipi riferimento nullable o di sospendere e discutere MetroFramework prima le sostituzioni. Al termine, rispondere confirm per bloccare le selezioni e passare alla pianificazione.

Esaminare il piano

Nella fase di pianificazione, l'agente converte la valutazione e le opzioni confermate in una specifica dettagliata. Scrive il risultato in plan.md e crea un scenario-instructions.md file che archivia preferenze, decisioni e istruzioni personalizzate per l'aggiornamento.

Importante

Se la modalità di flusso è Automatica, l'agente avvia l'esecuzione del piano senza tempo di revisione.

Il piano comprende elementi quali l'ordine di aggiornamento tra i vari progetti, il moniker del framework di destinazione per ogni progetto (net10.0-windows per i progetti Windows Forms), i percorsi di aggiornamento dei pacchetti e le strategie di mitigazione dei rischi associati alle modifiche che introducono incompatibilità individuate dall'analisi.

Per esaminare e personalizzare il piano:

  1. Apri plan.md in .github/upgrades/scenarios/dotnet-version-upgrade/.
  2. Esaminare le strategie di aggiornamento e gli aggiornamenti delle dipendenze.
  3. Modificare il piano per modificare i passaggi o aggiungere contesto in base alle esigenze.
  4. Indicare all'agente di passare alla fase di esecuzione.

Caution

Il piano dipende dalle interdipendenze del progetto. L'aggiornamento non riesce se si modifica il piano in modo da impedire il completamento del percorso di aggiornamento. Ad esempio, se MatchingGame dipende da MatchingGame.Logic e si rimuove MatchingGame.Logic dal piano, l'aggiornamento di MatchingGame potrebbe non riuscire.

Eseguire l'aggiornamento

Nella fase di esecuzione, l'agente suddivide il piano in attività sequenziali e concrete con criteri di convalida. L’agente scrive l’elenco di attività in .github/upgrades/scenarios/dotnet-version-upgrade/tasks.md e tiene traccia dell’avanzamento complessivo in quel file. Per ogni attività, l'agente crea una cartella in .github/upgrades/scenarios/dotnet-version-upgrade/tasks/ che contiene un file Markdown che descrive l'attività e un file markdown che segnala lo stato dell'attività.

Per l'esempio di gioco corrispondente, l'elenco di attività include in genere l'aggiornamento di MatchingGame.Logic , quindi MatchingGame, il ripristino di pacchetti, la compilazione della soluzione e il commit delle modifiche.

Per eseguire l'aggiornamento:

  1. Indicare all'agente di avviare l'aggiornamento.
  2. Monitora i progressi esaminando tasks.md man mano che l'agente aggiorna gli stati delle attività. Aprire le cartelle per attività in tasks/ per la descrizione dell'attività e un report di stato dettagliato.
  3. Se l'agente si imbatte in un problema che non può risolvere, fornisci l'aiuto richiesto. Ad esempio, l'agente potrebbe chiedere di scegliere tra due API sostitutive o confermare se mantenere un pacchetto deprecato.
  4. In base alle risposte, l'agente adatta la strategia alle attività rimanenti e continua.

L'agente esegue il commit delle modifiche in base alla strategia Git configurata durante la pre-inizializzazione: per attività, per gruppo di attività o alla fine.

Note per i progetti Visual Basic

I progetti Windows Forms di Visual Basic in .NET Framework spesso utilizzano file di impostazioni System.Configuration e le estensioni My, ad esempio My.Computer e My.User. Le My estensioni sono state rimosse in .NET. L'agente contrassegna questi modelli durante la valutazione e propone correzioni durante l'esecuzione, ma potrebbe essere necessario confermare le singole modifiche durante un'esecuzione guidata.

Se l'agente esegue la migrazione del progetto ma il progetto non si compila, verificare che il file di progetto sia destinato a Windows e faccia riferimento a Windows Forms. L'elemento <PropertyGroup> dovrebbe essere simile al frammento di codice seguente:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0-windows</TargetFramework>
    <UseWindowsForms>true</UseWindowsForms>
    <OutputType>WinExe</OutputType>
    <MyType>WindowsForms</MyType>

    <!-- Other settings removed for brevity. -->
  </PropertyGroup>
</Project>

Verificare l'aggiornamento

Al termine dell'aggiornamento, l'agente consiglia i passaggi successivi nella risposta alla chat. Richiedere all'agente di generare un report di modifica completo con "Generare un report di modifica".

Esaminare lo stato dell'attività finale in tasks.md e verificare che ogni passaggio sia stato completato.

Per verificare l'aggiornamento:

  1. Compilare la soluzione e risolvere eventuali errori di compilazione.

  2. Eseguire l'app e verificare che i moduli vengano caricati e si comportino come previsto.

    Il tipo di carattere predefinito in Windows Forms è cambiato tra .NET Framework e .NET, quindi controllare i moduli e i controlli personalizzati per individuare le differenze di layout.

  3. Eseguire tutti gli unit test nella soluzione e correggere gli errori.

  4. Verificare che i pacchetti NuGet aggiornati siano compatibili con l'app.

  5. Testare attentamente l'app per verificare che l'aggiornamento sia stato completato.

Tip

Se il progetto non viene eseguito e non è possibile collegare un debugger, provare a riavviare Visual Studio. La migrazione di file di progetto da .NET Framework a .NET potrebbe confondere la finestra di progettazione Windows Forms senza riavviare.

L'esempio di gioco corrispondente Windows Forms viene ora aggiornato a .NET 10.

Esperienza post-aggiornamento

Se hai portato l'app da .NET Framework a .NET, consulta Modernizzare dopo l'aggiornamento a .NET da .NET Framework per idee su come adottare schemi più moderni, ad esempio appsettings.json configurazione, iniezione delle dipendenze o servizi cloud. L'adozione di questi modelli è separata dall'aggiornamento a .NET e non è necessario completare l'aggiornamento.

Contenuti correlati

  • Last updated on