Share via

Allgemeine Migrationsstrategie

  • Artikel

Einführung

Das Windows App SDK bietet eine breite Palette von Windows-APIs - mit Implementierungen, die vom Betriebssystem entkoppelt sind und für Entwickler über NuGet-Pakete freigegeben werden. Als Entwickler einer Universal Windows Platform (UWP)-Anwendung können Sie Ihre vorhandenen Fähigkeiten und Ihren Quellcode optimal nutzen, indem Sie Ihre Anwendung in das Windows App SDK verschieben.

Mit dem Windows App SDK können Sie die neuesten Laufzeit-, Sprach- und Plattformfunktionen in Ihre Anwendung einbinden. Da jede Anwendung anders ist, ebenso wie Ihre Anforderungen und Präferenzen, gibt es viele verschiedene Möglichkeiten, den Quellcode Ihrer Anwendung zu migrieren. Der Ansatz auf hoher Ebene und die Codeänderungen, die für verschiedene Funktionsbereiche erforderlich sind, sind jedoch ähnlich. In diesem Thema werden wir daher Strategien für die Migration Ihrer Anwendung sowie weitere Informationen (und Einschränkungen) zu bestimmten Funktionsbereichen vorstellen. Siehe auch Was wird bei der Portierung von UWP nach WinUI 3 unterstützt.

Die meisten Windows Runtime (WinRT) APIs können von Windows App SDK-Anwendungen verwendet werden. Es gibt jedoch einige, die in Desktop-Anwendungen nicht unterstützt werden oder Einschränkungen unterliegen.

  • APIs, die von Benutzeroberflächenfeatures abhängig sind, die nur für die Verwendung in UWP-Apps entwickelt wurden.
  • APIs, für die Paketidentität benötigt wird. Diese APIs werden nur in Desktop-Anwendungen unterstützt, die mit MSIX verpackt sind.

Für diese APIs zeigen wir Ihnen, welche Alternativen Sie verwenden können. Die meisten dieser Alternativen sind in der Windows UI Library (WinUI) oder über WinRT COM-Schnittstellen, die im Windows App SDK verfügbar sind, verfügbar.

Zum Beispiel werden wir bestimmte UI-Szenarien sehen, in denen Sie Ihr Hauptfensterobjekt verfolgen müssen, und verschiedene HWND-basierte APIs und Interoperationsmuster verwenden, wie IInitializeWithWindow::Initialize.

Hinweis

Siehe auch Windows Runtime APIs, die in Desktop-Anwendungen nicht unterstützt werden. Windows App SDK-Anwendungen sind eine Art von Desktop-Anwendungen. Andere Arten von Desktop-Anwendungen sind .NET-Desktop-Anwendungen und C/C++-Win32-Desktop-Anwendungen. Die Zielgruppe dieses Themas sind Entwickler, die auf irgendetwas in der Vereinigung dieser verschiedenen Arten von Desktop-Anwendungen migrieren möchten, einschließlich (aber nicht beschränkt auf) Windows App SDK-Anwendungen.

Wir würden uns über Ihr Feedback zu diesem Migrationsleitfaden und über Ihre eigenen Erfahrungen mit der Migration freuen. Benutzen Sie den Bereich Feedback am Ende dieser Seite wie folgt:

  • Für Fragen und Feedback zum Windows App SDK oder um eine Diskussion zu starten, verwenden Sie die Schaltfläche Dieses Produkt. Sie können auch eine Diskussion auf der Registerkarte Discussions des WindowsAppSDK GitHub-Repos starten. Über diese Kanäle können Sie uns auch mitteilen, welches Problem Sie zu lösen versuchen, wie Sie es bisher zu lösen versucht haben und was die ideale Lösung für Ihre Anwendung wäre.
  • Wenn Sie Hinweise auf fehlende oder falsche Informationen in diesem Migrationsleitfaden haben, verwenden Sie die Schaltfläche Diese Seite .

Warum auf das Windows App SDK migrieren?

Das Windows App SDK bietet Ihnen die Möglichkeit, Ihre App mit neuen Plattformfunktionen sowie der modernen Windows UI 3 Library (WinUI 3) zu erweitern, die entwickelt wurde, um Ihre Benutzer zu begeistern.

Darüber hinaus ist das Windows App SDK abwärtskompatibel; es unterstützt Apps bis zu Windows 10, Version 1809 (10.0; Build 17763) - auch bekannt als Windows 10 Oktober 2018 Update.

