Migration vers le SDK d’application Windows de l’exemple d’application UWP PhotoLab (C#)

Article
01/08/2024

Ce sujet est une étude de cas sur la prise de l’exemple d’application PhotoLab UWP C# et de la migration vers le kit de développement logiciel (SDK) d’application Windows.

Commencez par cloner le répertoire de l’application UWP et ouvrez la solution dans Visual Studio.

Important

Pour connaître les considérations et les stratégies d’approche du processus de migration, et savoir comment configurer votre environnement de développement pour la migration, reportez-vous à Stratégie globale de migration. Il est particulièrement important de voir ce qui est pris en charge lors du portage de UWP vers WinUI 3 afin de vous assurer que toutes les fonctionnalités dont vous avez besoin pour votre application sont prises en charge avant de tenter la migration.

Installer des outils pour le SDK d’application Windows

Pour configurer votre ordinateur de développement, consultez Installer des outils pour le SDK d’application Windows.

Important

Vous trouverez des rubriques consacrées aux notes de publication ainsi que la rubrique Canaux de publication du SDK d’application Windows. Des notes de publication sont disponibles pour chaque canal. Pensez à prendre connaissance des limitations et problèmes connus présentés dans ces notes de publication, car ceux-ci peuvent affecter les résultats du suivi de cette étude de cas et/ou l’exécution de l’application migrée.

Créer un projet

Dans Visual Studio, créez un projet C# à partir du modèle de projet Blank App, Packaged (WinUI 3 in Desktop). Nommez le projet PhotoLabWinUI, désélectionnez l’option Placer la solution et le projet dans le même répertoire. Vous pouvez cibler la version la plus récente (et non la préversion) du système d’exploitation client.

Remarque

Nous ferons référence à la version UWP du projet d’exemple (celle que vous avez clonée à partir de son référentiel) en tant que solution/projet source. Nous ferons référence à la version du kit SDK d’application Windows en tant que solution/projet cible.

Ordre dans lequel nous allons migrer le code

MainPage est un élément important et majeur de l’application. Cependant, si nous la migrons, nous nous rendrons vite compte que MainPage dépend de la vue DetailPage, puis que DetailPage dépend du modèle ImageFileInfo. Dans le cadre de ce guide, nous adopterons l’approche suivante.

Nous commencerons par copier les fichiers de ressources.
Nous ferons ensuite migrer le modèle ImageFileInfo.
Vous le ferons ensuite pour la classe d’application (puisqu’elle doit subir des modifications dont dépendront DetailPage, MainPage et LoadedImageBrush).
Nous migrerons ensuite la classe LoadedImageBrush.
Nous commencerons ensuite à migrer les vues, en commençant par DetailPage.
Nous terminerons par la migration de la vue MainPage.

Copier des fichiers de ressources

Dans votre projet cible de Visual Studio, dans l’explorateur de solutions, cliquez avec le bouton droit de la souris sur le dossier Ressources et ajoutez un nouveau dossier nommé Samples.
Dans votre clone du projet source, dans l’explorateur de fichiers, localisez le dossier Windows-appsample-photo-lab> PhotoLab> Ressources. Vous trouverez dans ce dossier sept fichiers de ressources, ainsi qu’un sous-dossier intitulé Exemples contenant des images d’exemple. Sélectionnez ces sept fichiers de ressources, ainsi que le sous-dossier Exemples, et copiez-les dans le presse-papiers.
Toujours dans l’explorateur de fichiers, localisez le dossier correspondant dans le projet cible que vous avez créé. Le chemin d’accès à ce dossier est PhotoLabWinUI>PhotoLabWinUI>Ressources. Collez dans ce dossier les fichiers d’actifs et le sous-dossier que vous venez de copier, et acceptez l’invitation à remplacer tous les fichiers qui existent déjà dans la destination.
Dans votre projet cible dans Visual Studio, dans l’explorateur de solutions, avec le dossier Ressources développé, vous verrez dans le dossier Exemples le contenu du sous-dossier Exemples (que vous venez de coller). Vous pouvez passer le pointeur de la souris sur les fichiers d’actifs. Un aperçu s’affiche en miniature pour chacun d’entre eux, confirmant que vous avez remplacé/ajouté les fichiers de ressources correctement.

Faire migrer le modèle ImageFileInfo

ImageFileInfo est un modèle (au sens des modèles, des vues et des modèles de vue) qui représente un fichier image, tel qu’une photo.

Copier des fichiers de code source ImageFileInfo

Dans votre clone du projet source, dans l’explorateur de fichiers, localisez le dossier Windows-appsample-photo-lab>PhotoLab. Dans ce dossier, vous trouverez le fichier du code source ImageFileInfo.cs. Ce fichier contient l’implémentation ImageFileInfo. Sélectionnez ce fichier et copiez-le dans le presse-papiers.
Dans Visual Studio, cliquez avec le bouton droit de la souris sur le nœud du projet cible, puis cliquez sur Ouvrir le dossier dans l’Explorateur de fichiers. Le dossier du projet cible s’ouvre dans l’Explorateur de fichiers. Collez dans ce dossier le fichier que vous venez de copier.

Migrer le code source ImageFileInfo

Effectuez les recherches/remplacements suivants (en respectant la casse et le mot entier) dans le fichier ImageFileInfo.cs que vous venez de coller.

namespace PhotoLab =>namespace PhotoLabWinUI
Windows.UI.Xaml =>Microsoft.UI.Xaml

Windows.UI.Xaml est l’espace de noms pour XAML UWP. Microsoft.UI.Xaml est l’espace de noms pour XAML WinUI.

Remarque

La rubrique Mappage des API UWP avec le kit SDK d’application Windows fournit un mappage des API UWP avec leurs équivalents dans le kit SDK d’application Windows. Le changement que nous avons effectué ci-dessus est un exemple de changement de nom d’espace de noms nécessaire au cours du processus de migration.

Vérifiez à présent que vous pouvez créer la solution cible (mais ne l’exécutez pas encore).

Migrer la classe d’application

Dans le projet source, dans l’élément <Application.Resources> sous App.xaml, trouvez les quatre lignes suivantes. Copiez-les et collez-les dans le projet cible.

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

Remarque

Étant donné que le projet cible utilise une navigation différente (et plus simple) à partir du projet source, il n’est pas nécessaire de copier plus de code à partir du App.xaml.cs du projet source.

Dans le projet cible, l’application stocke l’objet fenêtre principale dans son champ privé m_window. Plus tard dans le processus de migration (lorsque nous migrerons l’utilisation de Window.Current dans le projet source), il sera pratique que ce champ privé soit à la place une propriété statique publique. Remplacez donc le champ m_window par une propriété Window et modifiez les références à m_window, comme indiqué ci-dessous.

// 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; }
}

