Code metrics from the command line

Yesterday, we made available a power tool that allows you to analyze assemblies in order to understand the complexity metrics associated with those assemblies. I’m going to describe how to use that power tool and the results it generates.

If you are not familiar with the code metrics capability built into Visual Studio, please see this MSDN documentation for details. This power tool uses the exact same functionality that you see inside the IDE, but encapsulates the code required to do the actual analysis in the metrics.exe application, described below.

Installation

Grab the power tool from this location.

After successfully installing the power tool, you will find two new files in your (%PROGRAMFILES%)\Microsoft Visual Studio 10.0\Team Tools\Static Analysis Tools\FxCop directory. One is the actual executable itself, Metrics.exe, the other MetricsReport.xsd, the XML Schema that defines the results format Metrics.exe generates.

I point this out as we don’t make that very obvious during install. We don’t slam anything into your Windows Start Menu, drop desktop icons, etc., so be aware of this directory location and executable as you start to play with this power tool.

Usage

To quickly see what this little power tool can do, locate any assembly you would like to generate code metrics and use the /f and /o command line options like so:

metrics /f:Metrics.exe /o:MetricsResults.xml

This will actually run the analysis over the metrics.exe itself and push the results into a file in the same directory called “MetricsResults.xml”. I point this out as you can run metrics analysis over any managed assembly whether you have the code for that assembly or not. However, if you do have the PDBs associated with those assemblies, that’s best. ( If you don’t have the PDBs you will get warning CA0068 ).

The /f and /o combination is the simplest form of usage, but many times, you need to provide the tool a little more information, such as where to find dependent assemblies. The /directory or /d option instructs the tool to look in the current directory to resolve necessary dependencies, while the /searchgac or /gac option will allow the tool to search the GAC to resolve those dependencies. You can also indicate per-file dependencies with the /reference or /ref option.

Results

But what do the results look like, and how do you consume them? Well, I would love to be able to say to you that the results are automatically pushed into your Team Foundation Server data warehouse or reported seemlessly in your reports directory of your team sharepoint projects, but alas, that is *not* the case. The results are XML in the form defined by the MetricsReport.xsd schema file. This is nice, as it allows you to consume and process these results any which way you’d like, but you do need to understand the form of the results to do so.

Double click on the MetricsReport.xsd file and it will appear in Visual Studio, like so:

If you click the  “Show Graph View” and “Top to Bottom” toolbar items, you’ll see the schema represented in a tree-like structure like so:

This is a great way to quickly understand the containment structure of the results you will see output from this tool which will be important when processing the XML. However, it doesn’t quite give you all the information you need in regards to the actual values you can expect, especially when wondering what types of metrics will be reported. For that, there’s nothing better than inspecting actual data generated.

Here’s a snippet of some results created from my example above:

The elements I highlighted are the five metrics that we are tracking, and these five metrics will be child elements of the five containers found in the xsd. Target ( the actual file you specified in the command line ), Module ( the .NET assembly found by following the target ), Namespace, Type, and Member.

Why did we provide this power tool?

Many customers are looking for a way to generate code metrics information as part of their build process. In this way, the complexity associated with assemblies coming out of your nightly builds could potentially be tracked and examined over time, which is where I think information like this is most valuable.

With this power tool, we’ve provided the raw capability, but we have a lot more to do to get to automating other parts of the desired workflow, such as providing default windows workflow activities that include this capability. But for now, if you find this information valuable, you can certainly incorporate this into any MSBuild or Windows Workflow ( Team Build is WF enabled in TFS 2010, by the way ) process.

Enjoy!

Cameron