How to: Build a multifile assembly

This article explains how to create a multifile assembly and provides code that illustrates each step in the procedure.

Create a multifile assembly

1. Compile all files that contain namespaces referenced by other modules in the assembly into code modules. The default extension for code modules is .netmodule.

   For example, let's say the Stringer file has a namespace called myStringer, which includes a class called Stringer. The Stringer class contains a method called StringerMethod that writes a single line to the console.

   // Assembly building example in the .NET Framework.
   using namespace System;
   
   namespace myStringer
   {
       public ref class Stringer
       {
       public:
           void StringerMethod()
           {
               System::Console::WriteLine("This is a line from StringerMethod.");
           }
       };
   }
   

   // Assembly building example in the .NET Framework.
   using System;
   
   namespace myStringer
   {
       public class Stringer
       {
           public void StringerMethod()
           {
               System.Console.WriteLine("This is a line from StringerMethod.");
           }
       }
   }
   

   ' Assembly building example in the .NET Framework.
   Namespace myStringer
       Public Class Stringer
           Public Sub StringerMethod()
               System.Console.WriteLine("This is a line from StringerMethod.")
           End Sub
       End Class
   End Namespace
   

2. Use the following command to compile this code:

   cl /clr:pure /LN Stringer.cpp
   

   csc /t:module Stringer.cs
   

   vbc /t:module Stringer.vb
   

   Specifying the module parameter with the /t: compiler option indicates that the file should be compiled as a module rather than as an assembly. The compiler produces a module called Stringer.netmodule, which can be added to an assembly.

3. Compile all other modules, using the necessary compiler options to indicate the other modules that are referenced in the code. This step uses the /addmodule compiler option.

   In the following example, a code module called Client has an entry point Main method that references a method in the Stringer.netmodule module created in step 1.

   #using "Stringer.netmodule"
   
   using namespace System;
   using namespace myStringer; //The namespace created in Stringer.netmodule.
   
   ref class MainClientApp
   {
       // Static method Main is the entry point method.
   public:
       static void Main()
       {
           Stringer^ myStringInstance = gcnew Stringer();
           Console::WriteLine("Client code executes");
           myStringInstance->StringerMethod();
       }
   };
   
   int main()
   {
       MainClientApp::Main();
   }
   

   using System;
   using myStringer;
   
   class MainClientApp
   {
       // Static method Main is the entry point method.
       public static void Main()
       {
           Stringer myStringInstance = new Stringer();
           Console.WriteLine("Client code executes");
           myStringInstance.StringerMethod();
       }
   }
   

   Imports myStringer
   
   Class MainClientApp
       ' Static method Main is the entry point method.
       Public Shared Sub Main()
           Dim myStringInstance As New Stringer()
           Console.WriteLine("Client code executes")
           myStringInstance.StringerMethod()
       End Sub
   End Class
   

4. Use the following command to compile this code:

   cl /clr:pure /FUStringer.netmodule /LN Client.cpp
   

   csc /addmodule:Stringer.netmodule /t:module Client.cs
   

   vbc /addmodule:Stringer.netmodule /t:module Client.vb
   

   Specify the /t:module option because this module will be added to an assembly in a future step. Specify the /addmodule option because the code in Client references a namespace created by the code in Stringer.netmodule. The compiler produces a module called Client.netmodule that contains a reference to another module, Stringer.netmodule.

   Note

   The C# and Visual Basic compilers support directly creating multifile assemblies using the following two different syntaxes.

   Two compilations create a two-file assembly:

   cl /clr:pure /LN Stringer.cpp
   cl /clr:pure Client.cpp /link /ASSEMBLYMODULE:Stringer.netmodule
   

   csc /t:module Stringer.cs
   csc Client.cs /addmodule:Stringer.netmodule
   

   vbc /t:module Stringer.vb
   vbc Client.vb /addmodule:Stringer.netmodule
   

   One compilation creates a two-file assembly:

   cl /clr:pure /LN Stringer.cpp
   cl /clr:pure Client.cpp /link /ASSEMBLYMODULE:Stringer.netmodule
   

   csc /out:Client.exe Client.cs /out:Stringer.netmodule Stringer.cs
   

   vbc /out:Client.exe Client.vb /out:Stringer.netmodule Stringer.vb
   

5. Use the Assembly Linker (Al.exe) to create the output file that contains the assembly manifest. This file contains reference information for all modules or resources that are part of the assembly.

   At the command prompt, type the following command:

   al <module name> <module name> … /main:<method name> /out:<file name> /target:<assembly file type>

   In this command, the module name arguments specify the name of each module to include in the assembly. The /main: option specifies the method name that is the assembly's entry point. The /out: option specifies the name of the output file, which contains assembly metadata. The /target: option specifies that the assembly is a console application executable (.exe) file, a Windows executable (.win) file, or a library (.lib) file.

   In the following example, Al.exe creates an assembly that is a console application executable called myAssembly.exe. The application consists of two modules called Client.netmodule and Stringer.netmodule, and the executable file called myAssembly.exe, which contains only assembly metadata. The entry point of the assembly is the Main method in the class MainClientApp, which is located in Client.dll.

   al Client.netmodule Stringer.netmodule /main:MainClientApp.Main /out:myAssembly.exe /target:exe
   

   You can use IL Disassembler (Ildasm.exe) to examine the contents of an assembly, or determine whether a file is an assembly or a module.

See also

• Create assemblies
• How to: View assembly contents
• How the runtime locates assemblies
• Multifile assemblies