The tool NDepend gathers data from a code base. This includes quality code metrics, test coverage statistics, componentization/architecture/dependencies, evolution and changes, state mutability, usage of tier code and much more. The amount of data produces is proportional to the size of the code base and can become pretty big in case of a large application analyzed. The NDepend added value lies in its capabilities to let user browse readily this huge amount of data. This way developers and architects can know precisely what’s really happening inside their shop and can take decisions based on real facts, not based on intuition and rumor. There are 2 distinct scenarios to browse data:

• Through a report: NDepend analysis process can be integrated into a build process and can produce a customizable HTML report each time the analysis is run. The report is suited to produce daily dash-boards useful for every members of the team, even non-technical ones.

• Through the stand-alone UI VisualNDepend: The VisualNDepend UI comes with several panels to visualize and query interactively information about the code base. This UI collaborates hand-in-hand with Visual Studio and Reflector. VisualNDepend users are architects and developers that need to dig into details of the code base at any time.

I would like to expose here some details about how to integrate NDepend into a build process but let's first explain how NDepend can provide useful warnings about the health of a build process.

NDepend warnings about the health of the build process

These warnings can be found in the file $AnalysisResultDir$\InfoWarnings.xml, in the report section NDepend information and warnings and in the Error List panel of the VisualNDepend UI.

What we mean by the health of the build process is some details that can reveal potential flaws. Concretely this includes:

Assemblies versionning issues such as:

• AssemblyA references AssemblyB v2.1 but only AssemblyB v2.0 is available.