Der Nutzen der Verlagerung des Windows App SDK ist vielfältig. Hier einige Überlegungen dazu:

  • Die neueste Plattform für Benutzeroberflächen (UI) und Steuerelemente wie Windows UI Library (WinUI) 3 und WebView2.
  • Eine einzige API-Oberfläche für alle Desktop-App-Plattformen.
  • Häufigere Veröffentlichungen, die getrennt von Windows erscheinen.
  • Ein einheitliches Erlebnis für alle Windows-Versionen.
  • .NET-Kompatibilität.
  • Abwärtskompatibel bis zu Windows 10, Version 1809.
  • Verbesserte Laufzeitumgebung. Siehe MSIX-Container.

Weitere Informationen finden Sie unter Windows App SDK.

Übersicht über den Migrationsprozess

Hinweis

Sie können sich die UWP-Version der Anwendung, die Sie migrieren möchten, als die Quelle Lösung/Projekt vorstellen (es ist die Quelle des Migrationsprozesses). Die Windows App SDK-Version ist die Lösung target (es ist das target des Migrationsprozesses).

Installieren Sie das Windows App SDK VSIX

Laden Sie das Installationsprogramm für die Windows App SDK Visual Studio-Erweiterung (VSIX) vom Stable Release Channel für das Windows App SDK herunter, und führen Sie es aus, um es zu installieren.

Erstellen eines neuen Projekts

Erstellen Sie in Visual Studio Ihr erstes WinUI 3-Projekt. Verwenden Sie zum Beispiel die Projektvorlage Blank App, Packaged (WinUI 3 in Desktop). Sie finden diese Projektvorlage im Dialog Neues Projekt erstellen durch Auswahl der Sprache: C# oder C++; Plattform: Windows App SDK; Projekttyp: WinUI oder Desktop.

Im Projektmappen-Explorer sehen Sie zwei Projekte, von denen eines als (Desktop) und das andere als (Paket) bezeichnet wird.

Migrieren Sie zuerst den Code mit den geringsten Abhängigkeiten

Um diese Empfehlung zu veranschaulichen, nehmen wir die Fallstudie PhotoLab als Beispiel. Für die PhotoLab-Beispielanwendung könnte ein vielleicht naheliegender Ansatz darin bestehen, mit der Migration von MainPage zu beginnen, da dies ein so wichtiger und auffälliger Teil der Anwendung ist. Aber wenn wir das tun würden, dann würden wir bald feststellen, dass MainPage eine Abhängigkeit von der DetailPage Ansicht hat; und dann, dass DetailPage eine Abhängigkeit von dem Photo Modell hat. Wenn wir diesen Weg einschlagen würden, müssten wir uns ständig selbst unterbrechen (umschalten, um an jeder neu entdeckten Abhängigkeit zu arbeiten). Natürlich würden wir nicht erwarten, einen sauberen build zu bekommen, bevor wir nicht alle Abhängigkeiten aufgespürt und das gesamte Projekt in einem großen Sprung portiert haben.

Wenn wir dagegen mit dem Teil des Projekts beginnen, der von nichts anderem abhängt, und uns von dort aus vorarbeiten (vom am wenigsten abhängigen zum am meisten abhängigen Teil), dann können wir uns auf jeden Teil einzeln konzentrieren. Außerdem können wir nach der Migration eines jeden Teils einen sauberen Build erstellen und auf diese Weise sicherstellen, dass der Migrationsprozess planmäßig verläuft.

Wenn Sie also Ihre eigenen Anwendungen migrieren, empfehlen wir Ihnen, zuerst den Code mit den geringsten Abhängigkeiten zu migrieren.

Dateien kopieren oder Dateiinhalte kopieren?

Bei der Migration werden Sie natürlich die Dateien (und nicht die Inhalte der Datei ) kopieren. Aber was ist mit Quellcode-Dateien? Als Beispiel nehmen wir wieder die Klasse MainPage aus der Fallstudie PhotoLab und der Fallstudie Photo Editor.

C#. In der C#-Version (PhotoLab) besteht MainPage aus den Quellcode-Dateien MainPage.xaml und MainPage.xaml.cs.

C++/WinRT. In der C++/WinRT-Version (Photo Editor) besteht MainPage aus den Quellcode-Dateien MainPage.xaml, MainPage.idl, MainPage.h und MainPage.cpp.

