Utiliser le SDK d'application Windows dans une application WPF

  • Article

Le SDK Windows App est la prochaine évolution de la plateforme de développement d’applications Windows. Mais cette rubrique montre comment vous pouvez utiliser les API du SDK Windows App (et les API du moteur d’exécution Windows) dans une application Windows Presentation Foundation (WPF) !

  • Dans de nombreux cas, vous aurez besoin de recréer votre application WPF sous la forme d’une application Windows UI Library 3 (WinUI 3). L’un des avantages de passer à WinUI 3 est d’avoir accès au Fluent Design System (voir aussi Concevoir et coder des application Windows). De plus, WinUI 3 fait partie du Windows App SDK – donc, naturellement, une application WinUI 3 peut également utiliser les autres fonctionnalités et API du Windows App SDK. Cette rubrique ne couvre pas le processus de migration de votre application WPF vers WinUI 3.
  • Mais si vous utilisez des fonctionnalités de WPF qui ne sont pas encore disponibles dans WinUI 3, vous pouvez toujours utiliser les applications du Windows App SDK (notamment App Lifecycle, MRT Core, DWriteCore et d’autres) dans votre application WPF. Cette rubrique vous montre comment procéder.

Et au cas où vous n’auriez pas encore de projet WPF existant (ou si vous voulez vous entraîner), cette rubrique inclut les étapes pour créer un projet WPF qui vous permettra de le suivre et de le configurer pour qu’il appelle les applications SDK Windows App.

Prérequis

  1. Installer les outils pour le SDK pour application Windows.
  2. Cette rubrique couvre à la fois les applications WPF packagées et non packagées. Si votre application WPF n’est pas packagée (ce qui est le cas par défaut), assurez-vous que toutes les dépendances des applications non packagées sont installées (voir le guide de déploiement du Windows App SDK pour les applications dépendantes du framework, packagées avec un emplacement externe ou non packagées). Un moyen rapide de le faire est de visiter la page Derniers téléchargements pour le Windows App SDK, puis de télécharger, de décompresser et d’exécuter l’un des téléchargements de la version stable du Runtime.

Important

La version du Runtime que vous installez doit correspondre à la version du package NuGet Microsoft.WindowsAppSDK que vous installerez dans une étape ultérieure.

Pour en savoir plus sur les termes « unpackaged » et « packaged », consultez Avantages et inconvénients du packaging de votre application.

Créer un projet WPF si vous n’en avez pas déjà un

Si vous avez déjà un projet WPF, vous pouvez passer à la section suivante.

  1. Dans Visual Studio, créez un nouveau projet C# WPF Application (qui est un projet .NET). Veillez à choisir le modèle de projet portant le nom exact de WPF Application, et non celui de WPF App (.NET Framework).
  2. Donnez un nom au projet et acceptez les options par défaut.

Vous avez maintenant un projet qui construit une application WPF non packagée.

Configurer votre projet WPF pour la prise en charge du Windows App SDK

Tout d’abord, nous allons modifier le fichier du projet.

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit de la souris sur votre projet et choisissez Modifier le fichier de projet.

  2. Cette étape vous permet d’appeler les API Windows Runtime (WinRT) (y compris les API SDK Windows App). L’élément PropertyGroup contient l’élément TargetFramework, qui est défini sur une valeur telle que net6.0. Ajoutez à cette valeur de cadre cible un moniker (plus précisément, un moniker de cadre cible) Par exemple, utilisez ce qui suit si votre application cible Windows 10, version 2004 :

    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>

  3. Toujours dans l’élément PropertyGroup, ajoutez un élément RuntimeIdentifiers, comme indiqué ci-dessous. Si vous ciblez .NET 8 ou une version ultérieure, utilisez plutôt la valeur win-x86;win-x64;win-arm64.

    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>

  4. Par défaut, une application WPF n’est pas packagée (c’est-à-dire qu’elle n’est pas installée à l’aide de MSIX). Une application non packagée doit initialiser le runtime du Windows App SDK avant d’utiliser toute autre fonctionnalité du Windows App SDK. Vous pouvez le faire automatiquement au démarrage de votre application via l’auto-initialisation. Il vous suffit de définir (également à l’intérieur de l’élément PropertyGroup) la propriété du projet WindowsPackageType de manière appropriée, comme suit :

    <WindowsPackageType>None</WindowsPackageType>

    Si vous avez des besoins avancés (comme une gestion personnalisée des erreurs ou le chargement d’une version spécifique du Windows App SDK), au lieu de l’auto-initialisation, vous pouvez appeler explicitement l’API bootstrapper. Pour en savoir plus, consultez la section Utiliser le moteur d’exécution du Windows App SDK pour les applications packagées avec un emplacement externe ou non packagées.

  5. Enregistrez et fermez le fichier projet.

Ensuite, nous allons installer le package NuGet Windows App SDK dans le projet.

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit de la souris sur le nœud Dépendances de votre projet, puis choisissez Gérer les packages Nuget….
  2. Dans la fenêtre NuGet Package Manager, sélectionnez l’onglet Parcourir et installez le package stableMicrosoft.WindowsAppSDK le plus récent.

Utiliser certaines fonctionnalités du Windows App SDK dans votre application WPF