Plus tard dans le processus de migration (lorsque nous migrerons le code qui affiche un FileSavePicker), il sera pratique que l’application expose le handle de la fenêtre principale (HWND). Ajoutez donc une propriété WindowHandle et initialisez-la dans la méthode OnLaunched, comme indiqué ci-dessous.

// 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; }
}

Migrer le modèle LoadedImageBrush

LoadedImageBrush est une spécialisation de XamlCompositionBrushBase. L’exemple d’application PhotoLab utilise la classe LoadedImageBrush pour appliquer des effets aux photos.

Référencer le package NuGet Win2D

Pour prendre en charge le code dans LoadedImageBrush, le projet source dépend de Win2D. Nous aurons donc également besoin d’une dépendance sur Win2D dans notre projet cible.

Dans la solution cible de Visual Studio, cliquez sur Outils> Gestionnaire de packages NuGet> Gérer les packages NuGet pour la solution...>Parcourir et tapez ou collez Microsoft.Graphics.Win2D. Sélectionnez le bon élément dans les résultats de la recherche, vérifiez le projet PhotoLabWinUI et cliquez sur Installer pour installer le paquet dans ce projet.

Copier les fichiers de code source LoadedImageBrush

Copiez LoadedImageBrush.cs du projet source vers le projet cible comme vous l’avez fait avec ImageFileInfo.cs.

Migrer le code source LoadedImageBrush

