How to resolve .NET reference and NuGet package version conflicts
Some problems in programming seem to stay and bother us forever. Much like cockroaches, these problems resist technological advancements and increasing human knowledge. One such problem is the infamous DLL Hell (and variations of it).
The original DLL hell issue was this: Several applications use a shared DLL file. Then, one of the applications updated the DLL file and now the other applications no longer work. In .NET, this issue is solved. We will usually ship DLL files separately for each application. Alternatively, we can use the GAC for shared DLL’s, which supports versioning. This means we can store different versions of the same DLL and the different applications will load their intended version.
In the modern world, we are dependent on dozens of libraries. These in turn, depend on dozens more and we end up with hundreds or thousands of dependencies. So now the problem arises for a single application. What to do when several of its projects depend on different version of the same assembly?
Here’s an example: project A might use log4net V1.1 and project B uses log4net V1.2. Both DLL files are copied to the output folder, but there can be only one log4net.dll file. As a result, our application will fail at runtime when trying to load the version that wasn’t copied.
Here’s another scenario: We reference project A with NuGet which references System.Net.Http v4.5. We also reference project B with NuGet which references System.Net.Http v4.0. This phenomenon is knows as NuGet Hell. The result is the same and our application will fail with:
Could not load file or assembly or one of its dependencies. The located assemly’s manifest definition does not match the assembly reference.
If you ran into this exception, you are in the right place.
Luckily, Microsoft put a lot of thought into this issue and there are a lot of things we can do about it.
If possible, resolve to a single reference version
The best solution is to remove the need for different reference versions. Sometimes it’s as easy as going to NuGet manager and changing the versions. This is widely referred as DLL Hell and isn’t in the scope of this article. Some resources to help with DLL Hell are: [1], [2], [3]
Sometimes tough, you can’t depend on a single reference version due to all kind of reasons. The references might be referenced by a 3rd party that you can’t edit or you might have limitations like .NET framework target. If you’re in one of those times, this article is for you.
Use a single reference versions or load versions side-by-side
First of all, there’s an important decision to make: Do we want to force our projects to use the same reference version? Or do we want to load different versions side by side and use both?
The CLR does supports side-by-side loading. which means multiple versions of the same assembly are loaded and act as different modules. This can be problematic. Each assembly version doesn’t expect there’s another instance of it loaded. The different versions might fight for resources or get in each other’s way somehow.
Having said that, you can’t always use a single version, since the referencing projects might rely on features that exist only in their respective referenced versions.
In solution #1, we will how to force a specific version with Binding Redirects. Solution #2 through #4 will show various methods to achieve side-by-side loading.
If possible, prefer Binding Redirect to side-by-side loading
Solution 1: Use a single assembly version with Binding Redirect
Solution 2: Override AssemblyResolve for side-by-side loading (No need for strong names)
Solution 3: Copy assemblies to different folders and use <codebase> to load them side-by-side (Requires strong names)
Solution 4: Install assemblies to the Global Assembly Cache (GAC)
Summary and resources
We saw the new version of DLL Hell and a lot of ways to deal with it. As mentioned, these solutions should be used with caution.
Here are more resources on the subject: