C#/WinRT

C#/WinRT je sada nástrojů s balíčkem NuGet, která poskytuje podporu projekce 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 využívání rozhraní API WinRT prostřednictvím Monikers cílového frameworku (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áření a referencování vlastních sestavení pro interoperabilitu 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 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+, vyjmuli jsme podporu projekce WinRT z kompilátoru .NET a modulu runtime a přesunuli ji do sady nástrojů C#/WinRT (viz Integrovaná podpora WinRT byla z .NET odstraněna). 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ů Windows Runtime.

C#/WinRT také podporuje komponenty v Windows App SDK, včetně WinUI 3. Windows App SDK z operačního systému zvedne nativní ovládací prvky uživatelského rozhraní Microsoftu a další nativní komponenty. 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 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. Potom můžete distribuovat sestavení interoperability C#/WinRT spolu s sestavením implementace pro .NET aplikace, které se mají odkazovat, obvykle jako balíček NuGet.

Další podrobnosti o generování a distribuci sestavení interop najdete v tématu Generování projekce jazyka C# z komponenty C++/WinRT a 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 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 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 (Preview)

Počínaje verzí C#/WinRT verze 1.4.1 je podpora 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 sadě Microsoft.Windows.SDK.NET.dll což sniž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 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 a předávat binární soubory Microsoft.VCLibs.Desktop do aplikací. 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 systému Windows můžete zadat pomocí vlastnosti <CsWinRTWindowsMetadata> project, 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 zadání vlastnosti <TargetFramework> najdete v dokumentaci k Volání rozhraní API Windows Runtime.

• 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í project, nebo prostřednictvím souboru .vcxproj.

Chyby správy verzí sady .NET SDK

V project vytvořeném s dřívější verzí sady .NET SDK, než je některá 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é nebylo možné vyřešit.	K tomuto upozornění sestavení dochází při odkazování na knihovnu, která zveřejňuje typy z Microsoft Windows SDK ve svém rozhraní 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 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ě