Skinner's Blog : DGML

Lovett is Blogging!

camerons — Mon, 19 Oct 2009 22:44:59 GMT

Chris Lovett, an architect on my team who has a glorious and long history with Microsoft, has finally joined the blogosphere! His expertise is all things .NET, but in particular he knows the code behind the new DGML graphs and dependency diagrams that are new in Visual Studio 2010 Ultimate.

His first two posts are fabulous, both of which include videos of Chris walking through some of the power of the DGML graphing technology. Be sure to check out his “teaser” post here, and a more in-depth post on our Standard Dependency Graphs.

Be sure to subscribe to his blog, as I know he’ll be putting up quite a bit more content in the weeks ahead.

You’ll be glad you did! :)

DGML, Containers, and VSTS 2010 Architecture Rendering

camerons — Mon, 23 Feb 2009 05:58:00 GMT

I previously pointed out how easy it was to manipulate and then render a .dgml file in the upcoming VSTS 2010 Architecture product. I want to continue that discussion by showing how easy it is to indicate to the product that you need to see nodes contained inside another, and a few other niceties along the way.

NOTE:

I do need to make one thing clear before we move forward. The difference between the core DGML and the additional capabilities you will find in the Architecture product is significant. The core DGML markup is limited to very few elements: DirectedGraph, Nodes, Node, Links, Link, Categories, and Category. Any additional markup beyond those basic elements is specific to the VSTS Architecture product.

So we had previously started with a graph that looked like this:

In order to tell the VSTS 2010 Architecture product's DGML rendering engine to draw a container around the "From" node, you first start by adding another Link element that has the Source attribute named "My Container" ( value doesn't matter ), and the Target attribute's value set to "From" ( this value does matter ). When you add that to your graph, you'll see this:

Not exactly containing the "From" node at this point, but we're not done. We need to add two more things to the markup.

The first step is to add a Category element to the Link element we just added, with a value of "Contains". Markup should now look like this:

The second step is to add a Nodes element with a single Node element contained inside, like so:

The resulting graph looks like this:

Let me point out a number of things, and bring them to your attention. In the image below, I've selected the contained "From" node:

This is a number that indicates how many nodes are actually contained in the container.
The Id of the container. The Id must match the Source attribute value of the Link element that has the "Contains" Category attribute applied to it. You can further include a Label attribute to the Node element in order to use a different value for the container's title than the Id value. VSTS 2010 Architecture defaults to the Id value when the Label attribute is not present.
A chevron that can be clicked resulting in a collapsed or expanded container. The container in this example is clearly expanded, allowing you to see the contents of the container in the graph. The expanded state is captured in the dgml file via the value of the Group attribute on the Node element set to "Expanded". Setting that value to "Collapsed" collapses the container, hiding its contents. Here's a shot that shows the results of setting that value to "Collapsed" as well as using the Label attribute on the Node element:
This is showing that I have selected the "From" node.
Because I have selected the "From" node, the link between the "From" node and "To" node shows up. If you aren't selecting "From" or the "To" nodes, that link disappears.

That's it! I should also add that you can have as many levels of containment as you'd like. Hope that helps!

Cameron

Directed Graph Markup Language ( DGML )

camerons — Tue, 27 Jan 2009 00:03:57 GMT

In this previous post I introduced you to the new format, and then this follow on post showed some of the examples of how the format is used to back some common graphs you can expect in the product.

In this post, I'm going to talk about a couple ways of controlling how links are rendered in the VSTS 2010 Architecture product.

The Graph Element

At the root of every DGML document is the DirectedGraph element. The default namespace for this document, attributed to this element, is http://schemas.microsoft.com/vs/2009/dgml. There are a number of xml attributes that is supported for this element that you will be able to quickly discover through the intellisense functionality off the file, but I want to call out the Background attribute in particular.

The Background attribute allows you to set the color of the background of the graph surface itself, either by name of ARGB hex values as documented here.

For example, this snippet of DGML:

Results in this graph:

Amazing, but good to know nonetheless. :)

The Link Element

A DGML graph is fundamentally all about nodes and the links between those nodes. You'll notice in the markup above the Links element containing one Link element. You'll also notice that the rendering engine that reads this particular DGML is smart enough to understand that a link cannot exist without nodes to connect, so automatically creates a "From" node and a "To" node based on the values found in the Source and Target attributes on the Link element.

