Freigeben über

Eine Windows App SDK-Migration der Beispiel-App für das UWP-PhotoLab (C#)

  • Artikel

Dieses Thema ist eine Fallstudie über die C# UWP PhotoLab-Beispiel-App, die auf das Windows App SDK migriert wird.

Beginnen Sie, indem Sie das Repository der UWP-Beispiel-App klonen und die Lösung in Visual Studio öffnen.

Wichtig

Überlegungen und Strategien zum Herangehen des Migrationsprozesses und zum Einrichten Ihrer Entwicklungsumgebung für die Migration finden Sie unter Allgemeine Migrationsstrategie. Es ist besonders wichtig zu sehen, was beim Portieren von UWP zu WinUI 3 unterstützt wird, damit Sie sicherstellen können, dass alle Features, die Sie für Ihre App benötigen, unterstützt werden, bevor Sie die Migration versuchen.

Installieren von Tools für das Windows App SDK

Informationen zum Einrichten Ihres Entwicklungscomputers finden Sie unter Installieren von Tools für das Windows App SDK.

Wichtig

Sie finden Themen mit Versionshinweisen zusammen mit dem Thema Windows App SDK – Veröffentlichungskanäle. Es gibt Versionshinweise für jeden Kanal. Überprüfen Sie unbedingt alle Einschränkungen und bekannten Probleme in den Versionshinweisen, da sich diese möglicherweise auf die Ergebnisse auswirken, wenn Sie dieser Fallstudie folgen und/oder die migrierte Anwendung ausführen.

Erstellen eines neuen Projekts

Erstellen Sie in Visual Studio ein neues C#-Projekt aus der Projektvorlage Leere App, Gepackt (WinUI 3 in Desktop). Benennen Sie das Projekt PhotoLabWinUI, deaktivieren Sie die Option Lösung und Projekt im selben Verzeichnis platzieren. Sie können auf das neueste Release (keine Vorschau) des Clientbetriebssystems abzielen.

Hinweis

Wir verweisen auf die UWP-Version des Beispielprojekts (das, das Sie aus dem Repository geklont haben) als Quelllösung/Projekt. Wir verweisen auf die Windows App SDK-Version als Ziellösung/Projekt.

Die Reihenfolge, in der der Code migriert wird

MainPage ist ein wichtiger und prominenter Teil der App. Aber wenn wir damit beginnen würden, dies zu migrieren, würden wir bald feststellen, dass MainPage eine Abhängigkeit von der DetailPage-Ansicht hat und dann hat die DetailPage eine Abhängigkeit vom ImageFileInfo-Modell. Für diese exemplarische Vorgehensweise werden wir also diesen Ansatz verfolgen.

  • Wir beginnen mit dem Kopieren der Ressourcen-Dateien.
  • Anschließend migrieren wir das ImageFileInfo-Modell.
  • Als Nächstes migrieren wir die App-Klasse (da hier Änderungen vorgenommen werden müssen, von denen DetailPage, MainPage und LoadedImageBrush abhängig sind).
  • Anschließend migrieren wir die LoadedImageBrush-Klasse.
  • Anschließend beginnen wir mit der Migration der Ansichten, beginnend mit DetailPage.
  • Zum Schluss migrieren wir noch die Ansicht MainPage.

Kopieren von Objektdateien

  1. Klicken Sie in Ihrem Zielprojekt in Visual Studio, im Projektmappen-Explorer, mit der rechten Maustaste auf den Ordner Ressourcen und fügen Sie einen neuen Ordner namens Samples hinzu.

  2. Suchen Sie in Ihrem Klon des Quellprojekts in Datei-Explorer den Ordner Windows-appsample-photo-lab>PhotoLab>Assets. Sie finden sieben Ressourcendateien in diesem Ordner zusammen mit einem Unterordner mit dem Namen Beispiele, die Beispielbilder enthalten. Wählen Sie diese sieben Ressourcendateien und den Unterordner Beispiele aus und kopieren Sie sie in die Zwischenablage.

  3. Suchen Sie nun auch in Datei-Explorer den entsprechenden Ordner im von Ihnen erstellten Zielprojekt. Der Pfad zu diesem Ordner ist PhotoLabWinUI>PhotoLabWinUI>Assets. Fügen Sie in diesen Ordner die Ressourcendateien und den soeben kopierten Unterordner ein und akzeptieren Sie die Aufforderung, alle Dateien zu ersetzen, die bereits im Ziel vorhanden sind.

  4. In Ihrem Zielprojekt in Visual Studio sehen Sie im Projektmappen-Explorer, wenn der Ordner Ressourcen erweitert ist, im Ordner Beispiele den Inhalt des Unterordners Beispiele (den Sie gerade eingefügt haben). Sie können mit dem Mauszeiger auf die Ressourcendateien zeigen. Für jede Datei wird eine Miniaturvorschau angezeigt, die bestätigt, dass Sie die Ressourcendateien korrekt ersetzt/hinzugefügt haben.

Das ImageFileInfo-Modell migrieren

ImageFileInfo ist ein Modell (im Sinne von Modellen, Ansichten und Ansichtsmodellen), das eine Bilddatei darstellt, z. B. ein Foto.

Kopieren von ImageFileInfo-Quellcodedateien

  1. Suchen Sie in Ihrem Klon des Quellprojekts in Datei-Explorer den Ordner Windows-appsample-photo-lab>PhotoLab. In diesem Ordner finden Sie die Quellcodedatei ImageFileInfo.cs; diese Datei enthält die Implementierung von ImageFileInfo. Wählen Sie diese Datei aus und kopieren Sie sie in die Zwischenablage.

  2. Klicken Sie mit der rechten Maustaste auf den Zielprojektknoten in Visual Studio, und klicken Sie dann auf Ordner im Datei-Explorer öffnen. Dadurch wird der Zielprojektordner im Datei-Explorer geöffnet. Fügen Sie die soeben kopierte Datei in diesen Ordner ein.

Migrieren von ImageFileInfo-Quellcode

  1. Nehmen Sie in der soeben eingefügten ImageFileInfo.cs-Datei die folgenden Such-/Ersetzungsvorgänge vor (Groß-/Kleinschreibung und ganzes Wort abgleichen).
  • namespace PhotoLab =>namespace PhotoLabWinUI
  • Windows.UI.Xaml =>Microsoft.UI.Xaml

Windows.UI.Xaml ist der Namespace für UWP-XAML; Microsoft.UI.Xaml ist der Namespace für WinUI-XAML.

Hinweis

Das Thema Zuordnen von UWP-APIs zum Windows App SDK bietet eine Zuordnung von UWP-APIs zu ihren Windows App SDK-Entsprechungen. Die oben vorgenommene Änderung ist ein Beispiel für eine Namespace-Namenänderung, die während des Migrationsprozesses erforderlich ist.

  1. Bestätigen Sie jetzt, dass Sie die Ziellösung erstellen können (Führen Sie sie aber noch nicht aus).

Migrieren der App-Klasse

  1. Im Quellprojekt finden Sie im Element <Application.Resources> in App.xaml die folgenden vier Zeilen. Kopieren Sie sie und fügen Sie sie in das Zielprojekt ein.
<SolidColorBrush x:Key="RatingControlSelectedForeground" Color="White"/>
<!--  Window width adaptive breakpoints.  -->
<x:Double x:Key="MinWindowBreakpoint">0</x:Double>
<x:Double x:Key="MediumWindowBreakpoint">641</x:Double>
<x:Double x:Key="LargeWindowBreakpoint">1008</x:Double>

Hinweis

Da das Zielprojekt eine andere (und einfachere) Navigation vom Quellprojekt verwendet, müssen Sie keinen weiteren Code aus dem Quellprojekt App.xaml.cs kopieren.

  1. Im Zielprojekt speichert die App das Hauptfensterobjekt im privaten Feld m_window. Später im Migrationsprozess (wenn wir die Verwendung von Window.Current im Quellprojekt migrieren) ist es praktisch, wenn es sich bei diesem privaten Feld stattdessen um eine öffentliche statische Eigenschaft handelt. Ersetzen Sie also das Feld m_window durch eine Window-Eigenschaft und ändern Sie Referenzen auf m_window, wie unten dargestellt.
// App.xaml.cs
public partial class App : Application
{
    ...
    protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
    {
        Window = new MainWindow();
        Window.Activate();
    }

    public static MainWindow Window { get; private set; }
}
  1. Später im Migrationsprozess (beim Migrieren des Codes, der ein FileSavePicker anzeigt) ist es praktisch, wenn die App das Handle des Hauptfensters (HWND) verfügbar macht. Fügen Sie also eine WindowHandle-Eigenschaft hinzu und initialisieren Sie sie in der OnLaunched-Methode, wie unten dargestellt.
// App.xaml.cs
public partial class App : Application
{
    ...
    protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
    {
        Window = new MainWindow();
        Window.Activate();
        WindowHandle = WinRT.Interop.WindowNative.GetWindowHandle(Window);
    }

    public static IntPtr WindowHandle { get; private set; }
}

Migrieren des LoadedImageBrush-Modells

LoadedImageBrush ist eine Spezialisierung von XamlCompositionBrushBase. Die PhotoLab-Beispiel-App verwendet die LoadedImageBrush-Klasse, um Effekte auf Fotos anzuwenden.

Verweisen Sie auf das Win2D NuGet-Paket

Um Code in LoadedImageBrush zu unterstützen, hat das Quellprojekt eine Abhängigkeit von Win2D. Daher benötigen wir auch eine Abhängigkeit von Win2D in unserem Zielprojekt.

Klicken Sie in der Ziellösung in Visual Studio auf Tools>NuGet-Paket-Manager>NuGet-Pakete für Lösung verwalten...>Browsen und geben Sie oder fügen Sie Microsoft.Graphics.Win2D ein. Wählen Sie das richtige Element in den Suchergebnissen aus, überprüfen Sie das PhotoLabWinUI-Projekt und klicken Sie auf Installieren, um das Paket in diesem Projekt zu installieren.

Kopieren von LoadedImageBrush-Quellcodedateien

Kopieren Sie LoadedImageBrush.cs aus dem Quellprojekt in das Zielprojekt auf die gleiche Weise, wie Sie ImageFileInfo.cs kopiert haben.

Migrieren von LoadedImageBrush-Quellcode

  1. Nehmen Sie in der soeben eingefügten LoadedImageBrush.cs-Datei die folgenden Such-/Ersetzungsvorgänge vor (Groß-/Kleinschreibung und ganzes Wort abgleichen).
  1. Vergewissern Sie sich, dass Sie die Ziellösung erstellen können (Führen Sie sie aber noch nicht aus).

Migrieren der DetailPage-Ansicht

DetailPage ist die Klasse, die die Foto-Editor-Seite darstellt, auf der Win2D-Effekte umgeschaltet, festgelegt und verkettet werden. Sie gelangen zur Foto-Editor-Seite, indem Sie auf MainPage eine Fotominiaturansicht auswählen. DetailPage ist ein Modell (im Sinne von Modellen, Ansichten und Ansichtsmodellen).

Kopieren von DetailPage-Quellcodedateien

Kopieren Sie DetailPage.xaml und DetailPage.xaml.cs aus dem Quellprojekt in das Zielprojekt auf die gleiche Weise, wie Sie Dateien in vorherigen Schritten kopiert haben.

Migrieren des DetailPage-Quellcodes

  1. Nehmen Sie in der soeben eingefügten DetailPage.xaml-Datei die folgenden Such-/Ersetzungsvorgänge vor (Groß-/Kleinschreibung und ganzes Wort abgleichen).
  • PhotoLab =>PhotoLabWinUI
  1. Nehmen Sie in der soeben eingefügten DetailPage.xaml.cs-Datei die folgenden Such-/Ersetzungsvorgänge vor (Groß-/Kleinschreibung und ganzes Wort abgleichen).
  • namespace PhotoLab =>namespace PhotoLabWinUI
  • Windows.UI.Colors =>Microsoft.UI.Colors
  • Windows.UI.Xaml =>Microsoft.UI.Xaml
  1. Im nächsten Schritt nehmen wir die in ContentDialog und Popup erläuterte Änderung vor. Fügen Sie also noch in DetailPage.xaml.cs in der Methode ShowSaveDialog unmittelbar vor der Zeile ContentDialogResult result = await saveDialog.ShowAsync(); diesen Code ein.
if (Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    saveDialog.XamlRoot = this.Content.XamlRoot;
}
  1. Löschen Sie in der OnNavigatedTo-Methode in DetailPage.xaml.cs die folgenden zwei Codezeilen. Nur diese beiden Zeilen; später in dieser Fallstudie werden wir die Funktionalität der Zurück-Schaltfläche, die wir gerade entfernt haben, wieder einführen.
...
SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility =
    AppViewBackButtonVisibility.Visible;
...
SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility = 
    AppViewBackButtonVisibility.Collapsed;
...
  1. Für diesen Schritt nehmen wir die in MessageDialog und Auswahl erläuterte Änderung vor. In DetailPage.xaml.cs fügen Sie in der Methode ExportImage unmittelbar vor der Zeile var outputFile = await fileSavePicker.PickSaveFileAsync(); diese Codezeile ein.
WinRT.Interop.InitializeWithWindow.Initialize(fileSavePicker, App.WindowHandle);

MainPage verfügt über Abhängigkeiten von DetailPage, weshalb wir zuerst DetailPage migriert haben. Aber DetailPage hat auch Abhängigkeiten von MainPage, sodass wir noch nicht in der Lage sein werden, zu erstellen.

Migrieren der MainPage-Ansicht

Die Hauptseite der App ist die Ansicht, die beim Ausführen der App zuerst angezeigt wird. Es ist die Seite, die die Fotos aus dem Ordner Beispiele lädt, der in die Beispiel-App integriert ist und zeigt eine nebeneinander angeordnete Miniaturansicht an.

Kopieren von MainPage-Quellcodedateien

Kopieren Sie MainPage.xaml und MainPage.xaml.cs aus dem Quellprojekt in das Zielprojekt auf die gleiche Weise, wie Sie Dateien in vorherigen Schritten kopiert haben.

Migrieren von MainPage-Quellcode

  1. Nehmen Sie in der soeben eingefügten MainPage.xaml-Datei die folgenden Such-/Ersetzungsvorgänge vor (Groß-/Kleinschreibung und ganzes Wort abgleichen).
  • PhotoLab =>PhotoLabWinUI

  1. Suchen Sie in MainPage.xaml das Markup animations:ReorderGridAnimation.Duration="400" und löschen Sie es.

  2. Nehmen Sie in der soeben eingefügten MainPage.xaml.cs-Datei die folgenden Such-/Ersetzungsvorgänge vor (Groß-/Kleinschreibung und ganzes Wort abgleichen).

  • namespace PhotoLab =>namespace PhotoLabWinUI
  • Windows.UI.Xaml =>Microsoft.UI.Xaml
  1. In diesem Schritt nehmen wir die in ContentDialog und Popup erläuterte Änderung vor. Fügen Sie also noch in MainPage.xaml.cs in der Methode GetItemsAsync unmittelbar vor der Zeile ContentDialogResult resultNotUsed = await unsupportedFilesDialog.ShowAsync(); diesen Code ein.
if (Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    unsupportedFilesDialog.XamlRoot = this.Content.XamlRoot;
}
  1. Löschen Sie in der OnNavigatedTo-Methode in MainPage.xaml.cs die Codezeile.
SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility =
    AppViewBackButtonVisibility.Collapsed;

Später in dieser Fallstudie werden wir die Funktionalität der Zurück-Schaltfläche, die wir gerade entfernt haben, wieder einführen.

  1. Vergewissern Sie sich, dass Sie die Ziellösung erstellen können (Führen Sie sie aber noch nicht aus).

Die PhotoLab-Beispiel-App verwendet Navigationslogik, um zunächst zu MainPage (und dann zwischen MainPage und DetailPage) zu navigieren. Weitere Informationen zu Windows App SDK-Apps, die Navigation benötigen (und die nicht), finden Sie unter Muss ich die Seitennavigation implementieren?.

Daher werden die Änderungen, die wir als Nächstes vornehmen, diese Navigation unterstützen.

  1. Löschen Sie in MainWindow.xaml das Element <StackPanel> und ersetzen Sie es durch ein benanntes Element <Frame>. Das Ergebnis sieht wie folgt aus:
<Window ...>
    <Frame x:Name="rootFrame"/>
</Window>

  1. Löschen Sie in MainWindow.xaml.cs die myButton_Click-Methode.

  2. Fügen Sie noch in MainWindow.xaml.cs die folgende Codezeile in den Konstruktor ein.

public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        this.InitializeComponent();
        rootFrame.Navigate(typeof(MainPage));
    }
}
  1. Vergewissern Sie sich, dass Sie die Ziellösung erstellen können (Führen Sie sie aber noch nicht aus).

