P/Invoke is a way of calling C/C++ functions from a .NET program. It’s very easy to use. This article will cover the basics of using P/Invoke.

See also:

• P/Invoke Tutorial: Passing strings (Part 2)
• P/Invoke Tutorial: Passing parameters (Part 3)
• P/Invoke Tutorial: Pinning (Part 4)

Project Structure #

For this tutorial, we need a small project structure containing two projects:

• NativeLib : a C++ library project
• PInvokeTest : a C# console project

To get you started real quick, you can download the project structure here:

PInvokeTest.zip

If you’re not using Visual Studio 2010 (or don’t want to use the provided zip file), adopt the following settings.

For project NativeLib, go to the project settings and (for all configurations):

• under C/C++ –> Preprocessor –> Preprocessor Definitions add MYAPI=__declspec(dllexport)
• under C/C++ –> Advanced: change Calling Convention to __stdcall (/Gz)

For project PInvokeTest:

• Specify NativeLib as dependency for PInvokeTest. Right click on PInvokeTest and choose Project Dependencies.... Then select NativeLib and hit OK.
• Change the Output path (under project settings: Build) to ../Debug and ../Release for the different Configurations respectively.

Simple P/Invoke #

First, let’s create a native function called print_line().

Add a file called NativeLib.h to NativeLib (or replace it contents):

#ifndef _NATIVELIB_H_
#define _NATIVELIB_H_

#ifndef MYAPI
  #define MYAPI
#endif

#ifdef __cplusplus
extern "C" {
#endif

MYAPI void print_line(const char* str);

#ifdef __cplusplus
}
#endif

#endif // _NATIVELIB_H_

Then, add NativeLib.cpp:

#include "NativeLib.h"
#include <stdio.h>

MYAPI void print_line(const char* str) {
  printf("%s\n", str);
}

Now, let’s call this function from the PInvokeTest project. To do this, add the highlighted lines to Program.cs:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Runtime.InteropServices;

namespace PInvokeTest {
  class Program {
    static void Main(string[] args) {
      print_line("Hello, PInvoke!");
    }

    [DllImport("NativeLib.dll")]
    private static extern void print_line(string str);
  }
}

The most important lines in this sections are lines 13 and 14. Here we’re specifying the C/C++ function to import into our .NET class. There are a couple of things to note about this:

• The modifier is static extern. extern means that the function is imported from C/C++. static is necessary because the function has no knowledge about the class Program.
• The name of the function matches the name of C/C++ function.
• The type of parameter str is a .NET type (here: string). P/Invoke automatically converts (also called: marshals) data types from .NET to C/C++ and the other way around.
• The attribute [DllImport] specifies the name of DLL file from which we import the function. Note: DllImport allows you to control almost every aspect of the import, like providing a different .NET method name or specifying the calling convention.

Now compile the project and it should print Hello, PInvoke! to the console.

You can download the complete project here:

PInvokeTest-Complete.zip

Troubleshooting #

There are a couple of things that can go wrong with P/Invoke.

Unable to load DLL #

You may get a DllNotFoundException with an error message like “The specified module could not be found.”

Exception: DLL not found

As the error message suggests the DLL “NativeLib.dll” could not be found.

The problem here is that Visual Studio doesn’t copy native DLLs to the output directory of .NET projects.

Solution: Change the output directory of the .NET project (PInvokeTest) to match the output directory of the native project (NativeLib). In PInvokeTest’s project settings under Build choose ../Debug and ../Release for Output path in the respective configuration.

Stack Imbalance #

You may get an error saying that a PInvokeStackImbalance was detected.

Exception: Stack imbalance

The reason is most likely that the native library uses another calling convention then the .NET project. By default, C/C++ projects use the __cdecl calling convention, whereas [DllImport] uses __stdcall by default.

Solution: Make sure the calling conventions match. Either:

• Specify the correct calling convention in [DllImport], for example [DllImport("NativeLib.dll", CallingConvention=CallingConvention.Cdecl)]
• Change the default calling convention for the native project. This is done in the project settings under C/C++ –> Advanced –> Calling Convention.
• Add the desired calling convention to the desired C/C++ functions, for example: void __stdcall print_line(const char* str). This will only change the calling convention for these functions.

In most cases, it doesn’t matter what calling convention you use. There are some differences, though. You can read more about these differences in the Code Project article Calling Conventions Demystified (Section: Conclusion).

Portability #

On non-Windows systems you can use Mono to execute .NET applications. If you’re planning on supporting multiple platforms with your .NET code, I suggest you either:

• Don’t specify a file extension (.dll) in [DllImport], like [DllImport("NativeLib")]. This way the appropriate file name will be chosen automatically. Note, however, that this only works as long as there is no dot in the file name (like in System.Network.dll).
• Or: Always specify the full Windows file name (i.e. including file extension) and use Mono’s library mapping mechanism to map platform-dependent file names to Windows file names.

C++/CLI #

Besides P/Invoke, the other way of integrating C/C++ functions is using C++/CLI. Although C++/CLI performs better than P/Invoke it also has several drawbacks:

• You need to learn a new language (if you only know C#; even if you know C++ as well). See my C++/CLI Cheat Sheet for an overview.
• C++/CLI is not supported by Mono; so you can use C++/CLI assemblies only on Windows.

Read On #

You can find more information about P/Invoke here:

• http://www.mono-project.com/Interop_with_Native_Libraries