C#/WinRT

C#/WinRT ist ein NuGet-paketiertes Toolkit, das Windows-Runtime(WinRT)-Projektionsunterstützung für die C#-Sprache bereitstellt. Eine Projektionsassembly ist eine Interopassembly, die es ermöglicht, WinRT-APIs auf natürliche und vertraute Weise für die Zielsprache zu programmieren. Die C#/WinRT-Projektion blendet die Details der Interoperabilität zwischen C#- und WinRT-Schnittstellen aus und stellt Zuordnungen vieler WinRT-Typen zu entsprechenden .NET-Entsprechungen bereit, z. B. Zeichenfolgen, URIs, allgemeine Werttypen und generische Auflistungen.

C#/WinRT bietet derzeit Unterstützung für die Nutzung von WinRT-APIs unter Verwendung von Target Framework Monikers (TFMs) in .NET. Durch Festlegen des TFM mit einer bestimmten Windows SDK-Version werden Verweise auf die windows SDK-Projektions- und Laufzeitassemblys hinzugefügt, die von C#/WinRT generiert werden.

Mit dem C#/WinRT NuGet-Paket können Sie eigene WinRT-Interopassemblys für .NET-Consumer erstellen und referenzieren . Die neueste C#/WinRT-Version enthält auch eine Vorschau der Erstellung von WinRT-Typen in C#.

Weitere Informationen finden Sie im GitHub-Repository "C#/WinRT".

Motivation für C#/WinRT

.NET (früher als .NET Core bezeichnet) ist eine plattformübergreifende Open Source-Laufzeit, die zum Erstellen von Geräte-, Cloud- und IoT-Anwendungen verwendet werden kann.

Frühere Versionen von .NET Framework und .NET Core verfügen über integrierte Kenntnisse von WinRT – einer Windows-spezifischen Technologie. Um die Portabilitäts- und Effizienzziele von .NET 6+ zu unterstützen, haben wir die WinRT-Projektionsunterstützung aus dem .NET-Compiler und der Laufzeit aufgehoben und in das C#/WinRT-Toolkit verschoben (siehe integrierte Unterstützung für WinRT wird aus .NET entfernt). Das Ziel von C#/WinRT ist die Parität mit der integrierten WinRT-Unterstützung, die von früheren Versionen des C#-Compilers und der .NET-Runtime bereitgestellt wird. Ausführliche Informationen finden Sie unter .NET-Zuordnungen von Windows-Runtime-Typen.

C#/WinRT unterstützt auch Komponenten im Windows App SDK, einschließlich WinUI. Das Windows App SDK hebt systemeigene Microsoft UI-Steuerelemente und andere systemeigene Komponenten aus dem Betriebssystem auf. Auf diese Weise können App-Entwickler die neuesten Steuerelemente und Komponenten unter Windows 10, Version 1809 und neueren Versionen verwenden.

Schließlich ist C#/WinRT ein allgemeines Toolkit und soll andere Szenarien unterstützen, in denen die integrierte Unterstützung für WinRT nicht in der C#-Compiler- oder .NET-Runtime verfügbar ist.

Neuerungen

Die neuesten C#/WinRT-Versionen finden Sie auf unserer Versionshinweise-Seite im GitHub-Repository.

Verbrauch

Das C#/WinRT NuGet-Paket kann verwendet werden, um sowohl C#-Projektionen (auch als Interop-Assemblys bezeichnet) aus WinRT-Komponenten zu generieren als auch für das Autorisieren von C#/WinRT-Komponenten. Weitere Informationen zu den Nutzungsszenarien für C#/WinRT finden Sie im Verwendungshandbuch zu unserem Repository.

Generieren und Verteilen einer Interop-Assembly

WinRT-APIs werden in Windows-Metadatendateien (WinMD) definiert. Das C#/WinRT NuGet-Paket (Microsoft.Windows.CsWinRT) enthält den C#/WinRT-Compiler cswinrt.exe, mit dem Sie WinMD-Dateien verarbeiten und .NET C#-Code generieren können. C#/WinRT kompiliert diese Quelldateien in einer Interopassembly, ähnlich wie C++/WinRT Header für die C++-Sprachprojektion generiert. Anschließend können Sie die C#/WinRT-Interop-Assembly zusammen mit der Implementierungs-Assembly für .NET-Anwendungen verteilen, die typischerweise als NuGet-Paket referenziert werden.

