C#/WinRT

A C#/WinRT egy NuGet-csomagú eszközkészlet, amely Windows Runtime (WinRT) előrejelzési támogatást biztosít 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-felületek 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 támogatja a WinRT API-k használatát a Target Framework Monikers (TFM-ek) használatával a .NET-ben. 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 saját WinRT interop szerelvények létrehozását és hivatkozását a .NET-felhasználók számára. A legújabb C#/WinRT-verzió a WinRT-típusok C#-ban való készítésének előnézetét is tartalmazza.

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

A C#/WinRT motivációja

A .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-keretrendszer és a .NET Core korábbi verziói beépített ismeretekkel rendelkeztek a WinRT-ről – egy Windows-specifikus technológiáról. A .NET 6+ hordozhatósági és hatékonysági céljainak támogatása érdekében eltávolítottuk a WinRT-vetítés támogatását 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ását a .NET-ből). A C#/WinRT célja, hogy paritásos legyen a C#-fordító és a .NET-futtatókörnyezet korábbi verziói által biztosított beépített WinRT-támogatás. További részletekért tekintse meg a Windows futtatókörnyezet típusainak .NET-leképezéseit.

A C#/WinRT a Windows App SDK összetevőit is támogatja, beleértve a WinUI-t 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 a Windows 10 1809-es és újabb verzióiban.

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 a .NET-futtatókörnyezetben.

Mik az újdonságok?

A legújabb C#/WinRT-kiadások a Github adattár kibocsátási megjegyzésoldalán találhatók.

Usage

A C#/WinRT NuGet-csomag C#-előrejelzések (más néven interop szerelvények) létrehozására használható a WinRT-összetevőkből és a C#/WinRT-összetevők létrehozásában. A C#/WinRT használati forgatókönyveivel kapcsolatos további részletekért tekintse meg a tárházban található használati útmutatót .

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

A WinRT API-k a Windows Metadata (WinMD) fájlokban vannak definiálva. A C#/WinRT NuGet-csomag (Microsoft.Windows.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 interop-szerelvényt a .NET-alkalmazások implementációs szerelvényével együtt, amely általában NuGet-csomagként használható.

Az interop-szerelvények létrehozásának és terjesztésének további részleteiért lásd: C#-kivetítés létrehozása C++/WinRT-összetevőből, terjesztés NuGet for .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ásprojektek követhetik az interop-szerelvény létrehozásának eljárását saját privát vetítési források létrehozásához. 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 (előzetes verzió)

A C#/WinRT 1.4.1-es verziójától kezdve a támogatás magában foglalja a Windows SDK kivetítési és futtatókörnyezeti források beágyazását a .NET és a .NET Standard 2.0 verzióhoz is, az Ön könyvtárának vagy alkalmazásának kimenetébe. 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 Microsoft.Windows.SDK.NET.dll függőségeit, ami csökkenti az erőforrástár vagy az alkalmazás kimenetének 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 a C#/WinRT beágyazott dokumentációját az adattárban.

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: Nem csomagolt asztali alkalmazások fejlesztése a Windows futtatókörnyezet összetevőivel) a Windows 10 1903-es és újabb verzióiban. A Natív C++-összetevőknek a Windows Asztali kompatibilis tulajdonságot True értékre kell állítaniuk a projekt tulajdonságain vagy a .vcxproj fájlon keresztül, hogy hivatkozhassanak a Microsoft.VCLibs.Desktop bináris fájljaira, és továbbíthassák azt a fogyasztó alkalmazásoknak. Ellenkező esetben a VCRT Forwarders-csomagra az alkalmazások felhasználásával lesz szükség, 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 a 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: "A Windows metadata nem megadva vagy nem észlelhető."

  A Windows metaadatait 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 ennél újabb verziókban ezen tulajdonság alapértelmezett értéke TargetPlatformVersion, amely a Windows SDK-verzióból származik, amit a TargetFramework tulajdonságban adnak meg.

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

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

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

  A tulajdonság megadásával kapcsolatos további részletekért tekintse meg a <TargetFramework> kapcsolatos dokumentumokat.

• 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 tekintse meg a COM interop útmutatót.

• 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ő True értékre állította a Windows Asztali kompatibilis tulajdonságot a projekt tulajdonságain vagy a .vcxproj fájlon keresztül.

.NET SDK-verziószámozási hibák

Az alábbi 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 különböző verziói vagy Microsoft.Windows.SDK.NET között, amelyek nem oldhatók fel.	Ez az összeállítási figyelmeztetés akkor fordul elő, ha olyan kódtárra hivatkozik, amely a Windows SDK-típusokat teszi 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ási hibája akkor fordul elő, ha a könyvtárban megadott Windows SDK-típusokra hivatkozik és használja őket.
System.IO.FileLoadException	Ez a futtatókörnyezeti hiba akkor fordulhat elő, ha bizonyos API-kat hív meg egy olyan kódtárban, amely nem teszi elérhetővé a Windows SDK-típusok használatát.

A hibák elhárításához frissítse a .NET SDK-t a legújabb verzióra. Ezzel biztosítja, hogy az alkalmazás által használt futtatókörnyezeti é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ényverziók 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 oldalán.

További erőforrások

• C#/WinRT GitHub-adattár