Migración de UWP al SDK de Aplicaciones de Windows con el Asistente para actualización de .NET

  • Artículo

El Asistente para actualización de .NET (consulte Información general del Asistente para actualización de .NET) es una extensión de Visual Studio (recomendada) y una herramienta de la línea de comandos que ayuda a migrar una aplicación de la Plataforma universal de Windows (UWP) en C# a una aplicación de la biblioteca de interfaz de usuario de Windows (WinUI) 3, que usa el SDK de Aplicaciones de Windows.

Nuestro plan de desarrollo para la compatibilidad con UWP en el Asistente para actualización de .NET incluye mejoras adicionales en las herramientas y la adición de compatibilidad con la migración para nuevas características. Si encuentra problemas relacionados con el Asistente para actualización de .NET, puede presentarlos en Visual Studio seleccionando Ayuda>Enviar comentarios>Notificar un problema.

Consulte también el repositorio de GitHub del Asistente para actualización. Las opciones para ejecutar la herramienta en la línea de comandos se documentan allí.

Instalación del Asistente para actualización de .NET

Puede instalar el Asistente para actualización de .NET como una extensión de Visual Studio o como una herramienta de línea de comandos de .NET. Para obtener más información, consulte Instalación del Asistente para actualización de .NET.

Resumen

Cuando usa el Asistente para actualización de .NET para migrar la aplicación para UWP, estos son los pasos y fases generales del proceso de migración que lleva a cabo la herramienta.

  • Opcionalmente copia el proyecto y migra la copia; dejando su proyecto original sin cambios.
  • Opcionalmente, migra el proyecto en contexto (en las mismas carpetas y archivos, sin cambiar el nombre de las carpetas), y no realiza una copia.
  • Actualice el proyecto desde el formato de proyecto de .NET Framework al formato de proyecto del SDK de .NET.
  • Limpia las referencias del paquete NuGet. Además de los paquetes a los que hace referencia la aplicación, el archivo packages.config contiene referencias a las dependencias de esos paquetes. Por ejemplo, si ha agregado una referencia al paquete A que depende del paquete B, se haría referencia a ambos paquetes en el archivo packages.config. En el nuevo sistema de proyectos, solo hace falta la referencia al paquete A. Así, en este paso se analizan las referencias al paquete y se quitan las que no son necesarias. La aplicación sigue haciendo referencia a los ensamblados de .NET Framework. Algunos de esos ensamblados pueden estar disponibles como paquetes de NuGet. Así, en este paso se analizan esos ensamblados y se hace referencia al paquete de NuGet adecuado.
  • Toma como destino .NET 6 y SDK de Aplicaciones de Windows.
  • Cambia el moniker de la plataforma de destino (TFM) (consulte Plataformas de destino en proyectos de estilo SDK) de .NET Framework al SDK sugerido. Por ejemplo, net6.0-windows.
  • Migra el código fuente de UWP de WinUI 2 a WinUI 3, realizando cambios de código específicos del origen.
  • Agrega o actualiza los archivos de plantilla, configuración y código. Por ejemplo, agregar los perfiles de publicación necesarios, App.xaml.cs, MainWindow.xaml.cs, MainWindow.xaml y otros.
  • Actualiza los espacios de nombres y agrega navegación MainPage.
  • Intenta detectar y corregir las API que son diferentes entre UWP y el SDK de Aplicaciones de Windows, y usa los pendientes de la lista de tareas para marcar las API que ya no se admiten.

A medida que se ejecuta, la herramienta también tiene como objetivo proporcionar instrucciones de migración en forma de mensajes de advertencia dentro de la salida de la herramienta y elementos pendientes de la lista de tareas en forma de comentarios en el código fuente del proyecto (por ejemplo, en casos en los que no es posible realizar una migración completamente automatizada del código fuente de UWP). Un elemento pendiente de la lista de tareas habitual incluye un vínculo a un tema de esta documentación de migración. Como desarrollador, siempre tiene el control del proceso de migración.

Sugerencia

Para ver todos los elementos pendientes que ha generado la herramienta, busque en la lista de tareas de Visual Studio.

