Eine Windows App SDK Migration der UWP PhotoLab-Beispiel-App (C#)

Dieses Thema ist eine Fallstudie zur Übernahme der C#-UWP PhotoLab-Beispiel-App und ihrer Migration zum Windows App SDK.

Beginnen Sie mit cloning des Repositorys der UWP-Beispiel-App und öffnen Sie die Lösung in Visual Studio.

Installieren von Tools für die Windows App SDK

Informationen zum Einrichten Ihres Entwicklungscomputers finden Sie unter Install-Tools für die Windows App SDK.

Neues Projekt erstellen

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

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 Anleitung werden wir diesen Ansatz verwenden.

• 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 Ziel-project in Visual Studio in Solution Explorer mit der rechten Maustaste auf den Ordner Assets, und fügen Sie einen neuen Ordner mit dem Namen Samples hinzu.

2. In Ihrem Klon des Quellprojekts, finden Sie im File 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 auch im File 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, im Solution Explorer, nachdem der Ordner Assets erweitert wurde, sehen Sie im Ordner Samples den Inhalt des Unterordners Samples (das Sie gerade eingefügt haben). Sie können den Mauszeiger über die Asset-Dateien bewegen. 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 im 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 in Visual Studio mit der rechten Maustaste auf den Zielprojektknoten, und klicken Sie auf Ordner im Datei-Explorer öffnen. Dadurch wird der Zielordner project in File 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.

2. 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. Suchen Sie im Quellprojekt im Element <Application.Resources> in App.xaml die folgenden vier Zeilen. Kopieren Sie sie, und fügen Sie sie in das Ziel project 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>

2. Im Ziel-project speichert App das Hauptfensterobjekt im privaten Feld m_window. Später im Migrationsprozess (beim Migrieren der Nutzung des Quellprojekts von Window.Current) 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; }
}

3. Später im Migrationsprozess (wenn wir den Code migrieren, der eine FileSavePicker anzeigt), ist es praktisch, wenn App das Handle (HWND) des Hauptfensters bereitstellt. 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

Zur Unterstützung von Code in LoadedImageBrush hat das Projekt eine Abhängigkeit von Win2D. Daher benötigen wir auch eine Abhängigkeit von Win2D in unserem Ziel-project.

Klicken Sie in der Ziellösung in Visual Studio auf Tools>NuGet Package Manager>Manage NuGet Packages for Solution... >Browse, und geben Sie Microsoft.Graphics.Win2D ein. Wählen Sie das richtige Element in den Suchergebnissen aus, überprüfen Sie die PhotoLabWinUI project, und klicken Sie auf Install, um das Paket in diesem project zu installieren.

Kopieren von LoadedImageBrush-Quellcodedateien

Kopieren Sie LoadedImageBrush.cs aus dem Quellenprojekt auf das Zielprojekt in derselben Weise, wie Sie ImageFileInfo.cs kopierten.

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

• namespace PhotoLab =>namespace PhotoLabWinUI
• Windows.UI.Composition =>Microsoft.UI.Composition
• Windows.UI.Xaml =>Microsoft.UI.Xaml
• Window.Current.Compositor =>App.Window.Compositor (siehe ändern Sie Windows.UI.Xaml.Window.Current in App.Window)

2. 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 Seite des Fotoeditors darstellt, auf der Win2D-Effekte aktiviert, konfiguriert und miteinander verknüpft 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 dieselbe 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

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

3. 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;
}

4. Bleiben Sie weiterhin in DetailPage.xaml.cs, und löschen Sie im OnNavigatedTo-Methode 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;
...

5. In diesem Schritt nehmen wir die in MessageDialog und Pickers 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 Samples lädt, der in die Beispiel-App integriert ist, und eine gekachelte Miniaturansicht anzeigt.

Kopieren von MainPage-Quellcodedateien

Kopieren Sie MainPage.xaml und MainPage.xaml.cs aus dem Quellprojekt in das Zielprojekt auf dieselbe 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

2. Suche in MainPage.xaml das Markup animations:ReorderGridAnimation.Duration="400" und lösche es.

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

4. 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;
}

5. Bleiben Sie in MainPage.xaml.cs und löschen Sie in der Methode OnNavigatedTo die folgende 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.

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

Navigieren Sie zu MainPage

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

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

3. Fügen Sie, während Sie sich noch in MainWindow.xaml.cs befinden, die folgende Codezeile in den Konstruktor ein.

public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        this.InitializeComponent();
        rootFrame.Navigate(typeof(MainPage));
    }
}

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

2. 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;
}

3. 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 App aus, um die App zu testen. Wählen Sie ein Bild aus, legen Sie einen Zoomfaktor fest, wählen Sie Effekte aus und konfigurieren Sie sie.

Siehe auch

• Windows App SDK und unterstützte Windows-Versionen