C# Reference ยท .NET, Tools and Concepts
Assemblies and NuGet packages
Reference for .NET assemblies and NuGet packages: what a DLL contains, assembly names and versions, internal visibility, project and package references.
An assembly is the unit of deployment, versioning and type visibility in .NET. When you build a project, the compiler produces one assembly: a .dll file (or an .exe for an application) that contains your compiled code in intermediate language, metadata that describes every type and member, and a manifest with the assembly's name, version and references to other assemblies.
A NuGet package is a different thing: a zip archive (.nupkg) with one or more assemblies, plus metadata such as a package id, a version and a list of dependencies. NuGet is how you share assemblies. Your project asks for a package by id and version, NuGet downloads it with everything it depends on, and the build references the assemblies inside.
<ItemGroup> <PackageReference Include="Polly" Version="8.5.0" /> <ProjectReference Include="..\Shop.Core\Shop.Core.csproj" /> </ItemGroup>
Try it
The runner has no dotnet CLI and no network, so you cannot install packages here. You can, however, look at the assemblies that are already loaded. This program reads the identity of three of them.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
An assembly has a four-part identity. The first three parts are plain text and the fourth is a hash:
Name, Version=1.2.3.0, Culture=neutral, PublicKeyToken=null
| Part | Description |
|---|---|
| Name | The file name without extension, taken from <AssemblyName> (default: the project name). |
| Version | Four numbers, major.minor.build.revision. The runtime uses it when it binds references. |
| Culture | neutral for code assemblies; satellite assemblies for translated resources carry a culture such as fr. |
| PublicKeyToken | Only for strong-named assemblies. Modern .NET does not enforce it, and most libraries are not strong named. |
Three version numbers exist per project, which is confusing at first:
| Property in the project file | Used for |
|---|---|
AssemblyVersion |
The identity that other assemblies bind to. Change it rarely. |
FileVersion |
The "file version" you see in Explorer; often the build number. |
Version (or InformationalVersion) |
The NuGet package version and the product version string, such as 2.1.0-beta.3. |
Referencing code
| Kind | Element | What happens |
|---|---|---|
| Project reference | <ProjectReference Include="...csproj" /> |
The other project is built first and its assembly is referenced. |
| Package reference | <PackageReference Include="id" Version="x.y.z" /> |
NuGet restores the package and its dependencies. |
| Framework reference | <FrameworkReference Include="Microsoft.AspNetCore.App" /> |
A shared framework that is installed with the runtime, not downloaded as a package. |
Errors: a package that cannot be found or restored fails with NU1101 (unable to find package) at restore time. A missing assembly at run time throws FileNotFoundException (or FileLoadException for a wrong version).
Usage notes
publicversusinternal.publictypes are visible to other assemblies;internal(the default for a top-level type) is visible only inside the assembly. Your assembly boundary is therefore your API boundary. Use[assembly: InternalsVisibleTo("Shop.Tests")]to let a named friend assembly see your internals, which is common for unit tests.- One project, one assembly. A project cannot be split over several DLLs. Splitting a solution into several projects is how you create several assemblies, usually to share code or to enforce dependency direction.
- Transitive dependencies. If your package references another package, you get it too. Restore picks the lowest version that satisfies every constraint. Run
dotnet list package --include-transitiveto see the full tree. - Versions are semantic. Packages use semantic versioning (
major.minor.patch, with an optional suffix like-preview.2). A major version change is allowed to break your code; minor and patch updates should not. - Pin what you ship. Central package management (
Directory.Packages.props) keeps versions in one file for a whole repository. A lock file (packages.lock.json) makes restores repeatable. - Trust what you install. A package runs with the same rights as your program. Review a new dependency's publisher and download count, and keep packages updated for security fixes (
dotnet list package --vulnerable). - Assembly loading. The runtime loads an assembly the first time a type from it is needed, not at start-up.
Assembly.LoadandAssemblyLoadContextload code dynamically (plug-ins), but trimming and Native AOT cannot always see such code (Native AOT and trimming). - Reflection works with assemblies.
Assembly.GetTypes(),GetExportedTypes()andGetReferencedAssemblies()let you inspect code, as the examples above do. See Assembly. - The runner is a single file. In this site's editors you write one file that becomes one assembly, and you cannot add NuGet packages. Everything in the shared frameworks (
System.*,Microsoft.Extensions.*, ASP.NET Core) is available.