Portieren eines Windows-Runtime 8.x-Projekts zu einem UWP-Projekt

  • Artikel

Sie haben zwei Optionen, wenn Sie mit dem Portierungsprozess beginnen. Eine Kopie Ihrer vorhandenen Projektdateien, einschließlich des App-Paketmanifests (für diese Option, finden Sie unter den Informationen zum Aktualisieren Ihrer Projektdateien in "Migrieren von Apps auf die Universelle Windows-Plattform (UWP)"). Die andere Option besteht darin, ein neues Windows 10-Projekt in Visual Studio zu erstellen und Ihre Dateien darin zu kopieren. Im ersten Abschnitt in diesem Thema wird die zweite Option beschrieben, der Rest des Themas enthält jedoch zusätzliche Informationen, die für beide Optionen gelten. Sie können auch auswählen, dass Ihr neues Windows 10-Projekt in derselben Projektmappe wie Ihre vorhandenen Projekte beibehalten und Quellcodedateien mithilfe eines freigegebenen Projekts freigegeben werden. Alternativ können Sie das neue Projekt in einer Eigenen Projektmappe beibehalten und Quellcodedateien mithilfe des Features für verknüpfte Dateien in Visual Studio freigeben.

Erstellen des Projekts und Kopieren von Dateien in das Projekt

