COM type definitions usually reside in a type library. In contrast, CLS-compliant compilers produce type metadata in an assembly. The two sources of type information are quite different.
Note When available, always use the primary interop assembly published by the author of the COM component you intend to incorporate in your managed code. Types in the primary interop assembly have been imported for you and are ready to activate and call from managed code. For details on producing and using primary interop assemblies, see Primary Interop Assemblies.
This topic describes techniques for generating metadata from a type library. The resulting assembly is called an interop assembly.
Generating Metadata
COM type libraries can be stand-alone TLB files, such as Loanlib.tlb. Some type libraries are embedded in the resource section of a DLL or EXE file. Other sources of type library information are OLB and OCX files.
After locating the type library containing the implementation of your target COM type, you have the options described in the following table for generating an interop assembly containing type metadata.
| Option | Description |
|---|---|
| Visual Studio .NET | Automatically converts COM types in a type library to metadata in an assembly. |
| Type Library Importer | Provides command-line switches to adjust metadata in the resulting interop file, imports types from an existing type library, and generates an interop assembly and a namespace. |
| TypeLibConverter Class | Exposes methods that perform conversion-related actions. Can convert in-memory type library information to metadata. |
| Custom Wrappers | As a less desirable option, you can create type definitions from scratch. This requires advanced programming skills. |
For details about the COM interop import process, see Type Library to Assembly Conversion Summary.
Visual Studio .NET
Visual Studio .NET generates an interop assembly containing metadata when you add a reference to a given type library. If a primary interop assembly is available, Visual Studio uses the existing assembly before generating a new interop assembly.
To add a reference to a type library
- Install the COM DLL or EXE file on your computer, unless a Windows Setup.exe performs the installation for you.
- From the Project menu, select References.
- Select the COM tab.
- Select the type library from the Available References list, or browse for the TLB file.
- Click OK.
Type Library Importer
The Type Library Importer (Tlbimp.exe) is a command-line tool that converts the coclasses and interfaces contained in a COM type library to metadata. This tool creates an interop assembly and namespace for the type information automatically. After the metadata of a class is available, managed clients can create instances of the COM type and call its methods, just as if it were a .NET instance. Tlbimp.exe converts an entire type library to metadata at once and cannot generate type information for a subset of the types defined in a type library.
To generate an interop assembly from a type library
- Use the following command to produce the Loanlib.dll assembly in the Loanlib namespace.
tlbimp Loanlib.dll
Adding the /out: switch produces an interop assembly with an altered name, such as LOANLib.dll. Altering the interop assembly name can help distinguish it from the original COM DLL and prevent problems that can occur from having duplicate names.
TypeLibConverter Class
The TypeLibConverter class (in the System.Runtime.InteropServices namespace) provides methods to convert coclasses and interfaces in a type library to metadata within an assembly. This API produces the same metadata output as Tlbimp.exe. However, unlike Tlbimp.exe, the TypeLibConverter class can convert an in-memory type library to metadata.
Custom Wrappers
When a type library is unavailable or incorrect, one option is to create a duplicate definition of the class or interface in managed source code. You then compile the source code with a compiler that targets the runtime to produce metadata in an assembly.
To define COM types manually, you must have access to the following items:
- Precise descriptions of the coclasses and interfaces being defined.
- A compiler, such as the C# compiler, that can generate the appropriate .NET Framework class definitions.
- Knowledge of the type library-to-assembly conversion rules.
Writing a custom wrapper is an advanced technique that you seldom perform. For additional information on generating a custom wrapper, see Customizing Standard Wrappers.