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

TLDR

• Use NuGet to manage packages whenever possible to resolve version control, framework compatibility, and dependency issues.
• If you must reference a local DLL, create a dedicated folder (not the bin directory) and include it in version control to ensure all projects reference the same source.
• Strictly avoid referencing DLLs directly from the bin directory, as this will lead to missing sources during compilation or version inconsistencies across multiple projects.
• For Website Projects (WSP), ensure .dll.refresh files are included in version control to record the correct source of the DLL reference.

Why NuGet Should Be the Priority for Package Management

In .NET development, referencing DLL files directly is not a best practice. Using NuGet is recommended for the following reasons:

• Convenient Version Management: NuGet supports easy upgrading and downgrading of packages.
• Framework Compatibility: NuGet automatically selects the most suitable package version based on the project's framework version.
• Automatic Dependency Handling: When installing a package, NuGet automatically installs other packages that the target package depends on.

For internal company libraries, it is recommended to set up an internal NuGet Server, package the libraries, and upload them so developers can reference them via Visual Studio.

The Correct Way to Reference Local DLLs

When you cannot use NuGet and must reference a local DLL, follow these steps to ensure smooth collaboration:

1. Create a Dedicated Directory: Create a dedicated folder at the solution level (or the root of the version control repository). It is recommended not to name it "packages" to avoid confusion with NuGet.
2. Centralize Storage and Referencing: Place all required DLL files in this folder and have the projects point to this path consistently.
3. Include in Version Control: This folder must be included in the version control system to ensure that all team members can obtain the same DLL versions.

Risks of Referencing the bin Directory Directly

When does this issue occur? It happens when developers, for convenience, reference DLL files directly from the compilation output directory (bin).

• Compilation Failure Risk: The bin directory is usually not included in version control. If the project file (.csproj) records a reference source pointing to the bin directory, the compiler will be unable to find the original DLL file after cleaning the project or deleting the bin directory, leading to build failures.
• Version Inconsistency: In multi-project solutions, if each project references DLLs from its own bin directory, it is easy for different projects to end up referencing different versions of the same DLL, making it difficult to manage.

Special Handling for Website Projects (WSP)

When does this issue occur? When the project type is a Website Project (WSP), the referencing mechanism differs because there is no .csproj project file.

When adding a reference in a WSP, a {DLL name}.dll.refresh file is generated in the bin directory, which records the actual path of the DLL reference. Although the bin directory itself is not version-controlled, .dll.refresh files must be included in version control to ensure that other developers can correctly restore the reference source.

Change Log

• 2022-09-30 Initial version created.