Random Musings of Jeremy Jameson : Visual Studio

Bug Deploying SQL Server Database Using VSDBCMD.EXE

Jeremy Jameson — Wed, 09 Dec 2009 14:32:00 GMT

Yesterday we encountered a bug while trying to deploy a new SQL Server database from a Visual Studio database project using the VSDBCMD.EXE utility, following the prescriptive guidance on MSDN:

How to: Prepare a Database for Deployment From a Command Prompt by Using VSDBCMD

http://msdn.microsoft.com/en-us/library/dd193258.aspx

According to this MSDN article, all you need to do is copy some files to the server running Microsoft SQL Server, and then run the VSDBCMD.EXE utility (specifying your .dbschema or .deploymanifest file).

Unfortunately, when we attempted to deploy our database to our Test environment, we encountered a NullReferenceException:

Object reference not set to an instance of an object.

Fortunately, it didn't take long to find Gert's recommendation to add the following registry key:

reg add HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\9.0

The error occurred since Visual Studio has never been installed on the SQL Server in TEST (unlike our local development VMs).

It certainly would be nice if the above MSDN article were updated to note the bug and associated workaround.

Note

As pointed out in a comment by Ramkumar Perumal, Microsoft.SqlServer.BatchParser.dll does not exist in any of the specified folders. This should also be reflected in the MSDN article.

You will also find instructions to add the registry key -- as well as an explanation for why you more than likely already have Microsoft.SqlServer.BatchParser.dll installed on your SQL Server -- in the following blog post:

Deploying your Database Project without VSTSDB installed. 2009-02-21

http://blogs.msdn.com/bahill/archive/2009/02/21/deploying-your-database-project-without-vstsdb-installed.aspx

The "Copy Local" Bug in Visual Studio

Jeremy Jameson — Wed, 18 Nov 2009 12:21:00 GMT

If you've ever worked with me on a Microsoft Office SharePoint Server (MOSS) 2007 project -- or if you've read my Sample Walkthrough of the DR.DADA Approach to SharePoint -- then you've probably seen the following comment:

Note: Referenced assemblies must be specified with a path corresponding to the build configuration. If the path is not specified to the referenced assembly, then the build works fine as long as the referenced assembly is not in the GAC.

