Click here to Skip to main content
15,860,859 members
Articles / Programming Languages / C#
Article

How to Marshal a C++ Class

Rate me:
Please Sign up or sign in to vote.
4.97/5 (77 votes)
15 Mar 20075 min read 392.3K   7.3K   169   61
An article on how to marshal a C++ class

Introduction

I recently needed to marshal some legacy C++ classes into a C# project on which I was working. Microsoft provides well documented means to marshal C-functions, and to marshal COM components, but they left out a mechanism to marshal C++ classes. This article documents the discoveries I made and the eventual solution I came up with.

Audience

This article assumes the reader is knowledgeable in C# and .NET and is already familiar with PInvoke and marshaling.

Article

I had existing (unmanaged) C++ DLLs which needed to be used with a managed C# project I was working on. Although I had access to the source code of the DLLs, one of the requirements was that the C++ source code and DLLs could not be dramatically altered. This was due to many reasons, including backwards compatibility with existing projects, the code having already been QA'ed, and project deadlines, so converting the original DLLs to be managed C++ DLLs, or converting the classes within the original DLLs to be COM components was out.

Upon first investigating this issue, I was hoping to be able to declare a definition for a C# version of the class and marshal the object back and forth between the managed and unmanaged memory spaces, similar to how a structure is marshaled back and forth. Unfortunately, this is not possible; in my research I discovered that unmanaged C++ classes can't be marshaled and that the best approach is to either create bridge/wrapper C-functions for the public methods of the class and marshal the functions, or to create a bridge DLL in managed C++.

Solution A: Create Bridge Functions in C and Use PInvoke

Suppose we have the following unmanaged C++ class:

C++
class EXAMPLEUNMANAGEDDLL_API CUnmanagedTestClass
{
public:
    CUnmanagedTestClass();
    virtual ~CUnmanagedTestClass();
    void PassInt(int nValue);
    void PassString(char* pchValue);
    char* ReturnString();
};

Running dumpbin on the DLL containing the class yields the following results:

Screenshot - dumpbin_example.jpg
(Click for larger view. We'll cover the results from dumpbin in a moment).

Since the instantiation of a C++ class object is just a pointer, we can use C#'s IntPtr data type to pass unmanaged C++ objects back and forth, but C-functions need to be added to the unmanaged DLL in order to create and dispose instantiations of the class:

C++
// C++:
extern "C" EXAMPLEUNMANAGEDDLL_API CUnmanagedTestClass* CreateTestClass()
{
    return new CUnmanagedTestClass();
}

extern "C" EXAMPLEUNMANAGEDDLL_API void DisposeTestClass(
    CUnmanagedTestClass* pObject)
{
    if(pObject != NULL)
    {
        delete pObject;
        pObject = NULL;
    }
}

C#
// C#:
[DllImport("ExampleUnmanagedDLL.dll")]
static public extern IntPtr CreateTestClass();

[DllImport("ExampleUnmanagedDLL.dll")]
static public extern void DisposeTestClass(IntPtr pTestClassObject);
 
IntPtr pTestClass = CreateTestClass();
DisposeTestClass(pTestClass);
pTestClass = IntPtr.Zero; 
// Always NULL out deleted objects in order to prevent a dirty pointer

This allows us to pass the object back and forth, but how do we call the methods of our class? There are two approaches to accessing the methods. The first approach is to use PInvoke and to use CallingConvention.ThisCall. If you go back to the output from dumpbin, you will see the mangled name for the PassInt() method is "?PassInt@CUnmanagedTestClass@@QAEXH@Z". Using CallingConvention.ThisCall, the PInvoke definition of PassInt() is:

C#
[DllImport("ExampleUnmanagedDLL.dll",
    EntryPoint="?PassInt@CUnmanagedTestClass@@QAEXH@Z",
    CallingConvention=CallingConvention.ThisCall)]
static public extern void PassInt(IntPtr pClassObject, int nValue);

The second approach is to create C-functions which act as a bridge for each public method within the DLL...

C++
// C++:
extern "C" EXAMPLEUNMANAGEDDLL_API void CallPassInt(
    CUnmanagedTestClass* pObject, int nValue)
{
    if(pObject != NULL)
    {
        pObject->PassInt(nValue);
    }
}
.
.
.

...and marshal each of new C-functions in C#...

C#
// C#:
[DllImport("ExampleUnmanagedDLL.dll")]
static public extern void CallPassInt(IntPtr pTestClassObject, int nValue);
.
.
.

I chose to go with the second approach; the name mangling the compiler does means that the first approach is susceptible to breaking if a different compiler is used to compile the C++ DLL (newer version, different vendor, etc...), or if additional methods are added to the class. There is a little extra work involved with the second approach, but I feel the extra work is rewarded by having better maintainable code and code which is less likely to break in the future.

At this point I should point out that I added the bridge functions to the original DLL and recompiled the DLL, but what if the DLL in question is a third party DLL and you don't have access to the sources so you can't recompile the DLL (you only have the rights to redistribute it)? In this scenario I suggest either:

  1. Creating a new DLL in unmanaged C and place the bridge functions within the new DLL.
  2. Create a managed C++ DLL and have it act as the bridge between the C# code and the unmanaged C++ classes (see Solution B further on).

At this point, the C# code to call our C++ class looks like:

C#
// C#:
IntPtr pTestClass = CreateTestClass();
CallPassInt(pTestClass, 42);
DisposeTestClass(pTestClass);
pTestClass = IntPtr.Zero;

This is fine as it is, but this isn't very Object-Oriented. Suppose you aren't the only one working on the project? Will other clients of your code remember to dispose the C++ class object via DisposeTestClass()? Will they correctly use an IntPtr created from CreatetestClassDLL() and not some other IntPtr? The next step is to wrap our C# code and PInvoke definitions into a class.

During my investigation, I came across the following newsgroup posting...

http://groups.google.com/group/microsoft.public.dotnet.framework.interop/ browse_thread/thread/d4022eb907736cdd/0e74fa0d34947251?lnk=gst&q= C%2B%2B+class&rnum=6&hl=en#0e74fa0d34947251

...and I decided to mirror this approach and create a class in C# called CSUnmanagedTestClass:
C#
// C#:
public class CSUnmanagedTestClass : IDisposable
{
    #region PInvokes
    [DllImport("TestClassDLL.dll")]
    static private extern IntPtr CreateTestClass();

    [DllImport("TestClassDLL.dll")]
    static private extern void DisposeTestClass(IntPtr pTestClassObject);

    [DllImport("TestClassDLL.dll")]
    static private extern void CallPassInt(IntPtr pTestClassObject, int nValue);
    .
    .
    .
    #endregion PInvokes

    #region Members
    private IntPtr m_pNativeObject; 
    // Variable to hold the C++ class's this pointer
    #endregion Members

    public CSUnmanagedTestClass()
    {
        // We have to Create an instance of this class through an exported 
        // function
        this.m_pNativeObject = CreateTestClass();
    }

    public void Dispose()
    {
        Dispose(true);
    }

    protected virtual void Dispose(bool bDisposing)
    {
        if(this.m_pNativeObject != IntPtr.Zero)
        {
            // Call the DLL Export to dispose this class
            DisposeTestClass(this.m_pNativeObject);
            this.m_pNativeObject = IntPtr.Zero;
        }

        if(bDisposing)
        {
            // No need to call the finalizer since we've now cleaned
            // up the unmanaged memory
            GC.SuppressFinalize(this);
        }
    }

    // This finalizer is called when Garbage collection occurs, but only if
    // the IDisposable.Dispose method wasn't already called.
    ~CSUnmanagedTestClass()
    {
        Dispose(false);
    }

    #region Wrapper methods
    public void PassInt(int nValue)
    {
        CallPassInt(this.m_pNativeObject, nValue);
    }
    .
    .
    .
    #endregion Wrapper methods
}

Now, the C# client of this code simply does:

C#
// C#:
CSUnmanagedTestClass testClass = new CSUnmanagedTestClass();
testClass.PassInt(42);
testClass.Dispose();

Solution B: Create a Bridge DLL in Managed C++

Another option is to leave the original DLL untouched and create a new DLL in managed C++ to act as a bridge between the managed C# code and the unmanaged C++ classes in the unmanaged DLL. Using the CUnmanagedTestClass within the managed DLL wasn't difficult, and PInvoke definitions weren't required, but the managed C++ syntax and classes which needed to be used was a bit vexing:

MC++
// MCPP:

// Forward declariation
class CUnmanagedTestClass;

public ref class CExampleMCppBridge
{
public:
    CExampleMCppBridge();
    virtual ~CExampleMCppBridge();
    void PassInt(int nValue);
    void PassString(String^ strValue);
    String^ ReturnString();

private:
    CUnmanagedTestClass* m_pUnmanagedTestClass;
};

CExampleMCppBridge::CExampleMCppBridge()
    : m_pUnmanagedTestClass(NULL)
{
    this->m_pUnmanagedTestClass = new CUnmanagedTestClass();
}

CExampleMCppBridge::~CExampleMCppBridge()
{
    delete this->m_pUnmanagedTestClass;
    this->m_pUnmanagedTestClass = NULL;
}

void CExampleMCppBridge::PassInt(int nValue)
{
    this->m_pUnmanagedTestClass->PassInt(nValue);
}
.
.
.

C#
// C#:
CExampleMCppBridge example = new CExampleMCppBridge();
example.PassInt(42);
example.Dispose();

(and I have to admit, I'm not very fluent in MCPP)

Pros/Cons

Both approach A and approach B have their own pros and cons. Are you unfamiliar with MCPP? Go with approach A and create C-functions to wrap the public methods of the class and use PInvoke. Can't modify the original DLL and don't want to create PInvode definitions? Create bridge classes in a new MCPP DLL as demonstrated in approach B.

Conclusion

In this article I have presented the reader with a number of different approaches and solutions to the problem of marshaling an unmanaged C++ class to C#. For the sake of brevity I have only included the CallPassInt() examples in this article, however the...

-
CallPassString()
CallReturnString()

...are in the source code accompanying this article.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


Written By
Software Developer
United States United States
In a nutshell, my forte is Windows, Macintosh, and cross-platform development, and my interests are in UI, image processing, and MIDI application development.

Comments and Discussions

 
GeneralMy vote of 5 Pin
Menon Santosh2-Feb-21 0:33
professionalMenon Santosh2-Feb-21 0:33 
QuestionC++ name mangling Pin
Tony Baloney1-Nov-17 5:07
Tony Baloney1-Nov-17 5:07 
GeneralMy vote of 5 Pin
MrInnocent28-Nov-16 21:00
MrInnocent28-Nov-16 21:00 
QuestionUsing VS2013, I am running into System.BadImageFormatException: An attempt was made to load a program with an incorrect format. Pin
Member 1229148927-Jan-16 11:59
Member 1229148927-Jan-16 11:59 
AnswerRe: Using VS2013, I am running into System.BadImageFormatException: An attempt was made to load a program with an incorrect format. Pin
Member 1229148927-Jan-16 12:26
Member 1229148927-Jan-16 12:26 
QuestionPerfect Pin
Kasparov9215-Sep-15 3:16
Kasparov9215-Sep-15 3:16 
QuestionThanks a lot for this article! Pin
sayooj cyriac10-Aug-15 7:06
sayooj cyriac10-Aug-15 7:06 
BugNice article with a small bug Pin
lonelygoat12-Dec-14 11:54
lonelygoat12-Dec-14 11:54 
Bug.Net 4.0 Tweak Needed Pin
Edw20-Oct-14 13:39
Edw20-Oct-14 13:39 
SuggestionC strings work better passed as IntPtr Pin
wcdeich428-Aug-14 11:01
wcdeich428-Aug-14 11:01 
QuestionThis is the best and most complete explanation I've found online yet. Pin
Shamaniac3-Aug-14 7:58
Shamaniac3-Aug-14 7:58 
QuestionNice Pin
Manikandan1011-Jun-14 3:56
professionalManikandan1011-Jun-14 3:56 
GeneralMy vote of 5 Pin
Member 874205917-Oct-13 22:22
Member 874205917-Oct-13 22:22 
GeneralMy vote of 5 Pin
Alan Balkany24-Jun-13 9:56
Alan Balkany24-Jun-13 9:56 
QuestionReturning an object Pin
Gyannea29-May-13 8:26
Gyannea29-May-13 8:26 
AnswerRe: Returning an object Pin
Shawn-USA30-May-13 15:36
Shawn-USA30-May-13 15:36 
GeneralRe: Returning an object Pin
Gyannea30-May-13 23:06
Gyannea30-May-13 23:06 
GeneralRe: Returning an object Pin
Shawn-USA31-May-13 7:24
Shawn-USA31-May-13 7:24 
QuestionApproach A for registered callbacks? (calling C# method from C++) Pin
Gyannea15-May-13 2:35
Gyannea15-May-13 2:35 
AnswerRe: Approach A for registered callbacks? (calling C# method from C++) Pin
jeffb4224-May-13 15:14
jeffb4224-May-13 15:14 
AnswerRe: Approach A for registered callbacks? (calling C# method from C++) Pin
Shawn-USA30-May-13 15:42
Shawn-USA30-May-13 15:42 
SuggestionOne more contribution to this article to make it better and a vote of 5 to you! Pin
Shawn-USA21-Apr-13 17:42
Shawn-USA21-Apr-13 17:42 
QuestionWhy extern "C"? Pin
Pokiaka13-Apr-13 23:13
Pokiaka13-Apr-13 23:13 
AnswerRe: Why extern "C"? Pin
jeffb4214-Apr-13 8:37
jeffb4214-Apr-13 8:37 
GeneralRe: Why extern "C"? Pin
Pokiaka15-Apr-13 22:52
Pokiaka15-Apr-13 22:52 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.