C#/WinRT

C#/WinRT je sada nástrojů s balíčkem NuGet, která poskytuje podporu projekce prostředí Windows Runtime (WinRT) pro jazyk C#. Projekční sestavení je interoperabilní sestavení, které umožňuje programování rozhraní WinRT API přirozeným a známým způsobem pro cílový jazyk. Projekce C#/WinRT skryje podrobnosti spolupráce mezi rozhraními C# a WinRT a poskytuje mapování mnoha typů WinRT na odpovídající .NET ekvivalenty, jako jsou řetězce, identifikátory URI, běžné typy hodnot a obecné kolekce.

C#/WinRT v současné době poskytuje podporu pro použití rozhraní API WinRT prostřednictvím Target Framework Monikers (TFM) v prostředí .NET. Nastavení TFM s konkrétní verzí sady WINDOWS SDK přidává odkazy na projekce sady Windows SDK a sestavení modulu runtime vygenerovaná jazykem C#/WinRT.

Balíček NuGet C#/WinRT umožňuje vytvářet a odkazovat vlastní WinRT interoperabilní sestavení pro prostředí .NET. Nejnovější verze C#/WinRT podporuje také vytváření typů WinRT v jazyce C#.

Další informace najdete v úložišti C#/WinRT GitHub.

Motivace pro C#/WinRT

.NET (dříve označovaný jako .NET Core) je opensourcový multiplatformní modul runtime, který se dá použít k vytváření aplikací pro zařízení, cloud a IoT.

Předchozí verze .NET Framework a .NET Core měly integrované znalosti WinRT – technologie specifické pro Windows. Abychom podpořili cíle přenositelnosti a efektivity .NET 6 a novějších, vyjmuli jsme projekční podporu WinRT z kompilátoru .NET a modulu runtime a přesunuli ji do sady nástrojů C#/WinRT (viz Vestavěná podpora pro WinRT byla odstraněna z .NET). Cílem jazyka C#/WinRT je poskytnout paritu s integrovanou podporou WinRT poskytovanou dřívějšími verzemi kompilátoru jazyka C# a modulem runtime .NET. Podrobnosti najdete v .NET mapování typů prostředí Windows Runtime.

C#/WinRT také podporuje komponenty v Windows App SDK, včetně WinUI 3. Windows App SDK zvedne nativní ovládací prvky uživatelského rozhraní Microsoft a další nativní komponenty z operačního systému. Vývojáři aplikací tak můžou používat nejnovější ovládací prvky a komponenty na Windows 10, verzi 1809 a novějších verzích.

A konečně C#/WinRT je obecná sada nástrojů a je určená k podpoře jiných scénářů, kdy integrovaná podpora winRT není k dispozici v kompilátoru jazyka C# nebo v modulu runtime .NET.

Co je nového

Nejnovější verze C#/WinRT najdete na naší stránce release notes v úložišti GitHub.

Využití

Balíček NuGet C#/WinRT lze použít ke generování projekcí jazyka C# (označovaných také jako sestavení vzájemné spolupráce) z komponent WinRT a v tvorbě komponent C#/WinRT. Další podrobnosti o scénářích použití pro C#/WinRT najdete v průvodci usage v našem úložišti.

Generujte a distribuujte assembly pro interoperabilitu

Rozhraní API WinRT jsou definována v souborech Windows Metadata (WinMD). Balíček NuGet C#/WinRT (Microsoft.Windows. CsWinRT) obsahuje kompilátor C#/WinRT, cswinrt.exe, který můžete použít ke zpracování souborů WinMD a generování kódu .NET C#. C#/WinRT tyto zdrojové soubory zkompiluje do mezivrstvového sestavení, podobně jako C++/WinRT vytváří hlavičky pro C++ projekci. Potom můžete distribuovat sestavení interoperability C#/WinRT spolu s implementačním sestavením, které budou odkazovat na .NET aplikace, obvykle jako balíček NuGet.

Další podrobnosti o tom, jak generovat a distribuovat interopní sestavení, najdete v tématu Generování projekce jazyka C# z komponenty C++/WinRT a její distribuce jako balíček NuGet pro aplikace .NET.

Odkazovat na sestavení pro spolupráci

Na sestavení vzájemné spolupráce jazyka C#/WinRT se obvykle odkazují projekty aplikací. Mohou však být také odkazovány prostřednictvím zprostředkujících sestavení pro interoperabilitu. Například interop sestavení WinUI by odkazovalo na interop sestavení Windows SDK.

Pokud distribuujete komponentu WinRT třetí strany bez oficiálního propojovacího sestavení, může aplikace projekt postupovat podle postupu pro generování propojovacího sestavení k vytvoření vlastních zdrojů soukromé projekce. Tento přístup nedoporučujeme, protože může způsobit konfliktní projekce stejného typu v rámci procesu. Balení NuGet, které používá schéma sémantického verzování, je navrženo tak, aby tomu zabránilo. Preferuje se oficiální sestavení zprostředkovatele komunikace třetích stran.

Podpora vložených typů WinRT

Počínaje verzí C#/WinRT verze 1.4.1 je podpora pro vkládání Windows SDK a zdrojů modulu runtime pro .NET i .NET Standard 2.0 do výstupu knihovny nebo aplikace. To je užitečné v případech, kdy je použití typů Windows SDK samostatné. Podpora pro zabudované systémy odstraňuje závislosti na WinRT.Runtime.dll a Microsoft.Windows.SDK.NET.dll, což zmenšuje velikost knihovny nebo výstupu aplikace. Umožňuje také vývojářům knihoven poskytovat podporu nižší úrovně a odebrat potřebu cílení na více instancí.

