C++/CLI is switched on by the compiler option /clr[:options]. Without it the same text is not C++/CLI: ref class is an error. With it the compiler reads the extensions, writes MSIL for managed code and metadata for the managed types, and the linker writes an assembly.
The arguments of /clr
| Option | Status | What it does |
|---|---|---|
/clr | current | creates metadata for the component, so that other CLR code can use its managed types and it can use the types in other components’ metadata. The code is mixed mode |
/clr:netcore | current since Visual Studio 2019 version 16.4 | creates metadata and code for the cross-platform .NET (.NET Core) instead of the .NET Framework: the component consumes and is consumed by .NET Core assemblies |
/clr:nostdlib | current | ignores the default \clr directory, so that the compiler does not report an error when several versions of a DLL such as System.dll are given; the program names the framework to use |
/clr:pure | removed in Visual Studio 2017 and later | compiled everything to pure MSIL, with no native code. Code that must be pure MSIL should be ported to C# |
/clr:safe | removed in Visual Studio 2017 and later | compiled to verifiable MSIL. Code that must be safe MSIL should be ported to C# |
/clr:noAssembly | deprecated; use /LN | does not put an assembly manifest in the output, so the output is a module; used only to produce a module (with /c, the linker option /NOASSEMBLY follows). /LD is implied |
/clr:initialAppDomain | obsolete | let a C++/CLI application run on version 1 of the CLR (not for ASP.NET) |
Earlier versions also had /clr:oldSyntax (to compile Managed Extensions) and /clr:nostdimport; the current page of the options does not list them.
What /clr implies
/MD, the dynamically linked multi-threaded run-time library: the garbage collector runs finalizers on its own thread, so the library must be thread-safe. All modules given to one link must use the same run-time library option (/MDor/LD)./EHa, the exception model that catches both C++ and structured exceptions; no other/EHoption is allowed with/clr.- the macro
_MANAGEDis 1 (Mixed mode). - Only managed (CLR) types live on the garbage-collected heap; a native class is allocated with
newon the native heap, as always.
With /c, the kind of CLR image of the output is chosen with the linker option /CLRIMAGETYPE, and the image can be inspected with /CLRHEADER.
Assembly options
| Option | Meaning |
|---|---|
/FU file | forced #using of a file for the whole compilation |
/AI dir | add a directory to the search of metadata |
/LN | create an MSIL module (no manifest) |
/ASSEMBLYMODULE, /ASSEMBLYRESOURCE | (linker) add a module or embed a managed resource in the assembly |
/KEYFILE, /KEYCONTAINER, /DELAYSIGN | (linker) sign the assembly with a strong name |
/ASSEMBLYDEBUG | (linker) add the DebuggableAttribute |
The project setting
In Visual Studio the setting is Common Language Runtime Support, on the C/C++ General page of the property pages (also on the Advanced page, where it sets the other CLR-related options at once). Microsoft recommends creating a project from a CLR template, which sets everything that a CLR component needs. In the .vcxproj file the setting is the CLRSupport property (true for /clr and NetCore for /clr:netcore; older versions also had Pure, Safe and OldSyntax); the file is an MSBuild project.
Not described
Known, not yet covered
- Reference: the options of
/clrare from the current Microsoft page (updated 2021). The page of restrictions (/clr Restrictions: the options and the features that cannot be used with/clr), the older pages foroldSyntaxandnostdimport, and the table ofCLRSupportvalues in the project files were not read; the lines about them above are from memory.