The Correct Way to Reference Dynamic Link Libraries (DLLs) in .NET Projects

How to use DLL files written by others

Generally, it is not recommended to directly reference DLL files written by others because C# has a NuGet Server, and most free packages today can be found there. If it is an internal company library, you can ask a technical consultant to set up a NuGet Server accessible via the intranet, and then have developers package the written library into a NuGet file and upload it. Those who need to reference it can simply add this NuGet Server link in their Visual Studio to use it. As for why you should use NuGet to download packages instead of directly referencing DLL files:

• NuGet makes version upgrades and downgrades convenient.
• DLL files have Framework compatibility issues. Many packages on NuGet today support multiple Framework versions. When you download from NuGet, it will find the most suitable version to install based on your project's Framework. However, this also means that when the project's Framework version changes, you need to run commands in the Package Manager to reinstall the referenced packages and manually modify the restored configuration files.
• There are dependency issues between packages. When installing, NuGet will help you install other packages that the package being installed depends on.

Explaining the correct way to reference DLL files using the NuGet approach

When installing a package from NuGet, a "packages" folder is created under the solution, which stores the DLL files of the installed packages. Opening the project file (.csproj) will reveal that the sources of the referenced DLLs are stored under "packages".

Therefore, the correct way to reference is as follows:

1. Create a folder under the solution (or higher up if the solution is not at the root of version control). It is recommended not to name it "packages" to avoid confusion.
2. Place the DLL files to be referenced in this folder. When adding references in each project, always reference the DLL files from this folder.
3. This folder must be under version control. "packages" does not need to be under version control because NuGet can be configured to restore the DLLs under "packages" from the NuGet Server.

Precautions for directly referencing DLL files written by others

• Common mistakes made by beginners:

  1. The project's "bin" folder is the output directory after compilation and is normally not under version control. If you reference DLL files correctly, when the DLL file is missing from "bin", the project can re-copy the DLL file from the source to "bin" during compilation. However, when you place the DLL file in "bin" to reference it, the project file (.csproj) records the source of the DLL file as being in "bin". When you delete the DLL file in "bin" and rebuild, it will fail to copy to "bin" because the source DLL file no longer exists.

  

  1. It is impossible to control the versions of referenced DLLs across multiple projects within the same solution, because many people do not pay attention to which extra DLL files other projects are referencing. Every time a DLL file is referenced, it is placed in "bin" rather than a common source, which makes it very likely that different projects will reference different versions.

• Website Projects (WSP) do not have project files. Where is the location of the DLL file reference recorded?

  When adding a reference in a WSP, in addition to generating the DLL file in the "bin" folder, a file named "{DLL name}.dll.refresh" is also created. Opening this file reveals the recorded source of the DLL file reference.

  

  

  Although theoretically "bin" is not under version control, the ".dll.refresh" files within it must be under version control.

Change Log

• 2022-09-30 Initial document creation.