Aufrufen von Win32-APIs aus einer C#-Windows-App

Die empfohlene Methode zum Aufrufen von Win32-APIs aus C# ist CsWin32, ein Quellgenerator, der typsichere P/Invoke-Wrapper zur Kompilierungszeit erzeugt. CsWin32 funktioniert mit jedem C#-Projekttyp – WinUI 3, WPF, WinForms, Konsole oder Klassenbibliothek – und beseitigt die Notwendigkeit von HandschreibDllImport- oder LibraryImport Deklarationen.

Sie listen die Win32-Funktionsnamen in einer Textdatei auf, und CsWin32 generiert die richtigen Signaturen, Strukturen, Konstanten und COM-Schnittstellen automatisch aus Windows SDK-Metadaten.

Auswählen eines Interoperabilitätsansatzes

Approach Wann verwenden? Pros Cons
CsWin32 (empfohlen) Jeder Win32/native API-Aufruf von C# Typsicher, generiert aus offiziellen Metadaten des Windows SDK, unterstützt Marshaling und Strukturen, AOT-freundlich mit Konfiguration Erfordert NuGet-Paket; Generierter Code ist standardmäßig nicht sichtbar.
LibraryImport (.NET 7+) Einmalige Anrufe, bei denen Sie die genaue Signatur kennen quellgeneriert, AOT-kompatibel, kein Marshalling zur Laufzeit Sie schreiben und verwalten jede Signatur manuell.
DllImport (veraltet) Vorhandene Code- oder .NET Framework-Projekte Funktioniert überall, umfangreiche Community-Beispiele Laufzeitmarsing, fehleranfällige Signaturen
C#/WinRT Windows-Runtime-APIs (Windows.* Namespaces) Projizierte .NET Typen, natürliche C#-Erfahrung Nur für WinRT-APIs, nicht unformatierte Win32

Note

Die Standardausgabe von CsWin32 verwendet den .NET Laufzeit-Marshaller und ist nicht automatisch AOT-kompatibel. Aktivieren Sie für NativeAOT oder Trimming CsWin32RunAsBuildTask und DisableRuntimeMarshalling – siehe die CsWin32-AOT-Anleitung.

Tip

Wenn sich die benötigte API in einem Windows.* Namespace befindet (zWindows.Storage. B. oder Windows.Media), handelt es sich um eine Windows-Runtime-API. Verwenden Sie eine WinRT-Projektion anstelle von P/Invoke. Siehe Aufrufen von Interoperabilitäts-APIs aus einer .NET-App.

Voraussetzungen

  • Visual Studio 2022 (Version 17.4 oder höher) oder das .NET 8+ SDK
  • Ein vorhandenes C#-Projekt (WinUI 3, WPF, WinForms oder Konsole)

Note

Zielbestimmung für .NET Framework oder .NET Standard? Legen Sie <LangVersion>9</LangVersion> (oder höher) in Ihrer Projektdatei fest, und fügen Sie die NuGet-Pakete System.Memory und System.Runtime.CompilerServices.Unsafe hinzu.

Schritt 1: Installieren des CsWin32 NuGet-Pakets

Führen Sie in Ihrem Projektverzeichnis Folgendes aus:

dotnet add package Microsoft.Windows.CsWin32

CsWin32 generiert Code, der Zeiger und unsichere Kontexte verwendet. Das NuGet-Paket aktiviert AllowUnsafeBlocks automatisch. Wenn in Ihrem Projekt <AllowUnsafeBlocks>false</AllowUnsafeBlocks> explizit festgelegt ist, entfernen Sie diese Zeile oder ersetzen Sie sie durch true, andernfalls lässt sich der generierte Code nicht kompilieren.

Schritt 2: Anfordern der benötigten APIs

Erstellen Sie eine Datei mit dem NamenNativeMethods.txt im Projektstamm (neben der .csproj Datei). Fügen Sie pro Zeile einen API-Namen hinzu. Beginnen Sie für diese exemplarische Vorgehensweise mit einer einfachen Funktion:

GetTickCount

Speichern Sie die Datei. CsWin32 liest sie während der Kompilierung und generiert den entsprechenden P/Invoke-Wrapper.

Schritt 3: Aufrufen der generierten API

Der generierte Code befindet sich im Windows.Win32 Namespace unter einer statischen Klasse namens PInvoke. Rufen Sie sie wie jede andere statische Methode auf:

using Windows.Win32;

// Get the number of milliseconds since the system started.
uint uptime = PInvoke.GetTickCount();
Console.WriteLine($"System uptime: {uptime} ms");

Erstellen Sie das Projekt. Wenn der Funktionsname in NativeMethods.txt gültig ist, wird der Aufruf kompiliert und ohne zusätzliche Arbeit ausgeführt.

Häufige Fallstricke

"Der generierte Code kann nicht angezeigt werden"

CsWin32 ist ein Quellgenerator, dessen Ausgabe standardmäßig nicht als Dateien in Ihrem Projekt angezeigt wird. So prüfen Sie den generierten Code:

  1. Erweitern Sie in Visual Studio Abhängigkeitsanalyses >> Microsoft.Windows. CsWin32 > Microsoft.Windows. CsWin32.SourceGenerator in Projektmappen-Explorer.
  2. Legen Sie alternativ <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> in Ihrer Projektdatei fest, damit die generierten Quellen in den Ordner obj/ geschrieben werden.

AnyCPU-Plattformziel

CsWin32-generierter Code funktioniert mit AnyCPU. Sie müssen Ihr Plattformziel für die meisten Win32-Anrufe nicht ändern.

Ermitteln des HWND in WinUI 3

Viele Win32-APIs erfordern ein Fensterhandle. Rufen Sie in einer WinUI 3-App das HWND aus Ihrer Window-Instanz ab:

using WinRT.Interop;

var hWnd = WindowNative.GetWindowHandle(this);

Übergeben Sie hWnd dann an die Win32-Funktion (als HWND oder nint). Weitere Informationen finden Sie unter Abrufen eines Fensterhandles (HWND).

Anpassen des CsWin32-Verhaltens

Erstellen Sie neben Ihrer Textdatei eine NativeMethods.json-Datei, um Generierungsoptionen wie das Marshalling von breiten gegenüber schmalen Zeichenfolgen oder anwenderfreundliche Überladungen zu steuern:

{
  "$schema": "https://aka.ms/CsWin32.schema.json",
  "emitSingleFile": false,
  "public": true
}

Alle Optionen finden Sie in der CsWin32-Konfigurationsreferenz .

Nächste Schritte

  • Last updated on