The #using Directive
Imports metadata into a program that will use the Managed Extensions for C++.
- A .dll, .exe, .netmodule, or .obj that was built with /clr.
file can be a Microsoft intermediate language (MSIL) file that you import for its managed data and managed constructs. If a .dll file contains an assembly manifest, then all the .dlls referenced in the manifest are imported and the assembly you are building will list file in the metadata as an assembly reference.
If file does not contain an assembly (if file is a module) and if you do not intend to use type information from the module in the current (assembly) application, you have the option of just indicating that the module is part the assembly; use /ASSEMBLYMODULE. The types in the module would then be available to any application that referenced the assembly.
An alternative to use #using is the /FU (Name Forced #using File) compiler option.
At run time only one .exe assembly can be loaded per process. Therefore, do not pass an .exe assembly to #using. Future versions of the common language runtime may allow .exe assembly references.
In order for the compiler to recognize a type in an assembly (not a module), it needs to be forced to resolve the type, which you can do, for example, by defining an instance of the type. There are other ways to resolve type names in an assembly for the compiler, for example, if you inherit from a type in an assembly, the type name will then become known to the compiler.
When importing metadata built from source code that used __declspec(thread), the thread semantics are not persisted in metadata. For example, a variable declared with __declspec(thread), compiled in a program that is build for the .NET Framework common language runtime, and then imported via #using, will no longer have __declspec(thread) semantics on the variable.
If file has metadata only and not an assembly manifest, the following guidelines discuss how to access the metadata:
- If the metadata contains only one class, the class and the file name must be the same.
- One of the classes must have the same name as the file name. Before you can use any of the other classes, you must first allocate memory for the class that has the same name as file.
- If one or more classes in the metadata are in a namespace, the namespace must have the same name as file. You can access classes in the metadata in one of two ways:
- Qualify access to each class with the namespace name.
- Use #using namespace file to load all classes in the namespace.
The file mscorlib.dll must be passed to #using in any program that uses Managed Extensions for C++. Note that any path that is specified for this file will be ignored.
The LIBPATH environment variable specifies the directories that will be searched when the compiler tries to resolve file names passed to #using.
The compiler will search for references along the following path:
- A path specified in the #using statement.
- The current directory.
- The .NET Framework system directory.
- Directories added with the /AI compiler option.
- Directories on LIBPATH environment variable.