/Vanara

A set of .NET libraries for Windows implementing PInvoke calls to many native Windows APIs with supporting wrappers.

Primary LanguageC#MIT LicenseMIT

Vanara

This project contains various .NET assemblies that contain P/Invoke functions, interfaces, enums and structures from Windows libraries. Each assembly is associated with one or a few tightly related libraries. For example, Shlwapi.dll has all the exported functions from shlwapi.lib; Kernel32.dll has all for both kernel32.lib and kernelbase.lib.

All assemblies are available via NuGet and provide builds against .NET 2.0, 3.5, 4.0 and 4.5. In all cases where a dependency doesn't disallow it, .NET Standard 2.0, .NET Core 2.0, and 2.1 builds are also included for use with UWP and other .NET Core and Standard projects.

Use

  1. Look for the function you need in Microsoft documentation. Note which library or DLL the function is in.
  2. Confirm the Vanara library exists and has your function by looking at the Supported Libraries table below. Clicking on the Assembly link will take you to a drill down of that assembly's coverage. Find your function and if there is a matching implementation it will appear to the right.
  3. Add the assembly to your project via NuGet.
  4. To use the function, you can:
    1. Call it directly var bret = Vanara.PInvoke.Kernel32.GetComputerName(sb, ref sbSz);
    2. Under C# 6.0 and later, use a static using directive and call it:
    using static Vanara.PInvoke.Kernel32;

var bret = GetComputerName(sb, ref sbSz);
  5. In some cases there is a corresponding helper/wrapper class in one of the Supporting Assemblies, especially for Security, System Services, Forms and Shell. Go to their library page (click on link in section) and look through the classes included in each library.

Design Concepts

