Agile SCM Talk

This post is an op-ed on how VS handles references.

Over the past few years not only have I experienced frustration on this, but I find that many others have similar views.

Just recently I took a significant amount of time to study the issue: reading the MSDN documentation and various blog postings on the subject. My overall impression is:

1. The MSDN documentation does not address or even mention the operative assumptions and requirements that Microsoft used resulting in the current VS features around references. So beyond what should be "clicked" it adds little value, and is of no help to those who are frustrated with how VS works in this regard.
2. A great many SW engineers are frustrated by VS in this area because what they understand as obvious requirements are not being met.

So what explains this "disconnect?"

The Revelation
Let me say that my attempt at a revelation is just a guess based on what I have found to work and seemly explain why it works the way it does.

As a first step it is important to understand the assumptions Microsoft was acting on when deciding how references were to work:

• Separate build environments must be provided for: namely, local and integration builds
• Further, that the better approach is for these environments to impose minimal constraints on each other allowing them to optimize on different goals.

This means that the developers have freedom to setup references in a way most easy and natural: not having to think about where to reference an assembly. The developer installs whatever software needed on the local development environment and then adds the references from the .NET extension list (i.e. takes the default location selected by VS).

However, it is not the same story for an integration build environment. Here the build machines are as clean as possible. That way the same build machine can support the build of many different applications that use different versions of the same software where in some cases couldn't even be installed on the same machine at the same time. So here the assemblies are organized into directory locations and referenced using MSBuild parameters like /p:ReferencePath=[path(s)].

The "Microsoft Way"
Here's the way I think Microsoft expects SW engineering work to happen:

1. The Dev Lead specifies the 3rd party products/versions
2. Developers setup their local environment, install the 3rd party products, and add references as needed from the .Net Extensions listing of assemblies (i.e. take the default location)
3. Developer checks-in and an integration build takes place at some point
4. The build machine does not have the 3rd party products installed, but uses a separate reference location of the assemblies as specified in item #1 above
5. The integration build is setup to check the reference path where those assemblies are located on the build machine

Why So Much Frustration?
The problem is that develoeprs don't know about the assumptions and requirements behind VS reference management (I've never found it). Further, those most frustrated clearly have a different idea of how reference management should work.

For example, it seems both simple and more obvious for references to be static and explicit: as a developer I set up my reference to a specific relative location and it never changes. That location is setup to work both for the local and integration builds.

I agree that this is simple and obvious. However, I believe this is a weaker approach for any team that uses a source contol tool and performs integration builds separate from the local environment.

Summary
I believe that local and integration environments do have different priorities and requirements. The "Microsoft Way" allows for and supports the optimization of each environment.