Diese Schritte konzentrieren sich auf die Option, ein neues Windows 10-Projekt in Visual Studio zu erstellen und Ihre Dateien darin zu kopieren. Einige der Einzelheiten dazu, wie viele Projekte Sie erstellen und welche Dateien Sie kopieren, hängen von den Faktoren und Entscheidungen ab, die in der Universellen 8.1-App und den folgenden Abschnitten beschrieben werden. Bei diesen Schritten wird der einfachste Fall vorausgesetzt.

  1. Starten Sie Microsoft Visual Studio 2015, und erstellen Sie ein neues Projekt für leere Anwendungen (Windows Universal). Weitere Informationen finden Sie unter Jumpstart your Windows-Runtime 8.x app using templates (C#, C++, Visual Basic).For more info, see Jumpstart your Windows-Runtime 8.x app using templates (C#, C++, Visual Basic). Das neue Projekt erstellt ein App-Paket (eine AppX-Datei), das auf allen Gerätefamilien ausgeführt wird.
  2. Identifizieren Sie in Ihrem Universellen 8.1-App-Projekt alle Quellcodedateien und visuellen Ressourcendateien, die Sie wiederverwenden möchten. Kopieren Sie mithilfe von Explorer Datenmodelle, Ansichtsmodelle, visuellen Ressourcen, Ressourcenverzeichnissen, Ordnerstruktur und allen anderen Elementen, die Sie wiederverwenden möchten, in Ihr neues Projekt. Kopieren oder erstellen Sie nach Bedarf Unterordner auf dem Datenträger.
  3. Kopieren Sie auch Ansichten (z. B. "MainPage.xaml" und "MainPage.xaml.cs") in das neue Projekt. Erstellen Sie bei Bedarf neue Unterordner, und entfernen Sie die vorhandenen Ansichten aus dem Projekt. Bevor Sie jedoch eine von Visual Studio generierte Ansicht überschreiben oder entfernen, behalten Sie eine Kopie bei, da sie später nützlich sein kann. Die erste Phase der Portierung einer universellen 8.1-App konzentriert sich darauf, dass sie gut aussieht und auf einer Gerätefamilie gut funktioniert. Später wenden Sie sich an Ihre Aufmerksamkeit, um sicherzustellen, dass sich die Ansichten gut an alle Formfaktoren anpassen, und optional alle adaptiven Code hinzufügen, um die optimale Nutzung von einer bestimmten Gerätefamilie zu erzielen.
  4. Vergewissern Sie sich im Projektmappen-Explorer, dass Alle Dateien anzeigen aktiviert ist. Wählen Sie die kopierten Dateien aus, klicken Sie mit der rechten Maustaste darauf, und klicken Sie dann auf "In Projekt einschließen". Dies schließt automatisch deren enthaltenden Ordner ein. Sie können dann bei Bedarf die Option "Alle Dateien anzeigen" deaktivieren. Wenn Sie es vorziehen, verwenden Sie den Befehl "Vorhandenes Element hinzufügen", nachdem Sie alle erforderlichen Unterordner in Visual Studio Projektmappen-Explorer erstellt haben. Überprüfen Sie, ob ihre visuellen Ressourcen "Buildaktion" auf "Inhalt" und "In Ausgabeverzeichnis kopieren" auf "Nicht kopieren" festgelegt haben.
  5. In dieser Phase werden wahrscheinlich einige Buildfehler angezeigt. Wenn Sie aber wissen, was Sie ändern müssen, können Sie den Befehl "Suchen und Ersetzen" von Visual Studio verwenden, um Massenänderungen an Ihrem Quellcode vorzunehmen. Verwenden Sie im imperativen Code-Editor in Visual Studio die Befehle "Auflösen und Organisieren von Verwendungen" im Kontextmenü, um gezieltere Änderungen vorzunehmen.

Maximieren der Wiederverwendung von Markup und Code

Sie werden feststellen, dass Die Umgestaltung ein wenig und/oder das Hinzufügen von adaptivem Code (siehe unten) ermöglicht Es Ihnen, das Markup und den Code zu maximieren, der in allen Gerätefamilien funktioniert. Hier sind weitere Details.

  • Dateien, die für alle Gerätefamilien gemeinsam sind, benötigen keine besondere Berücksichtigung. Diese Dateien werden von der App auf allen Gerätefamilien verwendet, auf denen sie ausgeführt wird. Dazu gehören XAML-Markupdateien, imperative Quellcodedateien und Objektdateien.
  • Es ist möglich, dass Ihre App die Gerätefamilie erkennt, auf der sie ausgeführt wird, und zu einer Ansicht navigieren, die speziell für diese Gerätefamilie entwickelt wurde. Weitere Informationen finden Sie unter Erkennen der Plattform, auf der Ihre App ausgeführt wird.
  • Eine ähnliche Technik, die Sie möglicherweise hilfreich finden, wenn keine Alternative vorhanden ist, wird eine Markupdatei oder eine ResourceDictionary-Datei (oder der Ordner, der die Datei enthält) einen speziellen Namen geben, sodass sie zur Laufzeit nur dann automatisch geladen wird, wenn Ihre App auf einer bestimmten Gerätefamilie ausgeführt wird. Diese Technik wird in der Fallstudie Bookstore1 veranschaulicht.
  • Sie sollten in der Lage sein, viele der Richtlinien für die bedingte Kompilierung im Quellcode Ihrer universellen 8.1-App zu entfernen, wenn Sie nur Windows 10 unterstützen müssen. Siehe Bedingte Kompilierung und adaptiver Code in diesem Thema.
  • Um Features zu verwenden, die nicht für alle Gerätefamilien verfügbar sind (z. B. Drucker, Scanner oder kamerataste), können Sie adaptiven Code schreiben. Weitere Informationen finden Sie im dritten Beispiel in der bedingten Kompilierung und im adaptiven Code in diesem Thema.
  • Wenn Sie Windows 8.1, Windows Phone 8.1 und Windows 10 unterstützen möchten, können Sie drei Projekte in derselben Lösung beibehalten und Code für ein freigegebenes Projekt freigeben. Alternativ können Sie Quellcodedateien zwischen Projekten freigeben. So geht's: Klicken Sie in Visual Studio mit der rechten Maustaste auf das Projekt in Projektmappen-Explorer, wählen Sie "Vorhandenes Element hinzufügen", wählen Sie die freizugebenden Dateien aus, und klicken Sie dann auf "Als Link hinzufügen". Speichern Sie Ihre Quellcodedateien in einem gemeinsamen Ordner im Dateisystem, in dem die Projekte, die mit ihnen verknüpft sind, diese sehen können. Und vergessen Sie nicht, sie zur Quellcodeverwaltung hinzuzufügen.
  • Informationen zur Wiederverwendung auf binärer Ebene anstelle der Quellcodeebene finden Sie unter Erstellen Windows-Runtime Komponenten in C# und Visual Basic. Es gibt auch portable Klassenbibliotheken, die die Teilmenge von .NET-APIs unterstützen, die in .NET Framework für Windows 8.1, Windows Phone 8.1 und Windows 10-Apps (.NET Core) und im vollständigen .NET Framework verfügbar sind. Portable Klassenbibliothekassemblys sind binärkompatibel mit all diesen Plattformen. Verwenden Sie Visual Studio, um ein Projekt zu erstellen, das auf eine portable Klassenbibliothek ausgerichtet ist. Siehe plattformübergreifende Entwicklung mit der portablen Klassenbibliothek.

Erweiterungs-SDKs

Die meisten Windows-Runtime APIs, die Ihre Universelle 8.1-App bereits aufruft, werden in der Gruppe der APIs implementiert, die als universelle Gerätefamilie bezeichnet werden. Einige werden jedoch in Erweiterungs-SDKs implementiert, und Visual Studio erkennt nur APIs, die von der Zielgerätefamilie Ihrer App oder von Erweiterungs-SDKs implementiert werden, auf die Verwiesen wird.

Wenn Sie Kompilierungsfehler zu Namespaces oder Typen oder Membern erhalten, die nicht gefunden werden konnten, ist dies wahrscheinlich die Ursache. Öffnen Sie das Thema der API in der API-Referenzdokumentation, und navigieren Sie zum Abschnitt "Anforderungen": Sie erfahren, was die implementierungsbezogene Gerätefamilie ist. Wenn dies nicht Ihre Zielgerätefamilie ist, benötigen Sie einen Verweis auf das Erweiterungs-SDK für diese Gerätefamilie, um die API für Ihr Projekt verfügbar zu machen.

Klicken Sie auf Project>Add Reference>Windows Universal>Extensions, und wählen Sie das entsprechende Erweiterungs-SDK aus. Wenn beispielsweise die APIs, die Sie aufrufen möchten, nur in der Familie mobiler Geräte verfügbar sind und sie in Version 10.0.x.y eingeführt wurden, wählen Sie windows Mobile-Erweiterungen für die UWP aus.

Dadurch wird der Projektdatei der folgende Verweis hinzugefügt:

<ItemGroup>
    <SDKReference Include="WindowsMobile, Version=10.0.x.y">
        <Name>Windows Mobile Extensions for the UWP</Name>
    </SDKReference>
</ItemGroup>

Der Name und die Versionsnummer stimmen mit den Ordnern am installierten Speicherort Ihres SDK überein. Die obigen Informationen entsprechen z. B. diesem Ordnernamen:

\Program Files (x86)\Windows Kits\10\Extension SDKs\WindowsMobile\10.0.x.y

Sofern Ihre App nicht auf die Gerätefamilie abzielt, die die API implementiert, müssen Sie die ApiInformation-Klasse verwenden, um das Vorhandensein der API zu testen, bevor Sie sie aufrufen (dies wird als adaptiver Code bezeichnet). Diese Bedingung wird dann überall ausgewertet, wo Ihre App ausgeführt wird. Sie wird jedoch nur auf Geräten ausgewertet, auf denen die API vorhanden ist und daher zum Aufrufen verfügbar ist. Verwenden Sie Erweiterungs-SDKs und adaptiven Code erst, nachdem Sie überprüft haben, ob eine universelle API vorhanden ist. Einige Beispiele finden Sie im folgenden Abschnitt.

Siehe auch das App-Paketmanifest.

Bedingte Kompilierung und adaptiver Code

Wenn Sie die bedingte Kompilierung (mit C#-Präprozessordirektiven) verwenden, damit Ihre Codedateien sowohl unter Windows 8.1 als auch unter Windows Phone 8.1 funktionieren, können Sie nun die bedingte Kompilierung anhand der Konvergenzarbeiten in Windows 10 überprüfen. Konvergenz bedeutet, dass einige Bedingungen in Ihrer Windows 10-App vollständig entfernt werden können. Andere ändern sich in Laufzeitprüfungen, wie in den folgenden Beispielen gezeigt.

Hinweis : Wenn Sie Windows 8.1, Windows Phone 8.1 und Windows 10 in einer einzigen Codedatei unterstützen möchten, können Sie dies auch tun. Wenn Sie in Ihrem Windows 10-Projekt auf den Projekteigenschaftenseiten suchen, sehen Sie, dass das Projekt WINDOWS_UAP als Symbol für die bedingte Kompilierung definiert. Sie können dies also in Kombination mit WINDOWS_APP und WINDOWS_PHONE_APP verwenden. Diese Beispiele zeigen den einfacheren Fall, die bedingte Kompilierung aus einer universellen 8.1-App zu entfernen und den entsprechenden Code für eine Windows 10-App zu ersetzen.

Dieses erste Beispiel zeigt das Verwendungsmuster für die PickSingleFileAsync-API (gilt nur für Windows 8.1) und die PickSingleFileAndContinue-API (gilt nur für Windows Phone 8.1).

#if WINDOWS_APP
    // Use Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAsync
#else
    // Use Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAndContinue
#endif // WINDOWS_APP

Windows 10 konvergiert in der PickSingleFileAsync-API , sodass Ihr Code dies vereinfacht:

    // Use Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAsync

In diesem Beispiel behandeln wir die Hardwareschaltfläche "Zurück" – aber nur auf Windows Phone.

#if WINDOWS_PHONE_APP
        Windows.Phone.UI.Input.HardwareButtons.BackPressed += this.HardwareButtons_BackPressed;
#endif // WINDOWS_PHONE_APP

...

#if WINDOWS_PHONE_APP
    void HardwareButtons_BackPressed(object sender, Windows.Phone.UI.Input.BackPressedEventArgs e)
    {
        // Handle the event.
    }
#endif // WINDOWS_PHONE_APP

In Windows 10 ist das Ereignis "Zurück"-Schaltfläche ein universelles Konzept. Zurück-Schaltflächen, die in Hardware oder in software implementiert sind, lösen das BackRequested-Ereignis aus, sodass dies die zu behandelnde Schaltfläche ist.

    Windows.UI.Core.SystemNavigationManager.GetForCurrentView().BackRequested +=
        this.ViewModelLocator_BackRequested;

...

private void ViewModelLocator_BackRequested(object sender, Windows.UI.Core.BackRequestedEventArgs e)
{
    // Handle the event.
}

Dieses letzte Beispiel ähnelt dem vorherigen Beispiel. Hier behandeln wir die Hardware-Kamerataste – aber auch wieder, nur im Code, der in das Windows Phone App-Paket kompiliert wurde.

#if WINDOWS_PHONE_APP
    Windows.Phone.UI.Input.HardwareButtons.CameraPressed += this.HardwareButtons_CameraPressed;
#endif // WINDOWS_PHONE_APP

...

#if WINDOWS_PHONE_APP
void HardwareButtons_CameraPressed(object sender, Windows.Phone.UI.Input.CameraEventArgs e)
{
    // Handle the event.
}
#endif // WINDOWS_PHONE_APP

In Windows 10 ist die Hardware-Kamerataste ein Konzept, das speziell für die Mobilgerätefamilie gilt. Da ein App-Paket auf allen Geräten ausgeführt wird, ändern wir unsere Kompilierungszeitbedingung in eine Laufzeitbedingung unter Verwendung des sogenannten adaptiven Codes. Dazu verwenden wir die ApiInformation-Klasse, um zur Laufzeit die Anwesenheit der HardwareButtons-Klasse abzufragen. HardwareButtons ist im sdk für die mobile Erweiterung definiert, daher müssen wir unserem Projekt einen Verweis auf dieses SDK hinzufügen, damit dieser Code kompiliert werden kann. Beachten Sie jedoch, dass der Handler nur auf einem Gerät ausgeführt wird, das die im SDK für mobile Erweiterung definierten Typen implementiert, und das ist die Mobilgerätefamilie. Dieser Code entspricht also moralisch dem Universellen 8.1-Code, da er nur features verwendet, die vorhanden sind, obwohl er dies auf andere Weise erreicht.

    // Note: Cache the value instead of querying it more than once.
    bool isHardwareButtonsAPIPresent = Windows.Foundation.Metadata.ApiInformation.IsTypePresent
        ("Windows.Phone.UI.Input.HardwareButtons");

    if (isHardwareButtonsAPIPresent)
    {
        Windows.Phone.UI.Input.HardwareButtons.CameraPressed +=
            this.HardwareButtons_CameraPressed;
    }

    ...

private void HardwareButtons_CameraPressed(object sender, Windows.Phone.UI.Input.CameraEventArgs e)
{
    // Handle the event.
}

Weitere Informationen finden Sie unter Erkennen der Plattform, auf der Ihre App ausgeführt wird.

App-Paketmanifest

Im Thema "Änderungen in Windows 10 " werden Änderungen an der Schemareferenz für das Paketmanifest für Windows 10 aufgelistet, einschließlich Elemente, die hinzugefügt, entfernt und geändert wurden. Referenzinformationen zu allen Elementen, Attributen und Typen im Schema finden Sie unter "Elementhierarchie". Wenn Sie eine Windows Phone Store-App portieren oder ihre App ein Update zu einer App aus dem Windows Phone Store ist, stellen Sie sicher, dass das mp:PhoneIdentity-Element dem Inhalt des App-Manifests Ihrer vorherigen App entspricht (verwenden Sie die gleichen GUIDs, die der App vom Store zugewiesen wurden). Dadurch wird sichergestellt, dass Benutzer Ihrer App, die ein Upgrade auf Windows 10 oder Windows 11 durchführen, Ihre neue App als Update erhalten, nicht als Duplikat. Weitere Details finden Sie im Mp:PhoneIdentity-Referenzthema.

Die Einstellungen in Ihrem Projekt (einschließlich der Verweise auf Erweiterungs-SDKs) bestimmen den API-Oberflächenbereich, den Ihre App aufrufen kann. Ihr App-Paketmanifest bestimmt jedoch den tatsächlichen Satz von Geräten, auf denen Ihre Kunden Ihre App aus dem Store installieren können. Weitere Informationen finden Sie in den Beispielen in TargetDeviceFamily.

Sie können das App-Paketmanifest bearbeiten, um verschiedene Deklarationen, Funktionen und andere Einstellungen festzulegen, die einige Features benötigen. Sie können den App-Paketmanifest-Editor von Visual Studio verwenden, um es zu bearbeiten. Wenn die Projektmappen-Explorer nicht angezeigt wird, wählen Sie sie im Menü "Ansicht" aus. Doppelklicken Sie auf Package.appxmanifest. Dadurch wird das Manifest-Editor-Fenster geöffnet. Wählen Sie die entsprechende Registerkarte aus, um Änderungen vorzunehmen und dann zu speichern.

Das nächste Thema ist die Problembehandlung.