Win32-API's aanroepen vanuit een C# Windows-app

De aanbevolen manier om Win32-API's aan te roepen vanuit C# is CsWin32, een brongenerator die typeveilige P/Invoke-wrappers produceert tijdens het compileren. CsWin32 werkt met elk type C#-project — WinUI 3, WPF, WinForms, console of klassenbibliotheek — en maakt het overbodig om declaraties voor DllImport of LibraryImport handmatig te schrijven.

U vermeldt de Win32-functienamen die u nodig hebt in een tekstbestand en CsWin32 genereert automatisch de juiste handtekeningen, structs, constanten en COM-interfaces uit Windows SDK-metagegevens.

Een interoperabiliteitsbenadering kiezen

Approach Wanneer gebruiken Pros Cons
CsWin32 (aanbevolen) Elke Win32/native API-aanroep van C# Type-veilig, gegenereerd op basis van officiële Windows SDK-metagegevens, verwerkt marshaling en structs, AOT-vriendelijk met configuratie Vereist NuGet-pakket; gegenereerde code is niet standaard zichtbaar
LibraryImport (.NET 7+) Eenmalige aanroepen waarbij u de exacte handtekening kent Door broncode gegenereerd, AOT-compatibel, zonder runtime-marshalling U schrijft en onderhoudt elke handtekening handmatig
DllImport (verouderd) Bestaande code- of .NET Framework-projecten Werkt overal, uitgebreide voorbeelden uit de community Gegevensconversie tijdens runtime, foutgevoelige signaturen
C#/WinRT Windows Runtime API’s (Windows.* naamruimten) Geprojecteerde .NET-types, natuurlijke C#-ervaring Alleen voor WinRT-API's, niet onbewerkte Win32

Note

De standaarduitvoer van CsWin32 maakt gebruik van de .NET runtime-marshaller en is niet automatisch AOT-compatibel. Schakel voor NativeAOT of trimming CsWin32RunAsBuildTask en DisableRuntimeMarshalling in — zie de CsWin32 AOT-richtlijnen.

Tip

Als de API die u nodig hebt zich in een Windows.* naamruimte bevindt (bijvoorbeeld Windows.Storage ofWindows.Media), is dit een Windows Runtime-API. Gebruik een WinRT-projectie in plaats van P/Invoke. Zie Interop-API's aanroepen vanuit een .NET-app.

Prerequisites

  • Visual Studio 2022 (versie 17.4 of hoger) of de .NET 8+ SDK
  • Een bestaand C#-project (WinUI 3, WPF, WinForms of console)

Note

Richten op .NET Framework of .NET Standard? Stel <LangVersion>9</LangVersion> (of hoger) in uw projectbestand in en voeg de System.MemorySystem.Runtime.CompilerServices.Unsafe NuGet-pakketten toe.

Stap 1: Het CsWin32 NuGet-pakket installeren

Voer in de projectmap het volgende uit:

dotnet add package Microsoft.Windows.CsWin32

CsWin32 genereert code die gebruikmaakt van aanwijzers en onveilige contexten. Het NuGet-pakket schakelt AllowUnsafeBlocks automatisch in. Als uw project expliciet is ingesteld op <AllowUnsafeBlocks>false</AllowUnsafeBlocks>, verwijder die regel of wijzig die in true, anders kan de gegenereerde code niet worden gecompileerd.

Stap 2: de API's aanvragen die u nodig hebt

Maak een bestand met de naamNativeMethods.txt in de hoofdmap van het project (naast het .csproj bestand). Voeg één API-naam per regel toe. Begin voor deze stapsgewijze uitleg met een eenvoudige functie:

GetTickCount

Sla het bestand op. CsWin32 leest het tijdens het compileren en genereert de overeenkomende P/Invoke-wrapper.

Stap 3: De gegenereerde API aanroepen

De gegenereerde code bevindt zich in de naamruimte Windows.Win32, in een statische klasse met de naam PInvoke. Roep deze aan als elke andere statische methode:

using Windows.Win32;

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

Bouw uw project. Als de functienaam in NativeMethods.txt geldig is, wordt de aanroep gecompileerd en uitgevoerd zonder extra werk.

Algemene valkuilen

"Ik kan de gegenereerde code niet zien"

CsWin32 is een brongenerator. De uitvoer wordt standaard niet weergegeven als bestanden in uw project. De gegenereerde code controleren:

  1. Vouw in Visual Studio Dependencies > Analyzers > Microsoft.Windows.CsWin32 > Microsoft.Windows.CsWin32.SourceGenerator uit in Solution Explorer.
  2. U kunt ook instellen <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> in het projectbestand om de gegenereerde bronnen naar de obj/ map te schrijven.

AnyCPU-platformdoel

Door CsWin32 gegenereerde code werkt met AnyCPU. U hoeft uw platformdoel niet te wijzigen voor de meeste Win32-aanroepen.

Een HWND verkrijgen in WinUI 3

Voor veel Win32-API's is een venstergreep vereist. Haal in een WinUI 3-app de HWND op van uw Window-exemplaar:

using WinRT.Interop;

var hWnd = WindowNative.GetWindowHandle(this);

Geef vervolgens hWnd (als een HWND of nint) door aan de Win32-functie. Zie Een venstergreep (HWND) ophalen voor meer informatie.

Gedrag van CsWin32 aanpassen

Maak een NativeMethods.json-bestand naast je tekstbestand om generatieopties te beheren, zoals marshaling van brede versus smalle tekenreeksen of gebruiksvriendelijke overloads:

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

Zie de csWin32-configuratiereferentie voor alle opties.

Volgende stappen 

  • Last updated on