Effectuez les recherches/remplacements suivants (en respectant la casse et le mot entier) dans le fichier LoadedImageBrush.cs que vous venez de coller.

namespace PhotoLab =>namespace PhotoLabWinUI
Windows.UI.Composition =>Microsoft.UI.Composition
Windows.UI.Xaml =>Microsoft.UI.Xaml
Window.Current.Compositor = >App.Window.Compositor (reportez-vous à Modifier Windows.UI.Xaml.Window.Current en App.Window)

Confirmez que vous pouvez créer la solution cible (mais ne l’exécutez pas encore).

Migrer la vue DetailPage

DetailPage est la classe qui représente la page de l’éditeur de photos, où les effets Win2D sont activés, définis et chaînés ensemble. Vous accédez à la page de l’éditeur de photos en sélectionnant une miniature de photo sur MainPage. DetailPage est un modèle (au sens des modèles, des vues et des viewmodels).

Copier les fichiers de code source DetailPage

Copiez DetailPage.xaml et DetailPage.xaml.cs du projet source vers le projet cible de la même manière que vous avez copié les fichiers dans les étapes précédentes.

Migrer le code source DetailPage

Effectuez les recherches/remplacements suivants (en respectant la casse et le mot entier) dans le fichier DetailPage.xaml que vous venez de coller.

PhotoLab =>PhotoLabWinUI

Effectuez les recherches/remplacements suivants (en respectant la casse et le mot entier) dans le fichier DetailPage.xaml.cs que vous venez de coller.

namespace PhotoLab =>namespace PhotoLabWinUI
Windows.UI.Colors =>Microsoft.UI.Colors
Windows.UI.Xaml =>Microsoft.UI.Xaml

Pour l’étape suivante, nous allons effectuer les changements expliqués dans ContentDialog, et Popup. Toujours dans DetailPage.xaml.cs, dans la méthode ShowSaveDialog, juste avant la ligne ContentDialogResult result = await saveDialog.ShowAsync();, ajoutez ce code.

if (Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    saveDialog.XamlRoot = this.Content.XamlRoot;
}

Toujours dans DetailPage.xaml.cs, dans la méthode OnNavigatedTo, supprimez les deux lignes de code suivantes. Faites-le uniquement pour ces deux lignes. Plus tard dans cette étude de cas, nous réintroduirons la fonctionnalité du bouton Précédent que nous venons de supprimer.

...
SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility =
    AppViewBackButtonVisibility.Visible;
...
SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility = 
    AppViewBackButtonVisibility.Collapsed;
...

Pour cette étape, nous allons effectuer les changements expliqués dans MessageDialog, et Sélecteurs. Toujours dans DetailPage.xaml.cs, dans la méthode ExportImage, juste avant la ligne var outputFile = await fileSavePicker.PickSaveFileAsync();, ajoutez cette ligne de code.

WinRT.Interop.InitializeWithWindow.Initialize(fileSavePicker, App.WindowHandle);

MainPage a des dépendances sur DetailPage, c’est pourquoi nous avons migré DetailPage en premier. Toutefois, DetailPage dépend aussi de MainPage. Nous ne pourrons donc pas encore générer.

Migrer la vue MainPage

La page principale de l’application est celle qui s’affiche en premier lorsque vous lancez l’application. Il s’agit de la page qui charge les photos à partir du dossier Exemples intégré à l’exemple d’application et affiche une vue miniature en mosaïque.

Copier les fichiers de code source MainPage

Copiez MainPage.xaml et MainPage.xaml.cs du projet source vers le projet cible de la même manière que vous avez copié les fichiers dans les étapes précédentes.

Migrer le code source MainPage

Effectuez les recherches/remplacements suivants (en respectant la casse et le mot entier) dans le fichier MainPage.xaml que vous venez de coller.

PhotoLab =>PhotoLabWinUI

Toujours dans MainPage.xaml, recherchez la balise animations:ReorderGridAnimation.Duration="400" et supprimez-la.
Effectuez les recherches/remplacements suivants (en respectant la casse et le mot entier) dans le fichier MainPage.xaml.cs que vous venez de coller.

