C#/WinRT

  • Artikel

Bei C#/WinRT handelt es sich um ein Toolkit als NuGet-Paket, das die Projektionsunterstützung in der Windows-Runtime (WinRT) für die C#-Sprache bereitstellt. Eine Projektionsassmbly ist eine Interop-Assembly, die die Programmierung von WinRT-APIs auf für die Zielsprache natürliche und vertraute Weise ermöglicht. Die C#/WinRT-Projektion verbirgt die Details der Interop zwischen C#- und WinRT-Schnittstellen und stellt Zuordnungen vieler WinRT-Typen zu geeigneten .NET-Entsprechungen wie Zeichenfolgen, URIs, allgemeinen Werttypen und generischen Sammlungen bereit.

C#/WinRT bietet derzeit Unterstützung für die Verarbeitung von WinRT-APIs durch die Verwendung von Zielframeworkmonikers (TFMs) in .NET. Wenn der Zielframeworkmoniker auf eine bestimmte Windows SDK-Version festgelegt wird, werden Verweise auf die Windows SDK-Projektion und Laufzeitassemblys hinzugefügt, die von C#/WinRT generiert wurden.

Mit dem C#/WinRT NuGet-Paket können Sie Ihre eigenen WinRT-Interopassemblys für .NET-Consumer erstellen und darauf verweisen. Die neueste C#/WinRT-Version enthält auch eine Vorschau auf die Erstellung von WinRT-Typen in C#.

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

Motivation für C#/WinRT

.NET (früher bekannt als .NET Core) ist eine plattformübergreifende Open-Source-Laufzeitumgebung, mit der Geräte-, Cloud- und IoT-Anwendungen erstellt werden können.

In frühere Versionen von .NET Framework und .NET Core waren Kenntnisse über WinRT integriert,—eine Windows-spezifische Technologie. Zur Unterstützung der Portabilitäts- und Effizienzziele von .NET 6+ haben wir die WinRT-Projektionsunterstützung aus dem .NET-Compiler und der Laufzeitumgebung entfernt und in das C#/WinRT-Toolkit verschoben (siehe Integrierte Unterstützung für WinRT wird aus .NET entfernt). C#/WinRT soll für Parität mit der integrierten WinRT-Unterstützung sorgen, die in früheren Versionen des C#-Compilers und der .NET-Laufzeit bereitgestellt wird. Einzelheiten hierzu finden Sie unter .NET-Zuordnungen von Windows-Runtime-Typen.

C#/WinRT unterstützt auch Komponenten im Windows App SDK, einschließlich WinUI 3. Mit dem Windows App SDK werden native Steuerelemente der Microsoft-Benutzeroberfläche und andere native Komponenten aus dem Betriebssystem herausgelöst. Dadurch können App-Entwickler die neuesten Steuerelemente und Komponenten unter Windows 10, Version 1809 und höheren Versionen verwenden.

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

Neuigkeiten

Die neuesten C#/WinRT-Releases finden Sie auf unserer Seite mit den Versionshinweisen im GitHub-Repository.

Verbrauch

Das C#/WinRT NuGet-Paket kann sowohl zum Generieren von C#-Projektionen (auch als Interopassemblys bezeichnet) von WinRT-Komponenten als auch zum Erstellen von C#/WinRT-Komponenten verwendet werden. Weitere Informationen zu den Verwendungsszenarien für C#/WinRT finden Sie im Benutzerhandbuch in unserem Repository.

Generieren und Verteilen einer Interopassembly

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 erstellen können. C#/WinRT kompiliert diese Quelldateien in eine Interop-Assembly, ähnlich wie C++/WinRT Header für die C++-Sprachprojektion generiert. Sie können die C#/WinRT-Interopassembly zusammen mit der Implementierungsassembly, auf die .NET-Anwendungen verweisen sollen, verteilen, typischerweise als NuGet-Paket.

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

Verweisen auf eine Interop-Assembly

In der Regel wird von Anwendungsprojekten auf C#/WinRT-Interop-Assemblys verwiesen. Es ist aber auch ein Verweis durch temporäre Interop-Assemblys möglich. So kann beispielsweise die WinUI-Interop-Assembly auf die Windows SDK-Interop-Assembly verweisen.

Wenn Sie eine WinRT-Komponente eines Drittanbieters ohne eine offizielle Interopassembly verteilen, kann ein Anwendungsprojekt das Verfahren zum Generieren einer Interopassembly befolgen, um eigene private Projektionsquellen zu generieren. Eine solche Vorgehensweise wird nicht empfohlen, da Sie in einem Prozess widersprüchliche Projektionen desselben Typs verursachen kann. Dies wird durch das Erstellen von NuGet-Paketen nach dem Schema der semantischen Versionierung verhindert. Eine offizielle Interop-Assembly von Drittanbietern ist zu bevorzugen.

Embedded-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 Ausgabe Ihrer Bibliothek oder App enthalten. Dies ist nützlich, wenn die Verwendung Windows SDK-Typen eigenständig ist. Durch die Embedded-Unterstützung werden Abhängigkeiten von „WinRT.Runtime.dll“ und „Microsoft.Windows.SDK.NET.dll“ entfernt, wodurch die Ausgabegröße der Bibliothek oder App reduziert wird. Außerdem können Bibliotheksentwickler Downlevelunterstützung bereitstellen und müssen nicht mehr mehrere Zielversionen festlegen.