Nota:

Una vez finalizada la ejecución de la herramienta, hay algunos pasos de seguimiento que puede elegir si es necesario. Puede mover el código de App.xaml.old.cs a App.xaml.cs y puede restaurar AssemblyInfo.cs desde la copia de seguridad que crea la herramienta.

Qué admite la herramienta

Esta versión del Asistente para actualización de .NET se encuentra actualmente en versión preliminar y recibe actualizaciones frecuentes. Actualmente, la herramienta solo admite el lenguaje de programación C#; no C++. Y en la mayoría de los casos con esta versión, el proyecto requerirá un esfuerzo adicional de su parte para completar la migración.

El objetivo de la herramienta es migrar el proyecto y el código para que se compile. Pero algunas características requieren que las investigue y las corrija (a través de elementos pendientes de la lista de tareas). Para obtener más información sobre lo que hay que tener en cuenta antes de migrar, vea ¿Qué se admite al migrar de UWP a WinUI 3?

Debido a las siguientes limitaciones de la versión actual del Asistente para actualización de .NET, puede optar por esperar una versión futura antes de migrar la aplicación:

  • No se admite la migración desde las API de ApplicationView.
  • No se admite la migración desde las API relacionadas con AppWindow.

Siempre que sea posible, la herramienta intenta generar una advertencia; y provoca intencionadamente que el código no se compile hasta que lo cambie.

  • No se admiten vistas personalizadas. Por ejemplo, no recibirá una advertencia ni una corrección para un cuadro de diálogo personalizado que extienda MessageDialog y llame a una API de forma incorrecta.
  • No se admiten los componentes de Windows Runtime.
  • Es posible que las aplicaciones de varias ventanas no se migren correctamente.
  • Es posible que un proyecto que siga una estructura de archivos no estándar (como App.xaml y App.xaml.cs que no estén en la carpeta raíz) no se migre correctamente.

El repositorio del Asistente para actualización de GitHub documenta sugerencias para solucionar problemas conocidos. Si encuentra algún problema al usar la herramienta, notifíquelo en ese mismo repositorio de GitHub, marcándolo con una etiqueta de área de UWP. ¡Lo agradecemos!

Nota:

Para obtener instrucciones sobre el proceso de migración y las diferencias entre las características y las API de UWP y SDK de Aplicaciones de Windows, consulte Migración de UWP a la SDK de Aplicaciones de Windows.

Sugerencia

Para ver qué versión de la herramienta tiene, emita el comando upgrade-assistant --version.

Prueba de la herramienta con el ejemplo PhotoLab de UWP

Vamos a probar el Asistente de actualización de .NET.

Como material de origen, migraremos la aplicación de ejemplo de PhotoLab de UWP. PhotoLab es una aplicación de ejemplo para ver y editar archivos de imagen. Muestra el diseño XAML, el enlace de datos y las características de personalización de la interfaz de usuario.

Nota:

Puede ver un caso práctico de la migración manual completa de la aplicación de ejemplo PhotoLab en Migración del SDK de Aplicaciones de Windows de la aplicación de ejemplo PhotoLab de UWP.

  1. Comience por clonar o descargar el código fuente del ejemplo de PhotoLab del vínculo anterior.

Sugerencia

Tenga en cuenta que después de haber usado la herramienta para automatizar la migración de la aplicación, se necesitará un esfuerzo manual adicional para completar la migración.

  1. Abra la solución PhotoLab en Visual Studio.

  2. Después de instalar la extensión del Asistente para actualización de .NET (vea Instalación del Asistente para actualización de .NET anteriormente en este tema), haga clic con el botón derecho en el proyecto en el Explorador de soluciones y haga clic en Actualizar.

  3. Elija la opción Actualizar proyecto a una versión más reciente de .NET.

  4. Elija la opción Actualización local del proyecto.

  5. Elija una plataforma de destino

  6. Haga clic en Actualizar selección.

  7. El Asistente para actualización de .NET se ejecuta y usa la ventana Salida de Visual Studio para imprimir la información y el estado a medida que avanza.

