Microsoft.Windows.CsWin32 0.3.18-beta

Prefix Reserved
.NET Standard 1.0 This package targets .NET Standard 1.0. The package is compatible with this framework or higher. .NET Framework 2.0 This package targets .NET Framework 2.0. The package is compatible with this framework or higher.
This is a prerelease version of Microsoft.Windows.CsWin32.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package Microsoft.Windows.CsWin32 --version 0.3.18-beta                

                    
                

            
NuGet\Install-Package Microsoft.Windows.CsWin32 -Version 0.3.18-beta
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Microsoft.Windows.CsWin32" Version="0.3.18-beta">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add Microsoft.Windows.CsWin32 --version 0.3.18-beta                

                    
                

            
#r "nuget: Microsoft.Windows.CsWin32, 0.3.18-beta"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install Microsoft.Windows.CsWin32 as a Cake Addin
#addin nuget:?package=Microsoft.Windows.CsWin32&version=0.3.18-beta&prerelease

// Install Microsoft.Windows.CsWin32 as a Cake Tool
#tool nuget:?package=Microsoft.Windows.CsWin32&version=0.3.18-beta&prerelease

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.

NuGet (prerelease) NuGet (daily)

Build Status

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

Animation demonstrating p/invoke code generation

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

Tip: Remove the IncludeAssets metadata from the package reference so that you get better code generation by allowing nuget to bring in the System.Memory package as a transitive dependency.

 <PackageReference Include="Microsoft.Windows.CsWin32" Version="0.1.647-beta">
   <PrivateAssets>all</PrivateAssets>
-  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 </PackageReference>

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. This may be qualified with a namespace but is only recommended in cases of ambiguity, which CsWin32 will prompt where appropriate.
  • A macro name (e.g. HRESULT_FROM_WIN32). These are generated into the same class with extern methods. Macros must be hand-authored into CsWin32, so let us know if you want to see a macro added.
  • A namespace to generate all APIs from (e.g. Windows.Win32.Storage.FileSystem would search the metadata for all APIs within that namespace and generate them).
  • 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. This may be qualified with a namespace but is only recommended in cases of ambiguity, which CsWin32 will prompt where appropriate.
  • A prefix shared by many constants, followed by *, to generate all constants that share that prefix (e.g. ALG_SID_MD*).
  • 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 Windows.Win32.PInvoke class, like this:

using Windows.Win32;

PInvoke.CreateFile(/*args*/);

Constants are defined on the same class as the p/invoke methods (by default, the Windows.Win32.PInvoke class).

Other supporting types are defined within or under the Windows.Win32 namespace. Discovery of the namespace for a given type can be done with the Go To All feature (Ctrl+T) in Visual Studio with the type name as the search query.

A project may include many NativeMethods.txt files (each one necessarily in its own directory). CsWin32 will read them all to generate APIs, provided these files are included as AdditionalFiles in the project. A NativeMethods.txt file directly in the project directory is added automatically to AdditionalFiles. Files in other directories must be added to the project file manually.

Whether API requests are all in a single NativeMethods.txt file or split across many makes no difference to the generated result. We recommend using just one NativeMethods.txt file and keeping it sorted for easy bookkeeping. Multiple files perhaps makes the most sense in a Shared Project scenario where several API requests will be common across many projects, so sharing a NativeMethods.txt file with those same projects that contain all the necessary APIs for the set of shared source files make maintenance easier.

Some APIs require targeting a specific architecture and are not available when your C# project compiles as "Any CPU". Learn more about how this manifests and what your options are.

Customizing generated code

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

  • The name of the class(es) that declare p/invoke methods
  • 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, and in fact is where all the documentation for the available settings is found.

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

Most generated types include the partial modifier so you can add your own members to that type within your code.

When you need to replace a generated type, simply copy and paste it from generated code into your own source files and remove the partial modifier. Be sure to keep the name and namespace exactly the same. CsWin32 will notice that your project already declares the type and skip generating it, but generate everything else. Note that if that type is the only thing that references some other generated type, CsWin32 will stop generating that type too. To keep CsWin32 generating the referred types you need, add them explicitly to NativeMethods.txt.

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 --prerelease

CsWin32 also consumes the WDK from a similarly named package: Microsoft.Windows.WDK.WDKMetadata.

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" />
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard1.0 is compatible.  netstandard1.1 was computed.  netstandard1.2 was computed.  netstandard1.3 was computed.  netstandard1.4 was computed.  netstandard1.5 was computed.  netstandard1.6 was computed.  netstandard2.0 was computed.  netstandard2.1 was computed. 
.NET Framework net20 is compatible.  net35 was computed.  net40 was computed.  net403 was computed.  net45 was computed.  net451 was computed.  net452 was computed.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Universal Windows Platform uap was computed.  uap10.0 was computed. 
Windows Phone wp8 was computed.  wp81 was computed.  wpa81 was computed. 
Windows Store netcore was computed.  netcore45 was computed.  netcore451 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Microsoft.Windows.CsWin32:

Package Downloads
WinConsole

WinConsole Library

GitHub repositories (93)

Showing the top 5 popular GitHub repositories that depend on Microsoft.Windows.CsWin32:

Repository Stars
microsoft/PowerToys
Windows system utilities to maximize productivity
files-community/Files
A modern file manager that helps users organize their files and folders.
DevToys-app/DevToys
A Swiss Army knife for developers.
AvaloniaUI/Avalonia
Develop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The most popular .NET UI client technology
netchx/netch
A simple proxy client
Version Downloads Last updated
0.3.106 174,656 5/10/2024
0.3.49-beta 132,372 10/10/2023
0.3.46-beta 12,797 9/22/2023
0.3.18-beta 55,946 6/28/2023
0.3.2-beta 6,953 5/27/2023
0.2.252-beta 1,393 5/25/2023
0.2.229-beta 8,166 5/1/2023
0.2.206-beta 10,439 3/20/2023
0.2.188-beta 25,414 1/23/2023
0.2.164-beta 100,445 12/9/2022
0.2.162-beta 3,952 12/5/2022
0.2.158-beta 399 11/29/2022
0.2.138-beta 9,221 11/18/2022
0.2.104-beta 20,047 10/28/2022
0.2.63-beta 86,482 9/22/2022
0.2.46-beta 28,584 9/2/2022
0.2.10-beta 12,233 7/12/2022
0.2.1-beta 15,742 6/6/2022
0.1.691-beta 5,282 5/19/2022
0.1.689-beta 228 5/19/2022
0.1.647-beta 121,431 4/26/2022
0.1.646-beta 236 4/25/2022
0.1.635-beta 43,026 1/27/2022
0.1.619-beta 15,047 11/15/2021
0.1.588-beta 29,872 9/20/2021
0.1.584-beta 323 9/18/2021
0.1.560-beta 517 9/8/2021
0.1.506-beta 6,877 6/28/2021
0.1.422-beta 4,945 3/17/2021
0.1.378-beta 3,125 2/24/2021
0.1.319-beta 13,393 1/21/2021

https://github.com/Microsoft/CsWin32/releases/tag/v0.3.18-beta