However, when the referenced assembly is in the GAC (i.e. after a deployment) then MakeCAB will not be able to find the referenced assembly (since it is no longer copied to the current project's bin\Debug or bin\Release folder).

It turns out that I was using a rather elaborate workaround for a problem that is actually much easier to solve.

To workaround the "Copy Local" bug and force a referenced assembly to always be copied to the output folder (regardless of whether the referenced assembly is in the GAC):

In the Solution Explorer window in Visual Studio, expand the References folder for the project and then select the referenced assembly.
In the Properties window, change the value of Copy Local to False, and then change it back to True.

Following these two simple steps explicitly adds <Private>True</Private> to the project file, as shown in the following example:

    <ProjectReference Include="..\CoreServices\CoreServices.csproj">
      <Project>{01C58D27-9818-45D6-A0B6-8EF765CA9397}</Project>
      <Name>CoreServices %28CoreServices\CoreServices%29</Name>
      <Private>True</Private>
    </ProjectReference>

When you add a referenced assembly in Visual Studio using a project reference, Copy Local defaults to True, but Visual Studio doesn't explicitly state this in the MSBuild project file. Toggling the value of Copy Local forces this element to be added to the project file and consequently you no longer need any hacks to reference the assembly in its original output folder.

At this point, you might be wondering why do I bring this up after all this time? After all, hasn't the hack I came up with for building SharePoint Web Solution Packages (WSPs) been working for several years? Well, yes, in most cases it works just fine.

However, there's one fundamental problem that I only recently discovered back in early October: you can't use Team Foundation Build to build the WSP when specifying relative paths to assemblies in the DDF file.

I'll cover this in my next post.

Recommendations for Code Analysis

Jeremy Jameson — Sat, 31 Oct 2009 13:44:00 GMT

In my previous post, I briefly mentioned the Code Analysis feature of Visual Studio in the context of using check-in policies with Team Foundation Server (TFS). However, there's a lot more to talk about with regards to using Code Analysis.

If you are ever find yourself "starting from a clean slate" on a software development project, I hope you take advantage of the opportunity to not only enable Code Analysis, but also to treat all Code Analysis warnings as errors. That's right, go ahead and check all of those boxes (for both Debug and Release configurations, of course) so that whenever potential issues are reported by Code Analysis, it stops developers dead in their tracks and considers the build to be broken.

While you're at it, go ahead and select the All option in the Treat warnings as errors section on the Build tab (something I definitely recommend as a best practice). Again, be sure to do this for all build configurations.

Yes, this is going to be really painful for some developers.

For example, you can say goodbye to using the overload of string.Format() that doesn't specify a CultureInfo:

            string foo = "here";

            string logMessage = string.Format(
                "Imagine something interesting {0}.",
                foo);

Attempting this will now result in a broken build:

Error 2 CA1305 : Microsoft.Globalization : Because the behavior of 'string.Format(string, object)' could vary based on the current user's locale settings, replace this call in 'Program.Main(string[])' with a call to 'string.Format(IFormatProvider, string, params object[])'. If the result of 'string.Format(IFormatProvider, string, params object[])' will be displayed to the user, specify 'CultureInfo.CurrentCulture' as the 'IFormatProvider' parameter. Otherwise, if the result will be stored and accessed by software, such as when it is persisted to disk or to a database, specify 'CultureInfo.InvariantCulture'.

To avoid the CA1305 error, you will need to use something like this instead:

            string foo = "here";

            string logMessage = string.Format(
                CultureInfo.InvariantCulture,
                "Imagine something interesting {0}.",
                foo);

You will also need to enable signing of all assemblies with a strong name key, and also specify various assembly level attributes (e.g. [assembly: CLSCompliant(true)]). However, if you follow the steps I've provided in a previous post, this should only take you at most 1-2 minutes.

Like I said before, this will probably cause some heartburn in the beginning, but trust me, developers will quickly get used to it and the code they write will be much better as a result.

Now what about the other 99% of the time when you aren't starting from a clean slate, but instead are dealing with a substantial code base that causes the Code Analysis feature in Visual Studio to "light up like a Christmas tree" when you turn it on?

Well, as with all software bugs, it all comes down to triage. You obviously cannot simply halt all feature development in order to resolve code analysis issues. Instead, you should go for the "low hanging fruit" (meaning the issues that occur frequently but can be resolved with relatively little effort or risk of changing). You should also try to enable the Code Analysis rules that are most important, such as potential security issues.

The following post provides some great information about which Code Analysis warnings to focus your attention on first:

What rules do Microsoft have turned on internally? 2007-08-09.

http://blogs.msdn.com/fxcop/archive/2007/08/09/what-rules-do-microsoft-have-turned-on-internally.aspx

This article is obviously a little dated, but still very relevant over two years later.

Note that you will undoubtedly need to suppress some specific Code Analysis warnings from time to time, and therefore you'll have to choose how to suppress the warnings (whether inline within the source, or in a GlobalSuppressions.cs file). However, I hope you'll choose to fix the underlying issue that causes the Code Analysis warning (whenever practical) instead of simply suppressing a bunch of warnings.

So, in conclusion, think of the Code Analysis feature in Visual Studio as a way of choosing a more strict compiler. For example, back in the days when I used to program in C on Unix, the compiler wouldn't complain when I wrote something like this (even though this is obviously very wrong):

I was relieved when I switched to C++ and these kinds of bugs were a thing of the past. [Note that I never switch my coding style to use something like "1 == i" in order to avoid these errors.]

Fortunately, in C# you don't have a choice about whether or not this compiles (it doesn't).

I like to think of enabling all of the Code Analysis rules in a similar fashion. In other words, I want the compiler to tell me whenever I am doing something potentially wrong, because then I can spend just a little bit of time fixing my code to do it right. By forcing the Code Analysis warnings as errors, I don't have a choice -- meaning I have to fix them before check-in.

Essential Add-Ins for Team Foundation Server

Jeremy Jameson — Sun, 25 Oct 2009 15:32:00 GMT

In a previous post, I mentioned how I use SourceGear's DiffMerge instead of the out-of-the-box tool that comes with Team Foundation Server (which is also called DiffMerge). If you haven't at least evaluated the SourceGear alternative, I definitely advise you to take a look.

The other "add-in" for TFS that I consider to be essential is the TFS Quick Search Plugin.

If you have Web access to your TFS instance (via Team System Web Access), then quickly locating work items by keywords is actually pretty easy. However if you either don't have access to Team System Web Access or you would simply rather prefer to search for a work item without leaving Visual Studio, then the TFS Quick Search Plugin is definitely the way to go.

Note that it doesn't search all of the fields in all work items, but rather searches the work items currently displayed within Visual Studio. However, if you know a keyword that appears in the title of a work item, this can make it very easy to locate the desired work item.

I tend to use the TFS Quick Search Plugin a lot for the scenario where I am trying to find a duplicate bug and I remember a couple of keywords in the title of the previous bug. It is certainly much faster than scrolling through a few hundred work items in order to find something, or trying to build a query on-the-fly in order to locate a work item.

I am really interested to see the improvements in Visual Studio 2010 and Team Foundation Server 2010, but honestly it's probably going to be a while before I'm able to use that in my day-to-day work. Nevertheless, I hope this kind of work item "quick search" comes out-of-the-box in the next release (as well as a better DiffMerge tool). [I did do some hands-on labs back in February that cover the new branching visualization features in TFS 2010, and I have to say that I absolutely love what I've seen so far.]

Formatting Code for My Blog

Jeremy Jameson — Fri, 09 Oct 2009 17:46:00 GMT

It occurred to me this morning that while I previously shared some details on how I manage my MSDN blog, I've never shared my method for formatting code for the Web.

Actually, calling it "my method" is definitely a bit of a stretch. I certainly didn't come up with the approach but rather refined someone else's approach (and code) to suit my needs. The original credit goes to David Anson.

Prior to adopting David's approach, I previously copied code from Visual Studio, pasted it into Microsoft Word, then copied it again in Microsoft Word, and finally pasted into Expression Web. While this achieved the desired end result -- meaning, formatted code with color syntax highlighting -- it definitely was a little kludgey. First, the four-step process -- while not excessively tedious -- was definitely less than desirable, because it often meant I had to fire up Word for the sole purpose of formatting code (note that copy/paste from Visual Studio into Expression Web does not preserve the formatting). Second -- and more importantly -- the resulting HTML markup was just "crap" (sorry, I can't think of a more eloquent way to put that right now).

When I started looking at approaches for improving the formatting of code for my blog, I found that there were numerous "solutions" out there. However, I knew what I really wanted was something that would produce a minimal amount of HTML markup (or at least a lot less HTML than Microsoft Word) and, preferably, something that generated semantic markup as well -- or at least reasonably semantic markup.

What I mean by semantic markup is that code should be wrapped in a <code> tag -- as well as a <pre> tag (in order to correctly display line breaks, indenting, etc.). To understand what I mean by semantic markup for code, consider the following example:

using System;

public class Class1
{
    public Class1()
    {
        string foo = "foo";
    }
}

In HTML markup, this is expressed as:

<div class='codeBlock'><pre><code><span style='color:#0000ff'>using</span> System;

<span style='color:#0000ff'>public</span> <span style='color:#0000ff'>class</span> <span style='color:#2b91af'>Class1
</span>{
    <span style='color:#0000ff'>public</span> Class1()
    {
        <span style='color:#0000ff'>string</span> foo = <span style='color:#a31515'>"foo"</span>;
    }
}</code></pre></div>

The <div class='codeBlock'> element is used to constrain lengthy code blocks (i.e. show a vertical scrollbar when necessary) and also format code with a background color and border.

Note that in the stricted sense, this isn't 100% semantic markup because the <span> tags are used to apply presentational styles, namely the various font colors. Truly semantic markup for code would specify something more like this:

<div class='codeBlock'><pre><code><span class='keyword'>using</span> System;

<span class='keyword'>public</span> <span class='keyword'>class</span> <span class="userType">Class1
</span>{
    <span class='keyword'>public</span> Class1()
    {
        <span class='keyword'>string</span> foo = <span class='string'>"foo"</span>;
    }
}
</code></pre></div>

CSS rules could then be used to achieve the color syntax highlighting:

code .keyword
{
    color: #0000ff;
}
code .string
{
    color: #a31515;
}
code .userType
{
    color: #2b91af;
}

Anyway, getting back to the real topic for this post...

I really liked David's approach since a) it was simple (meaning I didn't need to spend much time understanding his code sample), and b) it leveraged Visual Studio to handle the bulk of the formatting work.

However, there were a couple of "fixes" that I found I needed:

David's original code sample produced errors when I used it from SQL Server Management Studio 2005 (note that SQL Server Management Studio uses the Visual Studio "shell", so one should expect this to work)
David's code sample only inserted a <pre> tag (and not the corresponding <code> and <div class="codeBlock"> tags that I also wanted)

I also wanted to eliminate extraneous <span> tags for the default color (i.e. black).

Note that -- at least to this point -- I haven't made any attempt to generate 100% semantic markup (by converting the style attributes to corresponding CSS class names), because I think it would be somewhat brittle (i.e. dependent on the default color options in Visual Studio) and, honestly, not worth the effort.

Here's the updated code that I now use for my Rtf2Html.exe utility:

// Original source:
// http://blogs.msdn.com/delay/archive/2008/03/13/
// blogging-code-samples-should-be-easy-free-convertclipboardrtftohtmltext-tool-and-source-code.aspx

using System;
using System.Collections.Generic;
using System.Drawing;
using System.Text;
using System.Windows.Forms;

