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 path explained in the next section.
• Reference to baseline, trending, report... and all other settings

Notice that by default all paths referenced by a NDepend project are relative to the project location. Paths can be changed to absolute or can be prefixed with an environment variable.

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:

C:\Users\(username)\AppData\Local\Temp\NDependTemporaryProject\ NDependProject.ndproj

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.

NDepend Rules and Queries Persistence in Project File

By default, NDepend stores your CQLinq queries and rules in the project file.

Since NDepend v2022.2, untouched default queries and rules are persisted by default through their query ids, or just query names for the ones that don't have ids. The advantage is twofold:

• NDepend project files weight much less (from 570KB to 70KB roughly)
• Untouched default rules and queries are automatically updated to their new versions when a new version of NDepend is used.

The smallest query change - like just adding a space - is enough to consider a default query as touched and thus, not persist it through its id.

Any NDepend project created with NDepend version 2018.2.0 (released on the 11th September 2018) or higher, will see its untouched default queries updated to their id on the next query change. Since v2018.2.0 dozens of false positive situations have been fixed in the default rule set. Any concerned project will now benefit from these improvements.

A project setting let's go back to plain-text storage mode for untouched default queries and rules.

.ndrules NDepend Shared Rules 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.

Also when a rule file is created or modified, it inherits this query persistence kind setting from the current project setting.

.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

In the NDepend.API an IAnalysisResult object represents an analysis result loaded in memory. The code base can then be browsed from the property IAnalysisResult.CodeBase.

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).

Analysis Result Identifier

Since NDepend v2022.2 an analysis result can be identified with a human-readable identifier. Often such identifier will be a build number, a version or a milestone name.

The identifier is shown in the Dashboard for both the current snapshot and the baseline snapshot.

The new NDepend.Console command line argument /AnalysisResultId let's precise an identifier to the analysis result.

The NDepend APIs RunAnalysis() and RunAnalysisAndBuildReport() can now accept an identifier as an optional argument.

An identifier can be manually added to any existing analysis result file (.ndar extension). For example if the file name is NDependAnalysisResult_ProjectName_2022Oct11_13h14.ndar to assign the identifier "v2022.5.6" just rename to NDependAnalysisResult_ProjectName_2022Oct11_13h14_Id_v2022.5.6.ndar. As a consequence an analysis result identifier cannot contain characters that cannot fit in a file name \ / : * ? \" < > |. Also it must have a maximum of 32 characters.

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, Seconds: DD_HH_MM_SS.

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 Metrics

Trend 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. If the NDepend GitHub action is used, it is easy to download a project and its recent analysis result.
• .ndrules, .ndsettings: rules and settings files referenced by an NDepend project committed in the SCM must be committed as well.
• .ndar: If the analysis is performed with the NDepend GitHub action, the .ndar analysis result file and the report are stored as a GitHub artifact. They can be loaded locally as explained here. Else .ndar analysis result file are committed to SCM only if they represent something to share with the team, typically a baseline result. They can also 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.