Actualización de una aplicación de Windows Forms a .NET con modernización de GitHub Copilot

En este artículo se explica cómo actualizar una aplicación de escritorio de Windows Forms a .NET mediante el agente de modernización de GitHub Copilot. El agente funciona en tu editor, analiza el proyecto y orquesta un flujo de trabajo de tres fases: evaluación, planificación y ejecución.

En el ejemplo se usa el ejemplo Matching Game, una pequeña aplicación Windows Forms de .NET Framework compuesta por un proyecto principal y una biblioteca de clases.

Requisitos previos

Tip

Asegúrese de tener una copia de seguridad del código, como en el control de código fuente o una copia, antes de empezar.

Abra la solución

Los proyectos Matching Game están destinados a .NET Framework 4.5. Visual Studio le pide que cambie la versión de destino de los proyectos a una versión admitida de .NET Framework cuando abre la solución.

  1. Abra la solución MatchingGame en Visual Studio.
  2. Visual Studio muestra el cuadro de diálogo El marco de trabajo de destino no está instalado.
  3. Seleccione Actualizar el destino a .NET Framework 4.8 (Recomendado) y, a continuación, seleccione Continuar.
  4. Abra la ventana Cambios de Git y confirme los cambios de redestinación.

Notas importantes de Visual Basic

El agente de modernización de GitHub Copilot no es totalmente compatible con proyectos de Visual Basic .NET. El agente incluye barreras de protección diseñadas específicamente para garantizar que los proyectos de C# se actualicen de forma confiable, y esos límites de protección interfieren con el análisis y la ejecución del proyecto de VB. Si la solución contiene proyectos de VB, use una de estas alternativas en su lugar:

  • GitHub Copilot (agente estándar): use el agente de Copilot normal, sin el agente de modernización, para guiar la actualización de forma interactiva.
  • Asistente para actualización: una herramienta de migración dedicada con compatibilidad con VB.

Tip

Si la solución contiene proyectos de C# y VB, puede seguir usando el agente de modernización para los proyectos de C#. Actualice los proyectos de VB por separado mediante una de las alternativas enumeradas.

Si usa el agente de Copilot estándar o actualiza manualmente, siga estos pasos:

  1. Si el proyecto tiene como destino una versión no admitida de .NET Framework, reenvía primero a .NET Framework 4.8. Visual Studio le pide que lo haga al abrir la solución o puede cambiarla en las propiedades del proyecto.

  2. Actualice los paquetes NuGet obsoletos a sus versiones compatibles más recientes.

  3. Cree un nuevo proyecto de vb Windows Forms mediante una plantilla de Visual Studio o dotnet new winforms -lang vb. La plantilla genera un archivo de proyecto con estilo SDK y opciones de configuración distintas de las de .NET Framework.

  4. Copie los .vb archivos de origen de la carpeta del proyecto anterior en la nueva carpeta del proyecto.

  5. Copie los archivos que no sean de código de los que depende el proyecto, como app.config, .settings archivos, imágenes, iconos y otros recursos incrustados.

  6. Abra el archivo de proyecto antiguo (o packages.config) y anote cada referencia de paquete NuGet. Agregue esos mismos paquetes al nuevo proyecto mediante el Administrador de paquetes nuGet o dotnet add package <name>.

  7. Si el proyecto hace referencia a otros proyectos de la solución, vuelva a agregar esas referencias en el nuevo proyecto.

  8. Intente compilar la solución. No corrijas los errores todavía — la salida de compilación proporciona a Copilot una lista concreta de problemas con la que trabajar.

  9. Confirme el estado actual en el control de código fuente para que tenga una línea base limpia antes de Copilot realice cambios.

  10. Abra gitHub Copilot Chat y pídale que resuelva los problemas restantes. Por ejemplo:

    Este proyecto de Visual Basic Windows Forms se migró de .NET Framework 4.8 a .NET 10. El archivo de proyecto y los archivos de origen están en su lugar, pero la solución no se compila. Revise los errores de compilación y corrija las incompatibilidades de api, las referencias que faltan y los problemas de migración de configuración.

  11. Revise los cambios que Copilot propone, luego recompile y pruebe el proyecto.

