Platform Invocation Services

Two variants of P/Invoke currently in use are:

• Native code is imported via dynamic-linked libraries (DLLs)
• Metadata embedded in the caller's assembly defines how the native code is to be called and data accessed (usually requires attributed source specifiers to aid the compiler in generating marshal glue)
  • This definition is the "Explicit" part

• By using C++/CLI, an application may simultaneously use the managed heap (by way of tracking pointers) and any native memory region, without the explicit declaration. (Implicit)
• A primary benefit in this case being, if underlying native data structures change, so long as the naming is compatible, a breaking change is avoided.
  • i.e. Adding/removing/re-ordering structures in a native header will be transparently supported so long as the structure member names did not also change.

This first simple example shows how to get the version of a particular DLL:

DllGetVersion function signature in the Windows API:

HRESULT DllGetVersion
(
    DLLVERSIONINFO* pdvi
)

P/Invoke C# code to invoke the DllGetVersion function:

[StructLayout(LayoutKind.Sequential)]
private struct DLLVERSIONINFO {
    public int cbSize;
    public int dwMajorVersion;
    public int dwMinorVersion;
    public int dwBuildNumber;
    public int dwPlatformID;
}
[DllImport("shell32.dll")]
static extern int DllGetVersion(ref DLLVERSIONINFO pdvi);

The second example shows how to extract an icon in a file:

ExtractIcon function signature in the Windows API:

HICON ExtractIcon
(      
    HINSTANCE hInst,
    LPCTSTR lpszExeFileName,
    UINT nIconIndex
);

P/Invoke C# code to invoke the ExtractIcon function:

[DllImport("shell32.dll")]
static extern IntPtr ExtractIcon(
    IntPtr hInst, 
    [MarshalAs(UnmanagedType.LPStr)] string lpszExeFileName, 
    uint nIconIndex);

This next complex example shows how to share an Event between two processes in the Windows platform:

CreateEvent function signature:

 HANDLE CreateEvent(
     LPSECURITY_ATTRIBUTES lpEventAttributes,
     BOOL bManualReset,
     BOOL bInitialState,
     LPCTSTR lpName
 );

P/Invoke C# code to invoke the CreateEvent function:

[DllImport("kernel32.dll", SetLastError=true)]
static extern IntPtr CreateEvent(
    IntPtr lpEventAttributes, 
    bool bManualReset,
    bool bInitialState, 
    [MarshalAs(UnmanagedType.LPStr)] string lpName);

PInvoke.net is a wiki containing P/Invoke signatures for a large number of standard Windows APIs. It is owned by Redgate Software and has around 50000 hits per month.

The signatures are manually produced by users of the wiki. They can be searched using a free addin to Microsoft Visual Studio.

PInvoker is an application which imports native DLLs and C++ .h files and exports fully formed and compiled P/Invoke interop DLLs. It overcomes the ambiguity problem by wrapping native pointer function parameters in PInvoker specific .NET interface classes. Instead of using standard .NET parameter types in P/Invoke method definitions (char[], string, etc.) it uses these interface classes in the P/Invoke function calls.

For instance, if we consider the above example code, PInvoker would produce a .NET P/Invoke function accepting a .NET interface class wrapping the native char * pointer. The construction of this class could be from a string or from a char [] array. The actual native memory structure for both is the same, but the respective interface class constructors for each type will populate the memory in different ways. The responsibility for deciding what .NET type needs to be passed into the function is therefore passed to the developer.

Microsoft Interop Assistant is a free tool available with binaries and source code available for download on CodePlex. It is licensed under the Microsoft Limited Public License (Ms-LPL).

It has two parts:

• A converter which takes small sections of native C++ header file code containing struct and method definitions. It then produces C# P/Invoke code for you to copy and paste into your applications.
• A searchable database of converted Windows API constant, method and struct definitions.

Because this tool produces C# source code rather than a compiled dll the user is free to make any changes necessary to the code before use. So the ambiguity problem is solved by the application picking one particular .NET type to use in the P/Invoke method signature and if necessary the user can change this to the required type.

The P/Invoke Wizard uses a similar method to the Microsoft Interop Assistant in that it accepts native C++ .h file code and produces C# (or VB.NET) code for you to paste into your .NET application code.

It also has options for which framework you wish to target: .NET Framework for the desktop or .NET Compact Framework for Windows Mobile smart devices (and Windows CE).

xInterop C++ .NET Bridge is a windows application to created C# wrapper for native C++ DLLs and C++ bridge to access .NET assemblies, it comes with a C#/.NET library which wraps the standard C++ classes, such as string, iostream, etc., C++ classes and objects can be accessed from .NET.

This tool generates C# wrapper DLLs with source code from existing native C++ DLLs and the associated header files which are required by the tool to build a C# wrapper DLL. The P/Invoke signatures and data marshaling are generated by the application. The resulting C# wrapper has the similar interface of the C++ counterpart with the parameter type converted to the .NET code.

This tool recognizes template classes which is not exported from the C++ DLL and instantiates the template class and export it in a supplement DLL and the corresponding C++ interface can be used in .NET.