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
- 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:
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
- Corrupted or missing
- 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.
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
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
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.