NDepend – Code Query Language (CQL)

As I’ve mentioned in my first blog post, the Code Query Language (CQL) is used to help you write custom rules and query your own code. You can query your code on many specific ways. Also, the NDepend tool has nice CQL editor with excellent IntelliSense saupport.

Note: Please read the Getting Started before going forward with CQL.

You can use the CQL directly from Visual Studio.NET using the NDepend Add-In, you will first need to attach the NDepend Project to the current VS Solution

or you can work with Visual NDepend by starting the VisualNDepend.exe

If you work directly from Visual Studio.NET and you don’t have the CQL opened, you can open it from the NDepend’s menu

You have CQL Query Explorer and CQL Query Editor

CQL Query Explorer

CQL Query Editor

If you use Visual NDepend, after you load your project, you have the CQL at the top

so, you will have the same CQL Query Editor and CQL Query Explorer as in Visual Studio.NET

Next, lets see how CQL Editor works.

By default, we have the SELECT word at beginning. When I saw this for first time, I thought about SQL Queries. Well, the CQL works pretty much the same, which means if you know SQL syntax, you will know CQL too with no need of learning, especially when you see how much the IntelliSense helps here.

Now, once I click SPACEBAR to write next word after the SELECT, the CQL editor’s IntelliSense gives me the possible options to write (isn’t this great!?)

select the choice and and click enter, then again the IntelliSense is helping me for the next choice I have

So, as you can see, the SQL and CQL share both the same language syntax pattern

SELECT (TOP) <something> FROM <something> WHERE <something> ORDER BY <something>

Lets make some comparisons to SQL.

If you want in SQL to select all names from table person where name is equal to “hajan” you will do the following

SELECT Name FROM Person WHERE Name=”hajan”

In CQL, the target you are selecting is your CODE, so you may have something like this:

I want to select all the methods from a given namespace (or multiple namespaces) where the number of code lines is greater than 200, you can write the query on the following way:

SELECT METHODS OUT OF NAMESPACES “NamespaceName” WHERE NbLinesOfCode > 200

I’m testing this on the NopCommerce open source project:

And the result is

#1  - The CQL Query

#2 – When writing numeric values such as the number 200 in our example, the CQL gives you great way to increase/decrease the number using the slider you see in the picture above.

#3 – the result in our example is the SaveInfo() method which has 239 lines of code.

Now, lets write some useful real-world queries that you may probably need in your projects.

1. Find all methods who directly uses the NopSolutions.NopCommerce.Common.Utils.CommonHelper

CQL:

And the result is:

So, we have 519 methods who use directly the CommonHelper.

Similar keywords to IsDirectlyUsing that CQL uses are:

• IsDirectlyUsedBy
• IsDirectlyUsing
• IsUsedBy
• IsUsing
• DepthOfIsUsing
• DepthOfIsUsedBy

Now, I would like to mention one simple trick that may help you to do two things in same time: Generate and Learn CQL queries faster.

In the previous CQL code I’ve used the CommonHelper class. Now, lets go over the Class name with mouse right click and chose NDepend

As you can see from the picture, you have available options that NDepend gives you. I’ve selected Select Methods… and the conditions are shown. Let’s chose “…that I use directly” condition.

Right after you click the condition, the NDepend will automatically generate CQL code, and our generated code is

and the result is 137 methods

And last, I would like to show how to use some predefined queries to warn you when some condition is satisfied.

What is this? It means, WARN me if I have more than 0 (zero) result count of the query which follows.

The select query says SELECT all the types where the number of methods is greater than 500 and order by TypeRank.

TypeRank - TypeRank values are computed by applying the Google PageRank algorithm on the graph of types' dependencies. A homothety of center 0.15 is applied to make it so that the average of TypeRank is 1. (from NDepend CQL Specification Site)

In CQL v1.4, you can name your queries using <Name> … </Name> tags inside a line of a comment. Have in mind that unlike in SQL, the CQL comments are added with double slashes “//” same as  in C#.

You can read more about this and the CQL name conditions here.

Since NDepend’s CQL querying language gives unlimited possibilities, I will stop here. You can dig more by visiting Code Query Language 1.8 Specification Page. You can find there a lot of real-life examples and how to use the CQL query language for various scenarios.

I hope this was helpful and useful to you.

Kind Regards,
Hajan