Files generated and used by NDepend
NDepend relies on the file system to store its projects, results and all data. This makes it easy for the user to update or share any NDepend related data. This documentation explains how this file-based storage work.
.ndproj NDepend Project File
The .ndproj project files are XML files that contain all NDepend project info:
- Reference to Visual Studio solution(s) or assemblies to analyze (see more in NDepend Assemblies Resolving).
- Output directory relative or absolute path explained in the next section.
- Reference to baseline, trending, report... and all other settings
NDepend Project File attached to a Visual Studio Solution
Often, an .ndproj file is attached to a Visual Studio solution. In such case the .sln solution file contains a section that looks like:
GlobalSection(NDepend) = preSolution Project = ".\SolutionName.ndproj" EndGlobalSection
Such project file gets created or attached from this NDepend Visual Studio extension menu:
When a user loads a solution file without the NDepend Visual Studio extension installed, no error or warning is shown. Also the NDepend section in the .sln file is kept when closing the solution.
Project File Manual Creation
An NDepend Project file is usually created from the NDepend Start Page:
The button New NDepend Project let's create a new project from scratch.
Notice also the One-Off Analysis buttons that let's create a temporary project that is stored usually in this location:
Such project file is temporary and gets erased the next time a temporary project gets created. It is usefull to quickly analyze a solution or some assemblies and forget.
Project File Automatic Creation
An NDepend Project file can also be created automatically by invoking NDepend.Console.exe with the cp argument.
An NDepend Project file can also be created programmatically by running a program relying on the NDepend.API.
.ndrules NDepend Shared Rules File
By default, NDepend stores your CQLinq queries and rules in the project file.
Rule Files can be created and shared among NDepend projects through .ndrules files. This is useful to define company-level standard rules sets shared amongst projects, and get them applied by all teams. Read more about rule files here.
.ndsettings NDepend Shared Technical-Debt Settings File
Technical-debt computation and results can be fine-tuned through the settings in the panel NDepend > Project Properties > Issues and Debt. These debt settings can be shared among several NDepend projects through .ndsettings files as shown at the top of the screenshot below. Read more about Technical-Debt settings here
.ndar NDepend Analysis Result File
When an NDepend analysis is ran, the result gets persisted in a .ndar file. The .ndar binary format is proprietary and optimized. Changing any byte in this file will corrupt it and will make it unreadable by NDepend.
An .ndar file contains the entire code model resulting from the analysis, with classes, methods, dependencies, code metrics... When an NDepend project is loaded in the UI, the most recent .ndar is automatically loaded.
From the NDepend start page, any .ndar file can be loaded by right clicking a project item and then Load Previous Analysis Result. With the browse button you can even load a .ndar file not associated with the chosen project if needed.
In the Dashboard, most recent analysis results are listed. Clicking an analysis result provokes loading it to define the baseline. Clicking the button define let's define the baseline policy in the project file. The baseline policy defines the baseline that will be loaded when the project gets loaded in the UI or when building a report. It is usually either the analysis result obtained 30 days ago or a particular analysis result representing a snapshot of the last version released.
NDepend.API and Analysis Result
An IAnalysisResult object can be obtained from an IAnalysisResultRef object through the method IAnalysisResultRef.Load(). This loading operation is fast and takes at most a few seconds on very large code base (like 2 seconds for 10K+ classes).
The IAnalysisResultRef object representing the most recent analysis result for a project can be obtained with the extension method IAnalysisResultRef.TryGetMostRecentAnalysisResultRef(this IProject).
The IAnalysisResultRef object used for baseline for a project can be obtained through the extension method IAnalysisResultRef.TryGetAnalysisResultRefToCompareWith(this IProjectBaseline) where IProjectBaseline is either project.BaselineDuringAnalysis or project.BaselineInUI.
Finally the IAnalysisResultRef objects representing all historic analysis results available for a project (explained in the next section) can be obtained with the extension methods GetAvailableAnalysisResultsRefs(this IProject) or GetAvailableAnalysisResultsRefsGroupedPerMonth(this IProject).
The Output Directory Structure
By default the output directory of an NDepend project is set to .\NDependOut. This path is relative to the project file path location.
Files contained in this directory represent the output files obtained during the most recent analysis of this project. In the screenshot below we can see
- The .ndar analysis result file.
- SourceFiles.zip contains all source files analyzed zipped. When an analysis result is used as a baseline, zipped sources are used to diff changes.
- The file InfoWarnings.xml that contains the logs emitted during the analysis.
Historic Analysis Results
In the screenshot above, the directory named 2021_09 contains historic analysis results made during the month of September 2021. Here is its content. The sub-directories are named with the analysis date Days, Hours, Minutes: DD_HH_MM.
Per default historic analysis results are stored with the frequency: at most one per day. This frequency can be updated in the NDepend Project Properties > Analysis > Historic Analysis settings.
Trend MetricsTrend metrics values are stored in XML files in the directory .\NDependOut\TrendMetrics shown in the screenshot above. There is one XML file per year and it is named like named like NDependTrendData2022.xml. To read or modify these values programmatically, instead of reading/writing the XML data it is recommended instead to use the NDepend.API, demonstrated for example by the following Power Tools source code:
- List stored Trend Values
- Dated Log Trend Value
XML Files used to Build the Report
In an analysis result directory, it is possible to keep the XML files used to build the report through an XLST sheet, by setting the flag NDepend Project Properties > Report > Keep XML files used to build report. However it is recommended to use the NDepend.API instead if you wish to programmatically access any NDepend data (code model, diff, trend, metrics, issues, debt...)
The NDepend Options Persisted File
NDepend options are stored in a file name VisualNDependOptions.xml file. It contains settings defined in the Options dialog. The last option panel (below) explains how to access it and share it accross several machines.
Guidances to share NDepend files in your Source Code Management (SCM)
- .ndproj: An NDepend project file attached to a Visual Studio solution is a good candidate to be committed with the solution file in the SCM tool. In such case, if a user that doesn't have NDepend installed gather the solution and the NDepend project file, nothing will happen.
- .ndrules, .ndsettings: rules and settings files referenced by an NDepend project committed in the SCM must be committed as well.
- .ndar: Usually .ndar analysis result file are not committed to SCM. They can be shared easily if the project output directory is a UNC path (Universal Naming Convention) pointing to a shared folder like \\Server\Share\NDependOut.
- NDependTrendDataYYYY.xml, SourceFiles.zip: Like .ndar files, it is recommended to share other files in a project output directory through shared folders so all users can access them from their machines.
- VisualNDependOptions.xml, this file can be easily copy/pasted from one machine to another. Because it is located in the AppData directory it is not a good candidate to be committed with the solution file in the SCM tool.