Présentation de C++/WinRT

C++/WinRT est une projection de langage C++17 moderne entièrement standard pour les API Windows Runtime (WinRT), implémentée en tant que bibliothèque basée sur un fichier d’en-tête et conçue pour vous fournir un accès de première classe à l’API Windows moderne. Avec C++/WinRT, vous pouvez créer et consommer Windows Runtime API à l’aide de n’importe quel compilateur C++17 conforme aux normes. Le sdk Windows inclut C++/WinRT ; il a été introduit dans la version 10.0.17134.0 (Windows 10, version 1803).

C++/WinRT est le remplacement recommandé par Microsoft pour la projection de langage C++/CX et la bibliothèque de modèles C++ (WRL) Windows Runtime. La liste complète des sujets sur C++/WinRT comprend des informations à la fois sur l’interopérabilité avec C++/CX et WRL et sur la migration depuis C++/CX et WRL.

Voir également Où puis-je trouver des exemples d’applications C++/WinRT ?.

Projections linguistiques

Le Windows Runtime est basé sur les API COM (Component Object Model) et est conçu pour être accessible via des projections de langage. Une projection masque les détails COM et fournit une expérience de programmation plus naturelle pour un langage donné.

Projection du langage C++/WinRT dans le contenu de référence de l’API Windows Runtime

Lorsque vous parcourez Windows Runtime API, cliquez sur la zone de liste déroulante Langue en haut à droite, puis sélectionnez C++/WinRT pour afficher les blocs de syntaxe d'API lorsqu'ils apparaissent dans la projection de langage C++/WinRT.

Prise en charge de C++/WinRT, de XAML, de l’extension VSIX et du package NuGet dans Visual Studio

Pour Visual Studio support, vous aurez besoin de Visual Studio 2022, ou Visual Studio 2019 ou Visual Studio 2017 (au moins la version 15.6 ; nous vous recommandons au moins 15.7). À partir du programme d’installation Visual Studio, installez la charge de travail de développement plateforme Windows universelle. Dans Détails de l’installation>Développement de la plateforme Windows universelle, cochez l’option outils C++ (v14x) de la plateforme Windows universelle si ce n’est pas déjà fait. Et, dans Windows Paramètres>Confidentialité et sécurité (Windows 10 : Mise à jour et sécurité) >Pour les développeurs, activez l’option Mode développeur (Windows 10 : et non l’option Chargement indépendant des applications).

Bien que nous vous recommandions de développer avec les versions les plus récentes de Visual Studio et du SDK Windows, si vous utilisez une version de C++/WinRT fournie avec le SDK Windows antérieure à 10.0.17763.0 (Windows 10, version 1809), alors, pour utiliser les fichiers d’en-tête des espaces de noms Windows mentionnés ci-dessus, votre projet devra cibler au minimum la version 10.0.17134.0 du SDK Windows (Windows 10, version 1803).

Visual Studio 2022 est fourni avec des modèles de projet et d’élément C++/WinRT intégrés, afin que vous puissiez commencer à développer C++/WinRT immédiatement. Il inclut également la visualisation de débogage native de Visual Studio (natvis) des types projetés C++/WinRT, pour une expérience similaire à celle du débogage en C#. Natvis est automatique pour les builds de débogage. Pour plus d’informations, consultez la visualisation de débogage native dans Visual Studio pour C++/WinRT.

Pour les versions antérieures de Visual Studio, vous devez télécharger et installer la dernière version de l'extension Visual Studio C++/WinRT (VSIX) à partir de la Place de marché Visual Studio.

• L’extension VSIX vous donne des modèles de projet et d’élément C++/WinRT dans Visual Studio.
• En outre, il vous offre la visualisation de débogage native (natvis) dans Visual Studio pour les types projetés C++/WinRT.

Les modèles de projet Visual Studio pour C++/WinRT sont décrits dans les sections ci-dessous. Lorsque vous créez un projet C++/WinRT avec la dernière version de l’extension VSIX installée, le nouveau projet C++/WinRT installe automatiquement le Microsoft.Windows. Package NuGet CppWinRT. Microsoft.Windows. Le package NuGet CppWinRT fournit la prise en charge des builds C++/WinRT (propriétés et cibles MSBuild), ce qui rend votre projet portable entre un ordinateur de développement et un agent de build (sur lequel seul le package NuGet, et non l’extension VSIX, est installé).