// Convert Visual Studio 2008 RTF clipboard format into HTML by replacing the
// clipboard contents with its HTML representation in text format suitable for
// pasting into a web page or blog.
// USE: Copy to clipboard in VS, run this app (no UI), paste converted text
// NOTE: This is NOT a general-purpose RTF-to-HTML converter! It works well
// enough on the simple input I've tried, but may break for other input.
// TODO: Convert into a real application with a notify icon and hotkey.
namespace ConvertClipboardRtfToHtmlText
{
    static class ConvertClipboardRtfToHtmlText
    {
        private const string colorTbl = "\\colortbl;";
        private const string colorFieldTag = "cf";
        private const string tabExpansion = "    ";

        [System.Diagnostics.CodeAnalysis.SuppressMessage(
            "Microsoft.Maintainability",
            "CA1502:AvoidExcessiveComplexity")]
        [STAThread]
        static void Main()
        {
            if (Clipboard.ContainsText(TextDataFormat.Rtf))
            {
                // Create color table, populate with default color
                List<Color> colors = new List<Color>();
                Color defaultColor = Color.FromArgb(0, 0, 0);
                colors.Add(defaultColor);

                bool insideSpan = false;

                // Get RTF
                string rtf = Clipboard.GetText(TextDataFormat.Rtf);

                // Parse color table
                int i = rtf.IndexOf(
                    colorTbl,
                    StringComparison.OrdinalIgnoreCase);

                if (-1 != i)
                {
                    i += colorTbl.Length;

                    // When copying from Visual Studio, we expect
                    // "\\colortbl;\r\n". However when copying from SQL Server
                    // Management Studio, we expect just "\\colortbl;".
                    SkipOptionalText(rtf, ref i, "\r\n");

                    while ((i < rtf.Length) && ('}' != rtf[i]))
                    {
                        // Add color to color table
                        SkipOptionalText(rtf, ref i, "\r\n");
                        SkipExpectedText(rtf, ref i, "\\red");
                        byte red = (byte)ParseNumericField(rtf, ref i);
                        SkipExpectedText(rtf, ref i, "\\green");
                        byte green = (byte)ParseNumericField(rtf, ref i);
                        SkipExpectedText(rtf, ref i, "\\blue");
                        byte blue = (byte)ParseNumericField(rtf, ref i);
                        colors.Add(Color.FromArgb(red, green, blue));
                        SkipOptionalText(rtf, ref i, "\r\n");
                        SkipExpectedText(rtf, ref i, ";");
                    }
                }
                else
                {
                    throw new NotSupportedException(
                        "Missing/unknown colorTbl.");
                }

                // Find start of text and parse
                i = rtf.IndexOf("\\fs", StringComparison.OrdinalIgnoreCase);
                if (-1 != i)
                {
                    // Skip font size tag
                    while ((i < rtf.Length) && (' ' != rtf[i]))
                    {
                        i++;
                    }
                    i++;

                    // Begin building HTML text
                    StringBuilder sb = new StringBuilder();
                    sb.Append("<div class='codeBlock'><pre><code>");
                    while (i < rtf.Length)
                    {
                        if ('\\' == rtf[i])
                        {
                            // Parse escape code
                            i++;
                            if ((i < rtf.Length) &&
                                (('{' == rtf[i])
                                    || ('}' == rtf[i])
                                    || ('\\' == rtf[i])))
                            {
                                // Escaped '{' or '}' or '\'
                                sb.Append(rtf[i]);
                            }
                            else
                            {
                                // Parse tag
                                int tagEnd = rtf.IndexOf(' ', i);
                                if (-1 != tagEnd)
                                {
                                    if (rtf.Substring(
                                        i,
                                        tagEnd - i).StartsWith(
                                            colorFieldTag,
                                            StringComparison.OrdinalIgnoreCase))
                                    {
                                        // Parse color field tag
                                        i += colorFieldTag.Length;
                                        int colorIndex = ParseNumericField(rtf, ref i);
                                        if ((colorIndex < 0)
                                            || (colors.Count <= colorIndex))
                                        {
                                            throw new NotSupportedException(
                                                "Bad color index.");
                                        }

                                        if (insideSpan == true)
                                        {
                                            sb.Append("</span>");
                                            insideSpan = false;
                                        }

                                        // Change to new color
                                        if (colors[colorIndex] != defaultColor)
                                        {
                                            sb.AppendFormat(
                                                "<span style='color:#{0:x2}{1:x2}{2:x2}'>",
                                                colors[colorIndex].R, colors[colorIndex].G,
                                                colors[colorIndex].B);

                                            insideSpan = true;
                                        }
                                    }
                                    else if ("tab" ==
                                        rtf.Substring(i, tagEnd - i))
                                    {
                                        sb.Append(tabExpansion);
                                    }

                                    // Skip tag
                                    i = tagEnd;
                                }
                                else
                                {
                                    throw new NotSupportedException(
                                        "Malformed tag.");
                                }
                            }
                        }
                        else if ('}' == rtf[i])
                        {
                            // Terminal curly; done
                            break;
                        }
                        else
                        {
                            // Normal character; HTML-escape '<', '>', and '&'
                            switch (rtf[i])
                            {
                                case '<':
                                    sb.Append("&lt;");
                                    break;
                                case '>':
                                    sb.Append("&gt;");
                                    break;
                                case '&':
                                    sb.Append("&amp;");
                                    break;
                                default:
                                    sb.Append(rtf[i]);
                                    break;
                            }
                        }
                        i++;
                    }

                    // Finish building HTML text
                    if (insideSpan == true)
                    {
                        sb.Append("</span>");
                        insideSpan = false;
                    }

                    sb.Append("</code></pre></div>");

                    // Update the clipboard text
                    Clipboard.SetText(sb.ToString());
                }
                else
                {
                    throw new NotSupportedException(
                        "Missing text section.");
                }
            }
        }

        // Skip the specified text
        private static void SkipExpectedText(string s, ref int i, string text)
        {
            foreach (char c in text)
            {
                if ((s.Length <= i) || (c != s[i]))
                {
                    throw new NotSupportedException("Expected text missing.");
                }
                i++;
            }
        }

        private static void SkipOptionalText(
            string s,
            ref int i,
            string text)
        {
            string substring = s.Substring(i, text.Length);

            if (substring == text)
            {
                i += text.Length;
            }
        }

        // Parse a numeric field
        private static int ParseNumericField(string s, ref int i)
        {
            int value = 0;
            while ((i < s.Length) && char.IsDigit(s[i]))
            {
                value *= 10;
                value += s[i] - '0';
                i++;
            }
            return value;
        }
    }
}

I suppose I could have kept the ConvertClipboardRtfToHtmlText moniker that David originally had, but for some reason I decided to abbreviate it. In hindsight, I'm really not sure why I didn't keep the name, but oh well...

Whenever I need a code sample in a blog post, I simply copy the code in Visual Studio, double-click Rtf2Html.exe in my Toolbox, and then paste into Expression Web. It's still a three-step process, but not one that takes more than three or four seconds, and more importantly, it now produces much better HTML markup than the hack I used to use with Microsoft Word.

