Introduction
C++/CLI is C++ with a small set of extensions that let it write .NET code. A file is ordinary C++ source, kept in the same .cpp, .h and .hpp files as any other C++, and compiled by the Microsoft C++ compiler with the /clr option. The extensions add three new kinds of type (ref class, value class and interface class), a handle declarator ^ for objects that the garbage collector owns, a tracking reference %, the allocation operator gcnew, and members that .NET has and C++ does not: properties, events and delegates. The result is an assembly, the same kind of file as one written in C#, and the same file can also hold native C++ that the compiler turns into machine code. That mix of managed and native code in one assembly is what the language is used for: wrapping a native library for .NET, or calling .NET from a native program.
The language is defined by the Ecma standard ECMA-372, the C++/CLI Language Specification, and by Microsoft’s Component Extensions for .NET and UWP. It replaced the earlier Managed Extensions for C++, whose double-underscore keywords (__gc, __value, __property) the viewer also reads. C++/CLI is a different thing from C++/CX and C++/WinRT, which target the Windows Runtime (C++/CX and C++/WinRT), and from the plain C++ of the same extensions.
There is no signature. A C++/CLI file is a text file, and nothing in its first bytes says so. The explorer tells it from plain C++ by what the text contains, and a C++ file that contains none of these marks stays plain C++ (see below).
A C++/CLI file
// compile with: cl /clr hello.cpp
#using <System.dll>
using namespace System;
using namespace System::Collections::Generic;
public ref class Greeter {
String^ name;
public:
Greeter(String^ name) : name(name) {}
property String^ Name {
String^ get() { return name; }
}
void Greet(List<String^>^ others) {
Console::WriteLine("Hello, {0}", name);
for each (String^ other in others)
Console::WriteLine("and {0}", other);
}
};
int main(array<String^>^ args) {
Greeter^ g = gcnew Greeter("world");
g->Greet(gcnew List<String^>());
return 0;
}
main that takes the command line as a managed array. Everything that is not C++ in this file is on the pages of this section: #using on Mixed mode, public ref class on Managed types, ^ and gcnew on Handles, property on Members, for each on Statements. C++/CLI needs Windows and the Microsoft C++ compiler, so the examples on these pages were written from the documentation and were not compiled here (see Not described).The kinds of file
| Extension | What it is | Page |
|---|---|---|
.cpp, .cc, .cxx | a source file compiled with /clr: managed classes, native classes and the functions that join them | File structure |
.h, .hpp, .hh, .hxx | a header: a Windows Forms form with its designer code, the declaration of a managed class, or the #using lines shared by a project. A .h that is not C++/CLI is a C header | File structure |
the same, with __gc and __value | Managed Extensions for C++, the syntax of Visual Studio 2002 and 2003 | Managed Extensions |
the same, with ref new and Platform:: | C++/CX (Windows Runtime): not C++/CLI, shown as plain C++ | C++/CX |
.vcxproj | the project file that turns /clr on (CLRSupport); read as an Visual Studio project | The /clr options |
How the viewer reads each file
The explorer asks the text of a .cpp, .cc, .cxx, .hpp, .hh, .hxx or .h file for marks that only C++/CLI has. One strong mark is enough: a #using line, a ref class, value class or interface class declaration, gcnew followed by a type, safe_cast<, pin_ptr< or interior_ptr<, or generic<typename. A weaker mark needs a second one beside it: a for each ( statement (native Microsoft C++ has it too), #pragma managed or unmanaged, a handle declarator such as String^ s;, System::, cli::, array<T>^, __clrcall, or an attribute such as [DllImport(…)]. Marks inside comments are ignored. The text is read up to the first 256 KiB.
| File | Shown as |
|---|---|
| text with a C++/CLI mark | C++/CLI source file, coloured, with an outline, the #using references and the problems found |
text with __gc, __value, __property or a similar word of Managed Extensions | Managed Extensions for C++ source file, coloured the same way |
text with ref new, Platform:: or Windows:: and nothing of the CLR | plain C++ (see C++/CX) |
| any other C++ text | C++ source file (for .h, C header) |
The coloured text marks the words that the extensions add. A spaced keyword is one token (ref class, value struct, interface class, enum class, for each, ref new). ref and value alone stay plain, because they are ordinary names. The words that are keywords only in some places (property, event, delegate, literal, initonly, abstract, sealed, where, finally, internal, in of for each) are coloured only where the shape of the statement says so: property int Size { … } is a property, and int property = 0; is a variable. ^ and % are coloured as types where they declare a handle or a tracking reference (String^ s, int% n); a ^ b, a % b, ^= and %= are operators and stay plain. Attributes such as [Serializable] and [assembly: AssemblyVersion("1.0")] have a keyword target and a type name. The scanner has no parser, so it cannot be fooled into failing, only into leaving a word plain.
The Overview tab lists the namespaces, the managed types, the generics, the properties, events and delegates with their lines, the #using references and the mixed-mode pragmas; each list is paged so that none of it is out of reach. The Problems list holds every unterminated comment or string, every brace that does not pair, every #if without #endif and every managed or unmanaged pragma push without its pop.
The pages
- File structure – source files, headers, the files a Visual Studio project adds, and the order of a file
- Keywords and lexical structure – every reserved, context-sensitive and spaced keyword, the template-like words and the tokens
^and% - Managed types –
ref class,value class,interface class,enum class, visibility, arrays, strings and boxing - Handles and references –
^,%,gcnew,nullptr,interior_ptr,pin_ptr, destructors and finalizers - Members, delegates and generics – properties, events, delegates,
literal,initonly, override specifiers,genericandwhere - Statements, casts and attributes –
for each,safe_cast,finally,typeid, custom attributes - Interop with native code – It Just Works, P/Invoke, marshalling, pinning,
gcroot, thunks - Mixed mode and #using –
#pragma managedandunmanaged,#using,make_public, predefined macros - The /clr options –
/clr,pure,safe,oldSyntax,netcoreand the others - Versions and history – Managed Extensions, C++/CLI, the standard and .NET Core
- Managed Extensions for C++ – the double-underscore keywords and what replaced each
- C++/CX and C++/WinRT – the Windows Runtime languages that share the syntax or replace it
- Tooling – the compiler, the linker,
ildasm, decompilers and the project settings
Not described
Known, not yet covered
- Reference: the sources were the Microsoft Learn pages for C++/CLI (the component extensions, the
/clroptions, the pragmas,#using, interop and generics) and the ECMA-372 language specification, first edition, December 2005. The PDF of the standard was downloaded, but its text could not be extracted on this Mac, so the standard’s own grammar and numbering are not quoted; the Microsoft pages were used for every statement. Later editions of the standard were not looked at. - Reference: the C++/CLI support library (
cliext, the STL/CLR containers,msclrandmarshal_as) is named on the interop page and not described in full. - Viewer: C++/CX text is shown as plain C++, without the colours for
ref new, because it is not C++/CLI; there is no C++/CX page of its own (C++/CX and C++/WinRT). - Viewer: the colouring follows words and the shape of a line, not a parse. A handle declarator written in an unusual way (
String ^s, with the space before the caret), or a context word on a line that continues from the previous one, can be left plain.
Unknown
- Reference: none of the examples was compiled. C++/CLI needs the Microsoft C++ compiler, which does not run on this Mac, and the .NET SDK that is here (10.0.404) has no C++/CLI compiler. The examples follow the Microsoft documentation, and the files of the Microsoft ManagedSpy sample were used to test the viewer.
- Reference: which Visual Studio release first accepted each detail of the language (for instance the exact release that dropped
/clr:oldSyntax) is not stated in the pages that were read, and the pages say so where they leave it out.
Also used for
- C source code – Programs in the C language as plain text, with .h headers.
- C++ source code – C++ programs as plain text, with .hpp or .h headers.
Links
Software
- Visual Studio – the IDE with the Microsoft C++ compiler, project templates for C++/CLI and, in older versions, a Windows Forms designer (Windows)
- ILSpy – open-source .NET decompiler that opens the assembly a C++/CLI project builds (Windows, macOS, Linux)
- ildasm – the IL disassembler of .NET, which shows both the managed and the native parts of a mixed assembly (Windows, macOS, Linux)
Developers
- .NET programming with C++/CLI – Microsoft’s guide to writing, building and interoperating with C++/CLI (C++)
- /clr (Common Language Runtime compilation) – the compiler option that turns C++/CLI on
Reference
- ECMA-372 – the C++/CLI Language Specification
- Component Extensions for .NET and UWP – Microsoft’s reference for every keyword and operator of C++/CLI and C++/CX
- MicrosoftDocs/cpp-docs – the Markdown source of the Microsoft C++ documentation, including the C++/CLI pages
- C++ source code – the language that C++/CLI extends (on this site)
- CIL assembly source code – the intermediate language that C++/CLI compiles to (on this site)