When should one use a project reference opposed to a binary reference?

Question

My company has a common code library which consists of many class libary projects along with supporting test projects. Each class library project outputs a single binary, e.g. Company.Common.Serialization.dll. Since we own the compiled, tested binaries as well as the source code, there's debate as to whether our consuming applications should use binary or project references.

Some arguments in favor of project references:

• Project references would allow users to debug and view all solution code without the overhead of loading additional projects/solutions.
• Project references would assist in keeping up with common component changes committed to the source control system as changes would be easily identifiable without the active solution.

Some arguments in favor of binary references:

• Binary references would simplify solutions and make for faster solution loading times.
• Binary references would allow developers to focus on new code rather than potentially being distracted by code which is already baked and proven stable.
• Binary references would force us to appropriately dogfood our stuff as we would be using the common library just as those outside of our organization would be required to do.
• Since a binary reference can't be debugged (stepped into), one would be forced to replicate and fix issues by extending the existing test projects rather than testing and fixing within the context of the consuming application alone.
• Binary references will ensure that concurrent development on the class library project will have no impact on the consuming application as a stable version of the binary will be referenced rather than an influx version. It would be the decision of the project lead whether or not to incorporate a newer release of the component if necessary.

What is your policy/preference when it comes to using project or binary references?

Answer 1

It sounds to me as though you've covered all the major points. We've had a similar discussion at work recently and we're not quite decided yet.

However, one thing we've looked into is to reference the binary files, to gain all the advantages you note, but have the binaries built by a common build system where the source code is in a common location, accessible from all developer machines (at least if they're sitting on the network at work), so that any debugging can in fact dive into library code, if necessary.

However, on the same note, we've also tagged a lot of the base classes with appropriate attributes in order to make the debugger skip them completely, because any debugging you do in your own classes (at the level you're developing) would only be vastly outsized by code from the base libraries. This way when you hit the Step Into debugging shortcut key on a library class, you resurface into the next piece of code at your current level, instead of having to wade through tons of library code.

Basically, I definitely vote up (in SO terms) your comments about keeping proven library code out of sight for the normal developer.

Also, if I load the global solution file, that contains all the projects and basically, just everything, ReSharper 4 seems to have some kind of coronary problem, as Visual Studio practically comes to a stand-still.

Answer 2

In my opinion the greatest problem with using project references is that it does not provide consumers with a common baseline for their development. I am assuming that the libraries are changing. If that's the case, building them and ensuring that they are versioned will give you an easily reproducible environment.

Not doing this will mean that your code will mysteriously break when the referenced project changes. But only on some machines.

Answer 3

I think that if the project is not part of the solution, you shouldn't include it there... but that's just my opinion

I separate it by concept in short

Answer 4

when you don't want it in your solution, or have potential to split your solution, send all library output to a common, bin directory and reference there.

I have done this in order to allow developers to open a tight solution that only has the Domain, tests and Web projects. Our win services, and silverlight stuff, and web control libraries are in seperate solutions that include the projects you need when looking at those, but nant can build it all.

Answer 5

I believe your question is actually about when projects go together in the same solution; the reason being that projects in the same solution should have project references to each other, and projects in different solutions should have binary references to each other.

I tend to think solutions should contain projects that are developed closely together. Such as your API assemblies and your implementations of those APIs.

Closeness is relative, however. A designer for an application, by definition, is closely related to the app, however you wouldn't want to have the designer and the application within the same solution (if they are at all complex, that is). You'd probably want to develop the designer against a branch of the program that is merged at intervals further spaced apart than the normal daily integration.

Answer 6

I tend to treat common libraries like this as 3rd-party resources. This allows the library to have it's own build processes, QA testing, etc. When QA (or whomever) "blesses" a release of the library, it's copied to a central location available to all developers. It's then up to each project to decide which version of the library to consume by copying the binaries to a project folder and using binary references in the projects.

One thing that is important is to create debug symbol (pdb) files with each build of the library and make those available as well. The other option is to actually create a local symbol store on your network and have each developer add that symbol store to their VS configuration. This would allow you to debug through the code and still have the benefits of usinng binary references.

As for the benefits you mention for project references, I don't agree with your second point. To me, it's important that the consuming projects explicitly know which version of the common library they are consuming and for them to take a deliberate step to upgrade that version. This is the best way to guarantee that you don't accidentally pick up changes to the library that haven't been completed or tested.