Migración de proyectos de UWP de Xamarin.Forms

Artículo
05/14/2024

Para actualizar el proyecto de UWP de Xamarin.Forms a un proyecto de WinUI 3, debe:

Actualizar el archivo de proyecto para que sea de estilo SDK.
Actualizar espacios de nombres
Solucionar cualquier cambio de API
Actualice o reemplace las dependencias incompatibles por versiones de .NET 8.
Compilar y probar la aplicación.

Actualización a un archivo de proyecto de estilo SDK

El proyecto de UWP de Xamarin.Forms existente se puede actualizar a un proyecto winUI 3 de estilo SDK. Un proyecto de estilo SDK para una aplicación .NET MAUI WinUI 3 es similar al ejemplo siguiente:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType> <!-- in Xamarin.Forms this was AppContainerExe -->
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RootNamespace>YOUR_NAMESPACE_HERE.WinUI</RootNamespace>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Platforms>x86;x64;ARM64</Platforms>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <UseMaui>true</UseMaui>
    <!-- We do not want XAML files to be processed as .NET MAUI XAML -->
    <EnableDefaultMauiItems>false</EnableDefaultMauiItems>
  </PropertyGroup>
  ...
</Project>

Importante

El moniker de la plataforma de destino (TFM) es lo que denota el proyecto como mediante .NET, en este caso .NET 8. Para obtener información sobre las plataformas de destino en proyectos de estilo SDK, consulte Plataformas de destino en proyectos de estilo SDK.

Debe agregar <UseMaui>true</UseMaui> al archivo de proyecto para habilitar la compatibilidad con .NET MAUI. Además, asegúrese de que ha agregado <EnableDefaultMauiItems>false</EnableDefaultMauiItems> al archivo del proyecto. De esta manera, dejará de recibir errores de compilación relativos al método InitializeComponent que ya se está definiendo.

Cambios en las propiedades de MSBuild

Al actualizar el proyecto, se recomienda quitar las siguientes propiedades de MSBuild para UWP del archivo del proyecto:

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

También deberá asegurarse de que las arquitecturas de plataforma del proyecto de destino se especifican con los siguientes identificadores de tiempo de ejecución de .NET:

<PropertyGroup>
   <!-- Used in .NET MAUI WinUI projects -->
   <Platforms>x86;x64;ARM64</Platforms>
</PropertyGroup>

Para obtener más información sobre los los identificadores de entorno de ejecución, consulte el Catálogo de identificadores de entorno de ejecución (RID) de .NET.

Cambios en el espacio de nombres

Existen diferencias en los nombres de los espacios de nombres entre UWP y WinUI 3. En muchos casos, es tan fácil como cambiar un nombre de espacio de nombres y, a continuación, el código se compilará. Por ejemplo, deberá reemplazar el Windows.UI.Xaml espacio de nombres por el Microsoft.UI.Xaml espacio de nombres . Del mismo modo, deberá reemplazar el Windows.UI.Xaml.Controls espacio de nombres por el Microsoft.UI.Xaml.Controls espacio de nombres .

Otras veces, la asignación tarda un poco más en funcionar y, en raras ocasiones, requiere un cambio en el enfoque. Para obtener más información, consulta Asignación de api y bibliotecas para UWP a la SDK de Aplicaciones para Windows.

Cambios de API

Deberá solucionar los cambios de API que puedan afectar a la aplicación. Por ejemplo, algunos tipos, métodos y propiedades pueden haberse cambiado de nombre, en desuso o quitados. Para obtener información sobre lo que se admite al actualizar el proyecto de UWP a WinUI 3, consulta ¿Qué se admite al migrar de UWP a WinUI 3? Para obtener información sobre cómo asignar características y API de UWP a WinUI 3, consulta Asignación de características de UWP a las API y bibliotecas de UWP de SDK de Aplicaciones para Windows y asignación de bibliotecas a la SDK de Aplicaciones para Windows.

El proyecto se puede hacer compatible con versiones anteriores del sistema operativo estableciendo la propiedad en el $(SupportedOSPlatformVersion) archivo del proyecto:

<PropertyGroup>
   <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

La propiedad $(SupportedOSPlatformVersion) indica la versión mínima del sistema operativo necesaria para ejecutar la aplicación o la biblioteca. Si no especifica explícitamente esta versión mínima del sistema operativo en tiempo de ejecución en el proyecto, el valor predeterminado es la versión de la plataforma del Moniker de la plataforma de destino (TFM).

Si el proyecto solo tiene como destino Windows, es suficiente omitir la condición de comprobación de la plataforma y establecer la $(SupportedOSPlatformVersion) propiedad directamente:

<PropertyGroup>
   <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

Para obtener más información sobre la $(SupportedOSPlatformVersion) propiedad , consulte Compatibilidad con versiones anteriores del sistema operativo.

Para que una aplicación se ejecute correctamente en una versión anterior del sistema operativo, no puede llamar a las API que no existen en esa versión del sistema operativo. Sin embargo, puede agregar medidas de protección en torno a las llamadas a las API más recientes para que solo se llamen cuando se ejecuten en una versión del sistema operativo que las admita. Esto se puede lograr con el IsWindowsVersionAtLeast método :

if (OperatingSystem.IsWindowsVersionAtLeast(10))
{
    // Use the API here
}

Quitar archivos

Los siguientes archivos, que están presentes en proyectos de UWP de Xamarin.Forms, no existen en proyectos de WinUI 3:

MainPage.xaml y MainPage.xaml.cs
Assemblyinfo.cs
Default.rd.xml

Por lo tanto, debe quitar estos archivos si están en el proyecto de WinUI 3. Cualquier lógica de negocios necesaria contenida en estos archivos debe moverse en otro lugar.

Cambios en Package.appxmanifest

Los siguientes cambios deben realizarse en el archivo Package.appxmanifest del proyecto migrado:

Establezca el punto $targetentrypoint$ de entrada de la aplicación en . Para obtener más información, vea Punto de entrada de destino.
Agregue la runFullTrust funcionalidad. Para obtener más información, consulte Ejecución de la funcionalidad de plena confianza.
Agregue las Windows.Universal familias de dispositivos y Windows.Desktop de destino. Para obtener más información, consulte Familia de dispositivos de destino universal y Familia de dispositivos de destino de escritorio.

Al realizar estos cambios, se corrigen errores de implementación comunes para la aplicación en Windows.

Para obtener un ejemplo de un archivo Package.appxmanifest compatible, consulta Package.appxmanifest.

Comportamiento de tiempo de ejecución

Hay cambios de comportamiento en el método String.IndexOf() en .NET 5+ en distintas plataformas. Para obtener más información, consulte Globalización de .NET e ICU.

Pasos siguientes

Arranque de la aplicación

Compartir a través de