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 über die 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-Interop-Assemblys für .NET-Verbraucher erstellen und referenzieren. Die neueste C#/WinRT-Version enthält auch eine Vorschau der Erstellung von WinRT-Typen in C#.

Weitere Informationen finden Sie unter C#/WinRT GitHub Repo.

Motivation für C#/WinRT

.NET (früher bekannt als .NET Core) 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ügten ü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 entfernt und in das C#/WinRT-Toolkit verschoben (siehe Built-In-Unterstützung für WinRT wird aus .NET entfernt). Das Ziel von C#/WinRT ist die Gleichwertigkeit mit der integrierten WinRT-Unterstützung, die von früheren Versionen des C#-Compilers und der .NET-Laufzeit bereitgestellt wurden. 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 3. Die Windows App SDK hebt systemeigene Microsoft UI-Steuerelemente und andere systemeigene Komponenten aus dem Betriebssystem auf. Dadurch können App-Entwickler die neuesten Steuerelemente und Komponenten in Windows 10, Version 1809 und höheren 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 im C#-Compiler oder .NET Laufzeit verfügbar ist.

Neuerungen

Die neuesten C#/WinRT-Versionen finden Sie auf unserer VersionshinweiseSeite im Github Repository.

Verbrauch

Das C#/WinRT NuGet-Paket kann sowohl dafür verwendet werden, C#-Projektionen (auch als Interop-Assemblys bezeichnet) aus WinRT-Komponenten zu generieren, als auch in der Erstellung von C#/WinRT-Komponenten. Weitere Informationen zu den Nutzungsszenarien für C#/WinRT finden Sie im Leitfaden zur Verwendung in 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-Interopassembly zusammen mit der Implementierungsassembly verteilen, damit .NET-Anwendungen darauf verweisen können, typischerweise als NuGet-Paket.

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 für das Generieren einer Interopassembly befolgen, um eigene private Projektionsquellen zu generieren. 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. 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 Informationen finden Sie in der eingebetteten Dokumentation C#/WinRT in 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 Drittanbieter-Komponenten in einer Desktopanwendung wird durch registrierungsfreie WinRT-Aktivierung ermöglicht (siehe Enhancing Non-packaged Desktop Apps using Windows Runtime Components), verfügbar in Windows 10, Version 1903 und höher. Systemeigene C++-Komponenten sollten die Windows Desktop Compatible-Eigenschaft auf True festlegen, entweder über die Projekteigenschaften oder die -Datei, um auf die Binärdateien Microsoft.VCLibs.Desktop zu verweisen und sie 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 eigenschaft <CsWinRTWindowsMetadata> project 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 zu 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ätsleitfaden.

• 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 Eigenschaft Windows Desktop Compatible entweder auf True festgelegt hat, entweder über die Projekteigenschaften oder über die Datei .

Fehler bei der .NET SDK-Versionsverwaltung

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

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ühzeitigen Wartungs-/Funktionsupdates 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 C#/WinRT GitHub Repo notiert.

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

Weitere Ressourcen

• C#/WinRT GitHub Repo