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í ekvivalenty .NET, jako jsou řetězce, identifikátory URI, běžné typy hodnot a obecné kolekce.

C#/WinRT v současné době poskytuje podporu pro využívání rozhraní WinRT API pomocí monikery cílového rozhraní (TFM) v .NET. Nastavení TFM s konkrétní verzí sady Windows SDK přidává odkazy na projekci Windows SDK a běhové knihovny generované jazykem C#/WinRT.

Balíček NuGet C#/WinRT umožňuje vytvářet a odkazovat na vlastní sestavení vzájemné spolupráce WinRT pro uživatele .NET. Nejnovější verze C#/WinRT obsahuje také náhled vytváření typů WinRT v jazyce C#.

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

Motivace pro C#/WinRT

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

Předchozí verze rozhraní .NET Framework a .NET Core měly integrované znalosti winRT – technologie specifické pro Windows. Abychom podpořili cíle přenositelnosti a efektivity rozhraní .NET 6 nebo novější, zvedli jsme podporu projekce WinRT z kompilátoru a modulu runtime .NET a přesunuli ho do sady nástrojů C#/WinRT (viz Integrovaná podpora winRT je odebrá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 tématu Mapování .NET typů prostředí Windows Runtime.

C#/WinRT podporuje také komponenty v sadě Windows App SDK, včetně WinUI. Sada Windows App SDK zvedne nativní ovládací prvky uživatelského rozhraní Microsoftu 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 ve Windows 10 verze 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 modulu runtime .NET.

Co je nového

Nejnovější verze C#/WinRT najdete na naší stránce s poznámkami k verzi v úložišti GitHub.

Využití

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

Generujte a distribuujte assembly pro interoperabilitu

Rozhraní API WinRT jsou definována v souborech metadat Systému Windows (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. Pak můžete distribuovat sestavení interoperability C#/WinRT spolu se sestavením implementace pro .NET aplikace, které má být referencováno, obvykle jako balíček NuGet.

Další podrobnosti o tom, jak generovat a distribuovat sestavení vzájemné spolupráce, najdete v tématu Generování zobrazení jazyka C# z komponenty C++/WinRT a distribuujte ji 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 sestavení zprostředkovatele komunikace WinUI by odkazovalo na sestavení zprostředkovatele komunikace sady Windows SDK.

Pokud distribuujete komponentu WinRT třetí strany bez oficiálního sestavení vzájemné spolupráce, projekt aplikace může postupovat podle postupu generování sestavení vzájemné spolupráce a vygenerovat vlastní zdroje privátní 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 (Preview)

Počínaje verzí C#/WinRT verze 1.4.1 je podpora pro vkládání projekcí sady 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ů sady Windows SDK samostatné. Vložená podpora odebere 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 K#/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 povolena s registrací bezplatné aktivace WinRT (viz vylepšení nebalené desktopové aplikace pomocí komponent prostředí Windows Runtime), které jsou k dispozici ve Windows 10 verze 1903 a novější. Nativní komponenty jazyka C++ by měly nastavit vlastnost Kompatibilita s Windows Desktop na hodnotu True buď prostřednictvím vlastností projektu, nebo souboru .vcxproj, aby aplikace mohly odkazovat na a využívat binární soubory Microsoft.VCLibs.Desktop. V opačném případě bude balíček VCRT Forwarders vyžadován konzumujícími aplikacemi, pokud komponenta cílí pouze na UWP aplikace.

C#/WinRT také poskytuje záložní cestu aktivace, pokud se systému 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: Metadata Systému Windows nebyla poskytována nebo zjištěna.

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

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  V C#/WinRT verzi 1.2.1 a novější je tato vlastnost výchozí hodnota TargetPlatformVersion, která je odvozena z verze sady Windows SDK specifikované ve vlastnosti 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 určení vlastnosti najdete v dokumentaci k <TargetFramework>.

• 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 interoperabilitou modelu 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 Kompatibilní s Windows desktopem na Hodnotu True prostřednictvím vlastností projektu nebo souboru .vcxproj .

Chyby správy verzí sady .NET SDK

V projektu, který je sestavený se starší verzí sady .NET SDK, než je jakákoli z 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 prostředí 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 z Windows SDK na rozhraní jeho API.
Chyba CS1705: Sestavení AssemblyName1 používá TypeName, který má vyšší verzi než odkazované sestavení AssemblyName2.	K této chybě kompilátoru sestavení dochází při odkazování a využívání vystavených typů sady 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 typy sady Windows SDK.

Pokud chcete tyto chyby opravit, aktualizujte sadu .NET SDK na nejnovější verzi. Tím zajistíte, že verze sestavení runtime a sady Windows SDK používané vaší aplikací budou 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 na GitHubu.

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

• Úložiště GitHub v jazyce C#/WinRT