Freigeben über

Xamarin.Forms UWP-Projektmigration

  • Artikel

Um Ihr Xamarin.Forms UWP-Projekt auf ein WinUI 3-Projekt zu aktualisieren, sollten Sie:

  • Aktualisieren Sie Ihre Projektdatei auf SDK-Format.
  • Aktualisieren von Namespaces
  • Behandeln von API-Änderungen
  • Aktualisieren oder ersetzen Sie inkompatible Abhängigkeiten durch .NET 8-Versionen.
  • Kompilieren und Testen Der App.

Aktualisieren auf eine PROJEKTdatei im SDK-Stil

Ihr vorhandenes Xamarin.Forms UWP-Projekt kann auf ein winUI 3-Projekt im SDK-Stil aktualisiert werden. Ein SDK-Formatprojekt für eine .NET MAUI WinUI 3-App ähnelt dem folgenden Beispiel:

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

Wichtig

Der Zielframework-Moniker (TFM) bezeichnet das Projekt als .NET, in diesem Fall .NET 8. Informationen zu Zielframeworks in SDK-Formatprojekten finden Sie unter Target Frameworks in SDK-Formatprojekten.

Sie müssen Ihrer Projektdatei hinzufügen <UseMaui>true</UseMaui> , um die .NET MAUI-Unterstützung zu aktivieren. Stellen Sie außerdem sicher, dass Sie der Projektdatei hinzugefügt <EnableDefaultMauiItems>false</EnableDefaultMauiItems> haben. Dadurch erhalten Sie keine Buildfehler mehr über die InitializeComponent bereits definierte Methode.

Änderungen an MSBuild-Eigenschaften

Beim Aktualisieren des Projekts wird empfohlen, die folgenden UWP MSBuild-Eigenschaften aus der Projektdatei zu entfernen:

  • WindowsXamlEnableOverview
  • AppxPackageSigningEnabled
  • GenerateAssemblyInfo

Außerdem müssen Sie sicherstellen, dass die Plattformarchitekturen im Zielprojekt mit den folgenden .NET-Laufzeit-IDs angegeben werden:

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

Weitere Informationen zu Runtimebezeichnern finden Sie unter .NET-RID-Katalog.

Namespaceänderungen

Es gibt Unterschiede bei den Namen von Namespaces zwischen UWP und WinUI 3. In vielen Fällen ist es so einfach wie das Ändern eines Namespacenamens, und ihr Code wird kompiliert. Beispielsweise müssen Sie den Windows.UI.Xaml Namespace durch den Microsoft.UI.Xaml Namespace ersetzen. Ebenso müssen Sie den Windows.UI.Xaml.Controls Namespace durch den Microsoft.UI.Xaml.Controls Namespace ersetzen.

In anderen Fällen dauert die Zuordnung etwas mehr Arbeit, und in seltenen Fällen ist eine Änderung des Ansatzes erforderlich. Weitere Informationen finden Sie unter Zuordnen von UWP-APIs und -Bibliotheken zum Windows App SDK.

API-Änderungen

Sie müssen alle API-Änderungen behandeln, die sich auf Ihre App auswirken können. Beispielsweise wurden einige Typen, Methoden und Eigenschaften möglicherweise umbenannt, veraltet oder entfernt. Informationen dazu, was beim Upgrade Ihres UWP-Projekts auf WinUI 3 unterstützt wird, finden Sie unter "Was wird bei der Migration von UWP zu WinUI 3 unterstützt". Informationen zum Zuordnen von UWP-Features und APIs zu WinUI 3 finden Sie unter Zuordnen von UWP-Features zum Windows App SDK und zum Zuordnen von UWP-APIs und -Bibliotheken zum Windows App SDK.

Ihr Projekt kann mit früheren Betriebssystemversionen kompatibel gemacht werden, indem die $(SupportedOSPlatformVersion) Eigenschaft in der Projektdatei festgelegt wird:

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

Die Eigenschaft $(SupportedOSPlatformVersion) gibt die Betriebssystemversion an, die zum Ausführen Ihrer App oder Bibliothek mindestens erforderlich ist. Wenn Sie diese Mindestlaufzeit-Betriebssystemversion in Ihrem Projekt nicht explizit angeben, wird standardmäßig die Plattformversion aus dem Target Framework Moniker (TFM) verwendet.

Wenn Ihr Projekt nur auf Windows ausgerichtet ist, reicht es aus, die Plattformüberprüfungsbedingung auszulassen und die $(SupportedOSPlatformVersion) Eigenschaft direkt festzulegen:

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

Weitere Informationen zur $(SupportedOSPlatformVersion) Eigenschaft finden Sie unter Unterstützen älterer Betriebssystemversionen.

Damit eine App ordnungsgemäß auf einer älteren Betriebssystemversion ausgeführt wird, kann sie keine APIs aufrufen, die in dieser Version des Betriebssystems nicht vorhanden sind. Sie können jedoch Wächter für Aufrufe neuerer APIs hinzufügen, sodass die APIs nur aufgerufen werden, wenn sie in einer Version des Betriebssystems ausgeführt werden, die sie unterstützt. Dies kann mit der IsWindowsVersionAtLeast Methode erreicht werden:

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

Dateien entfernen

Die folgenden Dateien, die in Xamarin.Forms UWP-Projekten vorhanden sind, sind in WinUI 3-Projekten nicht vorhanden:

  • MainPage.xaml und MainPage.xaml.cs
  • Assemblyinfo.cs
  • Default.rd.xml

Daher sollten Sie diese Dateien entfernen, wenn sie sich in Ihrem WinUI 3-Projekt befinden. Alle erforderlichen Geschäftslogiken, die in diesen Dateien enthalten sind, sollten an eine andere Stelle verschoben werden.

Änderungen an Package.appxmanifest

Die folgenden Änderungen müssen an der Datei "Package.appxmanifest" des migrierten Projekts vorgenommen werden:

  1. Legen Sie den Einstiegspunkt der Anwendung auf $targetentrypoint$. Weitere Informationen finden Sie unter "Zieleinstiegspunkt".
  2. Fügen Sie die runFullTrust Funktion hinzu. Weitere Informationen finden Sie unter "Voll vertrauenswürdige Funktion ausführen".
  3. Fügen Sie die Windows.Universal Gerätefamilien und Windows.Desktop die Zielgerätefamilien hinzu. Weitere Informationen finden Sie unter Universelle Zielgerätefamilie und Desktopzielgerätefamilie.

Wenn Sie diese Änderungen vornehmen, werden häufige Bereitstellungsfehler für Ihre App unter Windows behoben.

Ein Beispiel für eine kompatible Package.appxmanifest-Datei finden Sie unter "Package.appxmanifest".

Laufzeitverhalten

Es gibt Verhaltensänderungen an der String.IndexOf() Methode in .NET 5+ auf verschiedenen Plattformen. Weitere Informationen finden Sie unter .NET-Globalisierung und ICU.

Nächste Schritte

Bootstrap ihrer App

Siehe auch