Guía del Asistente de actualización de .NET heredado para UWP

Importante

.NET Upgrade Assistant ha quedado en desuso. No lo use para iniciar una nueva migración. Este artículo sigue estando disponible para los equipos que necesitan mantener o reproducir una migración existente de C# de UWP a WinUI 3 en la que se usó la herramienta.

La actualización de GitHub Copilot sustituye a .NET Upgrade Assistant para las actualizaciones de .NET compatibles, pero actualmente no documenta la ruta de actualización de UWP a WinUI 3 como una ruta admitida. Para una nueva migración de UWP, sigue Migrar de UWP a la SDK de Aplicaciones para Windows o usa la guía de migración de UWP asistida por IA.

En las secciones restantes se describen el comportamiento y las limitaciones de la herramienta heredada.

Instalación de la herramienta heredada

Si necesita reproducir o continuar una migración existente, puede habilitar el asistente de actualización heredado integrado de .NET en una versión compatible de Visual Studio o instalarlo como una herramienta de línea de comandos de .NET. Para obtener más información, consulta Install the .NET Upgrade Assistant.

Resumen

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

• Opcionalmente, copia tu proyecto y migra la copia, dejando el proyecto original sin cambios.
• Opcionalmente, migra el proyecto en su ubicación original (en las mismas carpetas y archivos, sin renombrar carpetas) y no realiza una copia.
• Actualiza tu proyecto desde el formato de proyecto de .NET Framework al formato de proyecto del SDK de .NET más reciente.
• 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 project, solo se requiere 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 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.
• Tiene como destino .NET 6 y el SDK de Aplicaciones para Windows.
• Cambia el nombre del entorno de trabajo de destino (TFM) (consulte Entornos de trabajo en proyectos de estilo SDK) de .NET Framework al SDK sugerido. Por ejemplo, net6.0-windows.
• Migrará tu código fuente de UWP de WinUI para UWP a WinUI, realizando cambios en el código específicos de la fuente.
• 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 la navegación de MainPage.
• Intenta detectar y corregir las API que son diferentes entre UWP y el SDK de Aplicaciones para Windows, y usa Task List TODOs para marcar las API que ya no se admiten.

A medida que se ejecuta, la herramienta también tiene como objetivo proporcionar orientación de migración en forma de mensajes de advertencia dentro de la salida de la herramienta, y Task List TODOs en forma de comentarios dentro del código fuente de su proyecto (por ejemplo, para casos donde la migración completamente automatizada del código fuente de UWP no es posible). 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 TODOs que ha generado la herramienta, busque en la lista Task en Visual Studio.

Nota:

Una vez que la herramienta haya terminado de ejecutarse, hay algunos pasos de seguimiento que puede elegir hacer 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

La compatibilidad con la migración a UWP de la herramienta en desuso solo se aplica a C#, no a C++. En la mayoría de los casos, el proyecto requiere un trabajo manual adicional para completar la migración.

La herramienta tiene como objetivo migrar el proyecto y el código para que compile correctamente. Pero algunas características requieren que las investigue y las corrija (a través de los TODOs de la lista de tareas). Para obtener más información sobre lo que se debe tener en cuenta antes de migrar, consulta ¿Qué se admite al migrar de UWP a WinUI?

El flujo de trabajo de migración de UWP heredado tiene las siguientes limitaciones:

• 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 project que siga una estructura de archivos no estándar (como App.xaml y App.xaml.cs no esté en la carpeta raíz) no se migre correctamente.

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 para Windows, consulta Migrate de UWP a la SDK de Aplicaciones para Windows.

Sugerencia

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

Prueba la herramienta con la muestra de UWP PhotoLab

Probemos el Asistente de Actualización de .NET para una prueba.

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:

Puedes ver un estudio de caso del ejemplo PhotoLab que se migra completamente de forma manual en Una migración de SDK de Aplicaciones para Windows de la aplicación de ejemplo PhotoLab para 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 .NET Upgrade Assistant (vea Instalar la herramienta heredada anteriormente en este tema), haga clic con el botón derecho en el proyecto en Explorador de soluciones y haga clic en Actualizar.

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

4. Elija la opción Actualización de proyecto en el lugar.

5. Elija un marco de trabajo objetivo

6. Haga clic en Actualizar selección.

7. El Asistente para actualización de .NET se ejecuta y usa la ventana de Visual Studio Output para mostrar información y 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 cuadro de diálogo de contenido y el selector para guardar archivos.
• 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 TODO en 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>net8.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>win-x86;win-x64;win-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 project ahora hace referencia al SDK de Aplicaciones para Windows, WinUI y .NET 6. Ahora que PhotoLab se ha migrado, puede aprovechar todas las nuevas características que las aplicaciones winUI tienen para ofrecer y aumentar la aplicación con la plataforma.

Además, el Asistente de actualización de .NET agrega analizadores al proyecto que ayudan a continuar con 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 la solución o el proyecto PhotoLab migrados y ver los cambios realizados en el código fuente. El project necesita un poco más trabajo para terminar de enlazar cosas antes de que la versión de WinUI se compile, ejecute y se comporte como la versión de UWP.

Consulte el Task List en Visual Studio (View>Task List) para toDOs que debe realizar manualmente para completar la migración.

Es posible que la versión de UWP (.NET Framework) de la aplicación contenga referencias de biblioteca que tu project no esté usando realmente. 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 raíz <Paquete>.

xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

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

3. 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 actualizaciones de .NET. En algunos casos, estos problemas se producen con la herramienta try-convert que el Asistente para actualización de .NET usa internamente.

Para obtener instrucciones actuales sobre cómo completar la migración manualmente, consulta Migrar de UWP a la SDK de Aplicaciones para Windows.

Consulte también

• SDK de Aplicaciones para Windows y versiones de Windows compatibles