References

I would have thought the following was Visual Studio 101, but I’ve seen senior people confused by this, so I will elaborate.

If you’ve ever expanded the References section of a .NET Visual Studio project then you’ve seen the list of DLLs that your project can access.  Most of the items in a typical list are .NET Framework DLLs.  These are the Release build of DLLs, and they live in the GAC, or maybe somewhere in some Program Files directory if they are little extra packages, like the Silverlight Map Control.  Changing your project from Debug mode to Release mode doesn’t change the DLL link.  There’s only 1 available, the Release mode DLL from Microsoft or whoever.

Now, if you have a project in your solution that another project in your solution uses, (e.g. the business layer that your UI layer calls into) then there are at least 2 ways to add a reference.  One is a bad idea, and one is a good idea.  One way, the bad way, is the same as the references to framework DLLs – by referencing a particular DLL on disk.  The other way, the right way, is a project reference, which makes Visual Studio aware that project x depends on project y in the same solution.

If when adding a reference to another project in your solution you are using this tab then you’re doing it wrong:

See how you’re specifically selecting the debug version of a DLL in your project?  What will happen when you switch to Release mode and build your application?  It will include the debug version of this DLL, if it’s available on disk.  Not good.

The right way to set up a reference to another project in your solution is to use the next tab to the left, the Projects tab:

By using the Projects tab you get the following behaviour – when you switch your solution between Debug and Release build modes each project will use the corresponding build mode DLL from referenced projects.  That is, in Debug mode all Debug builds of referenced projects will be built and loaded.  In Release mode, all Release versions will be built and loaded.

There are a couple of ways of detecting references that were added using the Browse tab rather than the the Projects tab.  One way is to open .csproj files with a text editor and look for the following, which indicates a project reference:

<ProjectReference Include="..\DrinkLocatorMvvm.Data\DrinkLocatorMvvm.Data.csproj">

A non-project reference to a specific file will look like this:

<Reference Include="HtmlAgilityPack, Version=1.4.0.0, Culture=neutral, PublicKeyToken=bd319b19eaf3b43a, processorArchitecture=MSIL">

followed by a HintPath entry, which helps Visual Studio find the DLL on disk:

<HintPath>DLLs\HtmlAgilityPack.dll</HintPath>

If you don’t like looking at .csproj files then a dead give away is the behaviour of reference paths when you switch from Debug to Release.  Put your solution in a particular mode, say Debug.  Right click on the reference in one project to a DLL that you know is in another project in your solution, select Properties and make a note of the Path.  For example:

C:\Users\jmclachl\Documents\Visual Studio 2010\Projects\DrinkLocatorMvvm\Lcbo.Model\bin\Debug\Lcbo.Model.dll

Now switch your solution into the other mode, say Release, and check the Path property of the same reference.  If it has changed to the corresponding DLL version, then you’re looking at a properly set up project reference.  For example:

C:\Users\jmclachl\Documents\Visual Studio 2010\Projects\DrinkLocatorMvvm\Lcbo.Model\obj\Release\Lcbo.Model.dll

If it doesn’t change then the reference was added as a file reference with the Browse tab.  Remove the reference and re-add it with the Projects tab.

Using file references, added with the Browse tab, may build fine in one mode, e.g. Debug.  But if you, or someone else who has checked out the project from source control, perform a Clean before a Release build the compile will fail.  That’s because the debug version of some project doesn’t exist on disk.  One very bad solution for this is to perform a Debug build before a Release build, but that will still add a debug version of a project DLL to your release build.  How slow do you want your app to run in production with debug code?  And do you really want to suggest performing a Debug build before a Release build to the folks maintaining your build server?  They should laugh at you.  If they don’t then your company has at least 2 problems – you and the build server person to whom you’re talking.

Understand the difference between a project reference and a file reference and you won’t end up with broken builds or the wrong build version of DLLs in your bin directories.