Generating Primary Interop Assemblies

There are two ways to generate a primary interop assembly:

• Using the Type Library Importer (Tlbimp.exe) provided by the .NET Framework SDK.
• Creating primary interop assemblies manually.

You must have a cryptographic key pair to sign the assembly with a strong name. For details, see Creating A Key Pair.

Using the Type Library Importer

Producing a primary interop assembly by using Tlbimp.exe to import a type library is straightforward. Tlbimp.exe provides the following safeguards:

• Checks for other registered primary interop assemblies before creating new interop assemblies for any nested type library references.
• Fails to emit the primary interop assembly if you do not specify either the container or file name to give the primary interop assembly a strong name.
• Fails to emit a primary interop assembly if you omit references to dependent assemblies.
• Fails to emit a primary interop assembly if you add references to dependent assemblies that are not primary interop assemblies.

To generate a primary interop assembly using Tlbimp.exe

• At the command prompt, type:

  tlbimp tlbfile **/primary /keyfile:**filename **/out:**assemblyname

  In this command, tlbfile is the file containing the COM type library, filename is the name of the container or file that contains the key pair, and assemblyname is the name of the assembly to sign with a strong name.

The following example imports the COM type library LibUtil.tlb and signs the assembly LibUtil.dll with a strong name using the key file CompanyA.snk. By omitting a specific namespace name, this example produces the default namespace, LibUtil.

tlbimp LibUtil.tlb /primary /keyfile:CompanyA.snk /out:LibUtil.dll

For a more descriptive name (using the VendorName.LibraryName naming guideline), the following example overrides the default assembly file name and namespace name.

tlbimp LibUtil.tlb /primary /keyfile:CompanyA.snk /namespace:CompanyA.LibUtil /out:CompanyA.LibUtil.dll

Primary interop assemblies can reference only other primary interop assemblies. If your assembly references types from a third-party COM type library, you must obtain a primary interop assembly from the publisher before you can generate your primary interop assembly. If you are the publisher, you must generate a primary interop assembly for the dependent type library before generating the referencing primary interop assembly.

The following example imports MyLib.tlb, which references CompanyA.LibUtil.dll, and signs the assembly CompanyB.MyLib.dll with a strong name using the key file CompanyB.snk. The namespace, CompanyB.MyLib, overrides the default namespace name.

tlbimp MyLib.tlb /primary /keyfile:CompanyB.snk /namespace:CompanyB.MyLib /reference:CompanyA.LibUtil.dll /out:CompanyB.MyLib.dll

A dependent primary interop assembly with a version number that differs from that of the original type library is not discoverable when installed in the current directory. You must either register the dependent primary interop assembly in the Windows registry or use the /reference option to be sure that Tlbimp.exe finds the dependent DLL.

Optionally, you can wrap more than one version of a type library. For example, you can indicate that a primary interop assembly supports type library versions 1.0 and 1.1.

To wrap multiple versions of a type library

1. Import a type library file as described in the previous procedure:

   tlbimp LibUtil.tlb /primary /keyfile:CompanyA.snk /out:LibUtil.dll
   

2. Create a text file from the imported assembly by using the MSIL Disassembler (Ildasm.exe):

   ildasm LibUtil.dll /out:LibUtil.il
   

3. Using a text editor, insert a second PrimaryInteropAssemblyAttribute below the attribute added by Tlbimp.exe. Include the major and minor version numbers that represent the second type library version.

4. Generate and sign a new assembly from the modified text file by using the MSIL Assembler (Ilasm.exe):

   idasm LibUtil.il /dll /key:CompanyA.snk
   

Creating Primary Interop Assemblies Manually

A less frequently used approach for producing a type library involves creating a primary interop assembly manually in source code by using a language that is compliant with the Common Language Specification (CLS), such as C#. This approach is useful when a type library is unavailable.

To generate a primary interop assembly in source code

1. Create an interop assembly in source code. For instructions, see Creating a Wrapper Manually. Note that you must include all COM types from the original type library when you create a primary interop assembly manually.
2. At the assembly level, apply the following attributes:
   1. AssemblyKeyFileAttribute or AssemblyKeyNameAttribute, to specify the name of the file or container that contains the key pair to use when signing the assembly with a strong name.
   2. GuidAttribute, to specify the library identifier (LIBID) of the target type library.
   3. PrimaryInteropAssemblyAttribute, to identify the assembly as a primary interop assembly.

The following code example applies the AssemblyKeyFileAttribute with a key file called CompanyA.snk and specifies that this assembly is a primary interop assembly supporting type library versions 4.2 and 5.2. As the example shows, you can wrap more than one version of a type library by applying additional assembly-level attributes.

[assembly:AssemblyKeyFile(@"..\..\CompanyA.snk")]
[assembly:Guid("97d25db0-0363-1cf-abc4-02608 c9e7553"]
[assembly:PrimaryInteropAssembly(4, 2)]
[assembly:PrimaryInteropAssembly(5, 2)]

You can also delay sign an assembly when compiling. For more information, see Delay Signing an Assembly.

See Also

Producing Primary Interop Assemblies | Naming Primary Interop Assemblies | Customizing Primary Interop Assemblies | Distributing Primary Interop Assemblies to Developers