C#/WinRT

C#/WinRT är en NuGet-paketerad verktygslåda som tillhandahåller Windows Runtime(WinRT) projektionsstöd för C#-språket. En projektionssammansättning är en interop-sammansättning som möjliggör programmering av WinRT-API:er på ett naturligt och välbekant sätt för målspråket. C#/WinRT-projektionen döljer information om interop mellan C#- och WinRT-gränssnitt och innehåller mappningar av många WinRT-typer till lämpliga .NET motsvarigheter, till exempel strängar, URI:er, vanliga värdetyper och generiska samlingar.

C#/WinRT har för närvarande stöd för användning av WinRT-API:er med hjälp av Target Framework Monikers (TFM) i .NET. Om du ställer in TFM med en specifik Windows SDK-version läggs referenser till Windows SDK-projektionen och de körningssamlingar som genereras av C#/WinRT till.

Med C#/WinRT NuGet-paketet kan du skapa och referera till dina egna WinRT interop assembly för .NET användare. Den senaste C#/WinRT-versionen innehåller också en förhandsversion av redigering av WinRT-typer i C#.

Mer information finns i C#/WinRT GitHub-lagringsplatsen.

Motivation för C#/WinRT

.NET (tidigare kallat .NET Core) är en plattformsoberoende körning med öppen källkod som kan användas för att skapa enhets-, moln- och IoT-program.

Tidigare versioner av .NET Framework och .NET Core hade inbyggd kunskap om WinRT – en Windows-specifik teknik. För att stödja portabilitets- och effektivitetsmålen för .NET 6+ lyfte vi WinRT-projektionsstödet från .NET kompilatorn och körningen och flyttade det till C#/WinRT-verktygslådan (se Built-in-stöd för WinRT tas bort från .NET). Målet med C#/WinRT är att ge paritet med det inbyggda WinRT-stödet från tidigare versioner av C#-kompilatorn och .NET körning. Mer information finns i .NET-mappningarna av Windows Runtime-typerna.

C#/WinRT stöder även komponenter i Windows App SDK, inklusive WinUI 3. Windows App SDK lyfter inbyggda Microsoft-gränssnittskontroller och andra inbyggda komponenter från operativsystemet. Detta gör det möjligt för apputvecklare att använda de senaste kontrollerna och komponenterna i Windows 10 version 1809 och senare versioner.

Slutligen är C#/WinRT en allmän verktygslåda och är avsedd att stödja andra scenarier där inbyggt stöd för WinRT inte är tillgängligt i C#-kompilatorn eller .NET körning.

Vad är nytt

De senaste C#/WinRT-versionerna finns på vår versionsmeddelanden-sida i Github-repot.

Usage

NuGet-paketet C#/WinRT kan användas för att både generera C#-projektioner (kallas även interop-sammansättningar) från WinRT-komponenter och i Authoring C#/WinRT-komponenter. Mer information om användningsscenarier för C#/WinRT finns i användarguiden på vår lagringsplats.

Generera och distribuera en interop-sammansättning

WinRT-API:er definieras i WinMD-filer (Windows Metadata). C#/WinRT NuGet-paketet (Microsoft.Windows.CsWinRT) innehåller C#/WinRT-kompilatorn cswinrt.exe som du kan använda för att bearbeta WinMD-filer och generera .NET C#-kod. C#/WinRT kompilerar dessa källfiler till en interop-sammansättning, ungefär som C++/WinRT genererar rubriker för C++-språkprojektionen. Du kan sedan distribuera C#/WinRT-interopsammansättningen tillsammans med implementeringssammansättningen för .NET program att referera till, vanligtvis som ett NuGet-paket.

Mer information om hur du genererar och distribuerar en interop-sammansättning finns i Generera en C#-projektion från en C++/WinRT-komponent, distribuera som en NuGet för .NET-appar.

Referera till en interop-sammansättning

Vanligtvis refereras C#/WinRT interop-sammansättningar av programprojekt. Men de kan också refereras i sin tur av mellanliggande interop-sammansättningar. WinUI-interopsammansättningen refererar till till exempel Windows SDK-interop-sammansättningen.

Om du distribuerar en WinRT-komponent från tredje part utan en officiell interop-assembly kan ett applikationsprojekt följa proceduren för att generera en interop-assembly för att skapa egna privata projektionskällor. Vi rekommenderar inte den här metoden eftersom den kan skapa motstridiga projektioner av samma typ i en process. NuGet-paketering, som följer schemat för semantisk versionshantering , är utformat för att förhindra detta. En officiell tredje parts interop-samling föredras.

Inbäddat stöd för WinRT-typer (förhandsversion)

Från och med C#/WinRT version 1.4.1 ingår stöd för inbäddning av Windows SDK-projektion och körningskällor för både .NET och .NET Standard 2.0 i bibliotekets eller appens utdata. Detta är användbart i fall där användningen av Windows SDK-typer är fristående. Inbäddat stöd tar bort beroenden på WinRT.Runtime.dll och Microsoft.Windows.SDK.NET.dll vilket minskar utdatastorleken för biblioteket eller appen. Det gör det också möjligt för biblioteksutvecklare att tillhandahålla support på låg nivå och tar bort behovet av flera mål.

