What do you do in Visual Studio when you need to develop several related modules at the same time? Probably you’d create a solution to specify the references between related projects (or at the very least, make loading and debugging related projects easier). The interesting fact is while solution files are the main Visual Studio vehicle for building sets of projects, they have a proprietary format, not compliant with MSBuild.

So one might wonder – how is it then possible to build solutions from command line (msbuild solution1.sln)? How does the solution get built?

It turns out that in order to build the solution, MSBuild engine transforms it on-the-fly from proprietary format into MSBuild script, with the projects build order organized according to inter-project dependencies; the resulting script also reflects all configurations available in the solution. For every project in the solution, there are four targets in the temporary MSBuild script – Build, Rebuild, Clean and Publish, corresponding to four operations on the solution supported by Visual Studio.

In VS2005 (and MSBuild 2.0) one may modify somewhat obscure environment variable (msbuildemitsolution)  to make sure that the generated script is not deleted after the build and thus available for tweaking; in VS2008 (MSBuild 3.5) the generated script is not deleted from the file system for your convinience.

Now, why would one ever bother dealing with those generated scripts, and how MSBuild Sidekick can help you with that?

Two typical scenarios come to mind. First scenario would be investigating why solution build fails when building solution from command line (as opposed to Visual Studio IDE builds) – common problem in transition from development environment to build server. Working with script really helps in narrowing down problematic projects/references. Second scenario would be creating custom project builds – generated solution scripts may serve as a base scripts for that purpose.

MSBuild Sidekick lets you handle solution files as if they were in MSBuild format. You can open solution file in the Sidekick, and it will generate the MSBuild script for you and open it for viewing or editing and saving.

Moreover, viewing the dependencies between projects in solution file becomes a breeze with target visualization:

And of course, last but not least, you can actually build the solution script in MSBuild Sidekick. With those features, dealing with solutions becomes as routine task as working with any MSBuild project. 

One of the features that might strike one as “missing” in MSBuild Sidekick is a debugger. While we have this feature in our road-map for the next release and are working at it, we believe that using the logged data is the easiest way of diagnosing problems in build scripts.

The debugger might sound as the definite way to find an issue in MSBuild script, but probably by reviewing the sequence of the targets and tasks in most cases you will have a better chance of identifying the issue (especially if code includes external imports). And here is the reasoning why – browsing the log will give you immediate picture of the order the targets were executed in (though one might choose to use pre-build visualization for the same purpose), and what targets/tasks were executed. In addition to this information, if the target/task was skipped or failed during the build, the reason for that is readily available. And since this build “picture” is available for analysis together with the build script source, the user may easily navigate between log events and their source.

In MSBuild Sidekick v2 the logged data is available in several flavours – as console log, warnings/errors only log and detailed log. The console log is similar to MSBuild engine command-line output (including coloring of the text):

The detailed build log is a custom logger we have created, and its objective is to make all information available (as mentioned above) in a way that is easy to view and analyze. To illustrate this, let’s look at the detailed log output for typical C# project:

The log shows the collapsed list of targets executed in the order of execution; expanding collapsed target nodes displays all tasks executed in the target. For every target/task the following information is available:

• Element name

• Execution status (Succeeded, Failed or Skipped)

• Element execution time

• MSBuild project file the element is defined in

• Diagnostic message

Now, the most important of those are status and diagnostic columns. Let’s suppose that you have written custom script and your target is not executed during the run. Then, using the detailed log the target will be readily identified as skipped or failed, and the diagnostic message will contain the status specific reason. The message can be used to immediately identify the reason; for example, in the screenshot below PreBuildEvent target was skipped due to the condition evaluated to false, more specifically property $(PreBuildEvent) value being empty:

Double-clicking the target/task in the log will immediately jump to the element in the project tree, thus allowing the user to review the element definitions.

In order to increase the relevancy of data in the log, the output can be filtered by the status of targets/tasks (for example, showing only skipped tasks):

If the build script imports several files, the target source is readily available in File column. For stock C# project, one can see the targets defined in Common and C# specific imports:

Altogether, our belief is that the detailed log is a convenient tool to identify and fix issues in build scripts both during the ongoing development and maintenance thereafter; and it is fairly obvious how to use it for the purpose. While the detailed logger can be created as a stand-alone component (see Jonh Robbins’ blog for an example of one), together with the view of the project source and navigation abilities between log and the source, in MSBuild Sidekick detailed log information is sufficient to diagnose and solve most problems.