Weitere Informationen finden Sie in der C#/WinRT Embedded-Dokumentation in unserem Repository.

Aktivierung von WinRT-Typen

C#/WinRT unterstützt die Aktivierung von WinRT-Typen, die vom Betriebssystem gehostet werden, sowie von Drittanbieter-Komponenten wie z. B. Win2D. Die Unterstützung der Aktivierung von Drittanbieter-Komponenten in einer Desktopanwendung wird durch die registrierungsfreie WinRT-Aktivierung ermöglicht (siehe Verbessern nicht gepackter Desktop-Apps mithilfe von Windows-Runtime-Komponenten), die ab Windows 10, Version 1903 verfügbar ist. Für native C++-Komponenten sollte die Eigenschaft Windows Desktop Compatible entweder über die Projekteigenschaften oder die Datei auf True.vcxproj festgelegt werden, um die Microsoft.VCLibs.Desktop-Binärdateien zu referenzieren und an verarbeitende Apps weiterzuleiten. Andernfalls wird das VCRT Forwarders-Paket von verarbeitenden Apps benötigt, wenn die Komponente nur für UWP-Apps bestimmt ist.

C#/WinRT bietet auch einen Aktivierungs-Fallbackpfad, wenn Windows den Typ nicht wie oben beschrieben aktivieren kann. In diesem Fall versucht C#/WinRT, eine systemeigene Implementierungs-DLL anhand des vollqualifizierten Typnamens zu suchen, wobei Elemente progressiv entfernt werden. Die Fallbacklogik würde beispielsweise versuchen, den Typ „Contoso.Controls.Widget“ nacheinander aus den folgenden Modulen 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 aufzufinden. Eine App, die sich auf ein derartiges Fallbackverhalten stützt, muss die Implementierungs-DLL neben dem App-Modul verpacken.

Häufige Fehler und Problembehandlung

  • Fehler: „Es wurden keine Windows-Metadaten bereitgestellt oder erkannt.“

    Sie können Windows-Metadaten z. B. über die Projekteigenschaft <CsWinRTWindowsMetadata> angeben:

    <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>

    In C#/WinRT, Version 1.2.1 und höher, wird diese Eigenschaft standardmäßig auf TargetPlatformVersion festgelegt, was von der in der Eigenschaft TargetFramework 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, um z. B. eine bestimmte Windows-Version anzusteuern:

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

    Weitere Details zum Festlegen der <TargetFramework>-Eigenschaft finden Sie in der Dokumentation zum Aufrufen von Windows-Runtime-APIs.

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

    Beim Umwandeln eines Objekts auf eine Schnittstelle, die das Attribut ComImport aufweist, müssen Sie den Operator .As<> anstelle eines expliziten Cast-Ausdrucks verwenden. Zum Beispiel:

    someObject.As<SomeComImportInterface>

    Weitere Informationen finden Sie im COM-Interop-Leitfaden.

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

    • Wenn Sie beim Verarbeiten einer C#/WinRT-Projektion von einer C++/WinRT-Komponente diese Ausnahme sehen, stellen Sie sicher, dass die Eigenschaft Windows Desktop Compatible für die Komponente entweder über die Projekteigenschaften oder über die Datei .vcxproj auf True festgelegt wurde.

.NET SDK-Versionsverwaltungsfehler

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

Fehler- oder Warnmeldung `Reason`
Warnung MSB3277: Es wurden Konflikte zwischen verschiedenen Versionen von WinRT.Runtime oder Microsoft.Windows.SDK.NET gefunden, die nicht aufgelöst 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: Die Assembly „AssemblyName1“ verwendet „TypeName“ mit einer höheren Version als die referenzierte Assembly „AssemblyName2“. Dieser Buildcompilerfehler tritt auf, wenn auf verfügbar gemachte Windows SDK-Typen in einer Bibliothek verwiesen wird und diese verarbeitet werden.
System.IO.FileLoadException Dieser Laufzeitfehler kann beim Aufrufen bestimmter APIs in einer Bibliothek auftreten, die keine Windows SDK-Typen verfügbar macht.

Aktualisieren Sie das .NET SDK auf die neueste Version, um diese Fehler zu beheben. Dadurch wird sichergestellt, dass die von Ihrer Anwendung verwendeten Laufzeitversionen und Windows SDK-Assemblyversionen mit allen Abhängigkeiten kompatibel sind. Diese Fehler treten möglicherweise bei frühen Wartungs-/Featureaktualisierungen für das .NET SDK auf, da bei Laufzeitkorrekturen möglicherweise Aktualisierungen der Assemblyversionen erforderlich sind.

Bekannte Probleme

Bekannte Probleme und bedeutende Änderungen sind im C#/WinRT-GitHub-Repository aufgeführt.

Sollten Sie funktionale Probleme mit dem C#/WinRT NuGet-Paket, dem Compiler „cswinrt.exe“ oder den generierten Projektionsquellen feststellen, teilen Sie uns die Probleme über die Seite für C#/WinRT-Probleme mit.

Zusätzliche Ressourcen