Comparing Source Code Branches

Jeremy Jameson — Wed, 16 Sep 2009 15:54:00 GMT

During the more than three years I spent helping Agilent Technologies migrate their Internet site from their legacy, proprietary platform to Microsoft Office SharePoint Server (MOSS) 2007, we unfortunately never used Team Foundation Server (TFS). Instead, we used Visual SourceSafe (VSS) in combination with a "Work Items" list in SharePoint that I've described in previous posts.

While I certainly prefer TFS over VSS, sometimes you simply have to concede that you can't have everything you would like on a customer project and move on to actually getting the work done.

However, just because we used VSS doesn't mean we didn't follow good Software Configuration Management (SCM) principles. For example, as I've described in the past, I insist on using branching right from the start. Thus when I setup the Visual Studio solution for the Agilent project, I created a Main branch and subsequently created branches for the various releases (e.g. v1.0, v2.0, and v3.0).

The particular branch that a developer uses would thus depend on whether the changes are for the next major release or a QFE (hotfix) for the version running in Production. For example, after deploying the Technical Support site (i.e. v2.0), we began working on the "General Site" (i.e. v3.0). [Note that in Agilent's terminology, the "General Site" essentially refers to everything outside of Technical Support, the Literature Library, and the Online Store (i.e. the "Buy" tab).]

However, since we didn't create the v3.0 branch until shortly before the v3.0 release, all v3 ("General Site") development was initially done on the Main branch -- just like v2 (Tech Support) development was initially done in Main prior to creating the v2.0 branch.

This branching strategy works really well, regardless of which particular SCM system you actually use. The key thing to remember is that all of the changes should eventually make it into the Main branch (since that branch will eventually be used to create another branch for the next major release).

The problem with VSS is that while it certainly supports branching, the merging features, um...well, let's just say that they leave a lot to be desired ;-)

Personally speaking, I've never felt comfortable using the out-of-the-box merging features in VSS, and instead always insisted on merging the changes from one branch to another manually. TFS is obviously years ahead of VSS in terms of branching and merging, but as I said before, sometimes you simply have to deal with what you've got.

Fortunately, long before the Agilent project, I had previously created my own process that takes a great deal of the "pain" out of manually merging source code. Here is what I came up with.

In my Toolbox, I have two simple scripts: DiffBranches.cmd and CopyBranch.cmd.

Here are the contents of DiffBranches.cmd:

@echo off

setlocal

REM set DIFFTOOL=Windiff.exe
set DIFFTOOL=C:\NotBackedUp\Public\Toolbox\DiffMerge\DiffMerge.exe

set BRANCH1=%1
set BRANCH2=%2

if ("%BRANCH1%") == ("") set BRANCH1=Main

if ("%BRANCH2%") == ("") set BRANCH2=v3.0

call CopyBranch.cmd "%BRANCH1%" "%BRANCH1%_tmp"

call CopyBranch.cmd "%BRANCH2%" "%BRANCH2%_tmp"

"%DIFFTOOL%" "%BRANCH1%_tmp" "%BRANCH2%_tmp"

As you can see, there's not much to it. I simply make temporary copies of the two branches (i.e. by copying the branch folder into a new folder appended with "_tmp") and then use my "Diff Tool" to compare the two folders. Originally, I used WinDiff, but once I discovered DiffMerge, I quickly switched to using it exclusively for all of my "diff'ing" activities.

The real "magic" lies in CopyBranch.cmd:

@echo off

setlocal

set BRANCH1=%1
set BRANCH2=%2

if ("%BRANCH1%") == ("") set BRANCH1=Main

if ("%BRANCH2%") == ("") set BRANCH2="%BRANCH1%_tmp"

robocopy "%BRANCH1%" "%BRANCH2%" /E /MIR /XD bin obj TestResults /XF *.scc *.suo *.user *.vspscc

Note that I put the word magic in quotes because it's really not magic at all. When copying a source code branch, I simply use robocopy.exe and specify the following options:

robocoby.exe command-line options used in CopyBranch.cmd
Command-Line Option	Comments
/E	Copy subdirectories, including empty ones
/MIR	Mirror the directory tree, thus ensuring that when I subsequently run CopyBranch.cmd, any deleted files from the original branch are removed from the "temporary" copy of the branch)
/XD bin obj TestResults	Exclude directories matching the given names/paths, thus skipping the compiled output (i.e. bin and obj) as well as the test results generated by running unit tests from within Visual Studio
/XF .scc .suo .user .vspscc	Exclude files matching the given names/paths/wildcards, thus skipping source code control files (.scc and .vspscc), and Visual Studio solution/project user-specific options (i.e. .suo and .user)

For example, let's suppose that I've checked in some changes to the v3.0 branch that need to be propagated to the Main branch. I would open a command prompt and run the following:

C:\NotBackedUp\Agilent>DiffBranches.cmd v3.0 Main

After the two branches are copied to their respective temporary folders, DiffMerge.exe is launched to compare the two branches. Since I exclude many of the directories and files that are expected to differ between the two branches, I can quickly view only the differences that I am interested in. I can even use DiffMerge.exe to apply the changes interactively (checking out the files to be updated beforehand as necessary). This greatly reduces the effort involved in manually merging changes from one branch into another.

Note that it takes a little bit of time to copy a branch the first time, but this is lightning fast on subsequent runs. Hence why I don't delete the "_tmp" folders after comparing two branches.

I occasionally use this process even on projects where we've used Team Foundation Server. For example, I sometimes create a new workspace in TFS to represent a "temporary branch" where I want to experiment with some substantial changes to the source code (while I still have pending changes in my main workspace, that I may have shelved but don't want to check-in just yet). Using a little robocopy.exe and DiffMerge.exe, I can more easily compare two branches or workspaces.

Best Practices for .NET Assembly Versioning

Jeremy Jameson — Fri, 03 Apr 2009 15:59:00 GMT

Whenever a new .NET assembly project is created in Visual Studio, a file named AssemblyInfo is created that contains attributes used to define the version of the assembly during compilation.

Using assembly versions effectively enables various team members to identify deployed assemblies and helps troubleshoot problems that may occur in a particular environment (e.g. Development, Test, or Production).

Assembly versions consist of four different parts ({Major Version}.{Minor Version}.{Build Number}.{Revision}):

Major Version: Manually incremented for major releases, such as adding many new features to the solution.
Minor Version: Manually incremented for minor releases, such as introducing small changes to existing features.
Build Number: Typically incremented automatically as part of every build performed on the Build Server. This allows each build to be tracked and tested.
Revision: Incremented for QFEs (a.k.a. “hotfixes” or patches) to builds released into the Production environment (PROD). This is set to zero for the initial release of any major/minor version of the solution.

As a general guideline, it is best to use the same version number for all assemblies compiled as part of the solution. This is easily accomplished using linked files in Visual Studio solutions.

When building the solution, there are two version numbers that need to be considered: the file version number and the .NET assembly version number.

File Version

