BorisJ's Blog : Useful Code

Interop 101 – Part 5

borisj — Fri, 09 Feb 2007 21:40:00 GMT

As overdue as this post is, let's just jump in. In my first 4 installments, I focused on the different ways you could access native functionality from managed code. In this post, I will flip the actors around and investigate how to expose managed functionality to native clients.

The first thing to note is that COM Interop can always solve this problem. Using very little work, you can take a managed assembly and use built-in framework tools to generate a COM shim for native C++ (or VB) clients. Of course that means your calling code has to go through COM and if this is solely for the purpose of interop and you don't need to use COM as your component technology then the performance cost is absolutely not worth it. Thus, once again, C++/CLI will save us :-)

In our little story, I have a HelloWorld C# type that looks like this:

public class HelloWorld

{

private static int Counter = 0;

public void Speak()

{

MessageBox.Show("Hello World #" + Counter++);

}

Now we have a C++ client that wants to access this functionality (apparently, this user doesn't know that MessageBox exists as a purely native API). The simplest way to access it is to compile the file where the calling code is using /clr and then instantiating this object and calling the method. Super easy. Hold on, the client just called and said the code must remain 100% native. Why? Who knows :-) In this case, we'll have to create an inverted wrapper that provides a purely native interface. Here we go…

The execution is simple: build a new DLL that is compiled /clr but that exposes a native class as opposed to a reference class (remember, C++/CLI preserves native semantics and automagically exports things correctly).

// NativeHello.h

#ifdef _MANAGED

#using <HelloWorld.dll>

#include <vcclr.h>

#else

#include <stddef.h>

#endif

class NativeHello

{

private:

#ifdef _MANAGED

gcroot<HelloWorld^> hw;

#else

intptr_t hw;

#endif

public:

__declspec(dllexport) NativeHello();

__declspec(dllexport) ~NativeHello();

__declspec(dllexport) void Speak();

};

With the following implementation.

NativeHello::NativeHello()

{

// initialize managed hello world

hw = gcnew HelloWorld();

}

NativeHello::~NativeHello()

{

// nothing to do :)

}

void NativeHello::Speak()

{

hw->Speak();

}

Let's go through each part of this in turn. At the top, I enclosed two statements within a check to see if we are compiling as managed (i.e. with /clr). The #using statement is essentially the equivalent of #import for COM. For C# programmers out there, this statement is equivalent to adding a reference to an assembly. The #include statement introduces the gcroot abstraction, which I'll talk about in a second. Now why did I enclose these statements in #ifdef _MANAGED? Our goal is to create a DLL that can be accessed by a purely native client and unfortunately in the native world, libraries do not (exactly) describes themselves and we need to use a header file as the descriptor. When a native client includes our native wrapper header file, the code enclosed within the _MANAGED block will be ignored. This is necessary since these statements only make sense for managed compilands. Luckily, the native client only needs to know about the types/functions we're exporting and hiding these statements has no ill effect. The #else clause adds an #include for intptr_t mentioned below.

Our wrapper type is then declared with a private member called hw, which is of type gcroot< HelloWorld^>. In the converse example from my previous posts, we simply embedded a native pointer as a private member. The fact is, you can't have a handle embedded in a native type so the gcroot template creates an (seamless) indirection by using the BCL's GCHandle value type, which enables the native code to hold a managed object and prevents the CLR's garbage collection of the object. However, this template only makes sense when we're compiling managed. Thus, in the case of a native includer, the gcroot member is stored as a simple intptr_t, which has the same size as gcroot on any platform.

Of course, we need to start exporting some real functionality! The constructor, destructor and the Speak method are all exported in the traditional native manner using __declspec(dllexport). None of these prototypes expose the managed implementation as is our goal. In other words, here is the view of the wrapper class from a native client.

class NativeHello

{

private:

intptr_t hw;

public:

NativeHello();

~NativeHello();

void Speak();

};

Voila. We now have a wrapper for purely native clients that are unable to use /clr (VC6 clients I presume!). Of course, you should make sure these clients use the same compiler, unless you want to open the way for the most obscure bugs on the planet, nay, in the galaxy(mixing CRTs leads to the dark side).

If you find yourself needing this type of wrapper often, you should go take a peek at Paul DiLascia's generic version of this sample that generates wrappers for any managed type.

Interop 101 – Part 4

borisj — Fri, 29 Sep 2006 09:29:00 GMT

I apologize for the long delay for this section (although I suppose my average posting frequency is already pretty low), but I was on a much needed vacation. I finished the last chapter with a brief mention of what I would talk about now, which is the native support for interop that C++ provides. In a sense, I hope this is going to appear to be the simplest method even though I will introduce a few new concepts and use C++/CLI, which adds new language constructs to C++ in order to express .NET semantics (e.g. garbage collected types).

As always, let us reprise our original HelloWorld example. I'm going to include it again for sake of making this post depend as little as possible on the previous ones.

// HelloWorld.h

#pragma once

class __declspec(dllexport) HelloWorld

{

public:

HelloWorld();

~HelloWorld();

void SayThis(wchar_t *phrase);

};

// HelloWorld.cpp

void HelloWorld::SayThis(wchar_t *phrase)

{

MessageBox(NULL, phrase, L"Hello World Says", MB_OK);

}

Our goal is to access this type from .NET. As it stands, this piece of code already compiles into a native DLL. The question that stands before us first is what clients will access this code from now on. In other words, are we replacing all existing client code of this DLL with managed code or are we going to maintain some purely native clients. In the first case, we can write our wrapper code directly into the DLL and compile it into a managed assembly (with native code backing it). In the second case, we need to create a second DLL that will be a native client to this one while publishing a managed interface for .NET clients. It is the latter case that we are going to jump into now.

The first thing to do is to create a new CLR project, which we can do with a wizard (look under the Visual C++ > CLR node in the New Project dialog) or simply taking a blank slate and making the project compile with the /clr switch. This switch is the cornerstone of this entire scenario. If you remember the first part in this series, we showed how the C++ compiler is able to generate MSIL and furthermore, it can generate a process image with both a managed and a native section (the only compiler capable of doing so I might add). We have yet to really lay down the bricks for our wrapper so let's make a naïve wrapper for HelloWorld now.

// cppcliwrapper.h

#pragma once

#include "..\interop101\helloworld.h"

namespace cppcliwrapper {

class ManagedHelloWorld

{

private:

HelloWorld hw;

public:

ManagedHelloWorld();

~ManagedHelloWorld();

void SayThis(wchar_t *phrase);

};

}

This piece of code is a native wrapper around our native type using traditional OO encapsulation. Even though this piece of code will compile into MSIL, it does not solve our original problem. Why is that? It's because we're still dealing with a native type. In other words, the ManagedHelloWorld class still obeys the rules of native semantics, namely the fact that it must live on the native heap. Managed languages like C# have no knowledge of the native heap and their new operator only instantiates objects into the CLR's heap. We need to make this wrapper a managed type, which will have the same semantics as a class in C#. Enter C++/CLI. With these additions to the language, we can create two new types of classes: managed value and reference types (the difference is mainly in the way they are implicitly copied). For our wrapper, we simply need to change its declaration from class to ref class. Once we compile the resulting code, we get a pivotal error.

error C4368: cannot define 'hw' as a member of managed 'ManagedHelloWorld': mixed types are not supported

What could this possibly mean? This error is actually directly related to the problem we described just above. In order to be a proper managed reference type that C# and other managed languages can instantiate, we cannot encapsulate native members. Indeed, our wrapper cannot live on the CLR's managed heap as it contains a member that can only live on the native heap. We can resolve this issue by encapsulating a pointer to our native type. Thus we have the following wrapper code.

ref class ManagedHelloWorld

{

private:

HelloWorld *hw;

public:

ManagedHelloWorld();

~ManagedHelloWorld();

void SayThis(wchar_t *phrase);

};

Only three things remain in order to make this wrapper usable. The first is to make it public in accordance with .NET accessibility rules. The second is to change the interface of SayThis such that it uses a managed string. The third is to include the implementation! So here it goes.

// cppcliwrapper.cpp

#include "cppcliwrapper.h"

#include "marshal.h"

using namespace cppcliwrapper;

ManagedHelloWorld::ManagedHelloWorld() : hw(new HelloWorld())

{

}

ManagedHelloWorld::~ManagedHelloWorld()

{

delete hw;

}

void ManagedHelloWorld::SayThis(System::String^ phrase)

{

hw->SayThis(marshal::to<wchar_t*>(phrase));

}

There are two notable elements we have introduced in this final piece code, the managed handle and data marshalling. The handle or "hat" (or "accent circonflexe" even) is part of the C++/CLI language. It represents a pointer to a managed object. Other languages like Java, C# and VB don't use anything like this as they no longer have native semantics. However C++ needs to differentiate between the stack, the native heap and the managed heap and it does so using * and ^. Data marshalling is a huge topic and can eventually become one of the more complex things you have to manage when working with interop. In this example, we need to convert a managed String into a native pointer to wchar_t. In order to do this, a great pattern is to create a library of static template functions, which thus remain stateless and help maintain a certain level of consistency. In this example, we created the following functions:

namespace marshal {

template <typename T>

static T to(System::String^ str)

{

}

template<>

static wchar_t* to(System::String^ str)

{

pin_ptr<const wchar_t> cpwc = PtrToStringChars(str);

int len = str->Length + 1;

wchar_t* pwc = new wchar_t[len];

wcscpy_s(pwc, len, cpwc);

return pwc;

}

After this is all said and done, we compile our code into an assembly that 3rd party .NET clients can use as if it were written in C#. So here is our resulting client code, which is eerily similar to the COM example.

using System;

using System.Text;

using cppcliwrapper;

namespace CSharpDirectCaller

{

class Program

{

static void Main(string[] args)

{

ManagedHelloWorld mhw = new ManagedHelloWorld();

mhw.SayThis("I'm a C# application calling native code via C++ interop!");

}

I have a lot more to say about this, and I promised a performance comparison as well as a 5th part describing doing this in reverse. My next post should not be so long in the making.

Product Feedback woes and yet another macro

borisj — Mon, 05 Jun 2006 11:46:00 GMT

A while back, we received a suggestion via our product feedback website. The site lets anyone log bugs and/or suggestions for our product, which feed directly into our internal bug tracking mechanism. In other words, the site is not simply a façade but a direct input into our development, supplementing our internal testing (it’s hard to find every bug in a piece of code as large as Visual Studio) and helping us prioritize issues.

The upside of this website is that we have received valuable feedback, fixed real customer bugs (many of these fixes will be in our upcoming service pack) and identified certain features that are lacking and others that are slowly becoming superfluous. For example, many users voted on the fact that we lack support for code snippets in C++, a feature I would love to have and we are investigating providing this support in Orcas (our next release). When so many customers show their desire for the feature, it helps us allocate resources, something which is always in scarce supply

The downside of the product feedback is the simple fact that we can’t handle the quantity of bugs and suggestions that people submit (my personal opinion) and we’ve had to make some tough decisions with prioritization. While we fight to keep our product bug-free, we also understand the inescapable need to implement our customers’ suggestions. It’s one of the most simultaneously loathsome and attractive aspects of being a program manager at Microsoft. After all, few people in the industry can say they decide whether some feature will make it into a product used by millions

All this rambling has me straying from this post’s purpose. Yet another piece of (macro) code. Today’s macro was inspired by a suggestion we received via product feedback, which I deemed unworthy due to how easy it is to add using our extensibility model. Without further ado, here is a macro to preprocess the current file and bring it up in the editor.

Sub RunPreprocessor()

Dim doc As Document = DTE.ActiveDocument

Dim docname As String = doc.Name.ToLower

Dim project As Project = doc.ProjectItem.ContainingProject

If doc.Language = "C/C++" Then

' not the most accurate way of identifying a cpp file

If docname.EndsWith(".cpp") Then

Dim vcproj As VCProject = project.Object

Dim projfiles As IVCCollection = vcproj.Files

Dim vcfile As VCFile = Nothing

' find the file in current project

For Each f As VCFile In projfiles

If f.Name = doc.Name Then

vcfile = f

Exit For

End If

Dim activeconfigname As String = DTE.Solution.SolutionBuild.ActiveConfiguration.Name

Dim fileconfig As VCFileConfiguration = vcfile.FileConfigurations(activeconfigname)

Dim filecompiler As VCCLCompilerTool = fileconfig.Tool

' toggle preprocessing on, compile, toggle preprocessing

filecompiler.GeneratePreprocessedFile = preprocessOption.preprocessNoLineNumbers

fileconfig.Compile(True, True)

filecompiler.GeneratePreprocessedFile = preprocessOption.preprocessNo

Dim preprocessedpath = doc.Path + docname.Replace(".cpp", ".i")

ClearEmptyLines(preprocessedpath)

DTE.ItemOperations.OpenFile(preprocessedpath + ".cpp")

End If

End Sub

And the required helper function:

Sub ClearEmptyLines(ByVal filepath As String)

Dim line As String

' iterate through a file and write out non-empty lines into a new file

Using sr As New IO.StreamReader(filepath)

' out file name is <filename>.i.cpp (for highlighting)

Using sw As New IO.StreamWriter(New IO.FileStream(filepath + ".cpp", IO.FileMode.Create))

While Not sr.EndOfStream

line = sr.ReadLine()

If line.Length > 0 Then

sw.WriteLine(line)

End If

End While

End Using

End Sub

The implementation has two issues in its current form. The first is that changing the compiler property on the file causes the project file to change, which in turn requires checking out the project file and probably re-linking the project. The second is that the macro always rebuilds the preprocessed file even when there is no need to. I will post a follow-up, solving both of these issues.