Weitere Informationen zum Generieren und Verteilen einer Interopassembly finden Sie unter Generieren einer C#-Projektion aus einer C++/WinRT-Komponente, die als NuGet für .NET-Apps verteilt wird.

Verweisen auf eine Interopassembly

In der Regel werden C#/WinRT-Interop-Assemblys von Anwendungsprojekten referenziert. Sie können aber auch von Zwischen-Interop-Assemblys referenziert werden. Die WinUI-Interop-Assembly verweist beispielsweise auf die Interop-Assembly des Windows SDK.

Wenn Sie eine WinRT-Komponente eines Drittanbieters ohne offizielle Interopassembly verteilen, kann ein Anwendungsprojekt das Verfahren zum Generieren einer Interopassembly zum Generieren eigener privater Projektionsquellen befolgen. Wir empfehlen diesen Ansatz nicht, da er widersprüchliche Projektionen desselben Typs innerhalb eines Prozesses erzeugen kann. NuGet-Verpackungen nach dem Schema für die semantische Versionsverwaltung sollen dies verhindern. Eine offizielle Interop-Assembly von einem Drittanbieter wird bevorzugt.

Eingebettete Unterstützung für WinRT-Typen (Vorschau)

Ab C#/WinRT Version 1.4.1 ist unterstützung für das Einbetten von Windows SDK-Projektions- und Laufzeitquellen für .NET und .NET Standard 2.0 in die Bibliotheks- oder App-Ausgabe enthalten. Dies ist in Fällen hilfreich, in denen die Verwendung von Windows SDK-Typen eigenständig ist. Die eingebettete Unterstützung entfernt Abhängigkeiten von WinRT.Runtime.dll und Microsoft.Windows.SDK.NET.dll, wodurch die Bibliotheks- oder App-Ausgabegröße reduziert wird. Außerdem ermöglicht es Bibliotheksentwicklern, Unterstützung auf Downlevel bereitzustellen und die Notwendigkeit von Multi-Targeting zu entfernen.

Weitere Details finden Sie in der eingebetteten C#/WinRT-Dokumentation zu unserem Repository.

WinRT-Typaktivierung

C#/WinRT unterstützt die Aktivierung von WinRT-Typen, die vom Betriebssystem gehostet werden, sowie Drittanbieterkomponenten wie Win2D. Die Unterstützung für die Aktivierung von Drittanbieterkomponenten in einer Desktopanwendung ist mit der Registrierung kostenloser WinRT-Aktivierung aktiviert (siehe Verbessern nicht verpackter Desktop-Apps mit Windows-Runtime-Komponenten), verfügbar in Windows 10, Version 1903 und höher. Systemeigene C++-Komponenten sollten die Windows Desktop Compatible-Eigenschaft entweder über die Projekteigenschaften oder die .vcxproj-Datei auf "True" festlegen, um auf die Binärdateien Microsoft.VCLibs.Desktop zu verweisen und diese an nutzende Apps weiterzuleiten. Andernfalls wird das VCRT-Weiterleitungspaket von konsumierenden Apps benötigt, wenn die Komponente nur auf UWP-Apps ausgelegt ist.

C#/WinRT bietet auch einen Aktivierungs-Fallbackpfad, wenn Windows den Typ wie oben beschrieben nicht aktivieren kann. In diesem Fall versucht C#/WinRT, eine systemeigene Implementierungs-DLL basierend auf dem vollqualifizierten Typnamen zu finden, wobei Elemente schrittweise entfernt werden. Die Fallbacklogik würde beispielsweise versuchen, den Contoso.Controls.Widget-Typ aus den folgenden Modulen in Sequenz zu aktivieren:

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

C#/WinRT verwendet die alternative LoadLibrary-Suchreihenfolge , um eine Implementierungs-DLL zu finden. Eine App, die auf dieses Fallbackverhalten angewiesen ist, sollte die Implementierungs-DLL zusammen mit dem App-Modul verpacken.