The AssemblyFileVersionAttribute should be incremented automatically as part of the build process. At the beginning of the build process, before the build label is applied in the source control system, the Build Number portion of the file version is incremented (or the Revision, if building a QFE).

The file version should be isolated in its own file (e.g. AssemblyVersionInfo.cs) to easily automate the process of incrementing it with every build. This file can then be "linked into" each project in the solution, thus ensuring all of the various assemblies in the solution share the same file version for a particular build.

Assembly Version

The AssemblyVersionAttribute is the version that .NET uses when linking assemblies. This number is not incremented with every build to avoid having to specify binding redirects.

Assembly versions are incremented manually when branching the code for a release (to the PROD environment).

The assembly version number should be specified in a "shared assembly info" file (e.g. SharedAssemblyInfo.cs), thus ensuring that all of the various assemblies in the solution have the same assembly version.

By default, the Product version shown in the file properties window is the same as the value specified for AssemblyFileVersionAttribute. Setting AssemblyInformationalVersionAttribute to be the same as AssemblyVersionAttribute ensures the Product version shown in the file properties window matches the Version displayed in the GAC shell extension.

Shared Assembly Info in Visual Studio Projects

Jeremy Jameson — Fri, 03 Apr 2009 15:17:00 GMT

Yesterday I introduced the concept of linked files in Visual Studio solutions with a follow-up on my recommendation for configuring a custom dictionary to eliminate CA1704 code analysis warnings.

Another practical application of linked files is what I refer to as "shared assembly info" -- referring to the assembly attributes that should be the same across all projects in the solution, such as AssemblyCompanyAttribute.

To implement this, create a file in the solution folder named SharedAssemblyInfo.cs and then add a link in each project to SharedAssemblyInfo.cs. You can also move the linked SharedAssemblyInfo.cs into the Properties folder so that it sits side-by-side with the AssemblyInfo.cs that is specific to each project in the solution, as shown below.

Figure 1: Linked SharedAssemblyInfo.cs files in a Visual Studio solution

See full-sized image.

I recommend placing the following assembly attributes in SharedAssemblyInfo.cs (and, of course, removing them as necessary from the project-specific AssemblyInfo.cs files):

AssemblyCompany
AssemblyProduct
AssemblyCopyright
AssemblyTrademark
AssemblyConfiguration
AssemblyDescription
CLSCompliant
ComVisible
AssemblyVersion
AssemblyInformationalVersion

The AssemblyInfo.cs files typically have the following assembly attributes:

AssemblyTitle
AssemblyCulture
Guid

Here is a sample SharedAssemblyInfo.cs file:

using System;
using System.Reflection;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

// General Information about an assembly is controlled through the following 
// set of attributes. Change these attribute values to modify the information
// associated with an assembly.
[assembly: AssemblyCompany("Fabrikam Technologies")]
[assembly: AssemblyProduct("Demo")]
[assembly: AssemblyCopyright("Copyright ? Fabrikam Technologies 2009")]
[assembly: AssemblyTrademark("")]

// Make it easy to distinguish Debug and Release (i.e. Retail) builds;
// for example, through the file properties window.
#if DEBUG
[assembly: AssemblyConfiguration("Debug")]
[assembly: AssemblyDescription("Flavor=Debug")] // a.k.a. "Comments"
#else
[assembly: AssemblyConfiguration("Retail")]
[assembly: AssemblyDescription("Flavor=Retail")] // a.k.a. "Comments"
#endif

[assembly: CLSCompliant(true)]

// Setting ComVisible to false makes the types in this assembly not visible 
// to COM components.  If you need to access a type in this assembly from 
// COM, set the ComVisible attribute to true on that type.
[assembly: ComVisible(false)]

// Note that the assembly version does not get incremented for every build
// to avoid problems with assembly binding (or requiring a policy or
// <bindingRedirect> in the config file).
//
// The AssemblyFileVersionAttribute is incremented with every build in order
// to distinguish one build from another. AssemblyFileVersion is specified
// in AssemblyVersionInfo.cs so that it can be easily incremented by the
// automated build process.
[assembly: AssemblyVersion("1.0.0.0")]

// By default, the "Product version" shown in the file properties window is
// the same as the value specified for AssemblyFileVersionAttribute.
// Set AssemblyInformationalVersionAttribute to be the same as
// AssemblyVersionAttribute so that the "Product version" in the file
// properties window matches the version displayed in the GAC shell extension.
[assembly: AssemblyInformationalVersion("1.0.0.0")] // a.k.a. "Product version"

Note how the AssemblyConfigurationAttribute and AssemblyDescriptionAttribute are set based on conditional compilation constants (in order to easily distinguish Debug and Release builds).

Here is a sample AssemblyInfo.cs file:

using System.Reflection;
using System.Runtime.InteropServices;

// Note: Shared assembly information is specified in SharedAssemblyInfo.cs

// General Information about an assembly is controlled through the following 
// set of attributes. Change these attribute values to modify the information
// associated with an assembly.
[assembly: AssemblyTitle("Fabrikam.Demo.CoreServices")]
[assembly: AssemblyCulture("")]

// The following GUID is for the ID of the typelib if this project is exposed to COM
[assembly: Guid("88d50bdd-34bc-414a-98d6-6fefe701d41b")]

In my next post, I'll discuss assembly versioning in more detail.

CA1704 Code Analysis Warning and Using Custom Dictionaries in Visual Studio

Jeremy Jameson — Thu, 02 Apr 2009 17:16:00 GMT

In my previous post, I introduced the concept of linking files in Visual Studio solutions.

A good use of this feature is specifying a custom dictionary for your solution.

Once you enable Code Analysis on your projects, you are likely to encounter warnings similar to the following:

MSBUILD : warning : CA1704 : Microsoft.Naming : Correct the spelling of 'Fabrikam' in namespace name 'Fabrikam.Demo.CoreServices.Logging'.

If you right-click one of these warnings and then click Show Error Help, you will find the following:

How to Fix Violations
To fix a violation of this rule, correct the spelling of the word or add the word to a custom dictionary named CustomDictionary.xml. Place the dictionary in the installation directory of the tool, the project directory, or in the directory associated with the tool under the user's profile (%USERPROFILE%\Application Data\...).

Identifiers should be spelled correctly

http://msdn.microsoft.com/en-us/library/bb264492.aspx

However, I don't recommend using any of these options. Here's why...

We want our custom dictionary to be applied to all projects in our solution -- not just one project. This would make us tend to believe that the first or last option described above would be the best choice. However, we also want our custom dictionary to be easily updated by any developer on the team, and -- as always -- we also want to keep things as simple as possible.

Forcing each developer on your team to copy the CustomDictionary.xml file into some folder -- and subsequently manage updates to this file on his or her local development environment -- is certainly less than ideal.

Therefore, the best place to put CustomDictionary.xml is in source control right alongside the solution file. Thus when any developer "gets latest" on the solution, he or she will automatically get the latest custom dictionary. This also ensures that new team members get everything they need on the first "get" from source control.

