C#/WinRT

C#/WinRT is een NuGet-pakket-toolkit die ondersteuning biedt voor Projectie van Windows Runtime (WinRT) voor de C#-taal. Een projectieassembly is een interoperabiliteitsassembly die het mogelijk maakt om WinRT-API's op een natuurlijke en vertrouwde manier te programmeren in de doeltaal. De C#/WinRT-projectie verbergt de details van interop tussen C# en WinRT-interfaces en biedt toewijzingen van veel WinRT-typen aan de juiste .NET-equivalenten, zoals tekenreeksen, URI's, algemene waardetypen en algemene verzamelingen.

C#/WinRT biedt momenteel ondersteuning voor het gebruik van WinRT-API's via het gebruik van Target Framework Monikers (TFM's) in .NET. Als u de TFM instelt met een specifieke Windows SDK-versie, worden verwijzingen toegevoegd aan de Windows SDK-projectie en runtimeassembly's die zijn gegenereerd door C#/WinRT.

Met het C#/WinRT NuGet-pakket kunt u uw eigen WinRT-interopassembly's maken en ernaar verwijzen voor .NET-consumenten. De nieuwste C#/WinRT-versie bevat ook een preview van het ontwerpen van WinRT-typen in C#.

Zie de C#/WinRT GitHub-opslagplaats voor meer informatie.

Motivatie voor C#/WinRT

.NET (voorheen bekend als .NET Core) is een opensource-, platformoverschrijdende runtime die kan worden gebruikt om apparaat-, cloud- en IoT-toepassingen te bouwen.

Eerdere versies van .NET Framework en .NET Core hadden ingebouwde kennis van WinRT: een Windows-specifieke technologie. Ter ondersteuning van de draagbaarheids- en efficiëntiedoelen van .NET 6+ hebben we de WinRT-projectieondersteuning uit de .NET-compiler en runtime gehaald en verplaatst naar de C#/ WinRT-toolkit (zie ingebouwde ondersteuning voor WinRT wordt verwijderd uit .NET). Het doel van C#/WinRT is pariteit te bieden met de ingebouwde WinRT-ondersteuning die wordt geboden door eerdere versies van de C#-compiler en .NET-runtime. Zie .NET-toewijzingen van Windows Runtime-typen voor meer informatie.

C#/WinRT ondersteunt ook onderdelen in de Windows App SDK, waaronder WinUI. Met de Windows App SDK worden de systeemeigen Microsoft UI-besturingselementen en andere native componenten losgekoppeld van het besturingssysteem. Hierdoor kunnen app-ontwikkelaars de nieuwste besturingselementen en onderdelen gebruiken in Windows 10, versie 1809 en latere versies.

Ten slotte is C#/WinRT een algemene toolkit en is bedoeld ter ondersteuning van andere scenario's waarbij ingebouwde ondersteuning voor WinRT niet beschikbaar is in de C#-compiler of .NET-runtime.

Wat is nieuw?

De nieuwste C#/WinRT-releases vindt u op onze pagina met opmerkingen bij de release in de Github-opslagplaats.

Usage

Het C#/WinRT NuGet-pakket kan worden gebruikt om C#-projecties (ook wel interop-assemblies genoemd) te genereren vanuit WinRT-componenten en om C#/WinRT-componenten te ontwikkelen. Raadpleeg de gebruikshandleiding voor onze opslagplaats voor meer informatie over de gebruiksscenario's voor C#/WinRT.

Een interop-assembly genereren en distribueren

WinRT-API's worden gedefinieerd in WinMD-bestanden (Windows Metadata). Het C#/WinRT NuGet-pakket (Microsoft.Windows.CsWinRT) bevat de C#/WinRT-compiler, cswinrt.exe, die u kunt gebruiken om WinMD-bestanden te verwerken en .NET C#-code te genereren. C#/WinRT compileert deze bronbestanden in een interop-assembly, vergelijkbaar met de manier waarop C++/WinRT headers genereert voor de C++-taalprojectie. Vervolgens kunt u de C#/WinRT-interop-assembly distribueren, samen met de implementatieassembly voor .NET-toepassingen waarnaar wordt verwezen, meestal als een NuGet-pakket.

Zie Een C#-projectie genereren vanuit een C++/WinRT-onderdeel, distribueren als een NuGet voor .NET-apps voor meer informatie over het genereren en distribueren van een interop-assembly.

Verwijzen naar een interoperabiliteitsassembly

Meestal worden C#/WinRT-interopassemblies door toepassingsprojecten aangeroepen. Maar ze kunnen ook op hun beurt worden verwezen door tussenliggende interoperabiliteitsassembly's. De WinUI-interop-assembly verwijst bijvoorbeeld naar de Windows SDK-interop-assembly.

Als u een WinRT-onderdeel van derden distribueert zonder een officiële interop-assembly, kan een toepassingsproject de procedure volgen voor het genereren van een interop-assembly om een eigen privéprojectiebronnen te genereren. We raden deze methode niet aan, omdat deze conflicterende projecties van hetzelfde type binnen een proces kan produceren. NuGet-pakketten, volgens het Semantic Versioning-schema , zijn ontworpen om dit te voorkomen. Een officiële interop-assembly van derden heeft de voorkeur.

Ingesloten ondersteuning voor WinRT-typen (Preview)

Vanaf C#/WinRT versie 1.4.1 is ondersteuning opgenomen voor het insluiten van Windows SDK-projectie- en runtimebronnen voor zowel .NET als .NET Standard 2.0 in de uitvoer van uw bibliotheek of app. Dit is handig in gevallen waarin het gebruik van Windows SDK-typen zelfstandig is. Met ingesloten ondersteuning worden afhankelijkheden van WinRT.Runtime.dll en Microsoft.Windows.SDK.NET.dll verwijderd, waardoor de uitvoergrootte van de bibliotheek of app wordt verkleind. Hiermee kunnen bibliotheekontwikkelaars ook ondersteuning op downlevel bieden en wordt de noodzaak voor meerdere targeting verwijderd.

