Migration de projet UWP Xamarin.Forms

Article
05/14/2024

Pour mettre à jour votre projet UWP Xamarin.Forms vers un projet WinUI 3, vous devez :

Mettez à jour votre fichier projet de façon à ce qu’il soit de style SDK.
Mettre à jour les espaces de noms
Résoudre les modifications apportées à l’API
Mettez à jour ou remplacez les dépendances incompatibles par les versions de .NET 8.
Compilez et testez votre application.

Mise à jour vers un fichier projet de style SDK

Votre projet UWP Xamarin.Forms existant peut être mis à jour vers un projet WinUI 3 de style SDK en place. Un projet de style SDK pour une application .NET MAUI WinUI 3 est similaire à l’exemple suivant :

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

Important

Le moniker de framework cible (TFM) désigne le projet comme utilisant .NET, dans ce cas .NET 8. Pour plus d’informations sur les frameworks cibles dans les projets de style SDK, consultez Frameworks cibles dans les projets de style SDK.

Vous devez ajouter <UseMaui>true</UseMaui> à votre fichier projet pour activer la prise en charge de .NET MAUI. En outre, vérifiez que vous avez ajouté <EnableDefaultMauiItems>false</EnableDefaultMauiItems> au fichier projet. Cela vous empêche de recevoir des erreurs de build sur la InitializeComponent méthode déjà définie.

Modifications apportées aux propriétés MSBuild

Lors de la mise à niveau de votre projet, il est recommandé de supprimer les propriétés MSBuild UWP suivantes de votre fichier projet :

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

Vous devez également vous assurer que les architectures de plateforme dans le projet cible sont spécifiées avec les identificateurs de runtime .NET suivants :

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

Pour plus d’informations sur les identificateurs d’exécution, consultez le catalogue RID .NET.

Modifications de l’espace de noms

Il existe des différences dans les noms d’espaces de noms entre UWP et WinUI 3. Dans de nombreux cas, il est aussi simple que de modifier un nom d’espace de noms, puis votre code est compilé. Par exemple, vous devez remplacer l’espace Windows.UI.Xaml de noms par l’espace Microsoft.UI.Xaml de noms. De même, vous devez remplacer l’espace Windows.UI.Xaml.Controls de noms par l’espace Microsoft.UI.Xaml.Controls de noms.

D’autres fois, le mappage prend un peu plus de travail et, dans de rares cas, nécessite un changement d’approche. Pour plus d’informations, consultez Mappage des API et bibliothèques UWP au Kit de développement logiciel (SDK) d’application Windows.

Modifications d'API

Vous devrez résoudre les modifications d’API susceptibles d’affecter votre application. Par exemple, certains types, méthodes et propriétés peuvent avoir été renommés, déconseillés ou supprimés. Pour plus d’informations sur les éléments pris en charge lors de la mise à niveau de votre projet UWP vers WinUI 3, consultez Ce qui est pris en charge lors de la migration d’UWP vers WinUI 3. Pour plus d’informations sur le mappage des fonctionnalités et API UWP à WinUI 3, consultez Mappage des fonctionnalités UWP au SDK d’application Windows et mappage des API et bibliothèques UWP au SDK d’application Windows.

Votre projet peut être compatible avec les versions antérieures du système d’exploitation en définissant la $(SupportedOSPlatformVersion) propriété dans votre fichier projet :

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

La propriété $(SupportedOSPlatformVersion) indique la version minimale du système d’exploitation requise pour exécuter votre application ou bibliothèque. Si vous ne spécifiez pas explicitement cette version minimale du système d’exploitation runtime dans votre projet, elle est par défaut la version de la plateforme à partir du moniker du framework cible (TFM).

Si votre projet cible uniquement Windows, il est suffisant d’omettre la plateforme case activée condition de configuration et de définir la $(SupportedOSPlatformVersion) propriété directement :

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

Pour plus d’informations sur la $(SupportedOSPlatformVersion) propriété, consultez Prise en charge des versions antérieures du système d’exploitation.

Pour qu’une application s’exécute correctement sur une version antérieure du système d’exploitation, elle ne peut pas appeler d’API qui n’existent pas sur cette version du système d’exploitation. Toutefois, vous pouvez ajouter des protections aux appels à des API plus récentes pour qu’elles soient appelées uniquement en cas d’exécution sur une version du système d’exploitation qui les prend en charge. Pour ce faire, procédez comme IsWindowsVersionAtLeast suit :

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

Supprimer les fichiers

Les fichiers suivants, présents dans les projets UWP Xamarin.Forms, n’existent pas dans les projets WinUI 3 :

MainPage.xaml et MainPage.xaml.cs
AssemblyInfo.cs
Default.rd.xml

Par conséquent, vous devez supprimer ces fichiers s’ils se trouvent dans votre projet WinUI 3. Toute logique métier requise contenue dans ces fichiers doit être déplacée ailleurs.

Modifications apportées à Package.appxmanifest

Les modifications suivantes doivent être apportées au fichier Package.appxmanifest de votre projet migré :

Définissez le point d’entrée de l’application sur $targetentrypoint$ . Pour plus d’informations, consultez Le point d’entrée cible.
Ajoutez la runFullTrust fonctionnalité. Pour plus d’informations, consultez Exécuter la fonctionnalité d’approbation totale.
Ajoutez les familles d’appareils cibles et Windows.Desktop les familles d’appareils Windows.Universal cibles. Pour plus d’informations, consultez la famille d’appareils cibles universelle et la famille d’appareils cibles de bureau.

L’exécution de ces modifications corrige les erreurs de déploiement courantes pour votre application sur Windows.

Pour obtenir un exemple de fichier Package.appxmanifest conforme, consultez Package.appxmanifest.

Comportement du runtime

Il existe des modifications comportementales apportées à la String.IndexOf() méthode dans .NET 5+ sur différentes plateformes. Pour plus d’informations, consultez Globalisation et ICU .NET.

Étapes suivantes

Démarrage de votre application

Partager via