Managed C++ Wrapper For Unmanaged Code

It is sometimes necessary or preferred to use C++ to create a managed wrapper around unmanaged code. This article is a simple sample of a managed C++ Class Library that calls unmanaged code. It should help C++ programmers unfamilar with C# to create a wrapper around C and/or C++ code so the unmanaged code can be used from managed code. This article should also help C# programmers use unmanaged code. There are many details about C++ and unmanaged code that can be difficult for C# programmers to solve, so if you are unfamiliar with C++ this article can help but there might be more details to conquer.

Note that usually it is possible to use Platform Invoke (DllImport) to call native DLLs. That should usually be the solution chosen for calling native DLLs from managed code. One reason for using a managed wrapper around unmanaged code is when software exists as a static library. Another good reason to use unmanaged code is when an API is intended to be used from C++ and is too complicated and technical to be conveniently used from managed code.

This project creates a C++ CLR (managed) Class Library called UnmanagedWrap which uses an unmanaged class called Unmanaged. For the purposes of this article, the Unmanaged class has a function called Hello that simply calls the Windows API MessageBox function. Normally we would use the MessageBox managed class to show a MessageBox or if we wanted to use the Windows API version we would normally simply use Platform Invoke to call it, but I am using it in this manner just for purposes of this article.

The following is a summary of the steps used to create this sample:

1. Create a C++ CLR Class Library project and build it.
2. Add a class called Unmanaged with a Hello function.
3. Update stdafx.h (add windows.h).
4. Update UnmanagedWrap.h and UnmanagedWrap.cpp (add the Hello function).
5. Build again and fix errors LNK2028 and LNK2019 if present.
6. Test.

1. Create a C++ CLR Class Library Project

In Visual Studio 2010 use "File" -> "New" -> "Project...".

Then in the New Project dialog in "Installed Templates" (at the left) expand "Visual C++" then select "CLR". In the list of templates to the right, select "Class Library". In the toolbar along the top be sure to select ".NET Framework 4". Give the project a name (I am using the name "UnmanagedWrap"). The "Add New Project" dialog should look as in the following:

Click "OK". When the project has been generated, build it before making any changes to verify that it builds successfully, at least initially.

2. Add a Class Called Unmanaged.

There are at least a couple of ways to add a class to the project. One way is to use "Project" -> "Add Class....". In the "Add Class" dialog in "Installed Templates" (at the left) select "C++". Then in the list of templates to the right, select "C++ Class". The dialog should then look as in the following:

The "Name" and "Location" boxes along the bottom are disabled, so just click on "Add". A "Welcome to the Generic C++ Class Wizard" dialog will appear. Type a name into the "Class name" box. The wizard will automatically generate file names for a .h and .cpp file. Leave the base class empty (assuming you are not deriving from another class) and leave the "Access" as "public". Leave the "Virtual Destructor" and "Inline" checkboxes unchecked, but you absolutely must uncheck the checkbox for "Managed". The dialog should then look as in the following:

Then click "Finish".

Open the Unmanaged.h file if not already open. Note that there is not a namespace in the file for the class. At the end of the class (before the "};") add the following line:

int Hello(void);

Then open the Unmanaged.cpp file and add the folllowing three lines:

int Unmanaged::Hello(void) {
return MessageBox(NULL, L"Hello", L"Unmanaged", MB_OK);
}

3. Update stdafx.h (Add windows.h)

Since we are calling the Windows API, we must include windows.h. In the Solution Explorer expand the "Header Files" folder and then open the "stdafx.h" file. Add the following two lines to it:

#define WIN32_LEAN_AND_MEAN
#include <Windows.h>

The first of those lines is usefull but not important; it makes the compile slightly faster.

4. Update UnmanagedWrap.h and UnmanagedWrap.cpp (Add the Hello Function)

Open the UnmanagedWrap.h file. We need to add three things to the Class1 class; an unmanaged pointer to the Unmanaged class, a constructor that creates an object of the Unmanaged class and a method that calls the unmanaged function. The Class1 class will then look like:

public ref class Class1
{
public:
Unmanaged *pu;	// pointer to the Unmanaged class
// the constructor will allocate the pointer pu
Class1() : pu(new Unmanaged()) {};
int Hello() {
return pu->Hello();
};
};

Note that is is extremely normal for unmanaged C++ code (the majority of it) to separate class definitions into a header (h) and an implementation (cpp) file. C++ programmers consider that to be important. Microsoft however does not agree, at least to the extent that Microsoft designed managed code in a manner that is incompatible with the way that C++ is normally used. Therefore managed C++ classes are usuallly implemented entirely in the header (h) file. We do however need to add one line to the UnmanagedWrap.cpp file. Add the following line to it:

#include "Unmanaged.h"

That line however must precede the "#include "UnmanagedWrap.h"" line.

5. Build Again and Fix Errors LNK2028 and LNK2019 If Present

Build the project again. If you do not get the following two errors then skip the following and go directly to testing.

Unmanaged.obj : error LNK2028: unresolved token (0A00000C)
"extern "C" int __stdcall MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function
"extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)
Unmanaged.obj : error LNK2019: unresolved external symbol
"extern "C" int __stdcall MessageBoxW(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBoxW@@$$J216YGHPAUHWND__@@PB_W1I@Z)
referenced in function
"extern "C" int __cdecl MessageBox(struct HWND__ *,wchar_t const *,wchar_t const *,unsigned int)" (?MessageBox@@$$J0YAHPAUHWND__@@PB_W1I@Z)

If you get those errors then you must modify one more of the project's properties. In the project's properties (if needed) expand the "Configuration Properties" node, then expand the "Linker" node, then select the "Input" node. Then be sure that the "Configuration" in the top left is "All Configurations". Then at the top of the properties is "Additional Dependencies". Assuming that the value is blank, click in the box for the value and an arrow will appear at the right end of the box. Click it and in the drop-down list choose "<inherit from parent or project defaults>". This should tell the linker to look in the user32.dll file for the MessageBox function. Finally click on "OK".

6. Test

Create or use a separate project to test with. To that project, add a reference to the project created above. Then create an instance of the wrapper class (UnmanagedWrap or whatever) then call the method (the Hello function) or methods in the class.