Iniciar la actualización

La solución Juego coincidente contiene la aplicación MatchingGame y la biblioteca de clases MatchingGame.Logic . El agente determina automáticamente el grafo de proyectos, así que inicia la actualización a nivel de la solución.

  1. En Explorador de soluciones, haga clic con el botón derecho en la solución y seleccione Modernizar.

    Se abre la ventana Copilot Chat de GitHub e inicia una conversación con el agente de modernización.

  2. Seleccione un modelo con capacidades sólidas de razonamiento y codificación.

  3. Indique al agente lo que desea hacer. Por ejemplo:

    Actualice todo a .NET 10.

    El agente notifica el estado actual del código base y lo que planea hacer:

    • Plataforma de destino: indica que el agente actualiza los proyectos a .NET 10.
    • Modo de flujo: el valor predeterminado es Automático. En el caso de las aplicaciones complejas, pida al agente que cambie al modo guiado .
    • Control de código fuente: indica que el agente crea una nueva rama de trabajo.

    El agente escribe su trabajo en .github/upgrades/scenarios/dotnet-version-upgrade/ de tu repositorio. Si esa carpeta ya existe de un intento anterior, el agente pregunta si desea continuar o empezar de cero.

  4. Indique al agente start que inicie el proceso de actualización.

Revisión de la evaluación

En la fase de evaluación, el agente examina la estructura del proyecto, las dependencias y los patrones de código para identificar lo que necesita cambiar. Escribe los resultados en assessment.md en .github/upgrades/scenarios/dotnet-version-upgrade/.

Cuando Copilot finalice la evaluación, revise el resultado de la conversación. Por lo general, comienza con algo similar a lo siguiente:

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

Desglose de la evaluación

Copilot abre el .github/upgrades/scenarios/dotnet-version-upgrade/assessment.md archivo en el editor de Visual Studio. Desplácese hacia abajo hasta la MatchingGame\MatchingGame.csproj sección para ver una tabla de problemas:

Tecnología Problemas Porcentaje Ruta de migración
Sistema de configuración heredado 2 0.2% Sistema de configuración basado en XML heredado (app.config/web.config) que se ha reemplazado por un modelo de configuración más flexible en .NET Core. El sistema antiguo era rígido y basado en XML. Migre a Microsoft. Extensions.Configuration con variables JSON/environment; Use el paquete NuGet System.Configuration.ConfigurationManager como puente provisional si es necesario.
GDI+ / System.Drawing 208 23.7% API de System.Drawing para gráficos 2D, imágenes e impresión disponibles a través del paquete NuGet System.Drawing.Common. Nota: No se recomienda para escenarios de servidor debido a las dependencias de Windows; considere alternativas multiplataforma como SkiaSharp o ImageSharp para código nuevo.
Windows Forms 621 76.0% Windows Forms API para compilar aplicaciones de escritorio Windows con la interfaz de usuario tradicional basada en formularios que están disponibles en .NET en Windows. Habilitar la compatibilidad con Windows Forms: Opción 1 (recomendado): Establecer net10.0-windows como destino; Opción 2: Agregar <UseWindowsForms>true</UseWindowsForms>; Opción 3 (heredada): Use Microsoft.NET.Sdk.WindowsDesktop SDK.

La mayoría de estos problemas no son problemas reales. Examine la columna "Ruta de migración" de la fila GDI+ que muestra 208 problemas. La evaluación marca estas API porque están disponibles en .NET Framework, pero no en .NET. En la columna se explica la corrección: agregue el System.Drawing.Common paquete NuGet para restaurar las API.

La fila Windows Forms enumera 621 problemas de API por la misma razón. Windows Forms API no están disponibles en .NET de forma predeterminada, pero se restauran mediante el destino de un marco específico de Windows como net10.0-windows y la configuración <UseWindowsForms>true</UseWindowsForms> en el archivo de proyecto. La opción 3 sugiere una opción incorrecta. Las versiones anteriores de .NET requerían un proyecto de Windows Forms para dirigirse específicamente al Microsoft.NET.Sdk.WindowsDesktop SDK, pero ahora se hace referencia automáticamente cuando <UseWindowsForms>true</UseWindowsForms> se establece.

Tip

Para obtener más información sobre una opción, pregunte Copilot para obtener más información y contexto.

Revise las opciones de actualización.

Después de la evaluación, el agente presenta las decisiones sobre la estrategia de actualización y las guarda en upgrade-options.md en .github/upgrades/scenarios/dotnet-version-upgrade/. Para el ejemplo de juego de emparejamiento, el agente selecciona las siguientes opciones:

Aspecto Decisión Reason
Estrategia de actualización De abajo a arriba. El agente actualiza MatchingGame.Logic primero porque MatchingGame depende de él y, a continuación, valida cada nivel antes de continuar.
Enfoque del proyecto En el mismo lugar. Ambos proyectos se migran juntos porque ningún otro proyecto de .NET Framework los consume.
Paquetes no admitidos Resuelva en línea. La evaluación detectó solo unos pocos paquetes incompatibles, por lo que el agente busca alternativas sobre la marcha.
Control de API no compatible Corregir en línea. La mayoría de los cambios en las API de Windows Forms y GDI+ para .NET son mecánicos y no requieren una fase de planificación independiente.
API nativas de Windows Paquete de compatibilidad de Windows. La aplicación usa Windows Forms y GDI+ en gran medida y es inherentemente solo Windows.
Tipos de referencia anulables Deje deshabilitado. El agente considera la activación de la nulabilidad una tarea independiente después de la migración.

El agente también señala los riesgos que requieren tu atención. En el ejemplo del juego de emparejamiento, el agente marca los paquetes MetroFramework porque solo están disponibles para .NET Framework. El resultado probable es quitar MetroFramework y revertir a los controles de Windows Forms estándar, que cambia el estilo visual de la aplicación.

Revise las opciones propuestas y indique al agente lo que desea cambiar. Por ejemplo, indique al agente que habilite los tipos de referencia anulables o que haga una pausa y analice primero las sustituciones de MetroFramework. Cuando haya terminado, responda con confirm para confirmar las selecciones y pasar a la planificación.

Revisión del plan

En la fase de planificación, el agente convierte la evaluación y las opciones confirmadas en una especificación detallada. Escribe el resultado plan.md en y crea un scenario-instructions.md archivo que almacena preferencias, decisiones e instrucciones personalizadas para la actualización.

Importante

Si el modo de flujo es Automático, el agente comienza a ejecutar el plan sin tiempo de revisión.

El plan abarca elementos como el orden de actualización en los distintos proyectos, el identificador del marco de destino para cada proyecto (net10.0-windows para los proyectos de Windows Forms), las rutas para actualizar paquetes y las mitigaciones de riesgos para los cambios con incompatibilidades importantes detectados en la evaluación.

Para revisar y personalizar el plan:

  1. Abra plan.md en .github/upgrades/scenarios/dotnet-version-upgrade/.
  2. Revisar las estrategias de actualización y las modificaciones de dependencias.
  3. Edite el plan para ajustar los pasos o agregar contexto según sea necesario.
  4. Indique al agente que se mueva a la fase de ejecución.

Cuidado

El plan depende de las interdependencias del proyecto. La actualización no tiene éxito si modifica el plan de una manera que impide que se complete el proceso de actualización. Por ejemplo, si MatchingGame depende de MatchingGame.Logic y quita MatchingGame.Logic del plan, es posible que se produzca un error al actualizar MatchingGame .

Ejecución de la actualización

En la fase de ejecución, el agente divide el plan en tareas secuenciales y concretas con criterios de validación. El agente escribe la lista de tareas en .github/upgrades/scenarios/dotnet-version-upgrade/tasks.md y hace un seguimiento del progreso general en ese archivo. Para cada tarea, el agente crea una carpeta en .github/upgrades/scenarios/dotnet-version-upgrade/tasks/ que contiene un archivo Markdown que describe la tarea y un archivo markdown que informa del progreso de la tarea.

Para el ejemplo juego coincidente, la lista de tareas normalmente incluye actualizar MatchingGame.Logic primero, luego MatchingGame, restaurar paquetes, compilar la solución y confirmar los cambios.

Para ejecutar la actualización:

  1. Indique al agente que inicie la actualización.
  2. Supervise el progreso revisando tasks.md a medida que el agente actualiza los estados de la tarea. Abra las carpetas por tarea en tasks/ para la descripción de la tarea y un informe de progreso detallado.
  3. Si el agente encuentra un problema que no puede resolver, proporcione la ayuda solicitada. Por ejemplo, el agente puede pedirle que elija entre dos API de reemplazo o confirme si desea mantener un paquete en desuso.
  4. En función de las respuestas, el agente adapta su estrategia a las tareas restantes y continúa.

El agente confirma los cambios según la estrategia de Git que configuró durante la inicialización previa: por tarea, por grupo de tareas o al final.

Notas de los proyectos de Visual Basic

Los proyectos de Visual Basic Windows Forms en .NET Framework suelen usar archivos de configuración System.Configuration y extensiones My, como My.Computer y My.User. Las My extensiones se quitaron en .NET. El agente marca estos patrones durante la evaluación y propone correcciones durante la ejecución, pero es posible que tenga que confirmar los cambios individuales durante una ejecución guiada.

Si el agente migra el proyecto, pero no se compila, compruebe que el archivo de proyecto tiene como destino Windows y hace referencia a Windows Forms. El <PropertyGroup> elemento debe tener un aspecto similar al siguiente fragmento de código:

<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>

Comprobación de la actualización

Cuando finalice la actualización, el agente recomienda los pasos siguientes en la respuesta del chat. Pida al agente que genere un informe de cambios completo con "Generar un informe de cambios".

Revise el estado final de la tarea en tasks.md y confirme que cada paso está completo.

Para comprobar la actualización:

  1. Compile la solución y solucione los errores de compilación.

  2. Ejecute la aplicación y confirme que los formularios se cargan y se comportan según lo previsto.

    La fuente predeterminada de Windows Forms cambió entre .NET Framework y .NET, por lo que comprueba los formularios y los controles personalizados para ver las diferencias de diseño.

  3. Ejecute las pruebas unitarias en la solución y corrija los errores.

  4. Confirme que los paquetes NuGet actualizados son compatibles con la aplicación.

  5. Pruebe la aplicación exhaustivamente para comprobar que la actualización se ha realizado correctamente.

Tip

Si el proyecto no se ejecutará y no se puede adjuntar un depurador, intente reiniciar Visual Studio. La migración de archivos de proyecto de .NET Framework a .NET podría confundir el diseñador de Windows Forms sin reiniciar.

El ejemplo de juego coincidente de Windows Forms ahora se actualiza a .NET 10.

Experiencia posterior a la actualización

Si ha migrado la aplicación de .NET Framework a .NET, revise Modernize después de actualizar a .NET desde .NET Framework para obtener ideas sobre cómo adoptar patrones más recientes, como appsettings.json la configuración, la inserción de dependencias o los servicios en la nube. La adopción de estos patrones es independiente de actualizar a .NET y no es necesario para completar la actualización.

Contenido relacionado

  • Last updated on