• AssemblyA references 2 versions of AssemblyB (which is not necessarily a bad thing, but it's still useful to be aware of such situation).

Assembly conflicts such as:

• The name of my assembly main module file is different from the logical name of my assembly.

• Several different assemblies with the same name can be found (different = different hash code and/or different version).

PDB files issues such as:

• Missing PDB files.

• PDB files and code source files not in-sync.

• PDB files and assemblies are not in-sync.

Coverage files issues such as:

• Corrupted or missing coverage files.

• Coverage files and code source files not in-sync.

• Coverage files and assemblies are not in-sync.

In the Error List panel of VisualNDepend you have the possibility to deactivate false warnings to avoid being warned again and again during future analysis.

Running an Analysis with NDepend.Console.exe

NDepend comes with 2 executables that reflect the duality report/UI scenarios mentioned above: NDepend.Console.exe and VisualNDepend.exe. NDepend.Console.exe can run an analysis. It is a classic console executable that takes command line arguments. The minimal input is an absolute path to the NDepend project file that defines the code base to be analyzed. Several command line arguments can be provided and they are listed here: http://www.ndepend.com/NDependConsole.aspx. Basically these arguments will let you override folders where assemblies to be analyzed are stored, override the output folder where data produced by the analysis will be persisted and provide a XSL sheet to customize the report.

A simple exec command is needed to integrate NDepend.Console.exe into your build process. The NDepend redistributable also comes with a NAnt task and a MSBuild task.

More information about integrating NDepend into a CruiseControl.NET build are provided in the CruiseControl.NET documentation here .

Also Laurent Kempé (MVP) took the time to detail NDepend integration into a TeamCity build process here (merci Laurent :o)

Analysis Option

To handle real-world scenarios, there are several analysis options. Options can be tuned through the VisualNDepend > Project Properties panel (Ctrl+Shift+P). Options are then persisted into the NDepend project file and can be harnessed at analysis time.

The first option is the ability to choose between absolute and relative paths to folders where analyzed assemblies are stored. Analyzed assemblies include both your own assemblies, but also tier assemblies that are used by your application (like mscorlib.dll or Log4Net.dll). If you choose the option value relative path, paths are relative to the folder where the NDepend project is stored. This option is useful when the NDepend analysis is performed on several machines (build servers, developer machines…) where the root folder of the whole development shop can vary.

Notice that the folders where the .NET Framework assemblies are stored are not impacted by relative path option. NDepend automatically adapts folders path from the current machine .NET framework installation.

In the VisualNDepend > Project Properties > Analysis sub-panel, you’ll find 3 interesting options beside the project name and output folder.

The Analysis Comparison option lets define the previous analysis result on which to compare the current analysis performed. This is useful if you’ve defined some CQL rules about evolution of your code base like for example, like making sure that all new or refactored methods are 100% covered by tests:

WARN IF Count > 0 IN SELECT METHODS WHERE

(WasAdded OR CodeWasChanged) AND PercentageCoverage < 100

Basically, here WasAdded Or CodeWasChanged means was added or refactored compare to the last analysis result. The last analysis result to compare with can be a particular result (like the analysis of the last release we’ve made), a result made N days ago or the last analysis result available. Below, I'll give details about detecting  CQL result violations in the report.

The Code Coverage option lets specify the NCover or VisualStudio coverage file(s) from which NDepend will gather test coverage statistics. More detail about how to obtain these coverage files can be found in the NDepend documentation here: http://www.ndepend.com/Coverage.aspx

The Source File Rebasing option is useful if the code compilation and the NDepend analysis are executed on different machine. NDepend gathers information from the assemblies, but also from the source files if they are available. NDepend knows about source files from the PDB files produces by the compilation. PDB files contain absolute paths to source files. PDB files are initially used by the debugger to link IL compiled code with source files code. If the code compilation and the NDepend analysis are executed on 2 different machines, it might happen that source files locations are different between the 2 machines. In this case absolute source files paths contained in the PDB files should be rebased, hence the need for the Source File Rebasing option. More information about source files rebasing can be found here.

Report customization

Report can be customized through the VisualNDepend > Project Properties > Report sub-panel. You can choose to activate and re-order 11 pre-defined sections like Application and Assemblies metrics, some diagrams (dependencies, metrics, abstractness vs.instability…)  and more.

It is recommended to de-activate the Type Metrics and Type Dependencies sections since they can become pretty large if you have more than a thousand types in your application. Typically, browsing type metrics and dependencies is a scenario better addressed through the VisualNDepend.exe UI.

The section CQL Queries and Constraints is especially useful to detected CQL rules violation. For each CQL rule you can choose whether you want to display violation in report (Active tickbox) . In case of violation you can choose if you want to display list of items selected in report (be careful, the list can be pretty long, hence the usage of SELECT TOP 10 in pre-defined rules), statistics about this list of items, and a selection view of items selected:

Here is what a CQL rule violated looks like in report:

For most users the classic report provides enough information and when needed to dig into more details, the VisualNDepend UI comes to the rescue. But still, you can choose to build your own report by providing your own XSL sheet. It can be inspired from the one in $NDepend Install Dir$/CruiseControl.NET/ ndependreport-ccnet.v2.xsl. Input information can be taken from the following xml files outputted by the analysis in the $AnalysisResultDir$ folder: TypesMetrics.xml, TypeDependencies.xml, InfoWarnings.xml (see below for more information on Info/Warnings), AssembliesDependencies.xml, AssembliesMetrics.xml, ApplicationMetrics.xml, AssembliesBuildOrder.xml (provide a build order for your assemblies if there are no dependencies cycles). The tickbox VisualNDepend > Project Properties > Analysis > Keep XML files used to build reports and store warnings must be ticked, else these XML files get deleted by NDepend after the report is built.

In the output folder you’ll notice also a file named CQLResults.xml that contains information used to display CQL rules violation in the report. You might want to harness the XML content of this file for getting automatically some results from some CQL rules.

Finally, I would like to mention the under the hood possibility to get 100% of the information used internally by VisualNDepend. By providing the command line argument /EmitVisualNDependBinXml to NDepend.Console.exe the file $AnalysisResultDir$\VisualNDepend.bin.xml will be built by the analysis. However there are no guaranties that the XML schema of this file will remain compatible and it will likely evolve in the future.