When I took over our builds, one of the things I wanted to provide was a report after every build that showed the changes in assemblies between the current and previous build. This would include things like new or removed interfaces, classes, methods, and properties, as well as changes to method signatures. Well, it didn't take long to find a tool that performed this type of analysis: BitDiffer.

Similar to FxCop, BitDiffer has a standalone client app as well as a command-line executable, making it easy to integrate in a build process. BitDiffer can analyze versions of single assemblies as well as sets of assemblies across different directories. And not only can you check for changes on public types, but BitDiffer can check for changes in private members/types and even implementation differences.

BitDiffer Client

The user interface for the BitDiffer client is simple yet very polished, and done well. Here's a few screenshots of what the BitDiffer client app looks like:

Creating a new comparison set, in this case comparing all assemblies from two different builds.

Results after analysis. Assemblies in gray don't have changes, assemblies in black have non-breaking changes, and assemblies in red have breaking changes.

A breaking change. One of the constructor declarations of the Wiki class has changed.

BitDiffer Command-Line

The BitDiffer client is great for running comparisons ad-hoc, but it can't be automated; that's where the BitDiffer command-line executable comes in. It's name is BitDiffer.Console.exe and contains a number of options:

BitDiffer with MSBuild and CruiseControl.NET

With BitDiffer.Console.exe and its options comes the ability to include it as part of a build process, which in our case is performed with CruiseControl.NET. Each of our builds has a CC.NET config script that invokes a MSBuild script, most of which in turn invoke BitDiffer to compare assemblies from the previous build to the current one. For example, here's what the MSBuild script looks like for Community Server:

And here's a breakdown of that script:

• Line 2: We need the math functions from the MSBuild Community Tasks project, so we include that assembly here.
• Lines 5-7: Our CCNetLabel properties are simple incremental build numbers, so we subtract 1 from that to determine the PreviousCCNetLabel property value.
• Lines 10-11: We set the current and previous drop directory locations by using the CCNetLabel and PreviousCCNetLabel properties, respectively.
• Line 12: We're setting the full path to BitDiffer.Console.exe.
• Line 16: We're telling MSBuild to build the entire Community Server solution.
• Lines 18-22: We're telling MSBuild to copy all the assemblies from the CommunityServer.Web\bin directory to the current drop directory.
• Line 24-27: We invoke BitDiffer to perform the assembly comparisons.
  • The %22 is the code for " (double-quote); MSBuild needs it this way to properly surround the strings.
  • Line 25: We want to perform a directory comparison, but only for public types while ignoring implementation changes.
  • Line 26: We want BitDiffer to create an XML report named bitdiffer-results.xml in the CCNetArtifactDirectory, which is defined in the CC.NET config script.
  • Line 27: We're telling BitDiffer to analyze the assemblies from the previous drop directory to the current drop directory.

Once the build is finished, CC.NET adds the contents of the bitdiffer-results.xml file to the build log, at which point an email is sent with the overall results.

BitDiffer XML Report and XSL Stylesheet

Depending on the number of types in your assemblies, the size of the BitDiffer XML report will vary. For instance, for all the assemblies and types in Community Server, our BitDiffer XML report is over 5MB (you can download one of them here; don't worry, zipped it's only 320KB). That's a lot of data to churn through, but lucky for you I spent a lot of time putting together an XSL stylesheet to parse it all (download here). I'm by no means an XSL expert, but I kept the XSL pretty clean and straightforward, so feel free to adjust as necessary.

To use the XSL stylesheet in CC.NET, you need to add it to the appropriate xsl directories and edit dashboard.config (to see it on the web dashboard) and/or ccservice.exe.config (to see it in emails); consult the CC.NET web site for more details.

Here's a screenshot that gives a glimpse of what the report looks like. Note that the "Options" label at the top of the report is hardcoded to say "Public only, no implementation". BitDiffer doesn't put the command-line options used in the XML report, so that was the best I could do. Adjust that for your needs accordingly.

What's the catch?

I love free tools as much as anyone, but BitDiffer is not free. It does provide a 7-day trial, but after that it costs $60 per user or a mere $480 for a full site license. Take that for what you will, but I believe it's a small cost to keep track of changes between different versions of assemblies.

Disclaimer: BitWidgets, maker of BitDiffer, is an advertiser in The Lounge network, for which I am a part of. However, I was not asked to write this post, nor was I given a free license. I just think the tool rocks and thought people should know about it. I also think it's important to note that I got good support from Greg Ennis, the guy who wrote BitDiffer, on a number of questions I had when initially setting up BitDiffer. I told Greg months ago I was going to write this post and finally got around to it.

Similar Posts

1. Using svn:externals to Manage Project References
2. NHibernateRepository
3. TechEd 2005 Recap