Voor meer informatie, zie de C#/WinRT embedded-documentatie in onze repository.

Activering van WinRT-type

C#/WinRT ondersteunt de activering van WinRT-typen die worden gehost door het besturingssysteem, evenals onderdelen van derden, zoals Win2D. Ondersteuning voor activering van onderdelen van derden in een bureaubladtoepassing is ingeschakeld met gratis WinRT-activering (zie Niet-verpakte bureaublad-apps verbeteren met Windows Runtime-onderdelen), beschikbaar in Windows 10, versie 1903 en hoger. Systeemeigen C++-onderdelen moeten de eigenschap Compatibel met Windows Desktop instellen op True via de projecteigenschappen of het .vcxproj-bestand, om naar de binaries van Microsoft.VCLibs.Desktop te verwijzen en deze door te sturen naar applicaties die hiervan gebruikmaken. Anders is het VCRT Forwarders pakket vereist door apps die het gebruiken als het onderdeel alleen UWP-apps gericht is op.

C#/WinRT biedt ook een terugvalpad voor activering als Windows het type niet kan activeren, zoals hierboven beschreven. In dit geval probeert C#/WinRT een systeemeigen implementatie-DLL te vinden op basis van de volledig gekwalificeerde typenaam, waarbij elementen geleidelijk worden verwijderd. De terugvallogica probeert bijvoorbeeld het type Contoso.Controls.Widget te activeren uit de volgende modules, in volgorde:

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

C#/WinRT maakt gebruik van de alternatieve zoekvolgorde loadlibrary om een implementatie-DLL te vinden. Een app die afhankelijk is van dit terugvalgedrag, moet de implementatie-DLL naast de app-module verpakken.

Veelvoorkomende fouten en probleemoplossing

• Fout: 'Windows-metagegevens zijn niet opgegeven of gedetecteerd'.

  U kunt Windows-metagegevens opgeven met behulp van de <CsWinRTWindowsMetadata> projecteigenschap, bijvoorbeeld:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  In C#/WinRT versie 1.2.1 en hoger wordt deze eigenschap standaard TargetPlatformVersioningesteld op , die is afgeleid van de Windows SDK-versie die is opgegeven in de TargetFramework eigenschap.

• Fout CS0246: Het type of de naamruimtenaam 'Windows' is niet gevonden (ontbreekt er een using-instructie of een assembly-verwijzing?)

  Als u deze fout wilt oplossen, bewerkt u de <TargetFramework> eigenschap om een specifieke Windows-versie te bereiken, bijvoorbeeld:

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

  Raadpleeg de documenten over het aanroepen van Windows Runtime-API's voor meer informatie over het opgeven van de <TargetFramework> eigenschap.

• System.InvalidCastException bij het casten naar een interface met het ComImport kenmerk

  Wanneer u een object castt naar een interface met het ComImport kenmerk, moet u de .As<> operator gebruiken in plaats van een expliciete cast-expressie te gebruiken. Voorbeeld:

  someObject.As<SomeComImportInterface>
  

  Zie de COM-interoperabiliteitshandleiding voor meer informatie.

• System.Runtime.InteropServices.COMException: klasse niet geregistreerd (0x80040154 (REGDB_E_CLASSNOTREG))

  • Als u deze uitzondering ziet wanneer u een C#/WinRT-projectie van een C++/WinRT-onderdeel gebruikt, controleert u of het onderdeel de eigenschap Compatibel met Windows Desktop heeft ingesteld op True via de projecteigenschappen of via het .vcxproj bestand.

Fouten met .NET SDK-versiebeheer

Er kunnen de volgende fouten of waarschuwingen optreden in een project dat is gebouwd met een eerdere .NET SDK-versie dan een van de afhankelijkheden.

Fout- of waarschuwingsbericht	Reden
Waarschuwing MSB3277: Er zijn conflicten gevonden tussen verschillende versies van WinRT.Runtime of Microsoft.Windows.SDK.NET die niet kunnen worden opgelost.	Deze buildwaarschuwing treedt op wanneer u verwijst naar een bibliotheek die Windows SDK-typen beschikbaar maakt op het API-oppervlak.
Fout CS1705: Assembly 'AssemblyName1' maakt gebruik van 'TypeName' die een hogere versie heeft dan de assembly 'AssemblyName2'	Deze build-compilerfout treedt op wanneer naar beschikbare Windows SDK-typen in een bibliotheek wordt verwezen en ze worden gebruikt.
System.IO.FileLoadException	Deze runtimefout kan optreden bij het aanroepen van bepaalde API's in een bibliotheek die geen Windows SDK-typen beschikbaar maakt.

Werk uw .NET SDK bij naar de nieuwste versie om deze fouten op te lossen. Dit zorgt ervoor dat de runtime- en Windows SDK-assemblyversies die door uw toepassing worden gebruikt, compatibel zijn met alle afhankelijkheden. Deze fouten kunnen optreden bij vroege onderhouds-/functie-updates voor de .NET SDK, omdat runtimeoplossingen mogelijk updates voor onze assemblyversies vereisen.

Bekende problemen

Bekende problemen en belangrijke wijzigingen worden vermeld in de C#/WinRT GitHub-opslagplaats.

Als u functionele problemen ondervindt met het C#/WinRT NuGet-pakket, de cswinrt.exe compiler of de gegenereerde projectiebronnen, dient u problemen bij ons in via de pagina C#/WinRT-problemen.

Aanvullende bronnen

• C#/WinRT GitHub-opslagplaats