The Link element has a number of interesting attributes that are directly supported. I'll call out a few here.

In order to change the background color of a link arrowhead, set the Backround attribute to "Red". You'll get something like this:

In order to change the color of the entire link, set the Stroke attribute to your desired color. If you only specify Stroke and not Background, the arrowhead fill color will also be changed to the Stroke color value.

You can also change the thickness of the link itself by assigning a value to the StrokeThickness attribute, like so:

You can also make the link a dashed line by playing with values in the StrokeDashArray attribute. The comma delimited values are converted to doubles, and are taken in relation to the StrokeThickness value, which is 1 by default. For example, setting StrokeDashArray to 5 with a default thickness of 1 results in something like this:

You can make the dashed line much more involved by adding more values to the dash array, as specified here. Here's an example:

Summary

Just a quick taste on how to control link rendering. We'll start to build up more knowledge as we go. In a future post, I want to show the Node element, and specifically get into how grouping / nesting is supported. Stay tuned!

Visualize Java Code

camerons — Tue, 20 Jan 2009 08:09:10 GMT

In this last post I introduced you to some *very* basic understanding of how DGML works. Now I want to take that knowledge out for a test drive. :)

What I've decided to do is a couple of things. I've decided I'm going to show how to visualize Java code using Antlr and Visual Studio 2008 and output a DGML file that the VSTS 2010 Architecture product found in the latest CTP can render.

Why am I doing this? Because I think it will be an excellent example ( you'll be the judge of that ) of how easy it will be to visualize all kinds of data, not just .NET languages. Java code, Work Items, MSBuild dependencies, on and on. Literally, this list is potentially enormous, gated only by imagination and effort ( aren't all good things this way? ).

In some future posts, I'll show how you can continue to tweak the DGML to do some things that you can't do in the current CTP, but can with current bits ( such as node grouping, advanced selection, etc. ).

Prerequisites

If you want to follow along on this little journey, you need to get the following things:

Visual Studio 2008
Latest JDK from Sun. Lots of options here but I ultimately went here and followed the steps.
Antlr 3.1.1 ( see below for instructions )
VSTS 2010 CTP ( follow link for instructions )
The Visual Studio 2008 solution that I used to create this post

Establish "Base of Operations"

I'm going to be very descriptive of what I'm doing 'cause the complication is not going to be in the implementation, but more in the "configuration of the parts".

Create a directory where work will be done. This will be our "Base of Operations". From here on out, I'll refer to this directory as %BOO%.
Download Antlr 3.1.1
1. If this link becomes stale, go to http://www.antlr.org and download the latest source distribution which includes the runtime jars that you'll need.
Extract the contents of the download to the %BOO% directory. When done, you should have the following contents in the %BOO%\antlr-3.1.1 directory:
Ensure Java is installed correctly
1. Open up a command prompt, CD to your %BOO% directory.
2. Type the following: java -?
3. If you don't see a typical "Usage" statement, then you probably have something installed wrong. For me, I had to make sure that the java bin directory was in my path, so I added that to my system environment variables.
Create a BOO.bat file that contains the following contents, and save to %BOO%:

set BOO=%CD%
set ANTLR_LIB=%BOO%\antlr-3.1.1\lib
set classpath=.;%ANTLR_LIB%\antlr-3.1.1.jar;%ANTLR_LIB%\antlr-3.1.1-runtime.jar;%ANTLR_LIB%\stringtemplate-3.2.jar;%ANTLR_LIB%\antlr-2.7.7.jar
Ensure Antlr is now ready to go.
1. At the command prompt, type BOO.bat and hit enter
2. Now type java org.antlr.Tool and hit enter
3. You should see this:
  
  If you don't, double check your BOO.bat file and make sure you don't have any typos.