Vous pouvez également convertir un projet existant en installant manuellement Microsoft.Windows. Package NuGet CppWinRT. Après avoir installé (ou mis à jour) la dernière version de l’extension VSIX, ouvrez le project existant dans Visual Studio, cliquez sur Project>Manage De packages NuGet...>Parcourez, tapez ou collez Microsoft.Windows. CppWinRT dans la zone de recherche, sélectionnez l’élément dans les résultats de recherche, puis cliquez sur Installer pour installer le package pour cette project. Une fois que vous avez ajouté le package, vous bénéficierez de la prise en charge MSBuild de C++/WinRT pour le projet, avec notamment l’invocation de l’outil cppwinrt.exe.

• Étant donné que C++/WinRT utilise des fonctionnalités de la norme C++17, le package NuGet définit la propriété de projet C/C++>Language>C++ Language Standard> dans Visual Studio.
• Il ajoute également l’option du compilateur /bigobj .
• Il ajoute l’option du compilateur /await pour activer co_await.
• Il indique au compilateur XAML d’émettre du codegen C++/WinRT.
• Vous pouvez également définir le mode Conformité : Oui (/permissive-) qui limite davantage votre code à être conforme aux normes.
• Une autre propriété du projet dont il faut tenir compte est C/C++>Général>Traiter les avertissements comme des erreurs. Définissez cette valeur sur Oui(/WX) ou Non (/WX-) au goût. Parfois, les fichiers sources générés par l’outil cppwinrt.exe génèrent des avertissements jusqu’à ce que vous y ajoutiez votre implémentation.

Une fois votre système configuré comme décrit ci-dessus, vous pourrez créer et générer, ou ouvrir un projet C++/WinRT dans Visual Studio, puis le déployer.

À partir de la version 2.0, le package NuGet Microsoft.Windows.CppWinRT comprend l’outil cppwinrt.exe. Vous pouvez pointer l’outil cppwinrt.exe sur un fichier de métadonnées Windows Runtime (.winmd) pour générer une bibliothèque C++ standard basée sur un fichier d’en-tête qui projette les API décrites dans les métadonnées pour la consommation à partir du code C++/WinRT. Les fichiers de métadonnées Windows Runtime (.winmd) offrent un moyen normalisé de décrire une surface de l’API Windows Runtime. En pointant sur les cppwinrt.exe métadonnées, vous pouvez générer une bibliothèque à utiliser avec n’importe quelle classe runtime implémentée dans un composant de Windows Runtime tiers ou secondaire, ou implémentée dans votre propre application. Pour plus d’informations, consultez Utiliser des API avec C++/WinRT.

Avec C++/WinRT, vous pouvez également implémenter vos propres classes runtime à l’aide de C++standard, sans recourir à la programmation de style COM. Pour une classe d’exécution, il vous suffit de décrire vos types dans un fichier IDL, et midl.exe ainsi que cppwinrt.exe génèrent pour vous les fichiers de code source de base de votre implémentation. Vous pouvez également simplement implémenter des interfaces en dérivant d’une classe de base C++/WinRT. Pour plus d’informations, consultez Créer des API avec C++/WinRT.

Pour obtenir la liste des options de personnalisation de l’outil cppwinrt.exe, définies via les propriétés du projet, consultez le fichier readme du package NuGet Microsoft.Windows.CppWinRT.

Vous pouvez identifier un projet qui utilise la prise en charge MSBuild de C++/WinRT à la présence du package NuGet Microsoft.Windows.CppWinRT installé dans le projet.

Voici les modèles de projet Visual Studio fournis par l’extension VSIX.

Application vide (C++/WinRT)

Modèle de projet pour une application Plateforme Windows universelle (UWP) qui a une interface utilisateur XAML. Pour les applications de bureau WinUI 3, utilisez plutôt le modèle Application vide, Empaquetée (WinUI 3 dans Desktop).

Visual Studio fournit la prise en charge du compilateur XAML pour générer des stubs d’implémentation et d’en-tête à partir du fichier IDL (.idlInterface Definition Language) qui se trouve derrière chaque fichier de balisage XAML. Dans un fichier IDL, définissez les classes runtime locales que vous souhaitez référencer dans les pages XAML de votre application, puis générez le projet une fois pour générer des modèles d’implémentation dans Generated Files, et des définitions de type stub dans Generated Files\sources. Utilisez ensuite ces définitions de type stub pour la référence pour implémenter vos classes runtime locales. Consultez Factorisation des classes d’exécution dans des fichiers MIDL (.idl).

