Documenting Unhandled Exceptions as Part of an Automated Build Process

This is a showcase review for our sponsors at The Code Project. These reviews are intended to provide you with information on products and services that we consider useful and of value to developers.

Continuous Integration (CI) servers such as Cruise Control .NET make your life easier by checking for code changes and initiating automated builds of software when needed, saving the hassle of building software manually. This enables a team of developers to contribute code changes more freely. CI servers can also perform one or more automated tasks when the build completes, such as analyzing the newly-built assembly for best-practice compliance using FxCop or publishing the files to an FTP server.

Exception Hunter™ Finds Unhandled Exceptions in Managed Assemblies

Exception Hunter, from Red Gate Software, is a one-of-a-kind tool designed to analyze a .NET assembly for unhandled exceptions that can occur in its methods. This gives the developer the opportunity to make informed decisions about exception-handling practices and about producing more resilient code. Exception Hunter includes a command-line executable in addition to the Graphical User Interface version, making it possible to automate the reporting of methods that contain unhandled exceptions. Using the facilities of the CI server, it's possible to integrate these reports into your product's documentation or even into the CI server's logs.

Automatically Creating Exception Reports as Part of the Build Process

Adding an Exception Hunter method or exception report to the automated build process is performed by a CC .NET exec task in the server/ccnet.config file. The exec task is placed inside the <project> node, but after the source control and build tasks. Using the /mr (Method Report) argument to Exception Hunter, an HTML report is created detailing all of the unhandled exceptions. Since the project I've built creates two executables, I am creating one single method report covering both assemblies by specifying two /assembly arguments to Hunt.exe.

<exec>
    <executable>Hunt.exe</executable>
    <baseDirectory>c:\program files\red gate\exception hunter 1</baseDirectory>
    <buildArgs>/q 
        /xml:c:\Builds\ChatApplication\ExceptionReport.XML 
        /er:c:\Builds\ChatApplication\ExceptionReport.htm 
        /allpublicmethods 
        /ignoreCodeBranches:on 
        /force 
        /Assembly:c:\Builds\ChatApplication\ChatClient\Bin\Debug\ChatClient.exe 
        /Assembly:c:\Builds\ChatApplication\ChatServer\Bin\Debug\ChatServer.exe
    </buildArgs>
    <buildTimeoutSeconds>2800</buildTimeoutSeconds>
</exec>

This Exception Report will be created in the build folder and can be used as internal documentation about the type and number of unhandled exceptions that occur in all of the assemblies that have just been built.

Integrating Exception Reports into Automated Build Logs

Even more interestingly, the Exception Hunter method and exception reports can be output directly to CC .NET's build logs, allowing the build manager to view the exceptions in the CC .NET reports. These reports are included in the latest build log, as well as in their own individual report categories.

This clever trick is achieved by extracting the XSL template from the Exception Hunter executable itself (Hunt.exe), adding it to CC .NET's web dashboard and using a CC .NET publisher called "xmllogger" to merge the Exception Hunter's XML output into the build log.

The first step is to extract an XSL template from Hunt.exe. This can be done using a tool such as Reflector for .NET, which can read resources from an assembly. Once you have installed Reflector and opened %programfiles%\red gate\exception hunter 1\hunt.exe, click the Resources folder and locate both resources ending in *.xslt. The resource ending in Exceptions.xslt is the template for creating the report organized by exception type. Summary.xslt is the template for creating the report organized by method.

Right-click Exceptions.xslt and select view resource. Then highlight the content from the "disassembler" window and copy to the clipboard. Create a new file in CC .NET's webdashboard/xsl folder called ExceptionHunt-Methods.xsl. Paste in the contents of the clipboard and save the file. Finally, create a new file in the webdashboard/xsl folder called ExceptionHunt-Exceptions.xsl and perform the same task for the Summary.xslt resource. Make sure that both files have been saved.

Next, enable the reports in the list of CC .NET's list of reports by editing webdashboard/dashboard.config to add the Exception Hunter XSLT files into the <xslFileNames> node. Configure an <xslReportBuildPlugin> for each.

