C#/WinRT

A C#/WinRT egy NuGet-csomagú eszközkészlet, amely Windows-futtatókörnyezet (WinRT) vetítési támogatást nyújt a C# nyelvhez. A projection assembly egy együttműködő szerelvény, amely lehetővé teszi a WinRT API-k természetes és ismerős módon történő programozását a célnyelven. A C#/WinRT-vetítés elrejti a C# és a WinRT interfészek közötti interopció részleteit, és számos WinRT-típus megfeleltetését biztosítja a megfelelő .NET-ekvivalenseknek, például sztringeknek, URI-knak, általános értéktípusoknak és általános gyűjteményeknek.

A C#/WinRT jelenleg a .NET keretében a Target Framework Monikers (TFM-ek) használatával támogatja a WinRT API-k fogyasztását. Ha a TFM-et egy adott Windows SDK-verzióval állítja be, hivatkozásokat ad a C#/WinRT által létrehozott Windows SDK-vetítésre és futtatókörnyezet-szerelvényekre.

A C#/WinRT NuGet csomag lehetővé teszi, hogy létrehoz és hivatkozik saját WinRT interop assembly-ket .NET felhasználók számára. A legújabb C#/WinRT-verzió támogatja a WinRT-típusok C#-ban való készítését is.

További információ: C#/WinRT GitHub adattár.

A C#/WinRT motivációja

.NET (korábbi nevén .NET Core) egy nyílt forráskódú, platformfüggetlen futtatókörnyezet, amely eszköz-, felhő- és IoT-alkalmazások készítésére használható.

A .NET Framework és a .NET Core korábbi verziói beépített ismeretekkel rendelkeztek a WinRT-ről – Windows-specifikus technológiáról. A 6+ .NET hordozhatósági és hatékonysági céljainak támogatása érdekében eltávolítottuk a WinRT-kivetítési támogatást a .NET fordítóból és a futtatókörnyezetből, és áthelyeztük a C#/WinRT eszközkészletbe (lásd A WinRT beépített támogatása el lett távolítva .NET). A C#/WinRT célja, hogy paritást biztosítson a C# fordító és a .NET futtatókörnyezet korábbi verziói által biztosított beépített WinRT-támogatással. További információ: .NET Windows-futtatókörnyezet típusok leképezése.

A C#/WinRT a Windows App SDK összetevőit is támogatja, beleértve a WinUI 3-at is. A Windows App SDK natív Microsoft felhasználói felületi vezérlőket és más natív összetevőket emel ki az operációs rendszerből. Ez lehetővé teszi, hogy az alkalmazásfejlesztők a legújabb vezérlőket és összetevőket használják Windows 10, 1809-es és újabb kiadásokon.

Végül a C#/WinRT egy általános eszközkészlet, amely más olyan forgatókönyvek támogatására szolgál, ahol a WinRT beépített támogatása nem érhető el a C# fordítóban vagy .NET futtatókörnyezetben.

Mik az újdonságok?

A legújabb C#/WinRT-kiadások a release jegyzeteinkben az GitHub adattárban találhatók.

Usage

A C#/WinRT NuGet-csomagot lehet használni C#-vetületek (más néven interop szerelvények) generálására WinRT-összetevőkből, valamint C#/WinRT-összetevők szerkesztéséhez. A C#/WinRT használati forgatókönyveivel kapcsolatos további részletekért tekintse meg az adattárban található usage útmutatót.

Interop-szerelvény létrehozása és terjesztése

A WinRT API-k Windows Metaadatok (WinMD) fájlokban vannak definiálva. A C#/WinRT NuGet csomag (Microsoft.Windows. A CsWinRT) tartalmazza a C#/WinRT fordítót, cswinrt.exe, amellyel WinMD-fájlokat dolgozhat fel, és .NET C#-kódot hozhat létre. A C#/WinRT ezeket a forrásfájlokat egy interop-szerelvénybe fordítja, hasonlóan ahhoz, ahogyan a C++/WinRT fejléceket hoz létre a C++ nyelvi kivetítéshez. Ezután eloszthatja a C#/WinRT interoperabilitási szerelvényt és az implementációs szerelvényt, így .NET alkalmazások hivatkozhatnak rájuk, jellemzően NuGet-csomagként.