Häufige Fehler und Problembehandlung

• Fehler: "Windows-Metadaten wurden nicht bereitgestellt oder erkannt."

  Sie können Windows-Metadaten mithilfe der <CsWinRTWindowsMetadata> Projekteigenschaft angeben, z. B.:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  In C#/WinRT-Version 1.2.1 und höher ist diese Eigenschaft standardmäßig auf TargetPlatformVersion voreingestellt, was von der in der TargetFramework-Eigenschaft angegebenen Windows SDK-Version abgeleitet wird.

• Fehler CS0246: Der Typ oder Namespacename "Windows" konnte nicht gefunden werden (fehlt eine using-Anweisung oder ein Assemblyverweis?)

  Um diesen Fehler zu beheben, bearbeiten Sie Ihre <TargetFramework> Eigenschaft so, dass sie auf eine bestimmte Windows-Version ausgerichtet ist, z. B.:

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

  Weitere Informationen zum Angeben der Eigenschaft finden Sie in der Dokumentation zum Aufrufen von Windows-Runtime-APIs.

• System.InvalidCastException beim Umwandeln in eine Schnittstelle mit dem ComImport Attribut

  Wenn Sie ein Objekt in eine Schnittstelle umwandeln, die das ComImport Attribut aufweist, müssen Sie den .As<> Operator anstelle eines expliziten Umwandlungsausdrucks verwenden. Beispiel:

  someObject.As<SomeComImportInterface>
  

  Weitere Informationen finden Sie im COM-Interoperabilitätshandbuch.

• System.Runtime.InteropServices.COMException: Klasse nicht registriert (0x80040154 (REGDB_E_CLASSNOTREG))

  • Wenn diese Ausnahme beim Verwenden einer C#/WinRT-Projektion aus einer C++/WinRT-Komponente angezeigt wird, stellen Sie sicher, dass die Komponente die Windows Desktop Compatible-Eigenschaft entweder über die Projekteigenschaften oder über die Datei auf .vcxproj festgelegt hat.

.NET SDK-Versionsverwaltungsfehler

Möglicherweise treten die folgenden Fehler oder Warnungen in einem Projekt auf, das mit einer früheren .NET SDK-Version erstellt wurde, als jede seiner Abhängigkeiten.

Fehlermeldung oder Warnmeldung	Ursache
Warnung MSB3277: Es wurden Konflikte zwischen verschiedenen Versionen von WinRT.Runtime oder Microsoft.Windows.SDK.NET gefunden, die nicht behoben werden konnten.	Diese Buildwarnung tritt auf, wenn auf eine Bibliothek verwiesen wird, die Windows SDK-Typen auf der API-Oberfläche verfügbar macht.
Fehler CS1705: Assembly 'AssemblyName1' verwendet 'TypeName' mit einer höheren Version als auf die Assembly 'AssemblyName2' verwiesen wird.	Dieser Build-Compiler-Fehler tritt auf, wenn auf exponierte Windows SDK-Typen in einer Bibliothek verwiesen und verwendet werden.
System.IO.FileLoadException	Dieser Laufzeitfehler kann auftreten, wenn bestimmte APIs in einer Bibliothek aufgerufen werden, die keine Windows SDK-Typen verfügbar macht.

Um diese Fehler zu beheben, aktualisieren Sie Ihr .NET SDK auf die neueste Version. Dadurch wird sichergestellt, dass die von Ihrer Anwendung verwendeten Laufzeit- und Windows SDK-Assemblyversionen mit allen Abhängigkeiten kompatibel sind. Diese Fehler können bei frühen Wartungs-/Featureupdates für das .NET SDK auftreten, da Laufzeitfixes möglicherweise Updates für unsere Assemblyversionen erfordern.

Bekannte Probleme

Bekannte Probleme und wichtige Änderungen werden im GitHub-Repository "C#/WinRT" aufgeführt.

Wenn Sie funktionale Probleme mit dem C#/WinRT NuGet-Paket, dem cswinrt.exe Compiler oder den generierten Projektionsquellen haben, übermitteln Sie probleme über die Seite mit C#/WinRT-Problemen an uns.

Weitere Ressourcen

• C#/WinRT GitHub-Repository