Dans Visual Studio, la prise en charge de la surface de conception XAML pour C++/WinRT est presque au même niveau que pour C#. Dans Visual Studio, vous pouvez utiliser l’onglet Événements de la fenêtre Propriétés pour ajouter des gestionnaires d’événements dans un projet C++/WinRT. Vous pouvez également ajouter manuellement des gestionnaires d’événements à votre code : consultez Gérer les événements à l’aide de délégués en C++/WinRT pour plus d’informations.

Application principale (C++/WinRT)

Modèle de projet pour une application Plateforme Windows universelle (UWP) qui n'utilise pas XAML. Il n’existe pas d’équivalent WinUI 3 de ce modèle.

À la place, il utilise l’en-tête de l’espace de noms Windows de C++/WinRT pour l’espace de noms Windows.ApplicationModel.Core. Après avoir généré et exécuté, cliquez sur un espace vide pour ajouter un carré coloré ; cliquez ensuite sur un carré coloré pour le faire glisser.

Application de console Windows (C++/WinRT)

Modèle de projet pour une application cliente C++/WinRT pour Windows Desktop, avec une interface utilisateur console.

Application de bureau Windows (C++/WinRT)

Modèle de projet pour une application cliente C++/WinRT pour Windows Desktop, qui affiche un Windows Runtime Windows. Foundation.Uri à l’intérieur d’un MessageBox Win32.

Composant Windows Runtime (C++/WinRT)

Modèle de projet pour un composant ; généralement pour la consommation à partir d’un Plateforme Windows universelle (UWP).

Ce modèle illustre la chaîne d’outils midl.exe>cppwinrt.exe, où les métadonnées Windows Runtime (.winmd) sont générées à partir de l’IDL, puis les squelettes d’implémentation et d’en-tête sont générés à partir des métadonnées Windows Runtime.

Dans un fichier IDL, définissez les classes runtime dans votre composant, leur interface par défaut et toutes les autres interfaces qu’ils implémentent. Compilez le projet une fois pour générer module.g.cpp, module.h.cpp, des modèles d’implémentation dans Generated Files, et des définitions de types factices dans Generated Files\sources. Utilisez ensuite ces définitions de type stub pour référencer les classes runtime dans votre composant. Consultez Intégration des classes d’exécution dans des fichiers MIDL (.idl).

Regroupez le fichier binaire du composant Windows Runtime généré et son .winmd avec l’application UWP qui les consomme.

Versions antérieures de l’extension VSIX

Nous vous recommandons d’installer (ou de mettre à jour vers) la dernière version de l’extension VSIX. Il est configuré pour se mettre à jour par défaut. Si vous le faites et que vous avez des projets qui ont été créés avec une version de l’extension VSIX antérieure à 1.0.190128.4, cette section contient des informations importantes sur la mise à niveau de ces projets pour fonctionner avec la nouvelle version. Si vous ne mettez pas à jour, vous trouverez toujours les informations de cette section utiles.

En ce qui concerne les versions prises en charge du kit SDK Windows et de Visual Studio, ainsi que la configuration de Visual Studio, les informations de la section Prise en charge de Visual Studio pour C++/WinRT, XAML, l’extension VSIX et le package NuGet ci-dessus s’appliquent aux versions antérieures de l’extension VSIX. Les informations ci-dessous décrivent les différences importantes concernant le comportement et la configuration des projets créés avec (ou mis à niveau pour fonctionner avec) les versions antérieures.

Créé avant la version 1.0.181002.2

Si votre projet a été créé avec une version de l’extension VSIX antérieure à 1.0.181002.2, la prise en charge de la build C++/WinRT a été intégrée à cette version de l’extension VSIX. Votre projet a la <CppWinRTEnabled>true</CppWinRTEnabled> propriété définie dans le .vcxproj fichier.

<Project ...>
    <PropertyGroup Label="Globals">
        <CppWinRTEnabled>true</CppWinRTEnabled>
...

Vous pouvez mettre à niveau votre projet en installant manuellement le package NuGet Microsoft.Windows.CppWinRT. Après avoir installé (ou mis à niveau vers) la dernière version de l’extension VSIX, ouvrez votre project dans Visual Studio, cliquez sur Project>Manage de packages NuGet...>Parcourez, tapez ou collez Microsoft.Windows. CppWinRT dans la zone de recherche, sélectionnez l’élément dans les résultats de recherche, puis cliquez sur Installer pour installer le package pour votre project.

