Working with Reflector.Diff

4.5 Comparing Assemblies with Reflector.Diff

The ability to compare differences between assemblies can be useful when spelunking through new versions of an application or framework. Reflector.Diff, a Reflector add-in written by Sean Hederman, graphically displays the differences between two assemblies, or two versions of the same assembly. The assembly differences may then be exported to an XML difference report if required.

One way of using Reflector.Diff is to help track down the emergence of bugs. It can be difficult to determine exactly what change introduced a particular bug in a large project, when many developers are frequently checking code into and out of source control. But by differencing the last known good version and the later, buggy version, you can quickly zero in on specific changes. Looking at source code assembly changes can reveal the source of a bug and also provide a list of target source files to examine within your source control system.

Reflector.Diff at a Glance

Getting Started

Reflector.Diff runs on versions 1.0, 1.1, and 2.0 of the .NET Framework. The current version is compiled against Reflector v4.2. It will difference any CLR assembly that Reflector is capable of reading.

Reflector.Diff’s download is a simple .zip file, which you download from the tool’s home page. You’ll need to extract it to the directory containing Reflector.

Using Reflector.Diff

Start Reflector and select Add-Ins from the View menu. Click the Add button, choose Reflector.Diff.dll, and press OK. You should now see the screen shown in Figure 4-9.

Figure 4-9.  Reflector's Add-Ins screen

If you press Close, an item labeled “Assembly Diff”will be made available to you in the Tools menu. Select the Reflector node you wish to difference, and click this menu item.

A Reflector node is any item in the Reflector tree view, such as mscorlib in the following example.

The screenshot in Figure 4-10 shows the difference output of the mscorlib assembly for .NET 2.0. Notice that mscorlib from .NET 1.1 is automatically resolved as the assembly to compare against. We’ll look at the exact mechanism by which this resolution is performed momentarily. Lines deleted from the source are displayed in the lefthand pane in light grey. Lines with no changes are in white. Lines added to the destination (in the righthand pane) are displayed in light green. Replaced lines are depicted in red.

Figure 4-10.  Differencing an assembly

As you scroll through the difference results, the source and destination panes will be kept in sync for you.

While the Assembly Diff pane is open, selecting any node in Reflector will result in that node being differenced. Nodes with large numbers of members will take a very long time to difference, so it’s a good idea to keep this pane closed until you’ve reached the actual node you want to analyze.

Exporting the results

The toolbar’s Export button allows you to export the difference report to XML format. A standard File Save dialog prompts the user for an export location and report type. The report may be saved as either a standard XML report or a verbose XML report. The standard export displays only the changes between the source and destination, while the verbose report includes unchanged items as well.

Selecting your own assemblies

The difference engine easily determines which assemblies to load for the standard Framework assemblies. For custom assemblies, the user is required to find the destination assembly after selecting the source in the Reflector pane.

Clicking the toolbar’s Destination Browse button brings up the Load Assembly dialog (Figure 4-11), which you can use to choose the destination assembly. Cached assemblies are loaded into the list for selection. Alternatively, you can enter a path in the File text box at the bottom of the screen, either manually or by browsing for it using a standard File Open dialog (reached by clicking the “…” button).

Figure 4-11.  Selecting assemblies to load

Once you’ve selected a destination, the difference engine will store the match. The next time you try to difference the same source assembly, your last destination will be remembered and loaded automatically.

Modifying the options

The Options button, unsurprisingly, brings up the Options dialog. The General tab, shown in Figure 4-12, currently provides only one option (more options are envisioned for later versions of the software). The available option indicates the user’s requirement to include documentation for the assembly in the difference results. This works only if the necessary documentation is included in the underlying assembly. If it isn’t, the difference engine will prompt for this information while analyzing differences in the assemblies. This can be irritating, so be warned.

Figure 4-12.  General options

The second tab, Resolution (Figure 4-13), contains the options to control how the difference engine resolves a source assembly to a destination assembly. The initial option indicates whether or not prior custom matches are stored, and how many such matches are stored. The default is to store the last 20 matches.

There is also an option that indicates whether Reflector.Diff should perform automatic Framework resolution. When a Framework assembly is selected, the engine will always try to resolve that assembly to the option indicated here. The resolution options depicted in Figure 4-13 show that if you select a Framework assembly as the source, the destination resolves to the corresponding version 1.1 assembly. The default option is cleverly positioned as the second-highest version installed on your system, so if you have .NET 1.0 and .NET 1.1 installed, the default will be 1.0.

Figure 4-13.  Resolution options

However, bear in mind that custom matches override this option, so if you select version 2.0 of mscorlib and then use the Browse Destination button to select version 1.0 of mscorlib, the tool will from that point on use version 1.0 for mscorlib. The engine assumes that its users know what they’re doing here, possibly incorrectly.

Finally, the Export options (shown in Figure 4-14) control how the XML exports are performed. The default option exports the current node only. If the option to include subnodes is selected, all of the selected node’s subnodes will be exported as well. Correspondingly, the exports will take a much longer time to complete.

Figure 4-14.  Export options

Getting Support

Support for Reflector.Diff is solely via bug reports and feature requests sent to the author’s email address (sean.hederman@codingsanity.com). Source code can also be found on the download page.

Reflector.Diff in a Nutshell

Reflector.Diff is still in beta development, as is evidenced by its 0.75 version number. The exported differences do not currently contain an indent level, and including documentation
currently requires the selection of side-by-side versioning in the Reflector options. In addition, better multithreading support would help to improve the responsiveness for large nodes. Improvements to address all of these issues are on the drawing
board for the next release, but since this tool is a hobby, releases are, unfortunately,
fairly widely spaced.

Still, for its purpose, Reflector.Diff is pretty useful. Looking at differences between
assemblies is an edge case, with few applications beyond research. The original purpose of the tool was to assist its author in finding changes between .NET 1.1 and .NET 2.0 Framework assemblies, which is why the support for non-Framework assemblies is a bit
of an afterthought. Furthermore, since a primary goal of the tool is to support all Framework
versions, the tool must be developed in .NET 1.0, which limits the ease of adding some additional functionality.

Nonetheless, the ability to difference assemblies is very useful. This tool has been used
to identify breaking changes in vendors’ code, resulting in quick turnaround of bug fixes. It is also used by some large corporations to help zero in on change issues, and by many developers to research changes in versions of assemblies.

Reflector.Diff gives users a quick and easy way to visually inspect changes between two versions of a DLL for research or bug tracing.

—Sean Hederman, creator of Reflector.Diff

Please check back next week for the continuation of this article.