C#/WinRT

C#/WinRT est un outil sous forme de package NuGet qui fournit la prise en charge des projections de Windows Runtime (WinRT) pour le langage C#. Un assembly de projection est un assembly d’interopérabilité, qui permet de programmer des API WinRT de manière naturelle et familière pour le langage cible. La projection C#/WinRT masque les détails de l’interopérabilité entre les interfaces C# et WinRT, et fournit des mappages de nombreux types WinRT vers des équivalents .NET appropriés, tels que des chaînes, des URI, des types de valeurs courants et des collections génériques.

C#/WinRT prend actuellement en charge la consommation d’API WinRT par le biais de l’utilisation de Target Framework Monikers (TFMs) dans .NET. La définition du TFM avec une version spécifique du Kit de développement logiciel (SDK) Windows ajoute des références aux assemblys de projection et d’exécution du Kit de développement logiciel (SDK) Windows générés par C#/WinRT.

Le package NuGet C#/WinRT vous permet de créer et de référencer vos propres assemblies d’interopérabilité WinRT pour les consommateurs .NET. La dernière version C#/WinRT inclut également un aperçu de la création de types WinRT en C#.

Pour plus d’informations, consultez le dépôt C#/WinRT GitHub.

Motivations pour C#/WinRT

.NET (anciennement .NET Core) est un runtime open source multiplateforme qui peut être utilisé pour générer des applications appareil, cloud et IoT.

Les versions précédentes de .NET Framework et de .NET Core possédaient une connaissance intégrée de WinRT, une technologie spécifique à Windows. Pour prendre en charge les objectifs de portabilité et d’efficacité de .NET 6+, nous avons levé la prise en charge de la projection WinRT hors du compilateur et du runtime .NET et l’avez déplacée dans le kit de ressources C#/WinRT (voir Prise en charge de WinRT est supprimée de .NET). L’objectif de C#/WinRT est de fournir une parité avec la prise en charge intégrée de WinRT fournie par les versions antérieures du compilateur C# et du runtime .NET. Pour plus d’informations, consultez .NET correspondances des types Windows Runtime.

C#/WinRT prend également en charge les composants du Windows App SDK, y compris WinUI 3. Le Windows App SDK supprime les contrôles d’interface utilisateur Microsoft natifs et d’autres composants natifs hors du système d’exploitation. Cela permet aux développeurs d’applications d’utiliser les derniers contrôles et composants sur Windows 10, version 1809 et versions ultérieures.

Enfin, C#/WinRT est un kit de ressources général et est destiné à prendre en charge d’autres scénarios où la prise en charge intégrée de WinRT n’est pas disponible dans le compilateur C# ou .NET runtime.

Quoi de neuf

Vous trouverez les dernières versions de C#/WinRT dans notre page release dans le dépôt Github.

Usage

Le package NuGet C#/WinRT peut être utilisé pour générer des projections C# (également appelées assemblys d’interopérabilité) à partir de composants WinRT et pour la création de composants C#/WinRT. Pour plus d’informations sur les scénarios d’utilisation pour C#/WinRT, reportez-vous au guide usage sur notre dépôt.

Générer et distribuer un assembly d’interopérabilité

Les API WinRT sont définies dans les fichiers De métadonnées Windows (WinMD). Le package NuGet C#/WinRT (Microsoft.Windows.CsWinRT) inclut le compilateur C#/WinRT, cswinrt.exe, que vous pouvez utiliser pour traiter les fichiers WinMD et générer .NET code C#. C#/WinRT compile ces fichiers sources dans un assembly d’interopérabilité, comme la façon dont C++/WinRT génère des en-têtes pour la projection de langage C++. Vous pouvez ensuite distribuer l'assembly d'interopérabilité C#/WinRT ainsi que l'assembly d'implémentation pour que les applications .NET puissent les référencer, généralement sous forme de package NuGet.

Pour plus d’informations sur la génération et la distribution d’un assembly d’interopérabilité, consultez Générer une projection C# à partir d’un composant C++/WinRT, distribuer en tant que NuGet pour les applications .NET.

Référencer un assembly d’interopérabilité

En règle générale, les assemblages d’interopérabilité C#/WinRT sont référencés par les projets d’application. Mais ils peuvent également être référencés à leur tour par des assemblées d’interopérabilité intermédiaires. Par exemple, l’assembly d’interopérabilité WinUI référence l’assembly d’interopérabilité du Kit de développement logiciel (SDK) Windows.

Si vous distribuez un composant WinRT tiers sans assembly d’interopérabilité officiel, une application project peut suivre la procédure pour générer un assembly d’interopérabilité pour générer ses propres sources de projection privées. Nous vous déconseillons cette approche, car elle peut produire des projections conflictuelles du même type au sein d’un processus. L’empaquetage NuGet, suivant le schéma de gestion de version sémantique , est conçu pour empêcher cela. Un assembly d’interopérabilité tiers officiel est préféré.

Prise en charge incorporée des types WinRT (aperçu)