Sie haben also die Wahl zwischen diesen beiden Optionen:

  • (Empfohlen) Sie können die Dateien selbst kopieren (mit File Explorer), und dann die Kopien zum Zielprojekt hinzufügen. Ausnahmen von dieser Empfehlung sind Dateien wie App.xaml und App.xaml.cs, da diese Dateien bereits im Zielprojekt vorhanden sind und sie Quellcode enthalten, der für das Windows App SDK spezifisch ist. Für diese müssen Sie zusammenführen den Quellcode, der bereits vorhanden ist, mit Quellcode aus dem Quellprojekt.
  • Oder Sie können Visual Studio verwenden, um neue Seite Dateien (wie MainPage.xaml und MainPage.xaml.cs) im Zielprojekt zu erstellen und dann die Inhalte dieser Quellcodedateien aus dem Quellprojekt in das Zielprojekt zu kopieren. Für ein C++/WinRT-Projekt erfordert diese Option wesentlich mehr Schritte.

Siehe auch den Abschnitt MainPage und MainWindow.

Unterschiede zwischen Ordnern und Dateinamen (C++/WinRT)

In einem C++/WinRT UWP-Projekt werden Code-Behind-Dateien für XAML-Ansichten in der Form MainPage.h und MainPage.cpp benannt. In einem C++/WinRT Windows App SDK müssen Sie diese jedoch in MainPage.xaml.h und MainPage.xaml.cpp umbenennen.

Wenn Sie in einem C++/WinRT UWP-Projekt eine hypothetische XAML-Ansicht (im Sinne von Modellen, Ansichten und Ansichtsmodellen) mit dem Namen MyPage migrieren, müssen Sie in MyPage.xaml.cpp unmittelbar nach #include "DetailPage.xaml.h"#include "MyPage.g.cpp" hinzufügen. Und für ein hypothetisches Modell mit dem Namen MyModel, fügen Sie in MyModel.cpp unmittelbar nach #include „MyModel.h“ #include "MyModel.g.cpp" hinzu. Ein Beispiel finden Sie unter Migrate DetailPage source code.

Wenn Sie den Namen Ihres migrierten Projekts ändern

Während der Migration können Sie dem Zielprojekt einen anderen Namen geben als dem Ausgangsprojekt. Wenn Sie dies tun, wirkt sich dies auf den Standard-Namespace im Quellprojekt aus. Wenn Sie den Quellcode aus dem Quellprojekt in das Zielprojekt kopieren, müssen Sie möglicherweise die Namen der Namespaces ändern, die im Quellcode erwähnt werden.

Das Ändern des Projektnamens (und folglich des Standard-Namespaces) ist etwas, das wir zum Beispiel in der Fallstudie Eine Windows App SDK-Migration der UWP PhotoLab-Beispielanwendung (C#) durchführen. In dieser Fallstudie werden nicht die Inhalte der Datei aus dem Quell- in das Zielprojekt kopiert, sondern ganze Dateien mit dem Datei-Explorer. Der Name des Quellprojekts/Namespaces ist PhotoLab, und der Name des Zielprojekts/Namespaces ist PhotoLabWinUI3. Wir müssen also nach PhotoLab in den Inhalten aller Quellcodedateien suchen, die wir kopiert haben, und diese in PhotoLabWinUI3 ändern

In dieser speziellen Fallstudie haben wir diese Änderungen in App.xaml, App.xaml.cs, MainPage.xaml, MainPage.xaml.cs, DetailPage.xaml, DetailPage.xaml.cs, ImageFileInfo.cs und LoadedImageBrush.cs vorgenommen.

Installieren Sie die gleichen NuGet-Pakete, die im Quellprojekt installiert wurden

Eine Aufgabe während des Migrationsprozesses besteht darin, alle NuGet-Pakete zu identifizieren, von denen das Quellprojekt abhängt. Und installieren Sie dann dieselben NuGet-Pakete im Zielprojekt.

In der Fallstudie Eine Windows App SDK-Migration der UWP PhotoLab-Beispielanwendung (C#) enthält das Quellprojekt beispielsweise Verweise auf das NuGet-Paket Microsoft.Graphics.Win2D. In dieser Fallstudie fügen wir also einen Verweis auf dasselbe NuGet-Paket in das Zielprojekt ein.