How exactly does the "Specific Version" property of an assembly reference work in Visual Studio?

Question

It's a compile-time property!

One of the most important things to know is that "Specific Version" is a property that takes effect at compile-time and not at runtime.

What is it all about?

When a project is built, the project's assembly references need to be resolved in order to find the physical assemblies that the build system should use. If the "Specific Version" check is performed (see section "When is "Specific Version" checked?"), it affects the outcome of the assembly resolution process:

• The build system locates a physical assembly that it can potentially use
• The build system compares the physical assembly's version to the assembly version stored in the .csproj file for the assembly reference
• If the two assembly versions are exactly the same, the resolution process succeeds and the physical assembly found is used for the build
• If the two assembly versions do not match, the physical assembly is discarded and the resolution process continues by locating the next potential assembly
• If no more potential physical assemblies can be located, the resolution process fails. This results in a compiler warning (warning MSB3245) that tells you that the reference could not be resolved.
• Interestingly enough, the build then continues! If the code has no actual references to the assembly, the build succeeds (with the previously mentioned warning). If the code has references, the build fails with an error that looks as if the code were using unknown types or namespaces. The only indication why the build really failed is the warning MSB3245.

Order in which assemblies are resolved

The order in which the assembly resolution process locates potential assemblies appears to be this:

1. The assembly referenced by the <HintPath> element in the .csproj file
2. The project output path
3. The GAC

Note that if several versions of the assembly exist in the GAC, the resolution process first attempts to resolve to the assembly with the highest version. This is important only if the "Specific Version" check is not made.

When is "Specific Version" checked?

Visual Studio bases its decision whether to perform the "Specific Version" check on two pieces of information found in the .csproj file:

• The presence or absence of the <SpecificVersion> element, and its value (if it is present)
• The presence or absence of version information in the assembly reference

This is how a typical assembly reference with version information looks like:

<Reference Include="Foo, Version=1.2.3.4, Culture=neutral, processorArchitecture=MSIL">
  <SpecificVersion>True</SpecificVersion>
  <HintPath>..\..\Bar\Foo.dll</HintPath>
</Reference>

And this is how the assembly reference looks like without version information:

<Reference Include="Foo">
[...]

The following table shows when the "Specific Version" check is performed, and when it is not.

                   |     Version information
                   |  Present       Not present
-------------------+------------------------------
<SpecificVersion>  |
- Present(=True)   |  1.Yes         2.Yes (check always fails)
- Present(=False)  |  3.No          4.No
- Not present      |  5.Yes         6.No

The surprising thing here is that no check is performed if both <SpecificVersion> and version information are absent (case 6). I would have expected the check to be performed and to always fail (same as case 2) because in my understanding the absence of <SpecificVersion> implies the default value "True". This may be a quirk of Visual Studio 2010 where I did my tests.

When you examine the properties of an assembly reference in the Visual Studio UI (select the reference and hit F4), the value you see for the "Specific Version" property tells you whether or not Visual Studio is going to perform the "Specific Version" check. In case 6 the UI will show "True", although the <SpecificVersion> element is not present in the .csproj file.

Side-effects on "Copy local"

If the "Copy Local" property is set to "True" but the assembly resolution process fails because of the "Specific Version" check, no assembly is copied.

Reference material

• What you need to know about referenced assemblies in VS2005 (blogs.msdn.com article)
• What's New in .NET 2.0 for Assemblies and Versioning? (codemag.com article which reproduces the above MSDN article, down to the wording, but contains a few screenshots and additional information about assembly versioning)

When you add a reference then Visual Studio records the [AssemblyVersion] of the assembly in the project file. This is important. If you, say, create a bug fix a year later then you want to make sure that you rebuild the project with the exact same version of the reference so it is a true drop-in. You'll get an error if the reference assembly has changed.

But that isn't always desirable. Some programmers let the assembly version automatically increment, generating a new version every single time they rebuild. Even though the public interface of the assembly never changed. Some configure their project by using Nuget to obtain libraries and let it automatically update the library when there's a new release available. They will like to set the Specific Version property to False to suppress the compile error.

Pretty important to understand the consequence, you do need to redeploy the entire build of the program to avoid accidents. Version mismatches at runtime crash the program and can only be suppressed with a <bindingRedirect> in the .config file which is risky.