Información general sobre la actualización de aplicaciones de WPF

Este artículo le ayuda a comprender lo que implica actualizar una aplicación de Windows Presentation Foundation (WPF) de .NET Framework a .NET. WPF se admite en .NET y recibe una inversión activa, incluidas las mejoras de rendimiento, las actualizaciones de accesibilidad y las nuevas características. Si mantiene una aplicación de WPF existente y quiere aprovechar esas mejoras o pasar a una versión de .NET compatible, este artículo es para usted.

En el artículo se tratan las razones para actualizar, las rutas de actualización disponibles y el trabajo de preparación que hace que la actualización se realice sin problemas. También se explica qué tecnologías de .NET Framework no tienen equivalentes en .NET, cómo rellenar espacios de API mediante el paquete de compatibilidad de Windows y cómo pueden afectar los cambios importantes a la aplicación.

Para obtener más información sobre los cambios con respecto a .NET Framework, consulte Diferencias de WPF entre .NET y .NET Framework y Tecnologías de .NET Framework no disponibles en .NET.

Por qué actualizar

.NET Framework es un entorno de ejecución de código cerrado de solo Windows que ya no recibe actualizaciones de características. Aunque sigue recibiendo parches de seguridad para las versiones compatibles, no se beneficia de las mejoras de rendimiento, las mejoras del lenguaje ni la inversión activa de la que sí se beneficia .NET. Si mantiene una aplicación de Windows en .NET Framework, la actualización a .NET le proporciona acceso a una plataforma más rápida y capaz que se desarrolla activamente en la apertura.

Mantenerse al día con las versiones de .NET también es importante. Cada versión de .NET tiene una ventana de soporte técnico definida y las aplicaciones que se ejecutan en una versión fuera de soporte técnico dejan de recibir revisiones y correcciones de seguridad. Actualice antes del fin del soporte técnico para mantenerse protegido.

.NET ofrece mejoras de rendimiento significativas en el inicio, el rendimiento y el uso de memoria en tiempo de ejecución. Las aplicaciones de escritorio en .NET también se benefician de la inversión de características en curso:

  • Controles más modernos, mejoras de accesibilidad y mejoras para pantallas de alta densidad de píxeles.
  • Mejor integración con Windows. Algunas características, como el modo oscuro en Windows 11, solo están disponibles en .NET.
  • Características más recientes del lenguaje C# y Visual Basic y herramientas mejoradas.
  • Un ecosistema enriquecido de paquetes NuGet que tienen como destino .NET.

.NET lanza una nueva versión principal cada año, alternando entre versiones con soporte a largo plazo (LTS) y versiones con soporte estándar (STS):

  • Las versiones de LTS se admiten durante tres años y suelen ser la mejor opción para las aplicaciones de producción que prefieren estabilidad.
  • Las versiones STS tienen soporte durante 24 meses y son útiles si desea incorporar nuevas funcionalidades más pronto.

Planee la cadencia de actualización en torno a estas fechas para que la aplicación esté siempre en una versión compatible. Para conocer las versiones admitidas actuales y las fechas de finalización del soporte técnico, consulte .NET versiones, revisiones y soporte técnico.

Rutas de actualización

La mayoría de las actualizaciones se dividen en una de estas dos categorías. Identifique qué ruta de acceso se aplica a la aplicación y, a continuación, use las instrucciones y herramientas de este artículo para completar el trabajo.

  • De .NET Framework a .NET: el cambio más significativo.

    El formato de archivo del proyecto, algunas API y ciertas tecnologías son diferentes. Revise los requisitos previos, evalúe las dependencias y planee las brechas de API antes de empezar.

    Una vez que su aplicación se compile y ejecute en .NET, puede optar por adoptar patrones más recientes, como la appsettings.json configuración, la inyección de dependencias o los servicios en la nube. La adopción de estos patrones es independiente de la modernización a la .NET y no es necesario para completar la actualización. Para obtener ideas e instrucciones, consulte Modernización después de actualizar a .NET desde .NET Framework.

  • Desde una versión de .NET anterior a una más reciente: una actualización de ámbito más pequeña.

    Las tareas principales son actualizar el moniker de la plataforma de destino, revisar los cambios importantes de las versiones que está cruzando y actualizar las dependencias de NuGet.

Actualización de .NET Framework a .NET

La actualización de .NET Framework a .NET es la ruta de actualización más importante y el enfoque principal de esta sección.

Importante

Aunque .NET es una tecnología multiplataforma, las aplicaciones de escritorio de Windows para .NET siguen siendo exclusivas de Windows.

Un cambio es el formato de archivo del proyecto. .NET usa el formato de proyecto de estilo SDK, que es más conciso que el formato heredado. Puede convertir el archivo de proyecto al estilo del SDK mientras sigue teniendo como destino .NET Framework, lo que reduce el ámbito de cambio durante el puerto real y proporciona una mejor línea de base desde la que trabajar.

No todas las API de .NET Framework están disponibles en .NET. Algunas API aparentemente existen, pero generan PlatformNotSupportedException en tiempo de ejecución. El paquete de compatibilidad de Windows (Microsoft.Windows.Compatibilitypaquete NuGet) rellena muchas de estas lagunas al proporcionar acceso a las API específicas de Windows, como el registro de Windows, Windows registro de eventos, etc. Para obtener más información, consulte Use el paquete de compatibilidad de Windows para portar código a .NET.

Algunas tecnologías de .NET Framework no tienen equivalentes en .NET y requieren enfoques alternativos, como dominios de aplicación, seguridad de acceso a código (CAS) y Windows Workflow Foundation. Para obtener más información, consulte la sección Tecnologías de .NET Framework no disponibles.

Audite las dependencias de terceros. Es posible que los controles y bibliotecas que solo tienen como destino .NET Framework no funcionen en .NET. Prefiere paquetes NuGet que tienen como destino .NET Standard 2.0 o .NET directamente. En el caso de los paquetes que no se han migrado, busque alternativas de la comunidad o compruebe si el paquete de compatibilidad de Windows cubre las API necesarias.

Actualización entre versiones de .NET

Pasar de una versión de .NET a otra (por ejemplo, de .NET 9 a .NET 10) suele ser un esfuerzo menor que la modernización desde .NET Framework. La tarea principal consiste en actualizar la propiedad <TargetFramework> en el archivo del proyecto al nuevo identificador del marco de destino. Por ejemplo, cambiar net9.0-windows a net10.0-windows.

Antes de actualizar el destino, revise la documentación de cambios importantes para cada versión que esté cruzando. Los cambios disruptivos pueden ser de comportamiento, afectar a la compatibilidad binaria o con el código fuente, o cambiar el comportamiento en tiempo de diseño. Incluso las diferencias entre versiones menores pueden introducir cambios que afecten a tu aplicación. Revise Cambios importantes en .NET y filtre por el intervalo de versiones en el que va a actualizar.

Después de actualizar la plataforma de destino, actualice las dependencias de NuGet. Los paquetes que tienen como destino versiones anteriores de .NET podrían tener versiones más recientes que aprovechen el entorno de ejecución actual. Compruebe si hay actualizaciones y dé preferencia a los paquetes compatibles con la versión a la que va a migrar. Algunos paquetes también pueden tener API en desuso o cambiar el comportamiento en versiones más recientes, por lo que revise las notas de la versión al actualizar.

Modernización de aplicación Copilot de GitHub

El agente de modernización de GitHub Copilot es la herramienta recomendada para actualizar aplicaciones Windows Forms y WPF. Es una experiencia de un extremo a otro con tecnología de inteligencia artificial integrada en GitHub Copilot que controla todo el proceso de actualización.

El agente sigue un flujo de trabajo de tres fases:

  • Evaluación. Copilot examina la estructura, las dependencias y los patrones de código del proyecto. Identifica cambios importantes, problemas de compatibilidad de API, patrones en desuso y ámbito de actualización general. A continuación, presenta decisiones de estrategia, como el orden de actualización y el control de compatibilidad, para que pueda revisar antes de continuar.

  • Planificación. Copilot convierte la evaluación y las opciones confirmadas en un plan de actualización detallado, documentando estrategias de actualización, enfoques de refactorización, rutas de dependencias y medidas de mitigación de riesgos.

  • Ejecución. Copilot divide el plan en tareas secuenciales con criterios de validación, aplica correcciones de código y confirma los cambios incrementalmente. Si encuentra un problema que no se puede resolver automáticamente, solicita su ayuda y aprende de la corrección.

Todo el estado de actualización se almacena en .github/upgrades/ el repositorio, por lo que puede pausar y reanudar entre sesiones o cambiar entre entornos de desarrollo sin perder el progreso.

El agente admite estas rutas de actualización:

  • .NET Framework (cualquier versión) para .NET 8 o posterior
  • .NET Core 1.x–3.x para .NET 8 o posterior
  • de .NET 5-7 a .NET 8 o posterior
  • Migración a servicios de Azure

Está disponible en Visual Studio 2026, Visual Studio 2022 17.14.16+, Visual Studio Code y la CLI de GitHub. Para iniciar una actualización en Visual Studio, haga clic con el botón derecho en la solución o proyecto en Explorador de soluciones y seleccione Modernizar, o abra la ventana de gitHub Copilot Chat y escriba @Modernize. En Visual Studio Code, abra el panel Copilot Chat de GitHub y escriba @modernize-dotnet.

Para obtener detalles de configuración y uso, consulte ¿Qué es la modernización de GitHub Copilot?.

Tecnologías de .NET Framework no disponibles

Varias tecnologías de .NET Framework no tienen ningún equivalente en .NET y requieren enfoques alternativos para que la aplicación pueda ejecutarse en el nuevo entorno de ejecución. Identifique si la aplicación depende de cualquiera de estas tecnologías al principio, ya que representan la categoría más perjudicial del trabajo de migración. Para obtener la referencia completa, consulte las tecnologías de .NET Framework no disponibles en .NET.

  • Dominios de aplicación

    AppDomain no es compatible. Use AssemblyLoadContext para la carga dinámica de ensamblados y use procesos o contenedores independientes para el aislamiento. Algunos AppDomain miembros de la API están presentes, pero lanzan PlatformNotSupportedException en tiempo de ejecución.

  • Comunicación remota

    no se admite .NET comunicación remota. Use System.IO.Pipes o MemoryMappedFile para IPC local, o gRPC y ASP.NET Core para la comunicación entre equipos. Las llamadas a BeginInvoke() y EndInvoke() en los objetos delegados también producen PlatformNotSupportedException.

  • Seguridad de acceso al código (CAS)

    CAS no es compatible y ya no es un límite de seguridad. Use límites de seguridad de nivel de sistema operativo, como la virtualización, los contenedores o las cuentas de usuario en su lugar.

  • Transparencia de seguridad

    La transparencia de seguridad, que separaba el código en entorno aislado del código crítico para la seguridad, ya no se admite como barrera de seguridad. Al igual que CAS, esta funcionalidad dependía de la imposición en tiempo de ejecución que .NET no ofrece. En su lugar, use mecanismos de aislamiento de nivel de sistema operativo.

  • Windows Workflow Foundation (WF)

    WF no es compatible con .NET. Si la aplicación hospeda o usa flujos de trabajo, considere CoreWF, un puerto de código abierto del entorno de ejecución de Windows Workflow Foundation que tiene como destino .NET.

  • System.EnterpriseServices (COM+)

    System.EnterpriseServices no es compatible. Las aplicaciones que usan servicios COM+, como la agrupación de objetos, las transacciones o la seguridad System.EnterpriseServices basada en roles, deben rediseñarse para usar alternativas. Para las transacciones distribuidas, considere System.Transactions. Para escenarios de alojamiento de servicios, considere usar ASP.NET Core o servicios de trabajo en segundo plano.

Tenga en cuenta que algunas API en estas áreas están presentes en .NET, pero generan PlatformNotSupportedException en tiempo de ejecución en lugar de producir un error en tiempo de compilación. Pruebe su aplicación en .NET al inicio de la migración para detectar estos problemas antes de invertir en una migración completa.

Antes de empezar a actualizar desde .NET Framework

Antes de empezar a migrar la aplicación a .NET, complete un conjunto de pasos preparatorios mientras el proyecto sigue teniendo como destino .NET Framework. Realizar primero este trabajo preparatorio reduce el alcance de los cambios durante la actualización propiamente dicha y le proporciona una base de referencia validada y más limpia desde la que partir. Para obtener una referencia completa, consulte Requisitos previos para migrar código de .NET Framework.

  • Actualice las herramientas.

    Asegúrese de que está ejecutando una versión de Visual Studio que admita la versión de .NET de destino. Las versiones más recientes del SDK incluyen compatibilidad mejorada con la migración, mejores analizadores y plantillas de proyecto actualizadas. Para obtener la relación entre el SDK de .NET, MSBuild y las versiones de Visual Studio, consulte Relación de control de versiones entre el SDK de .NET, MSBuild y Visual Studio.

  • Use como destino .NET Framework 4.7.2 o una versión posterior.

    Vuelva a trasladar el proyecto a .NET Framework 4.7.2 o posterior antes de migrarlo. Esta versión proporciona la superficie de compatibilidad de API más amplia con .NET Standard 2.0, lo que reduce el número de brechas de API que encontrará durante la actualización.

    En Visual Studio, haga clic con el botón derecho en el proyecto, seleccione Propiedades y, a continuación, cambie la lista desplegable Plataforma de destino a .NET Framework 4.7.2. Vuelva a compilar y corrija los problemas antes de continuar.

  • Convierta al formato PackageReference.

    Si el proyecto usa un packages.config archivo para administrar las referencias de NuGet, migre al PackageReference formato. PackageReference es el enfoque moderno y se integra directamente en el formato de proyecto de estilo SDK que adoptará en el paso siguiente.

    En Visual Studio, haga clic packages.config con el botón derecho en Explorador de soluciones y seleccione Migrar packages.config a PackageReference. Revise la salida de la migración y resuelva las advertencias antes de continuar.

  • Convierta en formato de proyecto de estilo SDK.

    Cambie el archivo del proyecto al formato de estilo SDK. Los proyectos de estilo SDK son más concisos, admiten varios destinos y son necesarios para .NET. Esta conversión se puede realizar mientras sigue teniendo como destino .NET Framework, por lo que es un paso preparatorio seguro. Muchas herramientas de conversión controlan esto automáticamente o puede convertir manualmente el contenido del archivo de proyecto por el equivalente de estilo SDK y volver a agregar las propiedades necesarias.

  • Actualice las dependencias de NuGet.

    Actualice todos los paquetes NuGet a sus versiones más recientes y prefiera los paquetes que tienen como destino .NET Standard 2.0, en lugar de los paquetes que tienen como destino solo .NET Framework. Esto reduce el riesgo de bloqueadores de dependencias al cambiar la plataforma de destino. Revise las notas de la versión del paquete para ver los cambios importantes introducidos en las versiones más recientes.

Todas las sugerencias anteriores garantizan que los proyectos estén en buen estado antes de actualizar a .NET.

Paquete de compatibilidad de Windows

Uno de los problemas más comunes al migrar desde .NET Framework es la falta de API. .NET Estándar excluye deliberadamente las tecnologías que no pueden funcionar en todas las plataformas( como el Registro de Windows, WMI y emisión de reflexión, por lo que esas API no están disponibles de forma predeterminada. El Microsoft.Windows.Compatibility paquete NuGet rellena ese hueco. Proporciona aproximadamente 20 000 API en las siguientes áreas tecnológicas:

  • Registro de Windows
  • Registro de sucesos de Windows
  • Instrumentación de administración de Windows (WMI)
  • Contadores de rendimiento de Windows
  • Servicios de directorio
  • Listas de control de acceso de Windows (ACL)
  • servicios de Windows
  • Criptografía de Windows
  • Windows Communication Foundation (WCF)
  • Puertos, ODBC, CodeDom y mucho más

El paquete se encuentra encima de .NET Standard 2.0 y es especialmente útil al modernizar incrementalmente. Le permite crear y ejecutar la aplicación en .NET primero y, después, abordar la refactorización más adelante, sin tener que volver a escribir el uso de API específico de Windows por adelantado.

Para agregarlo al proyecto, instale el Microsoft.Windows.Compatibility paquete NuGet:

dotnet add package Microsoft.Windows.Compatibility

Para obtener información completa, consulte Uso del paquete de compatibilidad de Windows para portar código a .NET.

Cambios críticos

Los cambios importantes son una parte esperable de cualquier actualización, tanto si migra desde .NET Framework como si pasa de una versión de .NET a otra. Revisarlos antes de comenzar evita sorpresas al final de la migración. Para obtener la referencia completa, consulte Cambios importantes al migrar código.

Los cambios importantes se dividen en varias categorías y no todos provocan errores en tiempo de compilación:

  • Los cambios de comportamiento afectan a cómo funciona una API en tiempo de ejecución. La firma permanece igual, pero cambian la salida, las excepciones lanzadas o el comportamiento interno. Estos son los más difíciles de detectar porque no producen errores de compilación.
  • Los cambios de compatibilidad binaria afectan a si los ensamblados compilados existentes siguen funcionando sin volver a compilar. Quitar o modificar una superficie de API pública interrumpe la compatibilidad binaria.
  • La compatibilidad de origen exige modificar el código fuente antes de que se compile correctamente con la versión más reciente.
  • Compatibilidad en tiempo de diseño: los cambios afectan a cómo los proyectos se abren y se comportan en Visual Studio u otros entornos de diseño.

Al migrar desde .NET Framework, se cruza una brecha de versión grande, por lo que la lista de posibles cambios es más larga. Al actualizar entre versiones de .NET(por ejemplo, de .NET 6 a .NET 9), el ámbito es más estrecho, pero cada versión entre sí puede introducir cambios que afectan a la aplicación. Revise los cambios importantes de cada versión que omita, no solo la versión de destino.

Los cambios importantes específicos de Windows Forms se documentan en Cambios importantes para la migración de .NET Framework a .NET. Filtre la referencia de cambios importantes por el intervalo de versiones entre las que va a actualizar y revise las entradas que se aplican a las API que utiliza su aplicación.

Tareas posteriores a la actualización

Una vez que la aplicación se compila y se ejecuta en .NET, complete algunas tareas de limpieza para quitar artefactos dejados de la actualización.

Revise los paquetes NuGet.

Es posible que el proceso de actualización haya actualizado los paquetes a versiones más recientes. Algunas de esas versiones más recientes quitan las dependencias necesarias para las versiones anteriores. Después de la actualización, compruebe cada paquete actualizado y quite las dependencias transitivas que ya no sean necesarias. Revise las notas de la versión de los paquetes actualizados para detectar los cambios de comportamiento que no provocan errores de compilación.

Limpie los artefactos antiguos de NuGet.

Si el proyecto usó un packages.config archivo para administrar las referencias de NuGet, ya no es necesario después de migrar al PackageReference formato. Elimínelo del proyecto. También puede eliminar la carpeta local packages en el directorio del proyecto o la solución: NuGet ahora almacena paquetes en una carpeta de caché global en .nuget\packages el perfil de usuario.

Actualizar System.Configuration referencias.

La mayoría de las aplicaciones de .NET Framework hacen referencia System.Configuration directamente. Después de actualizar, es posible que el proyecto siga teniendo esa referencia. La biblioteca System.Configuration lee desde el archivo app.config para obtener la configuración en tiempo de ejecución. En .NET, sustitúyalo por el paquete NuGet System.Configuration.ConfigurationManager, que proporciona la misma API sin la referencia directa al ensamblado del framework.

Modernización después de la actualización

Una vez que la aplicación se ejecuta en .NET, puedes adoptar patrones modernos que no están disponibles en .NET Framework. Estos cambios no son necesarios para completar la actualización, pero mejoran la capacidad de mantenimiento y aprovechan las ventajas de la inversión activa en .NET. Para obtener un conjunto más amplio de ideas, consulte Modernización después de actualizar a .NET desde .NET Framework.

Migre de App.config a appsettings.json.

.NET Framework usa App.config para la configuración en tiempo de ejecución, como cadenas de conexión y configuración de registro. Las aplicaciones .NET suelen usar appsettings.json en su lugar, proporcionado por el paquete NuGet Microsoft.Extensions.Configuration. Muchas bibliotecas, incluidos los proveedores de registro, han dejado de admitir App.config en favor de appsettings.json. La migración alinea la aplicación con el ecosistema y simplifica la configuración a medida que agrega nuevas dependencias.

App.config archivos siguen funcionando en .NET a través del System.Configuration.ConfigurationManager paquete NuGet, por lo que puede migrar de forma incremental. Para obtener instrucciones, consulte Configuración en .NET.

Reemplace el control WebBrowser por WebView2 (WPF).

El WebBrowser control se basa en Internet Explorer, que ya no se admite. WPF para .NET puede usar el WebView2 control basado en Microsoft Edge en su lugar. WebView2 proporciona un control de explorador moderno y mantenido activamente con un rendimiento mejorado, seguridad y compatibilidad con estándares web.

Agregue el paquete NuGet Microsoft.Web.WebView2 al proyecto. Dependiendo de la versión de Windows que ejecute un usuario, es posible que necesite instalar por separado el entorno de ejecución WebView2. Para obtener más información, vea Introducción a Microsoft Edge WebView2.

Contenido relacionado

  • Last updated on