Repository navigation
A tour of the .NET Compiler SDK visualizer #4579
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
a58aebd
1de5b2f
1d81c4d
6a10d80
990590f
8d412f5
e5eee2b
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,130 @@ | ||
| --- | ||
| title: Explore code with the Roslyn syntax visualizer in Visual Studio | ||
| description: The syntax visualizer provides a visual tool to explore the models the .NET Compiler Platform SDK generates for code. | ||
| author: billwagner | ||
| ms.author: wiwagn | ||
| ms.date: 03/07/2018 | ||
| ms.topic: conceptual | ||
| ms.prod: .net | ||
| ms.devlang: devlang-csharp | ||
| ms.custom: mvc | ||
| --- | ||
| # Explore code with the Roslyn syntax visualizer in Visual Studio | ||
|
|
||
| This article provides an overview of the Syntax Visualizer tool that ships as part of the .NET Compiler Platform ("Roslyn") SDK. The Syntax Visualizer is a tool window that helps you inspect and explore syntax trees. It's an essential tool to understand the models for code you want to analyze. It's also a debugging aid when you develop your own applications using the .NET Compiler Platform (“Roslyn”) SDK. Open this tool as you create your first analyzers. The visualizer helps you understand the models used by the APIs. You can also use tools like [SharpLab](https://sharplab.io) or [LINQPad](https://www.linqpad.net/) to inspect code and understand syntax trees. | ||
|
|
||
| [!INCLUDE[interactive-note](~/includes/roslyn-installation.md)] | ||
|
|
||
| Familiarize yourself with the concepts used in the .NET Compiler Platform SDK by reading the [overview](compiler-api-model.md) article. It provides an introduction to syntax trees, nodes, tokens, and trivia. | ||
|
|
||
| ## Syntax Visualizer | ||
|
|
||
| The **Syntax Visualizer** enables inspection of the syntax tree for the C# or VB code file in the current active editor window inside the Visual Studio IDE. The visualizer can be launched by clicking on **View** > **Other Windows** > **Syntax Visualizer**. You can also use the **Quick Launch** toolbar in the upper right corner. Type "syntax", and the command to open the **Syntax Visualizer** should appear. | ||
|
|
||
| This command opens the Syntax Visualizer as a floating tool window. If you don't have a code editor window open, the display is blank, as shown in the following figure. | ||
|
|
||
|  | ||
|
|
||
| Dock this tool window at a convenient location inside Visual Studio, such as the left side. The Visualizer shows information about the current code file. | ||
|
|
||
| Create a new project using the **File** > **New Project** command. You can create either a VB or C# project. When Visual Studio opens the main code file for this project, the visualizer displays the syntax tree for it. You can open any existing C# / VB file in this Visual Studio instance, and the visualizer displays that file's syntax tree. If you have multiple code files open inside Visual Studio, the visualizer displays the syntax tree for the currently active code file, (the code file that has keyboard focus.) | ||
|
|
||
| # [C#](#tab/csharp) | ||
|  | ||
| # [Visual Basic](#tab/visual-basic) | ||
|  | ||
| --- | ||
|
|
||
| As shown in the preceding images, the visualizer tool window displays the syntax tree at the top and a property grid at the bottom. The property grid displays the properties of the item that is currently selected in the tree, including the .NET *Type* and the *Kind* (SyntaxKind) of the item. | ||
|
|
||
| Syntax trees comprise three types of items – *nodes*, *tokens*, and *trivia*. You can read more about these types in the [Work with syntax](work-with-syntax.md) article. Items of each type are represented using a different color. Click on the ‘Legend’ button for an overview of the colors used. | ||
|
|
||
| Each item in the tree also displays its own **span**. The **span** is the indices (the starting and ending position) of that node in the text file. In the preceding C# example, the selected “UsingKeyword [0..5)” token has a **Span** that is five characters wide, [0..5). The "[..)" notation means that the starting index is part of the span, but the ending index is not. | ||
|
|
||
| There are two ways to navigate the tree: | ||
| * Expand or click on items in the tree. The visualizer automatically selects the text corresponding to this item’s span in the code editor. | ||
| * Click or select text in the code editor. In the preceding VB example, if you select the line containing "Module Module1" in the code editor, the visualizer automatically navigates to the corresponding ModuleStatement node in the tree. | ||
|
|
||
| The visualizer highlights the item in the tree whose span best matches the span of the text selected in the editor. | ||
|
|
||
| The visualizer refreshes the tree to match modifications in the active code file. Add a call to `Console.WriteLine()` inside `Main()`. As you type, the visualizer refreshes the tree. | ||
|
|
||
| Pause typing once you have typed `Console.`. The tree has some items colored in pink. At this point, there are errors (also referred to as ‘Diagnostics’) in the typed code. These errors are attached to nodes, tokens, and trivia in the syntax tree. The visualizer shows you which items have errors attached to them highlighting the background in pink. You can inspect the errors on any item colored pink by hovering over the item. The visualizer only displays syntactic errors (those errors related to the syntax of the typed code); it doesn't display any semantic errors. | ||
|
|
||
| ## Syntax Graphs | ||
|
|
||
| Right click on any item in the tree and click on **View Directed Syntax Graph**. | ||
|
|
||
| The visualizer displays a graphical representation of the subtree rooted at the selected item. Try these steps for the **MethodDeclaration** node corresponding to the `Main()` method in the C# example. The visualizer displays a syntax graph that looks as follows: | ||
|
|
||
|  | ||
|
|
||
| Try the same for the **SubBlock** node corresponding to the `Main()` method in the preceding VB example. The visualizer displays a syntax graph that looks as follows: | ||
|
|
||
|  | ||
|
|
||
| The syntax graph viewer has an option to display a legend its coloring scheme. You can also hover over individual items in the syntax graph with the mouse to view the properties corresponding to that item. | ||
|
|
||
| You can view syntax graphs for different items in the tree repeatedly and the graphs will always be displayed in the same window inside Visual Studio. You can dock this window at a convenient location inside Visual Studio so that you don’t have to switch between tabs to view a new syntax graph. The bottom, below code editor windows, is often convenient. | ||
|
|
||
| Here is the docking layout to use with the visualizer tool window and the syntax graph window: | ||
|
|
||
|  | ||
|
|
||
| Another option is to put the syntax graph window on a second monitor, in a dual monitor setup. | ||
|
|
||
| # Inspecting semantics | ||
|
|
||
| The Syntax Visualizer enables rudimentary inspection of symbols and semantic information. Type `double x = 1 + 1;` inside Main() in the C# example. Then, select the expression `1 + 1` in the code editor window. The visualizer highlights the **AddExpression** node in the visualizer. Right click on this **AddExpression** and click on **View Symbol (if any)**. Notice that most of the menu items have the "if any" qualifier. The Syntax Visualizer inspects properties of a Node, including properties that may not be present for all nodes. | ||
|
|
||
| The property grid in the visualizer updates as shown in the following figure: The symbol for the expression is a **SynthesizedIntrinsicOperatorSymbol** with **Kind = Method**. | ||
|
|
||
|  | ||
|
|
||
| Try **View TypeSymbol (if any)** for the same **AddExpression** node. The property grid in the visualizer updates as shown in the following figure, indicating that the type of the selected expression is `Int32`. | ||
|
|
||
|  | ||
|
|
||
| Try **View Converted TypeSymbol (if any)** for the same **AddExpression** node. The property grid updates indicating that although the type of the expression is `Int32`, the converted type of the expression is `Double` as shown in the following figure. This node includes converted type symbol information because the `Int32` expression occurs in a context where it must be converted to a `Double`. This conversion satisfies the `Double` type specified for the variable `x` on the left-hand side of the assignment operator. | ||
|
|
||
|  | ||
|
|
||
| Finally, try **View Constant Value (if any)** for the same **AddExpression** node. The property grid shows that the value of the expression is a compile time constant with value `2`. | ||
|
|
||
|  | ||
|
|
||
| The preceding example can also be replicated in VB. Type `Dim x As Double = 1 + 1` in a VB file. Select the expression `1 + 1` in the code editor window. The visualizer highlights the corresponding **AddExpression** node in the visualizer. Repeat the preceding steps for this **AddExpression** and you should see identical results. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. With tabs, each could be in its own tab. |
||
|
|
||
| Examine more code in VB. Update your main VB file with the following code: | ||
|
|
||
| ```vb | ||
| Imports C = System.Console | ||
|
|
||
| Module Program | ||
| Sub Main(args As String()) | ||
| C.WriteLine() | ||
| End Sub | ||
| End Module | ||
| ``` | ||
|
|
||
| This code introduces an alias named `C` that maps to the type `System.Console` at the top of the file and uses this alias inside `Main()`. Select the use of this alias, the `C` in `C.WriteLine()`, inside the `Main()` method. The visualizer selects the corresponding **IdentifierName** node in the visualizer. Right-click this node and click on **View Symbol (if any)**. The property grid indicates that this identifier is bound to the type `System.Console` as shown in the following figure: | ||
|
|
||
|  | ||
|
|
||
| Try **View AliasSymbol (if any)** for the same **IdentifierName** node. The property grid indicates the identifier is an alias with name `C` that is bound to the `System.Console` target. In other words, the property grid provides information regarding the **AliasSymbol** corresponding to the identifier `C`. | ||
|
|
||
|  | ||
|
|
||
| Inspect the symbol corresponding to any declared type, method, property. Select the corresponding node in the visualizer and click on **View Symbol (if any)**. Select the method `Sub Main()`, including the body of the method. Click on **View Symbol (if any)** for the corresponding **SubBlock** node in the visualizer. The property grid shows the **MethodSymbol** for this **SubBlock** has name `Main` with return type `Void`. | ||
|
|
||
|  | ||
|
|
||
| The above VB examples can be easily replicated in C#. Type `using C = System.Console;` in place of `Imports C = System.Console` for the alias. The preceding steps in C# yield identical results in the visualizer window. | ||
|
|
||
| Semantic inspection operations are only available on nodes. They are not available on tokens or trivia. Not all nodes have interesting semantic information to inspect. When a node doesn't have interesting semantic information, clicking on **View * Symbol (if any)** shows a blank property grid. | ||
|
|
||
| You can read more about APIs for performing semantic analysis in the [Work with semantics](work-with-semantics.md) overview document. | ||
|
|
||
| ## Closing the syntax visualizer | ||
|
|
||
| You can close the visualizer window when you are not using it to examine source code. The syntax visualizer updates its display as you navigate through code, editing and changing source. It can get distracting when you are not using it. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| ## Installation instructions | ||
|
|
||
| There are two different ways to find the **.NET Compiler Platform SDK** in the **Visual Studio Installer**: | ||
|
|
||
| ### Install using the Workloads view | ||
|
|
||
| The .NET Compiler Platform SDK is not automatically selected as part of the Visual Studio extension development workload. You must select it as an optional component. | ||
|
|
||
| 1. Run **Visual Studio Installer** | ||
| 1. Select **Modify** | ||
| 1. Check the **Visual Studio extension development** workload. | ||
| 1. Open the **Visual Studio extension development** node in the summary tree. | ||
| 1. Check the box for **.NET Compiler Platform SDK**. You'll find it last under the optional components. | ||
|
|
||
| Optionally, you'll also want the **DGML editor** to display graphs in the visualizer: | ||
|
|
||
| 1. Open the **Individual components** node in the summary tree. | ||
| 1. Check the box for **DGML editor** | ||
|
|
||
| ### Install using the Individual components tab | ||
|
|
||
| 1. Run **Visual Studio Installer** | ||
| 1. Select **Modify** | ||
| 1. Select the **Individual components** tab | ||
| 1. Check the box for **.NET Compiler Platform SDK**. You'll find it last under the **Compilers, build tools ,and runtimes** section. | ||
|
|
||
| Optionally, you'll also want the **DGML editor** to display graphs in the visualizer: | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Sorry for being late but it seems that this is the wrong option The issue mentions Code map is the right choice but maybe it's both. I haven't tested either.
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @MaStr11 Thanks for pointing this out. I did experiments, and only the DGML editor is needed. The Code Map feature depends on the DGML editor, so that will work too. |
||
|
|
||
| 1. Check the box for **DGML editor**. You'll find it under the **Code tools** section. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There is something broken with the tab. The text starting with "As shown in preceding.." isn't shown if you open the C# tab. It is only visible if you open the VB tab:
visual-basic
csharp
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed in PR #4824