So, now that we know we want CustomDictionary.xml stored side-by-side with the Visual Studio solution file, the only thing left to do is configure Visual Studio to use our custom dictionary for each project in the solution.

This is accomplished by adding a link in each project to CustomDictionary.xml (in the solution folder) and subsequently configuring the following property on the linked file:

Build Action: CodeAnalysisDictionary

Now you can simply add items to the CustomDictionary.xml for the solution, as shown below, and eliminate those CA1704 warnings.

<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
  <Words>
    <Recognized>
      <Word>Fabrikam</Word>
    </Recognized>
  </Words>
</Dictionary>

Since the file is in source control, you can obviously track changes to the file and view the history at any point in the future.

Linked Files in Visual Studio Solutions

Jeremy Jameson — Thu, 02 Apr 2009 16:20:00 GMT

A couple of years ago, I wrote a post introducing my system for structuring Visual Studio solutions. However, I apparently forgot to post a follow-up providing additional details, such as configuring assembly versioning and what I like to call "shared assembly information."

Before I can cover these details, I need to first ensure that you are familiar with the concept of linking files in Visual Studio solutions, why this is a powerful feature, and when to use it.

If you ever used Visual SourceSafe (VSS), you likely used its feature for sharing files across multiple projects. For example, you could check-in a file at the root of your solution, and then drag-and-drop it into other projects (i.e. "subfolders") in your solution. Thus, whenever a change was made to the file (regardless of which particular VSS project the change was made in), the next time you "got latest" the change would be reflected in all locations. This was a common way of, for example, having all of your .NET assemblies in the same Visual Studio solution specify the same assembly version.

Note that Team Foundation Server (TFS) does not provide an equivalent "share file" feature. Fortunately, however, you no longer need such a feature.

Back in the days of the original Visual Studio .NET and the following version, Visual Studio .NET 2003, whenever you added an existing file to a project, it copied the file into the corresponding location in the project.

However, in Visual Studio 2005, the Add Existing Item feature provided the ability to choose to either Add the item or Add As Link (via the little down arrow on the button in the dialog box).

In other words, once you upgraded to Visual Studio 2005, it was no longer necessary to rely on any "sharing" features of your source control system in order to have multiple projects always reference the latest version of a file.

