C#/WinRT

C#/WinRT est une boîte à outils NuGet qui fournit la prise en charge de la projection 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 à des équivalents .NET appropriés, tels que des chaînes, des URI, des types de valeurs communs et des collections génériques.

C#/WinRT prend actuellement en charge la consommation d’API WinRT par le biais de l’utilisation des monikers du framework cible (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 assemblys 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 GitHub C#/WinRT.

Motivations pour C#/WinRT

.NET (précédemment appelé .NET Core) est un runtime open source multiplateforme qui peut être utilisé pour créer des applications IoT, cloud et appareil.

Les versions précédentes de .NET Framework et .NET Core avaient 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’avons déplacée dans le kit de ressources C#/WinRT (voir la prise en charge intégrée 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 les mappages .NET des types Windows Runtime.

C#/WinRT prend également en charge les composants du Kit de développement logiciel (SDK) d’application Windows, y compris WinUI. Le Kit de développement logiciel (SDK) d’application Windows supprime les contrôles d’interface utilisateur Microsoft natifs et d’autres composants natifs 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 le runtime .NET.

Quoi de neuf

Vous trouverez les dernières versions C#/WinRT sur notre page de notes de publication 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 d’utilisation de 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 du code C# .NET. 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 avec l’assembly d’implémentation pour les applications .NET à référencer, généralement en tant que 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, un projet d’application peut suivre la procédure de génération d’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 des sources de projection et d’exécution du SDK Windows pour .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 des Microsoft.Windows.SDK.NET.dll qui réduisent 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 incorporée C#/WinRT 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 gratuite de WinRT (voir Amélioration des applications de bureau non empaquetées à l’aide des composants Windows Runtime), disponible dans Windows 10, version 1903 et ultérieure. Les composants C++ natifs doivent définir la propriété Compatible Windows Desktop sur Vrai via les propriétés du projet ou le .vcxproj fichier afin de référencer et transférer les binaires Microsoft.VCLibs.Desktop aux applications qui les utilisent. 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é de <CsWinRTWindowsMetadata> projet, 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é, reportez-vous à la documentation sur <TargetFramework>.

• 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é Compatible avec le bureau Windows sur True via les propriétés du projet ou via le .vcxproj fichier.

Erreurs de contrôle de version du Kit de développement logiciel (SDK) .NET

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

Message d’erreur ou d’avertissement	Reason
Avertissement MSB3277 : conflits détectés entre différentes versions de WinRT.Runtime ou Microsoft.Windows.SDK.NET qui n’ont pas pu être résolus.	Cet avertissement de build se produit lors du référencement d’une bibliothèque qui expose les types du Kit de développement logiciel (SDK) Windows sur sa surface d’API.
Erreur CS1705 : L’assembly 'AssemblyName1' utilise 'TypeName' qui a une version supérieure à l’assembly référencé 'AssemblyName2'	Cette erreur du compilateur de build se produit lors du référencement et de l’utilisation des types de SDK Windows exposés dans une bibliothèque.
System.IO.FileLoadException	Cette erreur d’exécution peut se produire lors de l’appel de certaines API dans une bibliothèque qui n’expose pas les types de SDK Windows.

Pour corriger ces erreurs, mettez à jour votre Kit de développement logiciel (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 du Kit de développement logiciel (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 modifications perturbatrices sont notés dans le dépôt GitHub C#/WinRT.

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

• Dépôt GitHub C#/WinRT