Partager via

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ées en tant que bibliothèque basée sur un fichier d’en-tête et conçues pour vous fournir un accès de première classe à l’API Windows moderne. Avec C++/WinRT, vous pouvez créer et consommer des API Windows Runtime à l’aide de n’importe quel compilateur C++17 conforme aux normes. Le Kit de développement logiciel (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++ Windows Runtime (WRL). La liste complète des rubriques sur C++/WinRT inclut des informations à la fois sur l'interopérabilité avec, et le portage depuis, C++/CX et WRL.

Important

Certains des éléments les plus importants de C++/WinRT à connaître sont décrits dans les sections de prise en charge du Kit de développement logiciel (SDK) pour C++/WinRT et Visual Studio pour C++/WinRT, XAML, l’extension VSIX et le package NuGet.

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

Prévisions linguistiques

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 les API Windows Runtime, cliquez sur la zone de liste déroulante Langue dans le coin supérieur droit, 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 Visual Studio pour C++/WinRT, XAML, l’extension VSIX et le package NuGet

Pour la prise en charge de Visual Studio, 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). Depuis le Visual Studio Installer, installez l'ensemble d'outils de développement de la plate-forme Windows Universelle . Dans Détails de l’installation>Développement de la plateforme Windows universelle, vérifiez l'option des outils de la plateforme Windows universelle C++ (v14x) si vous ne l’avez pas déjà fait. Et, dans ParamètresConfidentialité & sécurité (Windows 10 : Mise à jour & sécurité) Pour développeurs, activez l’option Mode développeur (Windows 10 : pas l’option Chargement indépendant des applications).