I have tried to follow the concepts below in laying out the libraries.

  • All functions that are imported from a single DLL should be placed into a single assembly that is named after the DLL.
    • (e.g. The assembly Vanara.PInvoke.Gdi32.dll hosts all functions and supporting enumerations, constants and structures that are exported from gdi32.dll in the system directory.)
  • Any structure or macro or enumeration (no function) that is used by many libraries is put into either Vanara.Core or Vanara.PInvoke.Shared.
    • (e.g. The macro HIWORD and the structure SIZE are both in Vanara.PInvoke.Shared and classes to simplfy interop calls and native memory management are in Vanara.Core.)
  • Inside a project, all constructs are contained in a file named after the header file (*.h) in which they are defined in the Windows API.
    • (e.g. In the Vanara.PInvoke.Kernel32 project directory, you'll find a FileApi.cs, a WinBase.cs and a WinNT.cs file representing fileapi.h, winbase.h and winnt.h respectively.)
  • Where the direct interpretation of a structure or function leads to memory leaks or misuse, I have tried to simplify its use.
  • Where a structure is always passed by reference and where that structure needs to clean up memory allocations, I have changed the structure to a class implementing IDisposable.
  • Wherever possible, all handles have been turned into SafeHandle derivatives named after the Windows API handle. If those handles require a call to a function to release/close/destroy, a derived SafeHANDLE exists that performs that function on disposal.
    • e.g. HTOKEN is defined. SafeHTOKEN builds upon that handle with an automated release calling CloseHandle.
  • Wherever possible, all functions that allocate memory that is to be freed by the caller use a safe memory handle.
  • All PInvoke calls are in assemblies prefixed by Vanara.PInvoke.
  • If a structure is to passed into a function, that structure is marshaled using the in statement which will pass the structure by reference without requiring the ref keyword.
    • Windows API: BOOL MapDialogRect(HWND hDlg, LPRECT lpRect)
    • Vanara: bool MapDialogRect(HWND hDlg, in RECT lpRect);
  • If there are classes or extensions that make use of the PInvoke calls, they are in wrapper assemblies prefixed by Vanara and then followed by a logical name for the functionality. Today, those are Core, Security, SystemServices, Windows.Forms and Windows.Shell.

Supported Libraries

Library/DLL Assembly Coverage NuGet Link
Core (see Supporting Assemblies) Vanara.Core Coverage NuGet
Shared (see Supporting Assemblies) Vanara.PInvoke.Shared Coverage NuGet
AclUI.dll Vanara.PInvoke.AclUI Coverage NuGet
qmgr.dll (BITS) Vanara.PInvoke.BITS Coverage NuGet
Cabinet.dll Vanara.PInvoke.Cabinet Coverage NuGet
ComCtl32.dll Vanara.PInvoke.ComCtl32 Coverage NuGet
CredUI.dll Vanara.PInvoke.CredUI Coverage NuGet
BCrypt.dll, Crypt32.dll and NCrypt.dll Vanara.PInvoke.Cryptography Coverage NuGet
DwmApi.dll Vanara.PInvoke.DwmApi Coverage NuGet
Gdi32.dll Vanara.PInvoke.Gdi32 Coverage NuGet
IpHlpApi.dll Vanara.PInvoke.IpHlpApi Coverage NuGet
Kernel32.dll and KernelBase.dll Vanara.PInvoke.Kernel32 Coverage NuGet
Mpr.dll Vanara.PInvoke.Mpr Coverage NuGet
NetApi32.dll Vanara.PInvoke.NetApi32 Coverage NuGet
NetListMgr.dll Vanara.PInvoke.NetListMgr Coverage NuGet
NTDSApi.dll Vanara.PInvoke.NTDSApi Coverage NuGet
NTDll.dll Vanara.PInvoke.NTDll Coverage NuGet
Ole32.dll, OleAut32 and PropSys.dll Vanara.PInvoke.Ole Coverage NuGet
PowrProf.dll Vanara.PInvoke.PowrProf Coverage NuGet
AdvApi32.dll, Authz.dll and Secur32.dll Vanara.PInvoke.Security Coverage NuGet
Shell32.dll Vanara.PInvoke.Shell32 Coverage NuGet
ShlwApi.dll Vanara.PInvoke.ShlwApi Coverage NuGet
TaskSchd.dll and MSTask.dll Vanara.PInvoke.TaskSchd Coverage NuGet
User32.dll Vanara.PInvoke.User32 Coverage NuGet
User32.dll that have GDI references Vanara.PInvoke.User32.Gdi Coverage NuGet
UxTheme.dll Vanara.PInvoke.UxTheme Coverage NuGet
VirtDisk.dll Vanara.PInvoke.VirtDisk Coverage NuGet
WinINet.dll Vanara.PInvoke.WinINet Coverage NuGet
Ws2_32.dll Vanara.PInvoke.Ws2_32 Coverage NuGet

Supporting Assemblies

Assembly    NuGet Link    Description
Vanara.Core NuGet Shared methods, structures and constants for use throughout the Vanara assemblies. Think of it as windows.h with some useful extensions.
Vanara.PInvoke.Shared NuGet Shared methods, structures and constants for use throughout the Vanara.PInvoke assemblies.
Vanara.Security NuGet Classes for Windows Security that are missing or incomplete in .NET. Includes claims, privileges, impersonation, Active Directory, and UAC.
Vanara.SystemServices NuGet Classes for Windows system functions. Includes Background Transfer (BITS), Virtual Disk management, WOW64 interaction, and file, process, path, networking and service controller extensions.
Vanara.Windows.Forms NuGet Classes for user interface related items derived from the Vanara PInvoke libraries. Includes extensions for almost all common controls to give post Vista capabilities, WinForms controls (panel, commandlink, enhanced combo boxes, IPAddress, split button, trackbar and themed controls), shutdown/restart/lock control, buffered painting, resource files, access control editor, simplified designer framework for Windows.Forms.
Vanara.Windows.Shell NuGet Classes for Windows Shell items derived from the Vanara PInvoke libraries. Includes shell items, files, icons, links, shell properties, shell registration and taskbar lists.

Quick Links

Sample Code

There are numerous examples in the UnitTest folder.