Az interop-szerelvények létrehozásával és terjesztésével kapcsolatos további részletekért lásd: C#-kivetítés létrehozása C++/WinRT-összetevőből, terjesztés NuGet-ként .NET alkalmazásokhoz.

Interop-szerelvény hivatkozása

A C#/WinRT interop szerelvényekre általában alkalmazásprojektek hivatkoznak. Erre viszont hivatkozhatnak közbenső interop assemblyk. A WinUI interop szerelvény például a Windows SDK interop szerelvényre hivatkozik.

Ha egy külső WinRT-összetevőt hivatalos interop-szerelvény nélkül terjeszt, az alkalmazás project a az interop-szerelvény létrehozására vonatkozó eljárást követve hozhat létre saját privát vetületforrásokat. Ezt a megközelítést nem javasoljuk, mert ütköző, azonos típusú előrejelzéseket hozhat létre egy folyamaton belül. A NuGet-csomagolás a szemantikai verziókövetési sémát követve ennek megelőzésére lett kialakítva. Előnyben részesítik a hivatalos külső interop szerelvényt.

Beágyazott támogatás WinRT-típusokhoz

C#/WinRT 1.4.1-es verziójától támogatott a Windows SDK vetítési és futtatókörnyezeti források beágyazása a .NET és .NET Standard 2.0 könyvtárakhoz vagy alkalmazásokhoz. Ez akkor hasznos, ha a Windows SDK-típusok használata önálló. A beágyazott támogatás eltávolítja a WinRT.Runtime.dll és a Microsoft.Windows.SDK.NET.dll függőségeit, amely csökkenti a kódtár vagy az alkalmazás kimeneti méretét. Emellett lehetővé teszi a könyvtárfejlesztők számára, hogy alsó szintű támogatást nyújtsanak, és szükségtelenné teszik a többhelyes célzást.

További részletekért tekintse meg az adattárban található C#/WinRT embedded dokumentációt.

WinRT-típus aktiválása

A C#/WinRT támogatja az operációs rendszer által üzemeltetett WinRT-típusok aktiválását, valamint külső összetevőket, például a Win2D-t. Az asztali alkalmazásokban a harmadik féltől származó összetevők aktiválásának támogatása regisztráció nélküli WinRT-aktiválással engedélyezve van (lásd: Az Windows-futtatókörnyezet Components használatával nem csomagolt asztali alkalmazások engedélyezése, amely az Windows 10 1903-es és újabb verziójában érhető el. A natív C++ összetevőknek a Windows Desktop Compatible tulajdonságot True értékre kell állítaniuk a projekt tulajdonságainál vagy a .vcxproj fájlon keresztül, hogy a Microsoft.VCLibs.Desktop bináris fájlokat hivatkozhassák és továbbíthassák a felhasználó alkalmazások felé. Ellenkező esetben a VCRT Forwarders csomagra szükségük lesz az azt használó alkalmazásoknak, ha az összetevő csak az UWP-alkalmazásokat célozza meg.

A C#/WinRT emellett aktiválási tartalék elérési utat is biztosít, ha Windows nem tudja aktiválni a típust a fent leírtak szerint. Ebben az esetben a C#/WinRT megkísérli megkeresni a natív implementációs DLL-t a teljes típusnév alapján, fokozatosan eltávolítva az elemeket. A tartalék logika például a Contoso.Controls.Widget típust a következő modulokból próbálja meg egymás után aktiválni:

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

A C#/WinRT a LoadLibrary alternatív keresési sorrendjét használja egy implementációs DLL megkereséséhez. Az erre a tartalék viselkedésre támaszkodó alkalmazásnak az alkalmazásmodul mellé kell csomagolnia a megvalósítási DLL-t.

