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:
#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
And the result is:
So, we have 519 methods who use directly the CommonHelper.
Similar keywords to IsDirectlyUsing that CQL uses are:
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.