Cette section propose un exemple très simple d’appel des applications du Windows App SDK à partir d’une application WPF. Elle utilise la fonctionnalité MRT Core (voir Gérer les ressources avec MRT Core). Si cet exemple fonctionne pour votre projet WPF (et si vous en avez créé un nouveau pour cette procédure-à-pas, c’est le cas), vous pouvez suivre les étapes suivantes.

  1. Ajoutez la balise suivante à MainWindow.xaml (vous pouvez la coller à l’intérieur de la grille racine) :

    <StackPanel>
    <Button HorizontalAlignment="Center" Click="Button_Click">Click me!</Button>
    <TextBlock HorizontalAlignment="Center" x:Name="myTextBlock">Hello, World!</TextBlock>
</StackPanel>

  2. Nous allons maintenant ajouter du code qui utilise la classe ResourceManager du Windows App SDK pour charger une ressource de type chaîne de caractères.

    1. Ajoutez un nouveau fichier de ressources (.resw) à votre projet (laissez-lui le nom par défaut de Resources.resw).

    2. Le fichier de ressources étant ouvert dans l’éditeur, créez une nouvelle ressource de type chaîne avec les propriétés suivantes.

      • Nom : Message
      • Valeur : Bonjour, ressources!

    3. Enregistrez et fermez le fichier de ressources.

    4. Dans MainWindow.xaml.cs, ajoutez le gestionnaire d’événements suivant :

    private void Button_Click(object sender, RoutedEventArgs e)
{
    // Construct a resource manager using the resource index generated during build.
    var manager = 
      new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();

    // Look up a string in the resources file using the string's name.
    myTextBlock.Text = manager.MainResourceMap.GetValue("Resources/Message").ValueAsString;
}

  3. Créez le projet et exécutez l’application. Cliquez sur le bouton pour afficher la chaîne Hello, resources!.

Conseil

Si, au moment de l’exécution, vous voyez apparaître une boîte de message indiquant que l’application a besoin d’une version particulière du Runtime Windows App, et vous demandant si vous voulez l’installer maintenant, cliquez sur Oui. Vous accéderez alors aux derniers téléchargements du SDK Windows App. Pour plus d’informations, reportez-vous à la section Conditions préalables ci-dessus.

Consultez également la section Architecture du runtime pour en savoir plus sur la dépendance du package Framework que votre application prend lorsqu’elle utilise le Windows App SDK, et sur les composants supplémentaires requis pour fonctionner dans une application non packagée.

Packagez et déployez votre application WPF avec MSIX

Certaines fonctionnalités et API de Windows (y compris les API de notification du SDK Windows App) exigent que votre application ait une identité de package au moment de l’exécution (en d’autres termes, votre application doit être packagée). Pour plus d’informations, consultez Fonctionnalités nécessitant une identité de package.

  1. Dans l’Explorateur de solutions de Visual Studio, cliquez avec le bouton droit de la souris sur la solution, puis choisissez Ajouter> un nouveau projet....
  2. Dans la boîte de dialogue Ajouter un nouveau projet, recherchez le package, choisissez le modèle de projet C# Windows Application Packaging Project et cliquez sur Suivant.
  3. Nommez le projet et cliquez sur Créer.
  4. Nous voulons spécifier quelles applications de la solution doivent être incluses dans le package. Dans le package (pas le projet WPF), cliquez avec le bouton droit de la souris sur le nœud Dépendances et choisissez Ajouter une référence de projet….
  5. Dans la liste des projets de la solution, choisissez votre projet WPF et cliquez sur OK.
  6. Développez le nœud Dépendances>Applications du projet de packaging, et confirmez que votre projet WPF est référencé et mis en évidence en gras. Cela signifie qu’il sera utilisé comme point de départ pour le package.
  7. Cliquez avec le bouton droit de la souris sur le projet de packaging et choisissez Définir comme projet de démarrage.
  8. Cliquez avec le bouton droit de la souris sur le projet WPF et choisissez Modifier le fichier de projet.
  9. Supprimez <WindowsPackageType>None</WindowsPackageType>, enregistrez et fermez.
  10. Dans le menu déroulant Plateformes de la solution, sélectionnez x64 (au lieu de Tout processeur).
  11. Confirmez que vous pouvez compiler et exécuter le projet.

Maintenant que vous avez packagé votre application WPF, vous pouvez appeler les applications qui requièrent l’identité du package. Ainsi, dans MainWindow.xaml.cs, modifiez votre gestionnaire d’événements pour qu’il ressemble à ce qui suit :

private void Button_Click(object sender, RoutedEventArgs e)
{
    var notification = new AppNotificationBuilder()
        .AddArgument("action", "viewConversation")
        .AddArgument("conversationId", "9813")
        .AddText("Andrew sent you a picture")
        .AddText("Check this out, The Enchantments in Washington!")
        .BuildNotification();

    AppNotificationManager.Default.Show(notification);
}

Construisez et exécutez à nouveau. Cliquez sur le bouton et confirmez qu’une notification de toast s’affiche. Lorsqu’elles sont appelées à partir d’un processus qui n’a pas d’identité de package au moment de l’exécution, les API de notification lèvent une exception.

Remarque

Les étapes de cette section vous ont montré comment créer une application packagée. Une alternative consiste à créer une application package avec un emplacement externe. Pour un rappel de tous ces termes, voir Avantages et inconvénients du package de votre application.