Další podrobnosti najdete v dokumentaci C#/WinRT Embedded v našem úložišti.

Aktivace typu WinRT

C#/WinRT podporuje aktivaci typů WinRT hostovaných operačním systémem a také komponent třetích stran, jako je Win2D. Podpora aktivace komponent třetích stran v desktopové aplikaci je povolená registrací bezplatné aktivace WinRT (viz Enhancing Non-packaged Desktop Apps using prostředí Windows Runtime Components), která je dostupná v Windows 10, verzi 1903 a novější. Nativní komponenty C++ by měly nastavit vlastnost Windows Desktop Compatible na True buď prostřednictvím vlastností projektu, nebo souboru .vcxproj, aby bylo možné odkazovat na Microsoft. VCLibs.Desktop binární soubory pro využívání aplikací. Jinak bude balíček VCRT forwarders požadován aplikacemi, které ho spotřebovávají, pokud komponenta cílí jenom na aplikace UWP.

C#/WinRT také poskytuje záložní cestu aktivace, pokud se Windows nepodaří aktivovat typ, jak je popsáno výše. V tomto případě se C#/WinRT pokouší vyhledat nativní implementační knihovnu DLL založenou na plně kvalifikovaném názvu typu, přičemž postupně odstraňuje prvky. Logika pro záložní variantu by se například pokusila aktivovat typ Contoso.Controls.Widget z následujících modulů v pořadí:

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

C#/WinRT používá k vyhledání implementační knihovny DLL alternativní pořadí vyhledávání LoadLibrary . Aplikace, která se spoléhá na toto záložní chování, by měla zabalovat knihovnu DLL implementace společně s modulem aplikace.

Běžné chyby a řešení potíží

• Chyba: "Windows Metadata nebyla poskytována nebo zjištěna."

  Metadata Windows můžete zadat pomocí vlastnosti projektu <CsWinRTWindowsMetadata>, například:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  V jazyce C#/WinRT verze 1.2.1 a novější je tato vlastnost standardně nastavena na TargetPlatformVersion, která je odvozena od verze sady Windows SDK, která je určena vlastností TargetFramework.

• Chyba CS0246: Typ nebo název oboru názvů Windows nebyl nalezen (chybí direktiva using nebo odkaz na sestavení?)

  Pokud chcete tuto chybu vyřešit, upravte vlastnost <TargetFramework> tak, aby cílila na konkrétní verzi Windows, například:

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

  Další podrobnosti o zadání vlastnosti najdete v dokumentaci k .

• System.InvalidCastException při přetypování do rozhraní, které má ComImport atribut

  Při přetypování objektu do rozhraní, které má ComImport atribut, budete muset místo explicitního .As<> použít operátor. Například:

  someObject.As<SomeComImportInterface>
  

  Další podrobnosti najdete v průvodci vzájemné spolupráce COM.

• System.Runtime.InteropServices.COMException: Třída není zaregistrovaná (0x80040154 (REGDB_E_CLASSNOTREG))

  • Pokud se tato výjimka zobrazí při využívání projekce C#/WinRT z komponenty C++/WinRT, ujistěte se, že komponenta nastavila vlastnost Windows Desktop Compatible na True buď prostřednictvím vlastností projektu, nebo prostřednictvím souboru .vcxproj.

Chyby správy verzí sady .NET SDK

V projektu vytvořeném se starší verzí sady .NET SDK než u všech jejích závislostí může dojít k následujícím chybám nebo upozorněním.

Chybová nebo upozorňující zpráva	Důvod
Upozornění MSB3277: Byly nalezeny konflikty mezi různými verzemi WinRT.Runtime nebo Microsoft.Windows.SDK.NET, které se nepodařilo vyřešit.	K tomuto upozornění sestavení dochází při odkazování na knihovnu, která zveřejňuje typy Windows SDK na rozhraní jeho API.
Chyba CS1705: Sestavení AssemblyName1 používá TypeName, který má vyšší verzi než odkazované sestavení AssemblyName2.	K této kompilační chybě sestavení dochází při odkazování a používání vystavených typů Windows SDK v knihovně.
System.IO.FileLoadException	K této chybě za běhu může dojít při volání určitých rozhraní API v knihovně, která nezpřístupňuje Windows typy sady SDK.

Pokud chcete tyto chyby opravit, aktualizujte sadu .NET SDK na nejnovější verzi. Tím zajistíte, aby verze sestavení runtime a Windows SDK používané vaší aplikací byly kompatibilní se všemi závislostmi. K těmto chybám může dojít u dřívějších aktualizací údržby nebo funkcí sady .NET SDK, protože opravy modulu runtime mohou vyžadovat aktualizace našich verzí sestavení.

Známé problémy

Známé problémy a zásadní změny jsou uvedené v úložišti C#/WinRT GitHub.

Pokud narazíte na nějaké funkční problémy s balíčkem NuGet C#/WinRT, kompilátorem cswinrt.exe nebo vygenerovanými zdroji projekce, odešlete nám problémy prostřednictvím stránky problémů C#/WinRT.

Dodatečné zdroje

• C#/WinRT GitHub úložiště