NDepend OSS Power Tools
NDepend Power Tools are a set of short and open-source static analyzers, packed into the Visual Studio solution that you can find under: $NDependInstallPath$\NDepend.PowerTools.SourceCode\NDepend.PowerTools.sln
The Power Tools demonstrate NDepend API usage and capabilities. The solution contains the shared project NDepend.PowerTools.Shared.shproj used from two projects:
- NDepend.PowerTools.csproj that compiles to the net472 assembly $NDependInstallPath$\NDepend.PowerTools.exe
NDepend.PowerTools.MultiOS.csproj that compiles to the net7.0 cross-platform dll with entry point $NDependInstallPath$\net7.0\NDepend.PowerTools.MultiOS.dll. This dll can be executed on Windows, Linux and MacOS through the dotnet command.
This project defines the conditional symbol NETCORE to avoid invoking APIs that are only supported within a .NET Framework / Windows OS context. Also not all power tools can run on Linux or MacOS and we use the flag IPowerTool.AvailableOnLinuxMacOS to check before eventually running a power tool.
Power Tools List
When running NDepend.PowerTools.exe or NDepend.PowerTools.MultiOS.dll a console windows appear and list Power Tools:
- a) Technical Debt Evolution Since Baseline: Load the current snapshot and the baseline snapshot of a project and compute issues and technical-debt on both snapshots and then show results. The source code of this Power Tool is a good start for any custom program that would aim at chruning the technical-debt and the issues.
- b) Query Code with CQLinq:
Edit CQLinq and CQL code query and show results.
It is recommended to edit CQLinq queries and see query result
in NDepend UI thanks to intellisense and result display facilities.
But we notice many programmers enjoy console edition mode!
- F5 key to run the edited query.
- PageUp/PageDow shows previous/next edited queries
- Previous/next edited queries list is initially filled with queries of the NDepend project.
- Ctrl+C - Ctrl+V - Ctrl+X Copy/Paste/Cut from clipboard supported.
- Ctrl+A select all and Tab+Arrow selection supported.
- Ctrl+Z Ctrl+Y Undo/Redo supported.
- ESC key to exit the power tool.
- c) Detect Assemblies Versionning and Deployment Issues: Check several potential deployment issues, including making sure that all assemblies and their references share the same version number
- d) Public API Changes (including API Breaking Changes): Show API changes and especially highlights API breaking changes. Each kind of API change is matched by a CQLinq rule or query available in any default NDepend project.
- e) Search for Duplicate Code:
Use an original heuristic to spot potential duplicate code.
Two methods that are calling a same set
of N methods (or fields) is considered suspect.
The more methods are calling this set, the more it is considered suspect.
More explanation can be found here: Original Algorithm to Find .NET Code Duplicate
- f) Find potential Dead Code: Algorithms used to find dead types, methods and fields are the same as the default CQLinq dead code rules algorithms.
- g) Code Base Evolution: Retrieves the multiple analysis results available for a project and display the evolution of a few application metric. It would be easy to process some graphical charts with these metrics evolution or to follow the evolution of one or several particular code elements or to detect portions of the code that keeps being refactored again and again
- h) Code Review Methods Changed:
- Up/Down to browse methods changed
- Enter to compare older and newer versions of a method changed
The tool that compares older and newer source versions of the source file can be defined in: NDepend UI > Tools > Options > Build Comparison > Source Files Compare Tool
Note that the panel Search by Changes in NDepend UI proposes more options to code review diff
- i) Search Types by Name:
Search types by name matching.
- Up/Down to browse types
- Enter to open type source file decl
- The search is case insensitive
- Third-party types are not taken account
- Several matchers strings can be separated by spaces
- ESC to quit
Note that the Search panel in NDepend UI proposes many more options
- j) AppWords: List terms used in assemblies, namespaces, types, methods, fields identifiers sorted by relevancy, excepting common infrastructure terms. AppWords is useful to list domain words of an application. It can also be useful to detect forbidden words and spelling errors.
- k) Analyze Code on my Disk:
Gather Visual Studio solutions and projects from Visual Studio
Most Recently Used (MRU) list, for each Visual Studio installed version.
Gather all Debug assemblies from these solutions and analyze them.
Note that this is the only Power Tools that cannot work with .NET 7.0 or .NET 6.0 or .NET 5.0 because it consumes some API only available on Windows to read the Visual Studio MRU list.
- l) List stored Trend Values: List stored Trend Values for a project. This power tool aims at showing how to use NDepend.API to access programmatically stored trend values.
- m) Dated Log Trend Values: First analyze a project, obtain an analysis result, then compute Trend Values from the analysis result and log them, with any past or future date. This power tool aims at showing how to use NDepend.API to persist programmatically trend values.
- n) Analyze Assemblies in Folder: Gather .NET assemblies under the folder specified by the user and analyze them. User can choose to do a recursive search in the folder
- o) Analyze all .NET Framework Assemblies: Gather all assemblies of the most recent .NET Fx installation on the disk and analyze them!
- p) Convert CQL queries/rules of a project to CQLinq queries/rules: For a project file named XYZ.ndproj a backup file named XYZ.bkp#.ndproj is created before the conversion.
- q) .NET Framework v3.5 and v4.X installed, Core Public API Changes: Analyze .NET Framework v3.5 and v4.X installed, core assemblies and report API changes. v4.X can be v4.0 or v4.5+ depending which version is installed. v4.5+ doesn't live side-by-side with v4.0, it replaces it
- r) .NET v5.0 and v6.0 installed Public API Changes: Analyze .NET v5.0 and v6.0 installed, core assemblies and report API changes. Note that some API Breaking Changes might be due to types moved from one assembly to another.
Power Tools Usage of NDepend.API
This Dependency Matrix screenshot below shows which power tool uses which part of the NDepend.API.
- Rows are classes, interfaces and enumerations of the NDepend API consumed.
- Columns are namespaces: each namespace is a power tool.
- Numbers in cells represent the number of members of the row type used by the column namespace. If a cell number is 0 it means that only the type is used like in IList<APIType> or typeof(APIType) usage.
If you would like to use a particular API feature ( Project, Analysis, Code Model, Code Query, Technical Debt, Trend...) you can refer to this matrix and then browse the power tools source code.
Deploying Power Tools
When running NDepend.PowerTools.exe or NDepend.PowerTools.MultiOS.dll the executable first loads dynamically $NDependInstallPath$\Lib\NDepend.API.dll. This dynamically load requires some explicit code explained in this section How to build and deploy your programs that use NDepend.API?.
Once NDepend.API.dll is loaded in the process it will load other NDepend assemblies to run. In other words the power tools source code only references the NDepend.API.dll but at runtime the logic inside other NDepend assemblies is executed. This note is important to understand that all NDepend assemblies must be deployed to run power tools, not just \Lib\NDepend.API.dll