C#/WinRT

C#/WinRT är en NuGet-paketerad verktygslåda som tillhandahåller projektionsstöd för Windows Runtime (WinRT) 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 tillhandahå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 ger för närvarande stöd för att använda 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-sammansättningar för .NET-konsumenter. 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 program för enhet, moln och IoT.

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 Inbyggt 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örningen. Mer information finns i .NET-mappningar av Windows Runtime-typer.

C#/WinRT stöder även komponenter i Windows App SDK, inklusive WinUI. Windows App SDK lyfter inbyggda Microsoft UI-kontroller 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örningen.

Vad är nytt

De senaste C#/WinRT-versionerna finns på sidan med viktig information på Github-lagringsplatsen.

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ändningsguiden 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-sammansättning kan ett programprojekt följa proceduren för att generera en interop-sammansättning för att generera 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 bibliotekets eller appens utdatastorlek. 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.

Mer information finns i C#/WinRT Embedded-dokumentationen på vår lagringsplats.

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 Förbättra icke-paketerade skrivbordsappar med Windows Runtime-komponenter), som finns i Windows 10, version 1903 och senare. Interna C++-komponenter bör ange egenskapen Windows Desktop Compatible till True antingen via projektegenskaperna eller .vcxproj filen, för att referera till och vidarebefordra binärfilerna Microsoft.VCLibs.Desktop till att använda 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 hjälp av projektegenskapen <CsWinRTWindowsMetadata> , 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 hur du anger egenskapen finns i dokumenten om <TargetFramework>.

• 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-interopguiden.

• 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 projektegenskaperna eller via .vcxproj filen.

Versionsfel för .NET SDK

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

Fel eller varningsmeddelande	Reason
Varning MSB3277: Hittade 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-yta.
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 .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. De här felen kan uppstå vid tidig service/funktionsuppdateringar till .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-lagringsplatsen.

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 med C#/WinRT-problem.

Ytterligare resurser

• C#/WinRT GitHub-lagringsplats