Assemblies in .NET

Assemblies form the fundamental unit of deployment, version control, reuse, activation scoping, and security permissions for a .NET-based application. Assemblies take the form of an executable (.exe) file or dynamic link library (.dll) file, and are the building blocks of the .NET applications. They provide the common language runtime with the information it needs to be aware of type implementations. You can think of an assembly as a collection of types and resources that form a logical unit of functionality and are built to work together.

In .NET Core and .NET Framework, an assembly can be built from one or more source code files. In .NET Framework, assemblies can contain one or more modules. This allows larger projects to be planned in such a way that several individual developers work on separate source code files or modules, which are combined to create a single assembly. For more information about modules, see How to: Build a Multifile Assembly.

Assemblies have the following properties:

  • Assemblies are implemented as .exe or .dll files.

  • For libraries that target the .NET Framework, you can share an assembly between applications by putting it in the global assembly cache. Assemblies must be strong-named before they can be included in the global assembly cache. For more information, see Strong-Named Assemblies.

  • Assemblies are only loaded into memory if they are required. If they are not used, they are not loaded. This means that assemblies can be an efficient way to manage resources in larger projects.

  • You can programmatically obtain information about an assembly by using reflection. For more information, see Reflection (C#) or Reflection (Visual Basic).

  • You can load an assembly only to inspect it by calling a method Assembly.ReflectionOnlyLoadFrom.

Assembly manifest

Within every assembly is an assembly manifest. Similar to a table of contents, the assembly manifest contains the following:

  • The assembly's identity (its name and version).

  • A file table describing all the other files that make up the assembly, such as other assemblies you created that your .exe or .dll file relies on, or even bitmap or Readme files.

  • An assembly reference list, which is a list of all external dependencies — .dlls or other files your application needs that may have been created by someone else. Assembly references contain references to both global and private objects. Global objects are available to all other applications. In .NET Core, they are coupled with a particular .NET Core runtime. In .NET Framework, they reside in the global assembly cache. The System.IO namespace is an example of an assembly in the global assembly cache. Private objects must be in a directory at either the same level as or below the directory in which your application is installed.

Because assemblies contain information about content, versioning, and dependencies, the applications that use them need not rely on Windows registry values to function properly. Assemblies reduce .dll conflicts and make your applications more reliable and easier to deploy. In many cases, you can install a .NET-based application simply by copying its files to the target computer. For more information, see Assembly Manifest.

Adding a reference to an assembly

To use an assembly, you must add a reference to it. Next, you can use the using directive for C# or Imports statement for Visual Basic to choose the namespace of the items you want to use. Once an assembly is referenced and imported, all the accessible types, properties, methods, and other members of its namespaces are available to your application as if their code were part of your source file.

Note

Most assemblies from the .NET Class Library are referenced automatically. In some cases, though, a system assembly may not automatically be referenced. In .NET Core, you can add a reference to the NuGet package that contains the assembly either by using NuGet Package Manager in Visual Studio or by adding a element for the assembly to the *.csproj or *.vbproj project. In .NET Framework, you can add a reference to the assembly by using the Add Reference dialog in Visual Studio or by using the -reference command line option for the C# or Visual Basic compilers.

In C#, you can also use two versions of the same assembly in a single application. For more information, see extern alias.

Creating an assembly

Compile your application by building it in Visual Studio, by building it from the command line by using .NET Core command-line interface (CLI) tools, or by building .NET Framework assemblies with a command-line compiler. For more information about building assemblies using .NET CLI tools, see .NET Core command-line interface (CLI) tools. For building assemblies with the command-line compilers, see Command-line build with csc.exe for C# and Building from the Command Line for Visual Basic.

Note

To build an assembly in Visual Studio, on the Build menu choose Build.

See also