À compter de C#/WinRT version 1.4.1, la prise en charge est incluse pour l'incorporation de sources de projection et d'exécution du Kit de développement logiciel (SDK) Windows pour les .NET et .NET Standard 2.0 dans la sortie de votre bibliothèque ou application. Cela est utile dans les cas où l’utilisation des types de SDK Windows est autonome. La prise en charge incorporée supprime les dépendances des WinRT.Runtime.dll et microsoft.Windows.SDK.NET.dll ce qui réduit la taille de sortie de la bibliothèque ou de l’application. Il permet également aux développeurs de bibliothèques de fournir une prise en charge de niveau inférieur et supprime la nécessité d’un ciblage multiple.

Pour plus d’informations, consultez la documentation C#/WinRT incorporée sur notre dépôt.

Activation de type WinRT

C#/WinRT prend en charge l’activation des types WinRT hébergés par le système d’exploitation, ainsi que des composants tiers tels que Win2D. La prise en charge de l’activation de composants tiers dans une application de bureau est activée avec l’activation sans enregistrement de WinRT (voir Améliorer les applications de bureau non empaquetées en utilisant des composants Windows Runtime), disponible dans Windows 10, version 1903 et ultérieures. Les composants C++ natifs doivent définir la propriété Windows Desktop Compatible sur True via les propriétés project ou le fichier .vcxproj, pour référencer et transférer les fichiers binaires Microsoft.VCLibs.Desktop aux applications consommatrices. Sinon, le package VCRT Forwarders sera requis par les applications utilisant le composant si celui-ci cible uniquement les applications UWP.

C#/WinRT fournit également un chemin de repli d’activation si Windows ne parvient pas à activer le type comme décrit ci-dessus. Dans ce cas, C#/WinRT tente de localiser une DLL d’implémentation native basée sur le nom de type complet, supprimant progressivement les éléments. Par exemple, la logique de secours tenterait d’activer le type Contoso.Controls.Widget à partir des modules suivants, en séquence :

1. Contoso.Controls.Widget.dll
2. Contoso.Controls.dll
3. Contoso.dll

C#/WinRT utilise l’ordre de recherche de remplacement LoadLibrary pour localiser une DLL d’implémentation. Une application qui s’appuie sur ce comportement de secours doit empaqueter la DLL d’implémentation en même temps que le module d’application.

Erreurs courantes et résolution des problèmes

• Erreur : « Métadonnées Windows non fournies ou détectées ».

  Vous pouvez spécifier des métadonnées Windows à l’aide de la propriété <CsWinRTWindowsMetadata> project, par exemple :

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  Dans C#/WinRT version 1.2.1 et ultérieure, cette propriété est par défaut TargetPlatformVersiondérivée de la version du Kit de développement logiciel (SDK) Windows spécifiée dans la TargetFramework propriété.

• Erreur CS0246 : Impossible de trouver le nom du type ou de l’espace de noms « Windows » (manquez-vous une directive using ou une référence d’assembly ?)

  Pour résoudre cette erreur, modifiez votre <TargetFramework> propriété pour cibler une version Spécifique de Windows, par exemple :

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

  Pour plus d’informations sur la spécification de la propriété <TargetFramework>, reportez-vous à la documentation sur Appeler les API Windows Runtime.

• System.InvalidCastException lors de la conversion vers une interface qui a l’attribut ComImport

  Lors du cast d’un objet vers une interface qui a l’attribut ComImport , vous devez utiliser l’opérateur .As<> au lieu d’utiliser une expression de cast explicite. Par exemple:

  someObject.As<SomeComImportInterface>
  

  Pour plus d’informations, consultez le guide d’interopérabilité COM.

• System.Runtime.InteropServices.COMException : classe non inscrite (0x80040154 (REGDB_E_CLASSNOTREG))

  • Si vous voyez cette exception lors de l’utilisation d’une projection C#/WinRT à partir d’un composant C++/WinRT, vérifiez que le composant a défini la propriété Windows Desktop Compatible sur True via les propriétés project ou via le fichier .vcxproj.

erreurs de contrôle de version du KIT de développement logiciel (SDK) .NET

Vous pouvez rencontrer les erreurs ou avertissements suivants dans un project généré avec une version antérieure du SDK .NET que l’une de ses dépendances.

Pour corriger ces erreurs, mettez à jour votre sdk .NET vers la dernière version. Cela garantit que les versions d’assembly du kit de développement logiciel (SDK) runtime et Windows utilisées par votre application sont compatibles avec toutes les dépendances. Ces erreurs peuvent se produire avec des mises à jour de maintenance/de fonctionnalités anticipées dans le sdk .NET, car les correctifs d’exécution peuvent nécessiter des mises à jour de nos versions d’assembly.

Problèmes connus

Les problèmes connus et les changements majeurs sont notés dans le dépôt C#/WinRT GitHub.

Si vous rencontrez des problèmes fonctionnels avec le package NuGet C#/WinRT, le compilateur cswinrt.exe ou les sources de projection générées, envoyez-nous des problèmes via la page des problèmes C#/WinRT.

Ressources supplémentaires

• C#/WinRT GitHub référentiel