Créé avec (ou mis à niveau vers) entre 1.0.181002.2 et 1.0.190128.3

Si votre projet a été créé avec une version de l’extension VSIX comprise entre 1.0.181002.2 et 1.0.190128.3, bornes incluses, alors le package NuGet Microsoft.Windows.CppWinRT a été automatiquement installé dans le projet par le modèle de projet. Vous avez peut-être également mis à niveau un projet plus ancien pour utiliser une version de l’extension VSIX comprise dans cette plage. Si vous l’avez fait, alors — puisque la prise en charge de la génération était également toujours présente dans les versions de l’extension VSIX de cette gamme — votre projet mis à niveau peut inclure ou non le package NuGet Microsoft.Windows.CppWinRT.

Pour mettre à niveau votre projet, suivez les instructions de la section précédente et vérifiez que votre projet a bien le package NuGet Microsoft.Windows.CppWinRT installé.

Configurations de mise à niveau non valides

Avec la dernière version de l’extension VSIX, un projet ne peut pas comporter la propriété <CppWinRTEnabled>true</CppWinRTEnabled> s’il n’a pas également le package NuGet Microsoft.Windows.CppWinRT installé. Un projet avec cette configuration génère le message d’erreur de génération : « Le VSIX C++/WinRT ne fournit plus la prise en charge de la génération de projet. Ajoutez une référence de projet au Microsoft.Windows. Package Nuget CppWinRT. »

Comme mentionné ci-dessus, un projet C++/WinRT doit maintenant avoir installé le package NuGet.

Étant donné que l’élément <CppWinRTEnabled> est désormais obsolète, vous pouvez éventuellement modifier votre .vcxprojélément et supprimer l’élément. Ce n’est pas strictement nécessaire, mais c’est une option.

En outre, si votre .vcxproj contient <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, vous pouvez le supprimer afin de pouvoir générer sans nécessiter l’installation de l’extension VSIX C++/WinRT.

Prise en charge du Kit de développement logiciel (SDK) pour C++/WinRT

Bien qu’il soit désormais présent uniquement pour des raisons de compatibilité, à partir de la version 10.0.17134.0 (Windows 10, version 1803), le KIT de développement logiciel (SDK) Windows contient une bibliothèque C++ standard basée sur un en-tête pour consommer des API Windows internes (Windows Runtime API dans Windows espaces de noms). Ces en-têtes se trouvent dans le dossier %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. À partir de la version 10.0.17763.0 du SDK Windows (Windows 10, version 1809), ces en-têtes sont générés pour vous dans le dossier $(GeneratedFilesDir) de votre projet.

Là encore, pour la compatibilité, le sdk Windows est également fourni avec l’outilcppwinrt.exe. Toutefois, nous vous recommandons d’installer et d’utiliser à la place la version la plus récente de cppwinrt.exe, incluse dans la Microsoft.Windows. Package NuGet CppWinRT. Ce package et cppwinrt.exe, sont décrits dans les sections ci-dessus.

Types personnalisés dans la projection C++/WinRT

Dans votre programmation C++/WinRT, vous pouvez utiliser des fonctionnalités de langage C++ standard et des types de données C++ standard et C++/WinRT, y compris certains types de données de bibliothèque standard C++. Mais vous découvrirez aussi certains types de données personnalisés dans la projection, et vous pourrez choisir de les utiliser. Par exemple, nous utilisons winrt ::hstring dans l’exemple de code de démarrage rapide dans Prise en main de C++/WinRT.

winrt ::com_array est un autre type que vous êtes susceptible d’utiliser à un moment donné. Mais vous êtes moins susceptible d’utiliser directement un type tel que winrt ::array_view. Vous pouvez également choisir de ne pas l’utiliser afin que vous n’ayez pas de code à modifier si et quand un type équivalent apparaît dans la bibliothèque C++ Standard.

API importantes

• struct winrt::hstring
• espace de noms WinRT

Rubriques connexes

• C++/CX
• Extension de Visual Studio C++/WinRT (VSIX)
• Bien démarrer avec C++/WinRT
• Types de données C++ standard et C++/WinRT
• Gestion des chaînes en C++/WinRT
• API de Windows Runtime