namespace PhotoLab =>namespace PhotoLabWinUI
Windows.UI.Xaml =>Microsoft.UI.Xaml

Pour cette étape, nous allons effectuer les changements expliqués dans ContentDialog, et Popup. Toujours dans MainPage.xaml.cs, dans la méthode GetItemsAsync, juste avant la ligne ContentDialogResult resultNotUsed = await unsupportedFilesDialog.ShowAsync();, ajoutez ce code.

if (Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    unsupportedFilesDialog.XamlRoot = this.Content.XamlRoot;
}

Toujours dans MainPage.xaml.cs, dans la méthode OnNavigatedTo, supprimez la ligne de code suivante.

SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility =
    AppViewBackButtonVisibility.Collapsed;

Plus tard dans cette étude de cas, nous réintroduirons la fonctionnalité du bouton Précédent que nous venons de supprimer.

Confirmez que vous pouvez créer la solution cible (mais ne l’exécutez pas encore).

Navigation vers MainPage

L’exemple d’application PhotoLab utilise la logique de navigation pour naviguer d’abord vers la page principale (puis entre la MainPage et DetailPage). Pour en savoir plus sur les applications de kit SDK d’application Windows qui nécessitent une navigation (et celles qui n’en ont pas besoin), reportez-vous à la section Faut-il implémenter la navigation dans les pages ?.

Les changements que nous apporterons ensuite prendront donc en charge cette navigation.

Dans MainWindow.xaml, supprimez l’élément <StackPanel> et remplacez-le par un seul élément nommé <Frame>. Le résultat ressemble à ceci :

<Window ...>
    <Frame x:Name="rootFrame"/>
</Window>

Ouvrez MainWindow.xaml.cs et supprimez la méthode myButton_Click.
Toujours dans MainWindow.xaml.cs, ajoutez la ligne de code suivante au constructeur.

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

Confirmez que vous pouvez créer la solution cible (mais ne l’exécutez pas encore).

Restauration de la fonctionnalité bouton Précédent

Dans DetailPage.xaml, l’élément racine est RelativePanel. Ajoutez la balise suivante à l’intérieur de ce RelativePanel, immédiatement après l’élément StackPanel.

<AppBarButton x:Name="BackButton" Click="BackButton_Click" Margin="0,0,12,0">
    <SymbolIcon Symbol="Back"/>
</AppBarButton>

Dans DetailPage.xaml.cs, ajoutez les deux lignes de code suivantes à la méthode OnNavigatedTo, à l’endroit indiqué.

if (this.Frame.CanGoBack)
{
    BackButton.Visibility = Microsoft.UI.Xaml.Visibility.Visible;
}
else
{
    BackButton.Visibility = Microsoft.UI.Xaml.Visibility.Collapsed;
}

Toujours dans DetailPage.xaml.cs, ajoutez ce qui suit à votre gestionnaire d’événements.

private void BackButton_Click(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
    Frame.GoBack();
}

Tester l’application migrée

Créez à présent le projet et exécutez l’application pour la tester. Sélectionnez une image, définissez un niveau de zoom, choisissez des effets et configurez-les.

Voir aussi

Kit de développement logiciel (SDK) d’application Windows et versions Windows prises en charge

Partage via

Migration vers le SDK d’application Windows de l’exemple d’application UWP PhotoLab (C#)

Installer des outils pour le SDK d’application Windows

Créer un projet

Ordre dans lequel nous allons migrer le code

Copier des fichiers de ressources

Faire migrer le modèle ImageFileInfo

Copier des fichiers de code source ImageFileInfo

Migrer le code source ImageFileInfo

Migrer la classe d’application

Migrer le modèle LoadedImageBrush

Référencer le package NuGet Win2D

Copier les fichiers de code source LoadedImageBrush

Migrer le code source LoadedImageBrush

Migrer la vue DetailPage

Copier les fichiers de code source DetailPage

Migrer le code source DetailPage

Migrer la vue MainPage

Copier les fichiers de code source MainPage

Migrer le code source MainPage

Navigation vers MainPage

Restauration de la fonctionnalité bouton Précédent

Tester l’application migrée

Voir aussi

Ressources supplémentaires