Partage via

Utiliser le SDK d’application Windows dans une application Windows Forms (WinForms)

  • 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 des API du SDK d'application Windows (et des API Windows Runtime) dans une application Windows Forms (WinForms) !

  • Dans de nombreux cas, vous aurez besoin de recréer votre application WinForms sous la forme d’une application 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 WinForms vers WinUI 3.
  • Mais si vous utilisez des fonctionnalités de WinForms qui ne sont pas encore disponibles dans WinUI 3, vous pouvez toujours utiliser les applications du SDK d'application Windows (notamment App Lifecycle, MRT Core, DWriteCore et d’autres) dans votre application Winforms. Cette rubrique vous montre comment procéder.

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

Prérequis

  1. Installer les outils pour le SDK pour application Windows.
  2. Cette rubrique couvre à la fois les applications WinForms empaquetées et non empaquetées. Si votre application WinForms n’est pas empaquetée (ce qui est le cas par défaut), assurez-vous que toutes les dépendances des applications non empaquetées sont installées (voir le Guide de déploiement du SDK d’application Windows pour les applications dépendantes du framework empaquetées avec un emplacement externe ou non empaqueté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éez un projet WinForms si vous n'en avez pas déjà un

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

  1. Dans Visual Studio, créez un nouveau projet C# Windows Forms App (qui est un projet .NET). Veillez à choisir le modèle de projet portant le nom exact Windows Forms App, et non pas Windows Forms 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 WinForms non empaquetée.

Configurer votre projet WinForms pour la prise en charge du SDK d'application Windows

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

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

  4. Par défaut, une application WinForms n’est pas empaquetée (c’est-à-dire qu’elle n’est pas installée avec 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 Gestionnaire de package, sélectionnez l’onglet Parcourir et installez le package Microsoft.WindowsAppSDK stable le plus récent.

Utiliser certaines fonctionnalités du SDK d'application Windows dans votre application WinForms

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

  1. Ouvrez Form1.cs (à l’aide de la commande Concepteur de vues), puis faites glisser un Bouton et une Étiquette hors de la Boîte à outils et sur le concepteur.

  2. Double-cliquez sur button1 pour générer un gestionnaire d’événements.

  3. 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. Ouvrez Form1.cs (à l’aide de la commande Afficher le code) et modifiez le gestionnaire d’événements comme suit :

    private void button1_Click(object sender, EventArgs 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.
    label1.Text = manager.MainResourceMap.GetValue("Resources/Message").ValueAsString;
}

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

Empaqueter et déployer votre application WinForms 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 projet d'empaquetage (et non pas le projet Winforms), 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 WinForms et cliquez sur OK.
  6. Développez le nœud Dépendances>Applications du projet d'empaquetage, et confirmez que votre projet WinForms est référencé et s'affiche en caractères 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 sur le projet Winforms, 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 empaqueté votre application WinForms, vous pouvez appeler les API qui requièrent une identité de package. Ouvrez alors Form1.cs (à l’aide de la commande Afficher le code) et modifiez le gestionnaire d’événements comme suit :

private void button1_Click(object sender, EventArgs 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.