Gyakori hibák és hibaelhárítás

• Hiba: "Windows metaadatok nincsenek megadva vagy nem észlelhetők."

  A Windows metaadatokat a <CsWinRTWindowsMetadata> projekttulajdonság használatával adhatja meg, például:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  A C#/WinRT 1.2.1-es és újabb verzióiban ez a tulajdonság alapértelmezés szerint TargetPlatformVersion, amely a TargetFramework tulajdonságban megadott Windows SDK-verzióból származik.

• CS0246-os hiba: Nem található a "Windows" típus- vagy névtérnév (hiányzik egy használt irányelv vagy szerelvényhivatkozás?)

  A hiba elhárításához szerkessze a <TargetFramework> tulajdonságot egy adott Windows verzió megcélzásához, például:

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

  A A Windows-futtatókörnyezet API-k hívása dokumentációban talál további információt a <TargetFramework> tulajdonság megadásáról.

• System.InvalidCastException az ComImport attribútummal rendelkező felületre történő kasztoláskor

  Amikor egy objektumot egy ComImport attribútummal rendelkező felületre alakít át, a .As<> operátort kell használnia ahelyett, hogy explicit kifejezést használna. Például:

  someObject.As<SomeComImportInterface>
  

  További részletekért lásd a COM interop guide.

• System.Runtime.InteropServices.COMException: Osztály nincs regisztrálva (0x80040154 (REGDB_E_CLASSNOTREG))

  • Ha ez a kivétel C++/WinRT-összetevőből származó C#/WinRT-vetítés használatakor jelenik meg, győződjön meg arról, hogy az összetevő a Windows Asztali Kompatibilis tulajdonságot True-re a projekt tulajdonságain vagy a .vcxproj fájlon keresztül állította be.

.NET SDK verziószámozási hibái

A következő hibák vagy figyelmeztetések jelenhetnek meg egy olyan projektben, amely egy korábbi .NET SDK-verzióval készült, mint bármelyik függősége.

Hiba vagy figyelmeztető üzenet	Reason
Figyelmeztetés MSB3277: Ütközések találhatók a WinRT.Runtime vagy a Microsoft.Windows.SDK.NET különböző verziói között, amelyeket nem lehet feloldani.	Ez az összeállítási figyelmeztetés akkor fordul elő, ha olyan kódtárra hivatkozik, amely Windows SDK-típusokat tesz elérhetővé az API-felületén.
CS1705-ös hiba: A AssemblyName1 szerelvény a TypeName szerelvényt használja, amely magasabb verziójú, mint a hivatkozott "AssemblyName2" szerelvény	Ez a build fordító hiba akkor fordul elő, amikor egy könyvtárban elérhető Windows SDK-típusokra hivatkozik és azokat felhasználja.
System.IO.FileLoadException	Ez a futtatókörnyezeti hiba akkor fordulhat elő, ha meghív bizonyos API-kat olyan könyvtárban, amely nem biztosítja a Windows SDK típusokat.

A hibák elhárításához frissítse a .NET SDK-t a legújabb verzióra. Ez biztosítja, hogy az alkalmazás által használt futtatókörnyezet és Windows SDK-szerelvényverziók kompatibilisek legyenek az összes függőséggel. Ezek a hibák a .NET SDK korai karbantartási/funkciófrissítései esetén fordulhatnak elő, mivel a futtatókörnyezeti javításokhoz szükség lehet a szerelvény verzióinak frissítésére.

Ismert problémák

Az ismert problémákat és a kompatibilitástörő változásokat a C#/WinRT GitHub adattárban találja.

Ha funkcionális problémákat tapasztal a C#/WinRT NuGet-csomaggal, a cswinrt.exe fordítóval vagy a létrehozott kivetítési forrásokkal kapcsolatban, küldje el nekünk a problémákat a C#/WinRT-problémák lapján.

További erőforrások

• C#/WinRT GitHub adattár