Migrazione del progetto UWP Xamarin.Forms

Articolo
05/14/2024

Per aggiornare il progetto UWP Xamarin.Forms a un progetto WinUI 3, è necessario:

Aggiornare il file di progetto in modo che sia in stile SDK.
Aggiornare gli spazi dei nomi
Risolvere eventuali modifiche all'API
Aggiornare o sostituire dipendenze incompatibili con le versioni di .NET 8.
Compilare e testare l'app.

Eseguire l'aggiornamento a un file di progetto in stile SDK

Il progetto UWP Xamarin.Forms esistente può essere aggiornato a un progetto WinUI 3 in stile SDK. Un progetto in stile SDK per un'app WinUI 3 .NET MAUI è simile all'esempio seguente:

<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

Il moniker del framework di destinazione (TFM) indica il progetto come usando .NET, in questo caso .NET 8. Per informazioni sui framework di destinazione nei progetti in stile SDK, vedere Framework di destinazione nei progetti in stile SDK.

È necessario aggiungere <UseMaui>true</UseMaui> al file di progetto per abilitare il supporto DI MAUI .NET. Assicurarsi inoltre di aver aggiunto <EnableDefaultMauiItems>false</EnableDefaultMauiItems> al file di progetto. In questo modo si interrompe la ricezione di errori di compilazione relativi al InitializeComponent metodo già definito.

Modifiche alle proprietà di MSBuild

Durante l'aggiornamento del progetto, è consigliabile rimuovere le proprietà MSBuild UWP seguenti dal file di progetto:

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

È anche necessario assicurarsi che le architetture della piattaforma nel progetto di destinazione siano specificate con gli identificatori di runtime .NET seguenti:

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

Per altre informazioni sugli identificatori di runtime, vedere Catalogo RID .NET.

Modifiche dello spazio dei nomi

Esistono differenze nei nomi degli spazi dei nomi tra UWP e WinUI 3. In molti casi è facile modificare un nome di spazio dei nomi e quindi il codice verrà compilato. Ad esempio, sarà necessario sostituire lo Windows.UI.Xaml spazio dei nomi con lo spazio dei Microsoft.UI.Xaml nomi . Analogamente, sarà necessario sostituire lo Windows.UI.Xaml.Controls spazio dei nomi con lo spazio dei Microsoft.UI.Xaml.Controls nomi .

In altri casi, il mapping richiede un po' più di lavoro e in rari casi richiede un cambiamento nell'approccio. Per altre informazioni, vedi Mapping di API e librerie UWP alle SDK per app di Windows.

Modifiche API

Dovrai risolvere eventuali modifiche all'API che potrebbero influire sull'app. Ad esempio, alcuni tipi, metodi e proprietà possono essere stati rinominati, deprecati o rimossi. Per informazioni su cosa è supportato durante l'aggiornamento del progetto UWP a WinUI 3, vedi Cosa è supportato durante la migrazione da UWP a WinUI 3. Per informazioni sul mapping delle funzionalità e delle API UWP a WinUI 3, vedi Mapping delle funzionalità UWP ai SDK per app di Windows e Mapping di API e librerie UWP alle SDK per app di Windows.

Il progetto può essere reso compatibile con le versioni precedenti del sistema operativo impostando la $(SupportedOSPlatformVersion) proprietà nel file di progetto:

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

La $(SupportedOSPlatformVersion) proprietà indica la versione minima del sistema operativo necessaria per eseguire l'app o la libreria. Se non si specifica in modo esplicito questa versione minima del sistema operativo di runtime nel progetto, per impostazione predefinita viene impostata la versione della piattaforma dal moniker framework di destinazione (TFM).

Se il progetto è destinato solo a Windows, è sufficiente omettere la condizione di controllo della piattaforma e impostare la $(SupportedOSPlatformVersion) proprietà direttamente:

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

Per altre informazioni sulla proprietà, vedere Supportare le versioni precedenti del $(SupportedOSPlatformVersion) sistema operativo.

Perché un'app venga eseguita correttamente in una versione precedente del sistema operativo, non può chiamare API che non esistono in tale versione del sistema operativo. Tuttavia, è possibile aggiungere guardie intorno alle chiamate alle API più recenti in modo che vengano chiamate solo quando sono in esecuzione in una versione del sistema operativo che li supporta. Questa operazione può essere ottenuta con il IsWindowsVersionAtLeast metodo :

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

Rimuovere i file

I file seguenti, presenti nei progetti UWP Xamarin.Forms, non esistono nei progetti WinUI 3:

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

Pertanto, è consigliabile rimuovere questi file se si trovano nel progetto WinUI 3. Qualsiasi logica di business necessaria contenuta in questi file deve essere spostata altrove.

Modifiche apportate a Package.appxmanifest

Le modifiche seguenti devono essere apportate al file Package.appxmanifest del progetto migrato:

Impostare il punto di ingresso dell'applicazione su $targetentrypoint$ . Per altre informazioni, vedere Punto di ingresso di destinazione.
Aggiungere la runFullTrust funzionalità . Per altre informazioni, vedere Eseguire la funzionalità di attendibilità completa.
Aggiungere le famiglie di Windows.Universal dispositivi e Windows.Desktop di destinazione. Per altre informazioni, vedere Famiglia di dispositivi di destinazione universale e Famiglia di dispositivi di destinazione desktop.

L'esecuzione di queste modifiche consente di correggere gli errori di distribuzione comuni per l'app in Windows.

Per un esempio di file Package.appxmanifest conforme, vedere Package.appxmanifest.

Comportamento di runtime

Esistono modifiche comportamentali al String.IndexOf() metodo in .NET 5+ su piattaforme diverse. Per altre informazioni, vedere Globalizzazione .NET e ICU.

Passaggi successivi

Bootstrap dell'app

Condividi tramite