Bien que nous vous recommandons de développer avec les dernières versions de Visual Studio et du Kit de développement logiciel (SDK) Windows, si vous utilisez une version de C++/WinRT fournie avec le Kit de développement logiciel (SDK) Windows antérieure à la version 10.0.17763.0 (Windows 10, version 1809), puis, pour utiliser les en-têtes d’espaces de noms Windows mentionnés ci-dessus, vous aurez besoin d’une version cible minimale du SDK Windows dans votre projet 10.0.17134.0 (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 est également fourni avec la visualisation de débogage native de Visual Studio (natvis) des types projetés C++/WinRT, ce qui offre une expérience similaire au débogage C#. Natvis est activé automatiquement pour les builds de débogage. Pour plus d’informations, consultez Visualisation de débogage native de 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 Visual Studio Marketplace.

  • 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 de Visual Studio (natvis) 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 package NuGet Microsoft.Windows.CppWinRT. Le package NuGet Microsoft.Windows.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 le package NuGet Microsoft.Windows.CppWinRT . Après avoir installé (ou mis à jour) la dernière version de l’extension VSIX, ouvrez le projet existant dans Visual Studio, cliquez sur Project>Manage NuGet Packages...>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 ce projet. Une fois que vous avez ajouté le package, vous bénéficierez de la prise en charge de C++/WinRT MSBuild pour le projet, y compris la possibilité d'invoquer l'outil cppwinrt.exe.

Important

Si vous avez des projets créés avec (ou mis à niveau pour fonctionner avec) une version de l’extension VSIX antérieure à la version 1.0.190128.4, consultez les versions antérieures de l’extension VSIX. Cette section contient des informations importantes sur la configuration de vos projets, que vous devez savoir pour les mettre à niveau pour utiliser la dernière version de l’extension VSIX.

  • É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é de projet à connaître est C/C++>Général>Traiter les avertissements comme des erreurs. Définissez cette valeur sur Oui(/WX) ou Non (/WX-) selon vos préférences. 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 et le déployer.

À compter de la version 2.0, le package NuGet Microsoft.Windows.CppWinRT inclut 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 projets les API décrites dans les métadonnées pour la consommation à partir du code C++/WinRT. Les fichiers de métadonnées.winmd Windows Runtime fournissent un moyen canonique de décrire une surface d’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 Windows Runtime secondaire ou tiers, ou implémentée dans votre propre application. Pour plus d’informations, consultez Consommer 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, vous décrivez simplement vos types dans un fichier IDL, et midl.exe et cppwinrt.exe génèrent vos fichiers de code source d'implémentation standard pour vous. 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 définies via les propriétés du projet, consultez le fichier readmedu package NuGet Microsoft.Windows.CppWinRT .

Vous pouvez identifier un projet qui utilise la prise en charge MSBuild C++/WinRT par 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 de plateforme Windows universelle (UWP) qui a une interface utilisateur XAML.

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 les fichiers Midl (.idl).

La prise en charge de la surface de conception XAML dans Visual Studio pour C++/WinRT est proche de la parité avec 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 de plateforme Windows universelle (UWP) qui n’utilise pas XAML.

Au lieu de cela, il utilise l’en-tête d’espace de noms Windows 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 Console de 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 une Windows.Foundation.Uri Windows Runtime dans unMessageBox Win32.

Composant Windows Runtime (C++/WinRT)

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

Ce modèle illustre la midl.exe>cppwinrt.exe chaîne d’outils, où les métadonnées Windows Runtime (.winmd) sont générées à partir d’IDL, puis les stubs 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. Construisez le projet une fois pour générer module.g.cpp, des modèles d'implémentation dans module.h.cpp, et des définitions de type stub dans Generated Files. Utilisez ensuite ces définitions de type stub pour référencer les classes runtime dans votre composant. Consultez factorisation des classes d'exécution dans les 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 termes de sdk Windows et de versions de Visual Studio prises en charge et de la configuration de Visual Studio, les informations contenues dans le prise en charge de Visual Studio pour C++/WinRT, XAML, l’extension VSIX et la section 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éé antérieurement à 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 projet dans Visual Studio, cliquez sur Project>Manage NuGet Packages...>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 de votre projet.

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, inclus, le package NuGet Microsoft.Windows.CppWinRT a été installé automatiquement dans le projet par le modèle de projet. Vous avez peut-être également mis à jour un projet plus ancien pour utiliser une version de l’extension VSIX dans cette plage. Si vous l’avez fait, puisque le support de la génération était toujours présent dans les versions de l’extension VSIX dans cette plage, il est possible que votre projet mis à niveau ait ou n'ait pas installé 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 dispose des Microsoft.Windows.CppWinRT package NuGet installé.

Configurations de mise à niveau non valides

Avec la dernière version de l’extension VSIX, il n'est pas valide qu'un projet ait 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 package Nuget Microsoft.Windows.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 fichier d’en-tête pour consommer des API Windows tierces (API Windows Runtime dans les espaces de noms Windows). Ces en-têtes se trouvent dans le dossier %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. À compter de la version 10.0.17763.0 (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 Kit de développement logiciel (SDK) Windows est également fourni avec l’outil cppwinrt.exe . Toutefois, nous vous recommandons d’installer et d’utiliser la version la plus récente de cppwinrt.exe, incluse dans le package NuGet Microsoft.Windows.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 types de données C++ Standard et C++/WinRT, y compris certains types de données de bibliothèque standard C++. Toutefois, vous prendrez également connaissance de certains types de données personnalisés dans la projection, et vous pouvez 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.

Avertissement

Il existe également des types que vous pouvez voir si vous étudiez attentivement les en-têtes d’espace de noms Windows C++/WinRT. Un exemple est winrt::param::hstring, mais il existe également des exemples de collection. Il s'agit uniquement d'optimiser la liaison des paramètres d'entrée, ce qui entraîne de grandes améliorations de performance et permet à la plupart des modèles d'appel de fonctionner parfaitement avec les types et conteneurs C++ standard associés. Ces types ne sont utilisés par la projection que dans les cas où ils apportent le plus de valeur. Ils sont hautement optimisés et ne sont pas utilisés en général ; ne soyez pas tenté de les utiliser vous-même. Vous ne devez pas non plus utiliser les éléments de l'espace de noms winrt::impl, car ce sont des types d'implémentation et donc susceptibles de changer. Vous devez continuer à utiliser des types standard ou des types à partir de l’espace de noms winrt.

Consultez également Passage de paramètres dans la limite ABI.

API importantes