29
■ ■ ■
CHAPTER 3
Building C++/CLI Programs for
the .NET Developer Platform
with Visual C++
T
his chapter is a necessary distraction from your main purpose, which is to learn about the
C++/CLI language. In this chapter, you’ll find some important information that is not specifi-
cally related to the language syntax, but to the platform, compiler, and development tools.
There’s a great deal to the .NET Developer Platform (NDP); entire books have been written on
the subject. This chapter can’t begin to cover everything in detail, so it’ll just touch upon some
of the key concepts and give a few examples that will get you started.
While most of what this book covers will pertain to any implementation of the CLI, in this
chapter I assume you are using Visual C++, the Microsoft implementation of the CLI, and your
programs will run on the .NET Developer Platform. This chapter covers what you’ll need to
know about the NDP if you’re using Visual C++. If you are already familiar with targeting the
NDP in another language, such as C#, you’ll find much of this chapter a review, except for the
discussion of the C++/CLI #using statement and the discussion of the CLR compilation modes
available in C++.
Also, this chapter discusses compilation modes available in Visual C++. The compilation
modes produce different types of libraries and executables that are suited to different runtime
environments, ranging from code that is compiled natively to the instruction set of the processor
as previous generations of C++ compilers have always done, to verifiably safe managed code
that can run in some of the most restrictive environments such as inside an Internet browser
or inside a database engine such as Microsoft SQL Server 2005, where being certain that a
program will not crash and corrupt the server’s memory is crucial.
Targeting the .NET Developer Platform
with Visual C++ 2005
If you are using Visual C++ 2005, you may use the compiler directly from the command line,
perhaps using makefiles or a tool that ships with Visual Studio called MSBuild to build your

buffer overruns, access violations, and other memory corruption. If you’re familiar with C#,
pure code is like a C# program compiled with the /unsafe option. There is no equivalent in
Visual Basic.
If you try to compile a native C++ application with /clr:pure, it will work only if the code
being compiled has no constructs that generate machine-specific code. You can, however, link
with native libraries. The linker will add the necessary hookups to call into native libraries in
/clr:pure mode. For example, the program
// message_box.cpp
#include <windows.h>
int main()
{
::MessageBox(0,"message","caption",MB_OK);
}
Hogenson_705-2C03.fm Page 30 Friday, October 13, 2006 2:18 PM
CHAPTER 3
■
BUILDING C++/CLI PROGRAMS
31
compiled with
cl /clr:pure message_box.cpp user32.lib
will produce an executable that runs as expected.
Prepackaged libraries may or may not support the pure option. For example, as of Visual
C++ 2005, ATL and MFC don’t support /clr:pure. It depends on whether or not they were
compiled with the /clr:pure option. You may recompile your own native libraries as pure
code, provided they meet certain restrictions, such as not using
• Inline assembly.
• __declspec(align).
• Any construct that brings in native code.
• Code that generates native exports (i.e., not using __dllexport to expose functions
compiled in a pure assembly to native callers). This is because the calling convention

■
BUILDING C++/CLI PROGRAMS
Managed Extensions Syntax (/clr:oldSyntax Compiler Option)
If you have code that was written with the managed extensions syntax, you can still compile it
by using the /clr:oldSyntax option. You can link object files generated with this option with
C++/CLI code or native code. You should avoid using the old syntax too heavily, though, since
it is deprecated in the Visual C++ 2005 release.
None of the Above
Without /clr at all, of course, you are compiling native C++ in the classic way. If you try to use
any of the C++/CLI language features, you will get compiler errors.
Caveats When Upgrading Code to
Visual C++ 2005
Although we’ve said that preexisting code should compile in mixed mode just by turning on
the /clr option, there are many changes to the standard libraries in Visual C++ 2005 that will
cause compilation errors and warnings. For example, the C Runtime Library was updated to
support more secure versions of many functions; by default, the unsafe versions of these functions
will generate compiler warnings. Also, numerous changes were made to better conform with
the C++ and C standards. Refer to the “What’s New” section in the Visual C++ documentation
for details on these changes and how to disable the warnings, if necessary.
Library changes aside, most code written for native C++, for example with Visual C++ 6.0,
will work when compiled with the /clr option in Visual C++ 2005.
Architecture Dependence and 64-bit
Programming
The CLR implements a layer that abstracts the processor architecture. The IL itself contained
in managed assemblies is independent of any specific processor architecture. However, as
you’ve seen, code compiled with /clr rather than /clr:pure or /clr:safe may contain plat-
form-specific code. Also, even in pure mode, you can invoke platform-specific functions. If you
want to produce an application that is capable of running on any implementation of the CLI,
you should use the /clr:safe option. If you know you’ll be using the Microsoft Windows plat-
form, but want the output code to be neutral with respect to CPU architecture, then you can

Assemblies contain additional information called metadata that a traditional executable
or DLL does not contain. The metadata is stored in assemblies along with the generated code.
You can view the metadata using a tool called ILDasm.exe that ships with the .NET Framework,
as explained in the upcoming section “Viewing Metadata with ILDasm.exe.”
By default, Visual Studio Project packages all the source files in a project into a single
assembly when the project is built. Similarly, the default behavior of a command-line compila-
tion is to produce a single assembly. However, it is possible to change compiler options or
project settings to omit the manifest required in an assembly. If you specify the /LN compiler
option and the /NOASSEMBLY linker option, the resulting output is referred to as a module or
netmodule. A .NET module has the extension .netmodule to distinguish it from an assembly.
Where modules are useful is when you are planning to combine many modules from different
compilations into a single assembly. You could compile the modules separately, and then link
them all together with the linker (link.exe) or with something called the assembly linker (al.exe)
to produce your final assembly. The common language runtime won’t load modules that
haven’t been linked into an assembly since they don’t have a manifest. The CLR makes use of
the metadata in the manifest and cannot load code in a naked module without the metadata
from its parent assembly.
The Assembly Manifest
The term manifest comes from the Latin manifestus, which means “blatant, obvious.” It was
later used in the shipping industry to mean the list of cargo and passengers on a ship or train.
To find a particular passenger or to discover what cargo is contained on a train, you would
consult the manifest. The assembly manifest serves the same purpose for an assembly. The
runtime uses the manifest to find information about what types are in an assembly, and where
to find those types in the assembly. Because of the information in the manifest, the assembly is
said to be self-describing. This presents a significant advance from unmanaged executables
Hogenson_705-2C03.fm Page 33 Friday, October 13, 2006 2:18 PM