Getting Started with NDepend on Linux and macOS

                    Getting Started  
  on Windows     

> dotnet ~/ndepend/net8.0/NDepend.Console.MultiOS.dll RegEval

More information about report generation in the section Run an analysis and build a report below. Notice that on Linux and macOS the 4 diagrams are not yet generated.

OrchadCore v1.8.0 compared with v1.7.0 NopCommerce v4.60.4 compared with v4.50.1 eShopOnWeb v2023 compared with v2022 NodaTime v3.1.0 compared with v3.0.0 NDepend Trend Charts in report For all sample reports are imported: code coverage data obtained from running tests issues obtained from running NDepend Default Rules issues obtained from Roslyn Analyzers: Microsoft.CodeAnalysis.NetAnalyzers, Meziantou.Analyzers and Roslynator. Such serverless report can be generated by invoking... NDepend.Console.exe $absolute-path-to-an-NDepend-project-file$ ...from your CI/CD running on Windows, Linux and Mac . You can generate the report using a trial license, a Build-Machine license or with the NDepend GitHub Action, which requires a GitHub Action license.

NDepend.Console.MultiOS.dll can also be used to to:

• Register evaluation or a license
• Create an NDepend Project File
• Integration with a CI/CD system
• Use the same NDepend project on various OS.
• Run the NDepend PowerTools that are explained here.
• Run your own program based on NDepend.API as explained here.

Registering evaluation or a license on a Linux or macOS machine

NDepend.Console.MultiOS.dll can be used with these arguments to register or unregister NDepend on a Linux or macOS machine (case-insensitive):

• --RegEval : Start the NDepend 14 days evaluation on the current machine.
• --RegLic XYZ : Register a seat of the license key XYZ on the current machine. Notice that the license XYZ must be a Build Machine license to run NDepend.Console.MultiOS.dll.
• --UnregLic : Unregister a seat of the license key already registered on the current machine.
• --RefreshLic : Refresh the license data already registered on the current machine. This is useful when the license changes upon renewal.

A switch can be used as-is like RegEval or preceded by variousindicator like /RegEval, -RegEval or --RegEval.

Each of these operation requires internet access to do a roundtrip with the NDepend server. If the current machine doesn't have internet access, a procedure is proposed to complete the operation by accessing manually the NDepend server from a connected machine.

Create a Project File with NDepend.Console.MultiOS

NDepend.Console.MultiOS.dll can be used to create an NDepend project file (.ndproj extension). This is useful to create NDepend project(s) on-the-fly from a script.

Here are arguments required to created a project with NDepend.Console.exe:

• The first argument must be --CreateProject or -cp (case-insensitive).
• The second argument must be the project file path to create. The file name must have the extension .ndproj. If you need to specify a path that contains a space character use double quotes "...". The specified path can be either an absolute Linux or macOS path (like "/mnt/c/dir/MyProjectFile.ndproj"), a path relative to the current directory (obtained with System.Environment.CurrentDirectory), or a file name in the current directory.

• Then at least one or several sources of code to analyze must be precised. A source of code to analyze can be:

  • A path to a Visual Studio solution file.

    The solution file extension must be .sln.
    The vertical line character '|' can follow the path to declare a filter on project names (as explained in this section). If no filter is precised the default filter -test is defined. If you need to specify a path or a filter that contains a space character use double quotes "...".
    Example: "..\My File\MySolution.sln|filterIn -filterOut".

  • A path to a Visual Studio project file. The project file extension must be within: .csproj .vbproj .proj

  • A path to a compiled assembly file. The compiled assembly file extension must be within: .dll .exe .winmd

  Notice that source of code paths can be absolute or relative to the project file location.
  If you need to specify a path or a filter that contains a space character use double quotes "...".

Here is a short example that illustrates arguments to create a project:

>dotnet ~/ndepend/net8.0/NDepend.Console.MultiOS.dll -cp /mnt/c/temp/ndepend/MyProj.ndproj "../src/MySolution.sln|-filter"
"/mnt/c/My Dir/MyAssembly1.dll" /mnt/c/MyDir/MyAssembly2.dll

To modify the various properties of an NDepend project file created with NDepend.Console.exe.MultiOS the options are: Open the project with VisualNDepend.exe on a Windows machine and use the panel Project Properties. Create a C# program based on NDepend.API as explained here. .ndproj are XML formatted and can be edited manually.

Running an analysis and build a report on a Linux or macOS machine

NDepend.Console.MultiOS.dll can be used to run an NDepend analysis and build a report on a Linux or macOS machine.

Mandatory argument

• The path to the input .ndproj NDepend project file.

  It must be specified as the first argument. If you need to specify a path that contains a space character use double quotes ".. ..". The specified path can be either an absolute Linux or macOS path (like "/mnt/c/dir/MyProjectFile.ndproj"), a path relative to the current directory (obtained with System.Environment.CurrentDirectory), or a file name in the current directory.

Optional arguments

NDepend.Console.MultiOS.dll accepts several optional arguments to override various aspects of the analysis from the command line (help; historic analysis results; force log trend metrics; compare with a baseline; output dir; silent; view report...).

These optional arguments are listed in the ./NDepend.Console.exe documentation that accepts the same optional arguments.

Integration within a CI/CD system

NDepend analysis can be performed from any CI/CD system to pass the rules of an NDepend project, pass quality gates and build a report.

To do so ~/ndepend/net8.0/NDepend.Console.MultiOS.dll must be invoked from a CI/CD task. The previous section explains how to invoke NDepend.Console.MultiOS.dll.

Since NDepend consumes .NET assemblies built by the compilation in DEBUG mode (see explanations here), and eventually code coverage files built at test time (see explanations here), the NDepend analysis must be fired after the compilation and eventually after tests execution under coverage.

The HTML + javascript report can then be found here per default $ProjectLocation$/NDependOut/NDependReport.html and its resources are in this folder $ProjectLocation$/NDependOut/NDependReportFiles. This report can be duplicated to make it part of your CI/CD output.

Notice that NDepend.Console.MultiOS.dll returns a non-zero exit code when at least one Quality Gate fails. This exit code can be used to eventually stop your build process in such situation.

Use the same NDepend project on various OS

Windows absolute paths are formatted like "C:\Dir" and "\\Server\Share" while Linux or macOS absolute paths are formatted like "/mnt/c/dir/". Thus absolute paths are compatible between Linux and macOS, but incompatible with Windows (and vice-versa). As a consequence if a NDepend project or analysis result is aimed to be used on various OS there are a few caveats:

• If an NDepend project is used on various OS, it must reference only relative paths. These paths are then relative to the NDepend project file location.
• When using NDepend.Console.MultiOS.dll (or NDepend.Console.exe on Windows) to create a project, absolute paths provided are transformed to relative paths when possible.

• As explained in the documentation Understanding NDepend Analysis Inputs the primary sources of code analyzed are .NET assemblies, their PDB files and the source files referenced by the PDB files.

  When compiling an assembly, the PDB files are referencing absolute source files paths with the format of the underlying OS. NDepend extracts and stores these absolute paths in the analysis results it produces.

  As a consequence if an NDepend analysis result is consumed on a various OS, (for example an analysis result produced on Linux is opened with VisualNDepend.exe on Windows) the absolute source file paths that it contain are incompatible and cannot be used to locate or open the source file path.

  However an NDepend analysis result stores all source files analyzed zipped. Even when the absolute paths are OS incompatible, the source files can still be unzipped and even compared between two analysis results.