</buildPlugins>
    <buildReportBuildPlugin>
        <xslFileNames>
            <xslFile>xsl\ExceptionHunt-Methods.xsl</xslFile>
            <xslFile>xsl\ExceptionHunt-Exceptions.xsl</xslFile>
        </xslFileNames>
    </buildReportBuildPlugin>
    <xslReportBuildPlugin description="Methods with Unhandled Exceptions" 
        actionName="UnhandledMethods" xslFileName="xsl\ExceptionHunt-Methods.xsl"/>
    <xslReportBuildPlugin description="Unhandled Exceptions By Type" 
        actionName="UnhandledExceptions" xslFileName="xsl\ExceptionHunt-Exceptions.xsl"/>
</buildPlugins>

This will add two new reports to the CC .NET dashboard called "Methods with Unhandled Exceptions" and "Unhandled Exceptions By Type."

In order to get Exception Hunter's output into these reports, we need to create an exec task in the server/ccnet.config file after the build task to instruct Exception Hunter to produce XML output, and then configure an XML logger to send this output to the CC .NET log stream. To create the exec task, edit server/ccnet.config and add an exec task that runs Hunt.exe with the /xml argument.

<exec>
    <executable>Hunt.exe</executable>
    <baseDirectory>c:\program files\red gate\exception hunter 1</baseDirectory>
    <buildArgs>/q 
        /xml:c:\Builds\ChatApplication\ExceptionReport.XML 
        /allpublicmethods 
        /ignoreCodeBranches:on 
        /force 
        /Assembly:c:\Builds\ChatApplication\ChatClient\Bin\Debug\ChatClient.exe 
        /Assembly:c:\Builds\ChatApplication\ChatServer\Bin\Debug\ChatServer.exe
    </buildArgs>
    <buildTimeoutSeconds>2800</buildTimeoutSeconds>
</exec>

The final step is to add a merge publisher to server/ccnet.config that will merge the Exception Hunter's output with the rest of the build log.

<publishers>
    <merge>
        <files>
            <file>c:\Builds\ChatApplication\ExceptionReport.XML</file>
        </files>
    </merge>
    <xmllogger />
</publishers>

Note that it is possible to produce an HTML exception and method report, as well as an XML file from the same command line. Exception Hunter does not need to be run three times to achieve this.

<cruisecontrol>
<project name="Demo Exception Hunter">
<sourcecontrol type="vss" autoGetSource="true" applyLabel="true">
    <executable>C:\Program Files\Microsoft Visual SourceSafe\SS.EXE</executable>
    <project>$/PROJECTS/ChatApplication.root/ChatApplication</project>
    <username>Automated.Build</username>
    <password>P@ssw0rd</password>
    <ssdir>C:\VSS</ssdir>
    <workingDirectory>C:\builds\ChatApplication</workingDirectory>
    <culture>en-GB</culture>
    <cleanCopy>false</cleanCopy>
</sourcecontrol>
<tasks>
    <devenv>
        <solutionfile>c:\builds\ChatApplication\ChatApplication.sln</solutionfile>
        <configuration>debug</configuration>
        <buildtype>Build</buildtype>
        <executable>
            c:\program files\microsoft visual studio 8\Common7\ide\devenv.com
        </executable>
    </devenv>
    <exec>
        <executable>Hunt.exe</executable>
        <baseDirectory>c:\program files\red gate\exception hunter 1</baseDirectory>
        <buildArgs>/q 
            /xml:c:\Builds\ChatApplication\ExceptionReport.XML 
            /allpublicmethods 
            /ignoreCodeBranches:on 
            /force 
            /Assembly:c:\Builds\ChatApplication\ChatClient\Bin\Debug\ChatClient.exe 
            /Assembly:c:\Builds\ChatApplication\ChatServer\Bin\Debug\ChatServer.exe
        </buildArgs>
        <buildTimeoutSeconds>2800</buildTimeoutSeconds>
    </exec>
</tasks>
<publishers>
    <merge>
        <files>
            <file>c:\Builds\ChatApplication\ExceptionReport.XML</file>
        </files>
    </merge>
    <xmllogger />
</publishers>
</project>
</cruisecontrol>

Examining Exception Logs Will Identify Potential Problems in Code

Viewing the build logs in Cruise Control .NET for this project will now show the Exception Hunter method and exception information about the assemblies that have just been built. Using these reports, decision-makers and programmers can more easily evaluate the quality of their software and decide whether or not changes need to be made to improve the resiliency of the program code through more thorough exception handling.