C#/Win32 P/Invoke Source Generator

A source generator to add a user-defined set of Win32 P/Invoke methods and supporting types to a C# project.

Features

Rapidly add P/Invoke methods and supporting types to your C# project.
No bulky assemblies to ship alongside your application.
SafeHandle-types automatically generated.
Generates xml documentation based on and links back to docs.microsoft.com

Prerequisites

The .NET 5 SDK or Visual Studio 2019 Update 8 (16.8) for the C# compiler that added support for Source Generators. The experience with source generators in Visual Studio is still improving, and is noticeably better in VS 16.9. WPF projects have additional requirements.

In addition, some generated code may require use of the C# 9 language version (<LangVersion>9</LangVersion>) in your project file. See issue #4 for more on this.

See dotnet/pinvoke for precompiled NuGet packages with Win32 P/Invokes.

Usage

Install the Microsoft.Windows.CsWin32 package:

dotnet add package Microsoft.Windows.CsWin32 --prerelease

Your project must allow unsafe code to support the generated code that will likely use pointers. This does not automatically make all your code unsafe. Use of the unsafe keyword is required anywhere you use pointers. The source generator NuGet package sets the default value of the AllowUnsafeBlocks property for your project to true, but if you explicitly set it to false in your project file, generated code may produce compiler errors.

Create a NativeMethods.txt file in your project directory that lists the APIs to generate code for. Each line may consist of one of the following:

Exported method name (e.g. CreateFile). This may include the A or W suffix, where applicable.
A namespace to generate all APIs within (e.g. Windows.Win32.Storage.FileSystem).
Module name followed by .* to generate all methods exported from that module (e.g. Kernel32.*).
The name of a struct, enum, constant or interface to generate.
A comment (i.e. any line starting with //) or white space line, which will be ignored.

When generating any type or member, all supporting types will also be generated.

Generated code is added directly in the compiler. An IDE may make this generated code available to view through code navigation commands (e.g. Go to Definition) or a tree view of source files that include generated source files.

Assuming default settings and a NativeMethods.txt file with content that includes CreateFile, the P/Invoke methods can be found on the Microsoft.Windows.Sdk.PInvoke class, like this:

using Microsoft.Windows.Sdk;

PInvoke.CreateFile(/*args*/);

Constants are defined on the Microsoft.Windows.Sdk.Constants class.

Other supporting types are defined within the Microsoft.Windows.Sdk namespace.

Customizing generated code

Several aspects of the generated code can be customized, including:

The name of the class(es) that declare p/invoke methods
The namespace that declares all interop types
Whether to emit interop types as public or internal
Whether to emit ANSI functions as well where Wide character functions also exist
Set PreserveSig for COM interfaces or individual members
Force generation of blittable structs, COM structs instead of interfaces (for super high performance with 0 GC pressure), etc.

To configure these settings, create a NativeMethods.json file in your project directory. Specifying the $schema property adds completions, descriptions and validation in many JSON editors.

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

Newer metadata

To update the metadata used as the source for code generation, you may install a newer Microsoft.Windows.SDK.Win32Metadata package:

dotnet add package Microsoft.Windows.SDK.Win32Metadata -pre

Alternatively, you may set the MicrosoftWindowsSdkWin32MetadataBasePath property in your project file to the path of the directory containing Windows.Win32.winmd:

<MicrosoftWindowsSdkWin32MetadataBasePath>c:\path\to\dir</MicrosoftWindowsSdkWin32MetadataBasePath>

Known issues

Consuming daily builds

Can't wait for the next release to try out a bug fix? Follow these steps to consume directly from our daily build.

Just add this package feed to your nuget.config file:

<add key="winsdk" value="https://pkgs.dev.azure.com/azure-public/winsdk/_packaging/CI/nuget/v3/index.json" />

sharwell / CsWin32