Note that when you Add an item in Visual Studio 2005 or Visual Studio 2008, the behavior is the same as earlier versions (meaning the file is copied into the corresponding location within the project). When you choose to Add As Link, however, you simply reference the file in-place. [Don't worry, relative paths ensure that everyone on your team is free to choose whatever root folder they wish for their individual workspaces.]

To illustrate this concept, I quickly built out a "demo" solution, as shown below.

Figure 1: Linked files in a Visual Studio solution

See full-sized image.

The corresponding folder structure on disk resembles the following:

Fabrikam
- Demo
  - Dev (branch)
    - Lab1 (branch)
      - AssemblyVersionInfo.cs
      - CustomDictionary.xml
      - Fabrikam.Demo.sln
      - Fabrikam.Demo.snk
      - SharedAssemblyInfo.cs
      - AdminConsole
        
        AdminConsole.csproj
        
        Program.cs
        
        Properties
        
        AssemblyInfo.cs
      - CoreServices
        
        CoreServices.csproj
        
        Logging
        
        Logger.cs
        
        Properties
        
        AssemblyInfo.cs

Note that AssemblyVersionInfo.cs, CustomDictionary.xml, Fabrikam.Demo.snk, and SharedAssemblyInfo.cs reside in the same folder as the Visual Studio solution file and are subsequently "linked into" the two Visual C# projects. Thus whenever a change is made to one of these files, the next build of each project will reflect that change.

With this foundation in place, I'll explain some other recommended best practices over a series of follow-up posts, including:

Stay tuned!

DiffMerge - A Better Differencing Tool

Jeremy Jameson — Tue, 24 Mar 2009 17:01:00 GMT

Last summer, I added DiffMerge to my Toolbox and I haven't used WinDiff since.

DiffMerge can do everything WinDiff can, plus a whole lot more -- like intra-line highlighting, merging, and comparing files using configurable rulesets (although you'll likely never need any more than those that come "out-of-the-box" with DiffMerge).

And since the folks at SourceGear don't mind giving away DiffMerge for free, there's no reason not to use it!

Heck, I even configure Visual Studio to use DiffMerge as my comparison tool instead of the default tool that comes with Team Foundation Server (TFS).

To customize your TFS comparison tool in Visual Studio 2008:

On the Tools menu, click Options...
In the Options window, expand Source Control, select Visual Studio Team Foundation Server, and then click Configure User Tools...
In the Configure User Tools window, click the Add... or Modify... button as necessary to configure the following:

Extension: .*
Operation: Compare
Command: C:\NotBackedUp\Public\Toolbox\DiffMerge\DiffMerge.exe
Arguments: %1 %2

Obviously, you may need to adjust the path to DiffMerge.exe as necessary for your environment.

In the past, I tried other tools like BeyondCompare -- but I preferred the simplicity of WinDiff. Then, a couple of years ago, one of my peers pointed me to an internal tool called "Odd" that would do intra-line highlighting. However, I couldn't get over the fact that this was an internal tool only -- and thus not something I could recommend to customers.

When I stumbled across DiffMerge, I was delighted and I haven't looked back since.

Perhaps Visual Studio 2010 will ship with a vastly improved differencing tool, but in the meantime -- or just in case it doesn't -- DiffMerge is my tool of choice.

Visual Studio Macro for Collapsing All Items in Solution Explorer

Jeremy Jameson — Wed, 11 Mar 2009 17:18:00 GMT

Along with my Visual Studio macros for unloading/reloading projects in a solution, another macro that I use just as much, if not more frequently, is my CollapseAllItems() macro:

Public Sub CollapseAllItems()
    Dim solutionExplorer As Window = _
        DTE.Windows.Item(Constants.vsWindowKindSolutionExplorer)

    solutionExplorer.Activate()

    DTE.SuppressUI = True

    Try
        Dim solutionHierarchy As UIHierarchy = solutionExplorer.Object

        For Each item As UIHierarchyItem _
            In solutionHierarchy.UIHierarchyItems

            CollapseItem(item, solutionHierarchy)
        Next
    Catch ex As Exception
        WriteOutput("Error collapsing all items: " _
            & ex.Message)

    Finally
        DTE.SuppressUI = False
    End Try
End Sub

The CollapseItem() method is used to recursively collapse each item in the hierarchy:

Private Sub CollapseItem( _
    ByVal item As UIHierarchyItem, _
    ByVal solutionHierarchy As UIHierarchy)

    For Each child As UIHierarchyItem In item.UIHierarchyItems
        CollapseItem(child, solutionHierarchy)

        If (item.UIHierarchyItems.Expanded = True) Then
            WriteOutput("Collapsing item (" & item.Name & ")...")
            item.UIHierarchyItems.Expanded = False

            ' HACK: Known bug in Visual Studio 2005
            ' http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=114597
            If (item.UIHierarchyItems.Expanded = True) Then
                item.Select(vsUISelectionType.vsUISelectionTypeSelect)
                solutionHierarchy.DoDefaultAction()
            End If
        End If
    Next
End Sub

While it is great that Visual Studio "synchronizes" the Solution Explorer window to show the current file in the solution hierarchy, in large Visual Studio solutions, things can get a bit bewildering at times if many of the projects are expanded down to the level of individual files.

Perhaps in a future version of Visual Studio, we'll have the ability to right-click the solution in Solution Explorer and then click something like Collapse All. Until then, I don't see me giving up my dependency on this macro anytime soon.

Visual Studio Macros for Unloading/Reloading Projects

Jeremy Jameson — Wed, 11 Mar 2009 16:30:00 GMT

As promised in a post last week, here are the macros that I use to quickly unload or reload dozens of projects in a large Visual Studio solution. Hmmm, perhaps effortlessly is a better word choice -- considering I might need to wait 30 seconds or so for all of the projects to unload or reload.

Here is my UnloadAllProjects() macro:

Public Sub UnloadAllProjects()
    If (DTE.Solution Is Nothing _
        Or DTE.Solution.Count = 0) Then

        MessageBox.Show( _
            "Cannot unload all projects because no solution is open.", _
            "Error", _
            MessageBoxButtons.OK, _
            MessageBoxIcon.Error)

        Exit Sub
    End If

    Dim solutionName As String = _
        DTE.Solution.Properties.Item("Name").Value.ToString()

    WriteOutput("Unloading projects in solution (" & solutionName & ")...")

    Dim solutionExplorer As Window = _
        DTE.Windows.Item(Constants.vsWindowKindSolutionExplorer)

    solutionExplorer.Activate()

    Dim solutionHierarchy As UIHierarchy = solutionExplorer.Object

    For Each proj As Project In DTE.Solution.Projects
        ' Note that the project may be a solution folder, in which case we
        ' want to unload all of the projects within the solution folder.
        '
        ' Also note if the project is already unloaded, or is a solution
        ' folder containing no projects -- then a COM exception occurs.
        Try
            UnloadProject(proj, solutionName, solutionHierarchy)
        Catch ex As Exception
            WriteOutput("Error unloading project (" & proj.Name & "): " _
                & ex.Message)

        End Try
    Next

    WriteOutput("Successfully unloaded projects in solution (" _
                & solutionName & ").")
End Sub

The actual work of unloading a project is delegated to the UnloadProject() method:

Private Sub UnloadProject( _
    ByVal proj As Project, _
    ByVal solutionName As String, _
    ByVal solutionHierarchy As UIHierarchy)

    Debug.Assert(Not proj Is Nothing)
    Debug.Assert(String.IsNullOrEmpty(solutionName) = False)
    Debug.Assert(Not solutionHierarchy Is Nothing)

    WriteOutput("Unloading project (" & proj.Name & ")...")

    If (proj.Kind = Constants.vsProjectKindMisc) Then
        ' "Miscellaenous Files" cannot be unloaded
        WriteOutput("Project (" & proj.Name & ") cannot be unloaded.")
        Return
    End If

    Dim projPath As String = solutionName & "\" & proj.Name

    Dim obj As Object = solutionHierarchy.GetItem(projPath)
    obj.Select(vsUISelectionType.vsUISelectionTypeSelect)

    Dim projectName As String = proj.Name
    DTE.ExecuteCommand("Project.UnloadProject")
    WriteOutput("Successfully unloaded project (" & projectName & ").")
End Sub

A few interesting notes...

I originally used the Record TemporaryMacro feature in Visual Studio a few years ago to determine how projects are loaded and unloaded. This led me to the scantily documented DTE.ExecuteCommand("Project.UnloadProject").
I discovered that a specific project type ("Miscellaneous Files") will always throw a COM exception whenever you try to unload or reload it. Consequently, I skip that one altogether.
While I tried to find a way to determine if a particular project (or projects within a solution folder) are already unloaded -- and thus avoid a COM exception when subsequently attempting to unload it again -- I ended up punting this and instead simply wrapping the "unload" operation in a try/catch block.
The WriteOutput() method is provided in a previous post.

If you take the above code and essentially search-and-replace "unload" with "reload" then you will end up with my macro to reload all projects within the solution:

Public Sub ReloadAllProjects()
    If (DTE.Solution Is Nothing _
        Or DTE.Solution.Count = 0) Then

        MessageBox.Show( _
            "Cannot reload all projects because no solution is open.", _
            "Error", _
            MessageBoxButtons.OK, _
            MessageBoxIcon.Error)

        Exit Sub
    End If

    Dim solutionName As String = _
        DTE.Solution.Properties.Item("Name").Value.ToString()

    WriteOutput("Reloading projects in solution (" & solutionName & ")...")

    Dim solutionExplorer As Window = _
        DTE.Windows.Item(Constants.vsWindowKindSolutionExplorer)

    solutionExplorer.Activate()

    Dim solutionHierarchy As UIHierarchy = solutionExplorer.Object

    For Each proj As Project In DTE.Solution.Projects
        ' Note that the project may be a solution folder, in which case we
        ' want to reload all of the projects within the solution folder.
        '
        ' Also note if the project is already loaded, or is a solution
        ' folder containing no projects -- then a COM exception occurs.
        Try
            ReloadProject(proj, solutionName, solutionHierarchy)
        Catch ex As Exception
            WriteOutput("Error reloading project (" & proj.Name & "): " _
                & ex.Message)

        End Try
    Next

    WriteOutput("Successfully reloaded projects in solution (" _
                & solutionName & ").")
End Sub

Private Sub ReloadProject( _
    ByVal proj As Project, _
    ByVal solutionName As String, _
    ByVal solutionHierarchy As UIHierarchy)

    Debug.Assert(Not proj Is Nothing)
    Debug.Assert(String.IsNullOrEmpty(solutionName) = False)
    Debug.Assert(Not solutionHierarchy Is Nothing)

    WriteOutput("Reloading project (" & proj.Name & ")...")

    If (proj.Kind = Constants.vsProjectKindMisc) Then
        ' "Miscellaenous Files" cannot be unloaded
        WriteOutput("Project (" & proj.Name & ") cannot be unloaded.")
        Return
    End If

    Dim projPath As String = solutionName & "\" & proj.Name

    Dim obj As Object = solutionHierarchy.GetItem(projPath)
    obj.Select(vsUISelectionType.vsUISelectionTypeSelect)

    DTE.ExecuteCommand("Project.ReloadProject")
    WriteOutput("Successfully reloaded project (" & proj.Name & ").")
End Sub

Like I mentioned earlier, unloading or reloading all of the projects within a solution is not exactly an instantaneous operation. However, when you consider the incremental build time saved by unloading all of the projects in a large solution except for the few you are working on at any given time, you definitely come out far ahead in the end. You'll be amazed at how much more productive you can be when your solution containing 50+ projects incrementally builds in just a few seconds when all but a handful of the projects are unloaded.

I hope you find these macros as helpful as I have over the years.

Perhaps in a future version of Visual Studio, we'll have the ability to right-click the solution in Solution Explorer and then click something like Unload Projects in Solution (similar to the Unload Projects in Solution Folder option that is currently available -- but only for solution folders, not the solution itself). Until then, I don't see me giving up my dependency on these macros anytime soon.

Tracing and Logging from Visual Studio Macros

Jeremy Jameson — Wed, 11 Mar 2009 15:57:00 GMT

As I mentioned in a post last week, I often use macros in Visual Studio to automate development tasks.

Before sharing some of my most frequently used macros, however, I wanted to first introduce the method I use to trace events and log messages while running various macros.

Take a look at the following Output window from Visual Studio. Notice how there is an item in the Show output from dropdown list titled Macros (a.k.a. "the macro output pane").

Figure 1: Macro output pane

See full-sized image.

Chances are that when you look at your Visual Studio environment, you won't see this item. So, why does it appear in my environment?

The macro output pane is actually created on-the-fly, as necessary, whenever I run one of my macros that implements tracing (i.e. writes output). This is done via the GetMacroOutputPane() function, as shown below.

    Private Function GetMacroOutputPane() As OutputWindowPane
        Dim ow As OutputWindow = _
            DTE.Windows.Item(Constants.vsWindowKindOutput).Object()

        Dim outputPane As OutputWindowPane

        Try
            outputPane = ow.OutputWindowPanes.Item("Macros")
        Catch ex As Exception
            outputPane = ow.OutputWindowPanes.Add("Macros")
        End Try

        Return outputPane
    End Function

Pretty simple, eh? If the macro output pane exists, then use it; otherwise add a new pane.

In order to simplify writing output messages -- as well as timestamp each message as it is written -- I use the WriteOutput() method

    Private Sub WriteOutput( _
        ByVal s As String)

        Dim buffer As StringBuilder = New StringBuilder

        buffer.Append(Date.Now.ToLongTimeString())
        buffer.Append(" ")
        buffer.Append(s)
        buffer.Append(vbCrLf)

        Dim output As String = buffer.ToString()

        Dim outputPane As OutputWindowPane = GetMacroOutputPane()
        outputPane.OutputString(output)
    End Sub

Large Visual Studio Solutions and Loading/Unloading Projects

Jeremy Jameson — Fri, 06 Mar 2009 18:03:00 GMT

As I noted in my previous post, I typically work with "large" Visual Studio solutions. Note that I put this in quotes, because the definition of "large" will likely vary widely based on your individual experience. Note that I'm not referring to "large" like the source for the .NET Framework itself, but rather "large" like most enterprise customers that I typically engage with. If you want a number, then let's say somewhere in the range of 50-75 projects in a single Visual Studio solution.

On my previous project, we had 52 projects in our solution. On my current project, there are 30.

You may very well have more or less, but the following concepts and tips should still apply. If you are on a development team with several hundred projects, then either you are a member of the NetFx team or you more than likely already know about what I'm about to tell you in this post ;-)

If you work with multiple Visual Studio solutions that only have a handful of projects, but this is simply because your team decided to break up one big solution into several smaller ones, then this post is intended especially for you.

As you start adding more and more projects to a solution, you'll inevitably discover the following to be true:

Load time increases (i.e. the time it takes to start Visual Studio and open your solution)
Incremental build time increases, even when the only changes that have been made are in "leaf" projects (i.e. projects that don't reference other projects)

Obviously we should expect the build time to take a while whenever we make a change in one project that is referenced by many others (e.g. a "CoreServices" project like I've described in the past).

If, like me, you've grown accustomed to Test Driven Development (TDD) however, then you know that it's essential to minimize the "Red, Green, Refactor" cycle. If your incremental build time requires 28 seconds, then your developer productivity is going to take a hit in a big, big way.

So, what can we do to mitigate these issues?

One approach is to create multiple Visual Studio solutions with a subset of projects. Developers could then open the specific solution (or, possibly, solutions -- plural) containing a subset of the projects they need to work on at any given time.

I really don't like -- or obviously recommend -- this approach, because it can be very problematic (for example, having to synchronize changes to the build configuration). Even worse, though, is that depending on how you partition your solution, you may end up having to switch from project references to file references for assembly dependencies. Anyone who has ever used file references for their own code should tell you that this is something to avoid.

Note that the recommendation to use a single, "master" solution is nothing new. We've had this prescriptive guidance out for a number of years now (please forgive the fact that MSDN still refers to using Visual SourceSafe instead of Team Foundation Server in this article -- there may very well be an updated article that I simply haven't bothered to take the time and find).

Unfortunately, what was fundamentally missing from the original prescriptive guidance was any mention of the feature in Visual Studio that allows you to effectively work with a solution containing numerous projects. This has become critical in light of the shift to TDD.

If you right-click a project in Visual Studio, you'll see the Unload Project option way down near the bottom of the context menu. When you unload a project, Visual Studio completely ignores the project (and all of the items in the project). Unloaded projects are not compiled when you press CTRL+SHIFT+B, which can substantially reduce your incremental build time, thereby making you a much more productive TDD developer! You will also find the time required to open the solution can be greatly reduced by unloading projects.

Whenever you need to change something in an unloaded project, simply right-click the project and click Reload Project.

Unloading a project is also useful whenever you need to edit the MSBuild file -- for example, to rebuild a CAB or WSP whenever a dependency changes.

An important thing to understand about loading and unloading projects is that the settings are stored in the solutions options (.suo) file which is specific to each developer and should never be stored in source control. In other words, if I unload a project in my workspace, this has no effect on other team members. Removing a project, on the other hand, changes the solution file (.sln) itself and therefore impacts other members of the development team.

Note that you can quickly unload or reload multiple projects at a time by using solution folders within Visual Studio. If you right-click a solution folder, you will see the option to Unload Projects in Solution Folder. I typically structure my Visual Studio solutions in a hierarchical fashion (i.e. nested solution folders) to make it very easy to load or unload various "subsystems" or features.

Also note that you can use Visual Studio macros to quickly unload or reload all of the projects in a solution with a single click (well, actually a double-click, but you get the point).

I'll share the macros that I developed and have been using for years in a separate post.

There is one caveat that you should be aware of when unloading projects. Visual Studio warns you when you attempt to unload projects with pending changes in source control. Generally speaking, you want to avoid proceeding whenever Visual Studio displays the warning for this scenario.

Note that modified files in unloaded projects are still shown in the Pending Changes window when using TFS as the source code control provider. However, this isn't true for all providers (e.g. Visual SourceSafe).

I've been using the loading/unloading project feature since my old Visual C++ 4.2 days, but -- at least based on my experience -- there seem to be a number of developers who are unaware of this great feature in Visual Studio. If I recall correctly, this was missing in the original Visual Studio.NET but, thankfully, was added back in a subsequent version, either Visual Studio .NET 2003 or Visual Studio 2005 (honestly, it's been too long to remember). Perhaps that the reason why the original prescriptive guidance on MSDN makes no mention of unloading/loading projects. Thank goodness it's back!