A C++/CLI file is a C++ file. It has the same translation unit, the same #include lines and the same split between headers and sources as any C++ program, and the extensions of the language sit inside it. What makes it C++/CLI is how it is compiled: with /clr, which turns on the keywords below and makes the compiler write MSIL for the managed code.
Extensions and encodings
| Name | Used for |
|---|---|
.cpp | implementation file; the extension Visual Studio uses (.cc and .cxx are also compiled as C++) |
.h | header; the extension of the Visual Studio templates for CLR projects. The same extension is a C header, so a .h is C++/CLI only when its text says so |
.hpp, .hh, .hxx | other header extensions |
.vcxproj | the project that sets /clr (The /clr options) |
The text is C++ source: the compiler reads a file with a UTF-8 or UTF-16 byte-order mark as Unicode and any other file in the code page of the machine (UTF-8 without a mark only with the /utf-8 option). The viewer reads UTF-8 and falls back to Windows-1252. A managed string literal ("text", L"text") is converted to System::String^ where a handle is expected.
The order of a file
- comments and
#pragma onceor include guards; #includelines for native headers;#usinglines, which import the metadata of assemblies (Mixed mode);mscorlibis always referenced;using namespacedirectives (the .NET namespaces are written with::, as inSystem::Collections::Generic);- assembly attributes:
[assembly: AssemblyVersion("1.0.0.0")];, with the semicolon after the bracket; - namespaces, types and functions. A type is private to its assembly unless it is declared
public.
The pragmas #pragma managed and #pragma unmanaged may follow the #include lines (and must not come before them), and switch the code that follows between MSIL and native machine code.
What a project adds
The Visual Studio templates for C++/CLI create the files below beside the source. None of them is special to the language: they are C++ files with /clr text in them.
- AssemblyInfo.cpp – the assembly attributes (
AssemblyTitle,AssemblyVersion,ComVisibleand the others) as[assembly: …];lines. - stdafx.h and stdafx.cpp (older) or pch.h and pch.cpp (newer) – the precompiled header.
- A form header – for a Windows Forms application, a
.hwith aref classderived fromSystem::Windows::Forms::Form, anInitializeComponentmethod between#pragma regionlines that the designer rewrites, and a.resxfile beside it. - app.rc and resource.h – native resources, for the projects that have an icon or version resource.
How it is compiled
The compiler is the Microsoft C++ compiler, cl, with /clr. The compiler writes an object file that holds both MSIL and native code (for a mixed-mode file), and the linker writes an assembly: a .dll or .exe that is a .NET assembly with its own metadata, and that the .NET runtime loads. The assembly can be read by the .NET assembly pages of this site, and the intermediate language in it by the IL pages. main may be written in the ordinary C++ way or take array<String^>^ args. Each public ref class is a type that C# and Visual Basic can use; native classes are not visible to them, and neither are native functions, unless they are wrapped.
Not described
Known, not yet covered
- Reference: the exact files of every Visual Studio template (they differ between releases) are described only in outline.
- Viewer: a form header is shown as C++/CLI text; the
#pragma regionblocks are coloured as directives and are not folded.