Puede supervisar la barra de progreso hasta que se complete la operación de actualización.

La migración de código para la aplicación de ejemplo PhotoLab incluye:

  • Cambios en las API del selector para guardar archivos y el cuadro de diálogo de contenido.
  • Actualización XAML para el paquete Animaciones.
  • Visualización de mensajes de advertencia y adición de elementos pendientes de la lista de tareas en DetailPage.xaml, DetailPage.xaml.cs y MainPage.xaml.cs para el botón Atrás personalizado.
  • Implementación de la funcionalidad del botón Atrás e incorporación de un elemento pendiente de la lista de tareas para personalizar el botón XAML.
  • Se proporciona un vínculo a la documentación que puede usar para obtener más información sobre la implementación del botón Atrás.

Los números de versión en su .csproj resultante serán ligeramente diferentes, pero básicamente tendrá este aspecto (con algunos de los grupos de propiedades de configuración de compilación eliminados por brevedad):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <OutputType>WinExe</OutputType>
    <DefaultLanguage>en-US</DefaultLanguage>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <EnableMsixTooling>true</EnableMsixTooling>
    <Platforms>x86;x64;arm64</Platforms>
    <PublishProfile>win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>
  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.1.0" />
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
    <PackageReference Include="CommunityToolkit.WinUI.UI.Animations" Version="7.1.2" />
  </ItemGroup>
  <ItemGroup>
    <Compile Remove="App.xaml.old.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.xaml.old.cs" />
  </ItemGroup>
</Project>

Como puede ver, el proyecto ahora hace referencia a la SDK de Aplicaciones de Windows, WinUI 3 y .NET 6. Ahora que PhotoLab se ha migrado, puede aprovechar todas las nuevas características que las aplicaciones WinUI 3 tienen que ofrecer y hacer crecer tu aplicación con la plataforma.

Además, el Asistente para actualización de .NET agrega analizadores al proyecto que ayudan a continuar el proceso de actualización. Por ejemplo, el paquete NuGet Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers.

Seguimiento de la migración manual

En este momento puede abrir el proyecto o la solución PhotoLab migrada y ver los cambios realizados en el código fuente. El proyecto necesita un poco más de trabajo para terminar de conectar todo antes de que la versión WinUI 3 se compile, se ejecute y se comporte como la versión UWP.

Consulte la lista de tareas en Visual Studio (Ver>Lista de tareas) para ver los elementos pendientes que debe realizar para completar manualmente la migración.

Es posible que la versión de UWP (.NET Framework) de la aplicación tuviera referencias a bibliotecas que el proyecto, en realidad, no está usando. Debe analizar cada referencia y comprobar si es necesaria o no. Es posible que la herramienta también haya agregado o actualizado una referencia al paquete NuGet a una versión incorrecta.

El Asistente para actualización no edita Package.appxmanifest, que necesitará algunas modificaciones para que la aplicación se inicie:

  1. Agregue este espacio de nombres en el elemento <Paquete> de la raíz:
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

  1. Edición del elemento <Aplicación> de EntryPoint="appnamehere.App" a EntryPoint="$targetentrypoint$"

  2. Reemplace cualquier Capability especificado por esto:

<rescap:Capability Name="runFullTrust" />

En su archivo .csproj, es posible que tenga que editar el archivo de proyecto para establecer <OutputType>WinExe</OutputType> y <UseMaui>False</UseMaui>.

Para usar muchos de los controles XAML, asegúrese de que el archivo app.xaml incluye <XamlControlsResources>, como en este ejemplo:

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <!-- Other merged dictionaries here -->
        </ResourceDictionary.MergedDictionaries>
        <!-- Other app resources here -->
    </ResourceDictionary>
</Application.Resources>

Sugerencias de solución de problemas

Hay varios problemas conocidos que pueden producirse al usar el Asistente para actualización de .NET. En algunos casos, se trata de problemas con la herramienta try-convert, que el Asistente para actualización de .NET usa internamente.

Pero para obtener más consejos para la solución de problemas y ver problemas conocidos, consulte el repositorio del Asistente para actualización de GitHub.