Partager via

C#/WinRT

  • Article

C#/WinRT est un kit de ressources empaqueté dans NuGet qui fournit une 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 aux équivalents .NET appropriés, comme des chaînes, des URI, des types valeur courants et des collections génériques.

C#/WinRT prend en charge la consommation des API WinRT via l’utilisation de TFM (monikers de framework cible) dans .NET. La définition du TFM avec une version spécifique du kit SDK Windows ajoute des références aux assemblys de projection et de runtime du kit 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 de C#/WinRT comprend é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.

Motivation pour C#/WinRT

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

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

C#/WinRT prend également en charge les composants du SDK d’application Windows, notamment WinUI 3. Le SDK d’application Windows extrait du système d’exploitation des contrôles d’interface utilisateur Microsoft natifs et d’autres composants natifs. Les développeurs d’applications peuvent ainsi utiliser les derniers contrôles et composants disponibles sur Windows 10 versions 1809 et ultérieures.

Enfin, C#/WinRT est un kit de ressources général conçu pour 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.

Nouveautés

Les dernières versions de C#/WinRT sont accessibles dans la page des notes de publication de notre dépôt GitHub.

Utilisation

Le package NuGet C#/WinRT permet de générer des projections C# (également appelées « assemblys d’interopérabilité ») à partir de composants WinRT et de créer des composants C#/WinRT. Pour plus d’informations sur les scénarios d’utilisation de C#/WinRT, reportez-vous au guide d’utilisation dans notre dépôt.

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

Les API WinRT sont définies dans des fichiers de métadonnées Windows (WinMD). Le package NuGet C#/WinRT (Microsoft.Windows.CsWinRT) comprend le compilateur C#/WinRT, cswinrt.exe, qui vous permet de traiter les fichiers WinMD et de générer du code C# .NET. C#/WinRT compile ces fichiers sources en un assembly d’interopérabilité, à peu près de la même façon que C++/WinRT génère des en-têtes pour la projection du langage C++. Vous pouvez alors distribuer l’assembly d’interopérabilité C#/WinRT avec l’assembly d’implémentation pour les applications .NET à référencer, en général sous forme d’un 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 et la distribuer sous forme de package NuGet pour les applications .NET.

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

En général, les assemblys d’interopérabilité C#/WinRT sont référencés par les projets d’application. Mais ils peuvent également être, à leur tour, référencés par des assemblys d’interopérabilité intermédiaires. Par exemple, l’assembly d’interopérabilité WinUI fait référence à l’assembly d’interopérabilité du 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 ne recommandons pas cette approche, car elle peut produire des projections en conflit du même type dans un processus. La création de package NuGet, qui suit le schéma de gestion sémantique de version, est conçue pour éviter cela. Utilisez de préférence un assembly d’interopérabilité tiers officiel.

Prise en charge incorporée des types WinRT (préversion)

À compter de C#/WinRT version 1.4.1, vous pouvez incorporer les sources de projection et de runtime du SDK Windows pour .NET et .NET Standard 2.0 dans la sortie de votre bibliothèque ou application. Cela est utile lorsque les types du SDK Windows sont utilisés de manière autonome. La prise en charge incorporée supprime les dépendances à 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. Cela permet également aux développeurs de bibliothèques de prendre en charge des versions antérieures, éliminant ainsi le recours au multiciblage.

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

Activation du type WinRT

C#/WinRT prend en charge l’activation de types WinRT hébergés par le système d’exploitation, ainsi que des composants tiers comme Win2D. La prise en charge de l’activation de composants tiers dans une application de bureau est rendue possible avec l’activation WinRT sans inscription (voir Augmenter les applications de bureau sans package avec les composants de runtime Windows), disponible dans Windows 10 version 1903 et les ultérieures. Les composants C++ natifs doivent définir la propriété Windows Desktop Compatible sur True via les propriétés du projet ou le fichier .vcxproj afin de référencer et transférer les binaires Microsoft.VCLibs.Desktop aux applications consommatrices. Dans le cas contraire, le package VCRT Forwarders sera demandé par les applications consommatrices si le composant cible uniquement les applications UWP.

C#/WinRT fournit également un chemin d’activation de secours 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 complet du type, en supprimant progressivement des éléments. Par exemple, la logique de secours tentera d’activer le type Contoso.Controls.Widget à partir des modules suivants, dans l’ordre :

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

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

Erreurs fréquentes et résolution des problèmes

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

    Vous pouvez spécifier des métadonnées Windows en utilisant la propriété de projet <CsWinRTWindowsMetadata>, par exemple :

    <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>

    Dans C#/WinRT version 1.2.1 et les versions ultérieures, la valeur par défaut de cette propriété est TargetPlatformVersion. Elle est dérivée de la version du kit SDK Windows spécifiée dans la propriété TargetFramework.

  • Erreur CS0246 : Le type ou le nom de l’espace de noms « Windows » est introuvable (une directive using ou une référence d’assembly est-elle manquante ?)

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

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

    Reportez-vous à la documentation sur l’Appel des API Windows Runtime pour plus de détails sur la spécification de la propriété <TargetFramework>.

  • System.InvalidCastException lors d’un cast en une interface qui a l’attribut ComImport

    Lorsque vous effectuez un cast d’un objet en une interface qui a l’attribut ComImport, vous devez utiliser l’opérateur .As<> au lieu d’une expression Cast explicite. Par exemple :

    someObject.As<SomeComImportInterface>

    Pour plus d’informations, consultez le guide COM Interop.

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

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

Erreurs de versioning du kit SDK .NET

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

Message d'erreur ou d’avertissement Motif
Avertissement MSB3277 : Détection de conflits entre les 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 des types de SDK Windows sur sa surface d’API.
Erreur CS1705: L’assembly 'AssemblyName1' utilise 'TypeName' dont la version est supérieure à celle de l’assembly référencé 'AssemblyName2' Cette erreur du compilateur de build se produit lors du référencement et de la consommation 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 de types SDK Windows.

Pour corriger ces erreurs, mettez à jour votre kit SDK .NET avec la dernière version. Cette mise à jour permet de vous assurer que les versions d’assembly de SDK Windows et de runtime utilisées par votre application sont compatibles avec toutes les dépendances. Ces erreurs peuvent se produire avec des mises à jour de fonctionnalités ou de maintenance anticipées du kit SDK .NET, car les correctifs de runtime peuvent demander des mises à jour de vos versions d’assembly.

Problèmes connus

Les problèmes connus et les changements cassants 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, signalez-les-nous par le biais de la page relative aux problèmes liées à C#/WinRT.

Ressources supplémentaires