Feel free to download the original Java.g file also available on the Antlr site. I've included the one I have modified in the solution I've made available in the "Prerequisites section":
1. Click here.
2. If it looks like a page just full of text, right click and say view source, then "Save As..." java.g into your %BOO% directory.
Unzip the solution I created into your %BOO% directory.
You'll need to replace the references to antlr.runtime, Antlr3.Runtime, Antlr3.Utility, and StringTemplate to those now in your %BOO% directory:
1. Add Antlr C# runtime references to the project.
  1. First we have to extract the runtime files found in the %BOO%\antlr-3.1.1\runtime\CSharp\dist\DOT-NET-runtime-3.1.1.zip.
    1. Extract the contents of that zip to %BOO%\antlr-3.1.1\runtime\CSharp\Libraries
    2. Once extracted, you should have a bin directory.
  2. Right click on the References node in the project
  3. Click on the Browse tab.
  4. Navigate to %BOO%\antlr-3.1.1\runtime\CSharp\Libraries\bin\net-2.0
  5. Add all the dlls found in that directory as references. There should be four dlls in there, as mentioned above ( If you do everything I've just mentioned just right, this step shouldn't be necessary, as the solution I provided should be relative )
OK, we're ready to build.
1. Rebuild the solution.
If all went well, you now have a parser that's ready to parse Java 1.5 code!

Results

The executable created after building the solution is Java2DGML.exe. If you drop to the command line, CD into the debug directory where the exe is found, run the following command:

Java2DGML.exe /f %BOO%\antlr-3.1.1\src\org\antlr\Tool.java > Tool.dgml

then open Tool.dgml in the VSTS 2010 CTP, here's what you'll see:

Here's the XPS file of that image as well.

The exe is by no means a robust piece of software. It currently understands how to gather information for simple Java classes ( i.e., not templated ), fields, and methods. No interfaces, enums, etc., but after this post, you should have all the info you need to take this example a bit farther.

Now let me explain the source a little bit...

Taxonomy of the Solution

Here is a shot of the Solution Explorer with the Java2DGML solution loaded:

Generated Files

Java.Tokens, JavaLexer.cs, and JavaParser.cs are all generated files. You can regenerate those files by executing the following command in you command window where you executed BOO.bat, in the %BOO%\Java2DGML\Java2DGML directory:

java org.antlr.Tool Java.g

Java.g

The Java.g file is where the grammar for parsing Java 1.5 is defined. This grammar file instructs the org.antlr.Tool object how to generate a parser in C# capable of parsing Java 1.5 code. More on this later.

DGMLContext.cs

A simple utility class used to gather information during the parse that is later used to generate the appropriate DGML. For every Java class, one DGMLContext object will be created to capture the relevant details.

DGMLFile.st

Antlr has a great mechanism built in called the StringTemplate framework. Check out this link for more details. This file is an example of a StringTemplate for DGML files. More on this later.

JavaParserImpl.cs

Antlr allows the C# developer to tell Antlr to create a partial class for its parser implementation so that additional behavior can be added and used in the grammar file more easily. I've taken advantage of that in this file.

Program.cs

This is the main program, where all the pieces come together.

Summary

This post is really meant to whet your appetite on some of the possibilities coming in the 2010 version of the Architecture product around visualization. Admittedly, I'm clearly just scratching the surface of this particular example ( Java source visualization ), but that's ok. From time to time, I may come back to this example and flesh out a little more in order to exemplify some deeper features.

In the meantime, I think in my next post I'll start to show some more of the features inherent in DGML, beyond just the simple nodes and links I've shown to date.

Stay Tuned!

Introduction to Directed Graph Markup Language ( DGML )

camerons — Tue, 16 Dec 2008 23:59:53 GMT

DGML, or "Directed Graph Markup Language" is what we are using in VSTS 2010 Architecture to render graphs like the one below:

The power of DGML is in its simplicity. Let me show you what I mean.

If you launch the VSTS 2010 CTP, open a project, click View->Architecture Explorer, then click the button shown below...

...you'll get a new dgml editor in the document well. You can then right click inside that document and select "View Code". Right click on the tab of the resulting editor and select "New Horizontal Tab Group". You'll have something similar to this:

If you add a Link element as a child element to the Links node, with a Source and Target attribute, you'll get something similar to this:

To add a few more elements, try this:

You'll notice the Nodes element isn't even needed to render the graph above. That is really all you need to know to visualize all kinds of data. Rest assured there is a lot more goodness to discuss about this technology, but the simplicity of it is one of the most exciting aspects as far as I'm concerned!

In my next post, I'm actually going to show you how, armed with just this little nugget of DGML information, you can visualize some Java code. Stay tuned!