För mer information, se dokumentationen C#/WinRT embedded på vår repo.

Aktivering av WinRT-typ

C#/WinRT stöder aktivering av WinRT-typer som hanteras av operativsystemet samt komponenter från tredje part, till exempel Win2D. Stöd för komponentaktivering från tredje part i ett skrivbordsprogram är aktiverat med kostnadsfri WinRT-aktivering för registrering (se Enhancing Icke-paketerade skrivbordsappar med Windows Runtime Components), som finns i Windows 10 version 1903 och senare. Native C++-komponenter bör ange egenskapen Windows Desktop Compatible till True antingen via projektinställningarna eller filen .vcxproj, för att referera till och vidarebefordra dessa Microsoft.VCLibs.Desktop binärfiler till konsumerande appar. Annars kommer VCRT-vidarebefordrarpaketet att krävas för de appar som använder den, om komponenten endast riktar sig mot UWP-appar.

C#/WinRT tillhandahåller också en återställningssökväg för aktivering om Windows inte kan aktivera typen enligt beskrivningen ovan. I det här fallet försöker C#/WinRT hitta en intern implementerings-DLL baserat på det fullständigt kvalificerade typnamnet och gradvis ta bort element. Reservlogiken skulle till exempel försöka starta typen Contoso.Controls.Widget från följande moduler i tur och ordning:

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

C#/WinRT använder den alternativa sökordningen LoadLibrary för att hitta en implementerings-DLL. En app som förlitar sig på det här återställningsbeteendet bör paketera implementerings-DLL:en tillsammans med appmodulen.

Vanliga fel och felsökning

• Fel: "Windows-metadata har inte angetts eller identifierats."

  Du kan ange Windows-metadata med egenskapen <CsWinRTWindowsMetadata> project, till exempel:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  I C#/WinRT version 1.2.1 och senare är den här egenskapen standardvärdet TargetPlatformVersion, som härleds från den Windows SDK-version som anges i TargetFramework egenskapen.

• Fel CS0246: Det gick inte att hitta typen eller namnområdets namn "Windows" (saknar du ett användningsdirektiv eller en sammansättningsreferens?)

  Åtgärda det här felet genom att redigera din <TargetFramework> egenskap för att rikta in dig på en viss Windows-version, till exempel:

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

  Mer information om att ange egenskapen finns i dokumenten om Calling Windows Runtime APIs.

• System.InvalidCastException vid konvertering till ett gränssnitt som har ComImport attributet

  När du omvandlar ett objekt till ett gränssnitt som har ComImport attributet måste du använda operatorn .As<> i stället för att använda ett explicit cast-uttryck. Till exempel:

  someObject.As<SomeComImportInterface>
  

  Mer information finns i COM interop guide.

• System.Runtime.InteropServices.COMException: Klasserna är ej registrerade (0x80040154 (REGDB_E_CLASSNOTREG))

  • Om du ser det här undantaget när du använder en C#/WinRT-projektion från en C++/WinRT-komponent kontrollerar du att komponenten har angett egenskapen Windows Desktop Compatible till True antingen via egenskaperna project eller via filen .vcxproj.

.NET SDK-versionsfel

Du kan stöta på följande fel eller varningar i en project som har skapats med en tidigare .NET SDK-version än något av dess beroenden.

Fel eller varningsmeddelande	Reason
Varning MSB3277: Det gick inte att lösa konflikter mellan olika versioner av WinRT.Runtime eller Microsoft.Windows.SDK.NET som inte kunde lösas.	Den här byggvarningen inträffar när du refererar till ett bibliotek som exponerar Windows SDK-typer på dess API-surface.
Fel CS1705: Sammansättningen "AssemblyName1" använder "TypeName" som har en högre version än den refererade sammansättningen "AssemblyName2"	Det här kompilatorfelet uppstår när du refererar till och använder exponerade Windows SDK-typer i ett bibliotek.
System.IO.FileLoadException	Det här körningsfelet kan inträffa när vissa API:er anropas i ett bibliotek som inte exponerar Windows SDK-typer.

Åtgärda dessa fel genom att uppdatera din .NET SDK till den senaste versionen. Om du gör det ser du till att de runtime- och Windows SDK-sammansättningsversioner som används av ditt program är kompatibla med alla beroenden. Dessa fel kan uppstå vid tidig service/funktionsuppdateringar av .NET SDK, eftersom körningskorrigeringar kan kräva uppdateringar av våra sammansättningsversioner.

Kända problemområden

Kända problem och icke-bakåtkompatibla ändringar noteras i C#/WinRT GitHub lagringsplats.

Om du stöter på några funktionella problem med C#/WinRT NuGet-paketet, cswinrt.exe-kompilatorn eller de genererade projektionskällorna skickar du problem till oss via sidan C#/WinRT-problem.

Ytterligare resurser

• C#/WinRT GitHub lagringsplats