Wiederherstellen der Schaltflächenfunktion „Zurück“

  1. In DetailPage.xaml ist das Wurzelelement ein RelativePanel. Fügen Sie das folgende Markup in das RelativePanel unmittelbar nach dem StackPanel-Element ein.
<AppBarButton x:Name="BackButton" Click="BackButton_Click" Margin="0,0,12,0">
    <SymbolIcon Symbol="Back"/>
</AppBarButton>
  1. Fügen Sie in DetailPage.xaml.cs der Methode OnNavigatedTo an der angegebenen Stelle die folgenden zwei Codezeilen hinzu.
if (this.Frame.CanGoBack)
{
    BackButton.Visibility = Microsoft.UI.Xaml.Visibility.Visible;
}
else
{
    BackButton.Visibility = Microsoft.UI.Xaml.Visibility.Collapsed;
}
  1. Fügen Sie noch in DetailPage.xaml.cs den folgenden Ereignishandler hinzu.
private void BackButton_Click(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
    Frame.GoBack();
}

Testen der migrierten App

Erstellen Sie nun das Projekt und führen Sie die Anwendung aus, um sie zu testen. Wählen Sie ein Bild aus, legen Sie einen Zoomfaktor fest, wählen Sie Effekte aus und konfigurieren Sie sie.

Weitere Informationen