Introduction

So you have to or want to develop a native component (typically a DLL written in C or C++) with a simple API and you need to use it from another component developed in C#.
You know that you can use the DllImport mechanism and you’ve seen the 156387 tutorials that show how to make it with kernel32.dll (and by the way this is sometimes only what you need).
You’ve also seen some tutorials that to illustrate what you think is a simple matter are using huge codes and made you scream “pleeaaase get to the point!”, or the ones that ask you to setup a Visual Studio project but you want to avoid useless plumbing and understand what happens under the hood.
You’ve tried by yourself and feel you’re almost there but you still have errors and start to feel frustrated.

The good news are : first you’re right when you think DllImport is straightforward for simple interfaces, second this is the no-overengineering, no-overhead, no-nonsense, KISS tutorial for it.

So keep reading and in 10 minutes you’ll DllImport (almost) like a pro.

(Source code is available here)

The awesome C library

Here is the C code for our top-notch numerical library, lib.c:

__declspec(dllexport)
int next(int n)
{
    return n + 1;
}

The first line I’ve highlighted is the only thing to notice: it’s a directive that asks the compiler to mark the function as public so that it can be accessed from external components.
Without this directive the functions are by default internal to the library and are hidden from the outside.

Generating the library is straightforward and I give you three solutions:

• if you have Visual Studio on your computer: open a Visual Studio Command Prompt, go to the folder containing your source code and invoke the CL compiler:

  cl /LD lib.c
  Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86
  Copyright (C) Microsoft Corporation.  All rights reserved.
  
  lib.c
  Microsoft (R) Incremental Linker Version 10.00.40219.01
  Copyright (C) Microsoft Corporation.  All rights reserved.
  
  /out:lib.dll
  /dll
  /implib:lib.lib
  lib.obj
     Creating library lib.lib and object lib.exp

  This will generate a bunch of files, you can keep only the “lib.dll” library.
  You can check that the “next” function has been correctly exported with dumpbin :

  dumpbin /exports lib.dll
  Microsoft (R) COFF/PE Dumper Version 10.00.40219.01
  Copyright (C) Microsoft Corporation.  All rights reserved.
  
  Dump of file lib.dll
  
  File Type: DLL
  
    Section contains the following exports for lib.dll
  
      00000000 characteristics
      512A5028 time date stamp Sun Feb 24 18:38:48 2013
          0.00 version
             1 ordinal base
             1 number of functions
             1 number of names
  
      ordinal hint RVA      name
  
            1    0 00001000 next
  
    Summary
  
          2000 .data
          2000 .rdata
          1000 .reloc
          5000 .text

• if you do not use Visual Studio you can use MinGW, a great cross-compiler: open the MinGW shell, go to the folder and invoke the GCC compiler:

  gcc -shared -o lib.dll lib.c

  This will only generate the “lib.dll” dynamic library.
  You can check that the “next” function is exported with the NM utility:

  nm --extern-only --demangle lib.dll | grep next
  61fc1254 T next

• you can also use the Windows SDK that contains the CL compiler: instructions and output are similar to the Visual Studio situation.

Whatever the tools you’ve used you now have a “lib.dll” dynamic library.

The C# application

With such an incredible C library we needed a decent C# application to demonstrate its power :

using System; // Console
using System.Runtime.InteropServices; // DllImport

class App
{
    [DllImport("lib.dll", CallingConvention = CallingConvention.Cdecl)]
    extern static int next(int n);

    static void Main()
    {
        Console.WriteLine(next(0));
    }
}

When run it will reveal you what is the number following 0.
But to maintain the suspense we first analyze the code, at least the two highlighted lines: they tell the C# compiler that somewhere in the “lib.dll” file there is a function named “next” which takes an integer as unique parameter and returns an integer.
(If you’re in a hurry you can skip the next paragraph and directly go to the compilation part)

Moreover this code says that a specific procedure should be used to call the native function: the so-called CDecl calling-convention.
If you don’t specify this parameter all will appear to work fine and you won’t notice any error, except if you activate the MDAs: you will then be presented with an error like “A call to PInvoke function has unbalanced the stack. This is likely because the managed PInvoke signature does not match the unmanaged target signature“.
But why?
First you should know that the default calling convention for C functions is CDecl.
But by default DllImport uses StdCall, hence the need to explicitly specify CDecl to override the default behavior.
Second, without diving too deep into the technical details, CDecl states that the calling side has to do some cleanup after the call, whereas StdCall states that this is the responsibility of the called side.
So without more clues the C# code would have called the function expecting it to cleanup but would have been surprised if it was not the case, hence the pInvokeStackImbalance MDA.
(This kind of misconception about who has to do the cleanup after diner has caused more than one divorce!)

Let’s now compile our C# application:
locate the CSC C# compiler you want to use on your system (e.g. if you have .Net 4.0 you can find one in C:\Windows\Microsoft.NET\Framework\v4.0.30319) and invoke it this way :

csc /platform:x86 App.cs
Microsoft (R) Visual C# Compiler version 4.0.30319.17929
for Microsoft (R) .NET Framework 4.5
Copyright (C) Microsoft Corporation. All rights reserved.

Simple, except the compilation flag /platform:x86: it specifies that this application targets a specific native platform (x86) (i.e. 32-bit platform), and will then be allowed to call native x86 functions.
(If you’re not interested by the technical intricacies you can safely go to the end of this article)

But why do we need to specify the target platform?
Because, as you may have noticed in the CL compiler self-description, we’ve used the 32-bit version of CL, so we generated a 32-bit native library that can only be called from 32-bit native code.
And, tough the .Net assembly code generated by CSC, the MSIL, will be the same for all the target platforms, it will be loaded and turned into different native codes, during the JIT compilation, by different CLR.
So we ask the CSC compiler to mark the resulting .Net executable assembly as tied to 32-bit native code meaning it must be handled by a 32-bit CLR who knows how to interact with 32-bit native code.
If you forget this flag you’ll end up with this kind of error when running the generated EXE on a 64-bit system: “Unhandled Exception: System.BadImageFormatException: An attempt was made to load a program with an incorrect format. (Exception from HRESULT: 0x8007000B)” because, by default, CSC marks the assembly as targeting the anycpu platform, meaning it can be used by any CLR: on a 64-bit system it will then be handled by the 64-bit CLR, not the 32-bit one.

Hey! we’re done, we only have to run our Test.exe managed application to know the integer following 0:

App.exe
1

Wow, I’d never have guessed!

Conclusion

You’ve seen how to do simple DllImport and you should now be able to use .Net/native interop via DllImport in more complex, real-life, scenario.
Moreover, for those intrepid enough to read the technical details, I hope you’ve learned something useful about the inner workings of the .Net framework.

DllImport is perfect for simple procedural APIs but if you have a richer object-oriented API (typically written in C++) then you’ll need more powerful tools:

• C++/CLI wrapper: low-level approach without any external tools based on the ability of the C++/CLI language to talk both to .Net and native code,
• SWIG: generic interop framework with support for a large range of languages.

If you have any question or remark about this article feel free to let a comment, I really appreciate any feedback.