Visualizing Roslyn Syntax Trees

Hello everyone! I hope you had a chance to catch the recent announcements around the .NET Compiler Platform (“Roslyn”). If not, I encourage you to view Anders’s presentation at Build 2014 (skip to 1:10:28). If you haven’t already, download the previews and take them for a spin!

What’s included?

The Roslyn compiler codebase is now open source. Check out Matt’s recent post for details around how to enlist in the open source project and modify the compiler. In addition to the End User Preview that Matt discussed at the beginning of his post, we are also releasing an SDK Preview. The End User Preview allows you to try out the new Roslyn IDE experience as well as some new language features (like multiline string literals!) that we are planning to include in the next version of Visual Basic. The SDK Preview on the other hand, contains tools and samples that will help you build your own applications, code refactoring extensions, quick fixes etc. atop the Roslyn APIs.

In this post, I’d like to introduce to you the Syntax Visualizer tool included in the SDK Preview. Detailed documentation for this tool is available on the Roslyn CodePlex site.

If you are new to Roslyn, I recommend starting with the Roslyn Overview document which provides a nice overview of how VB syntax and semantics are modelled in the Roslyn APIs. Also check out this talk that Dustin and Mads presented at Build 2014 for a tour of what’s in the above previews. More documentation and learning resources are available on the Roslyn CodePlex site.

What is the Syntax Visualizer?

The Syntax Visualizer is a Visual Studio extension that allows you to inspect and explore Roslyn syntax trees. This tool will be your faithful companion as you build your own applications atop the Roslyn APIs.

Why do I need a Syntax Visualizer?

In Roslyn, each type of syntactic construct in the language is modelled using a type named SyntaxNode. For example, VB method declarations are modelled using the type MethodBlockSyntax that is a derived type of SyntaxNode. A SyntaxNode can contain other SyntaxNodes. For example, the SyntaxNode for a class declaration contains SyntaxNodes for each method declaration in this class. The SyntaxNode for a method declaration in turn contains SyntaxNodes corresponding to each variable declaration inside this method and so on.

The source code in each file for a given program is thus modelled by a tree of SyntaxNodes. SyntaxNodes also contain SyntaxTokens and SyntaxTrivia which form the leaf nodes of syntax trees. SyntaxTokens represent significant text in the code (such as keywords, identifiers, literals and punctuation) while SyntaxTrivia represent text that is largely insignificant for normal understanding of the code (such as whitespace and comments).

The following image depicts what the syntax tree for a small snippet of VB code would look like. You can read more about SyntaxNodes, SyntaxTokens and SyntaxTrivia in the Roslyn Overview document.

Now the VB language supports a large variety of syntactic constructs (type declarations, method declarations, lambdas, variable declarations, method calls etc. etc.). So we have a corresponding large variety of SyntaxNodes in Roslyn and a variety of configurations in which these SyntaxNodes can appear within different syntax trees.

SyntaxNodes also happen to be the primary form of currency in the world of Roslyn APIs. Most tasks in the Roslyn APIs begin with SyntaxNodes. For example, you pass the SyntaxNode for the construct that you are interested in to other APIs such as SemanticModel to get richer semantic information about the construct. You specify which types of SyntaxNodes you wish to “handle” when you use the Roslyn Diagnostics and Code Fixes APIs to implement your own code fixes and code refactoring extensions.

When you combine these two aspects (i.e. a large surface area of syntactic constructs and the need to communicate in terms of these constructs all the time), it is clear that in order to be productive when building applications atop Roslyn, you need some easy way to inspect and navigate syntax trees. You need some easy way to answer questions like – What does the syntax tree for this piece of code look like? What is the type / Kind of the SyntaxNode that represents this language construct? This is where the Syntax Visualizer tool comes in handy.

What can I do with the Syntax Visualizer?

Once installed, the Syntax Visualizer allows you to inspect the syntax tree for any VB or C# code file that is open inside the Visual Studio IDE. You can select any piece of code in your file and the Syntax Visualizer will tell you what SyntaxNode it corresponds to and what the properties of this SyntaxNode look like. You can also select nodes from the Visualizer’s tree view and it will tell you what piece of code each node corresponds to.

The Syntax Visualizer also allows you to view a Directed Syntax Graph for selected sub-trees in case you want a more detailed graphical view of the nodes in this sub-tree.

Finally, the Syntax Visualizer also has some rudimentary support for inspection of Symbols and semantic information. You can read more about Symbols and APIs for performing semantic analysis in the Roslyn Overview document.

As I mentioned above, detailed documentation around how to install and use the Syntax Visualizer tool is available on Roslyn CodePlex site. Do try it out and use it as you explore and build rich code applications and extensions atop Roslyn! :)

Feedback

We would love to hear your feedback, ideas and suggestions. A list of the different ways in which you can provide feedback for the preview is available here. You can provide general feedback about the Syntax Visualizer here and report any issues you find over here.

Have fun with Roslyn! :)

--Shyam Namboodiripad on behalf of the Roslyn team