A tour of the .NET Compiler SDK visualizer (#4579)

* checkin source from wiwki This commit addes the following: 1. Import syntax visualizer doc from roslyn-wiki: https://github.com/dotnet/roslyn/wiki/Syntax%20Visualizer 2. Add images. 3. provide include for installation instructions. 4. update index and TOC. * review and update The existing text was written when the SDK was in preview mode. All screenshots have been updated. The text was updated for product names, formatted, and reviewed. * proofread and update * respond to feedback. * respond to feedback * fix install notes * respond to feedback.
dotnet · BillWagner · Feb 21, 2018 · Feb 21, 2018 · Feb 21, 2018 · Feb 21, 2018
commit ce425b1f31472d5b2a9f761cb9c08f77507c90e4
diff --git a/docs/csharp/roslyn-sdk/get-started/semantic-analysis.md b/docs/csharp/roslyn-sdk/get-started/semantic-analysis.md
@@ -16,6 +16,10 @@ This tutorial assumes you're familiar with the Syntax API. The [get started with
 
 In this tutorial, you explore the **Symbol** and **Binding APIs**. These APIs provide information about the _semantic meaning_ of a program. They enable you to ask and answer questions about the types represented by any symbol in your program.
 
+You'll need to install the **.NET Compiler Platform SDK**:
+
+[!INCLUDE[interactive-note](~/includes/roslyn-installation.md)]
+
 ## Understanding Compilations and Symbols
 
 As you work more with the .NET Compiler SDK, you become familiar with the distinctions between Syntax API and the Semantic API. The **Syntax API** allows you to look at the _structure_ of a program. However, often you want richer information about the semantics or _meaning_ of a program. While a loose code file or snippet of VB or C# code can be syntactically analyzed in isolation, it's not meaningful to ask questions such as "what's the type of this variable" in a vacuum. The meaning of a type name may be dependent on assembly references, namespace imports, or other code files. Those questions are answered using the **Semantic API**, specifically the <xref:Microsoft.CodeAnalysis.Compilation?displayProperty=nameWithType> class.
@@ -28,9 +32,6 @@ Like <xref:Microsoft.CodeAnalysis.SyntaxTree?displayProperty=nameWithType>, <xre
 
 In this tutorial, you look at the "Hello World" program again. This time, you query the symbols in the program to understand what types those symbols represent. You query for the types in a namespace, and learn to find the methods available on a type.
 
-> [!IMPORTANT]
-> The following samples require the **.NET Compiler SDK** installed as part of Visual Studio 2017. You can find the .NET Compiler SDK as the last optional component listed under the **Visual Studio extension development** workload. The templates aren't installed without this component.
-
 You can see the finished code for this sample in [our GitHub repository](https://github.com/dotnet/docs/tree/master/samples/csharp/roslyn-sdk/SemanticQuickStart).
 
 > [!NOTE]

diff --git a/docs/csharp/roslyn-sdk/get-started/syntax-analysis.md b/docs/csharp/roslyn-sdk/get-started/syntax-analysis.md
@@ -38,6 +38,10 @@ The Syntax API creates a tree structure with the root representing the compilati
 
 That brief description provides an overview of the kind of information accessible using the Syntax API. The Syntax API is nothing more than a formal API that describes the familiar code constructs you know from C#. The full capabilities include information about how the code is formatted including line breaks, whitespace, and indenting. Using this information, you can fully represent the code as written and read by human programmers or the compiler. Using this structure enables you to interact with the source code on a deeply meaningful level. It's no longer text strings, but data that represents the structure of a C# program.
 
+To get started, you'll need to install the **.NET Compiler Platform SDK**:
+
+[!INCLUDE[interactive-note](~/includes/roslyn-installation.md)]
+
 ## Understanding syntax trees
 
 You use the Syntax API for any analysis of the structure of C# code. The **Syntax API** exposes the parsers, the syntax trees, and utilities for analyzing and constructing syntax trees. It's how you search code for specific syntax elements or read the code for a program.
@@ -64,9 +68,6 @@ While you can find anything in a code file using the Syntax APIs, most scenarios
 
 You can examine the nodes in a syntax tree in two ways. You can traverse the tree to examine each node, or you can query for specific elements or nodes.
 
-> [!IMPORTANT]
-> The following samples require the **.NET Compiler Platform SDK** installed as part of Visual Studio 2017. You can find the .NET Compiler SDK as the last optional component listed under the **Visual Studio extension development** workload. The templates aren't installed without this component.
-
 ### Manual traversal
 
 You can see the finished code for this sample in [our GitHub repository](https://github.com/dotnet/docs/tree/master/samples/csharp/roslyn-sdk/SyntaxQuickStart).

diff --git a/docs/csharp/roslyn-sdk/index.md b/docs/csharp/roslyn-sdk/index.md
@@ -130,10 +130,15 @@ found in the quickstarts, samples and tutorials sections.
 
 You can learn more about the concepts in the .NET Compiler Platform SDK in these four topics:
 
+ - [Explore code with the syntax visualizer](syntax-visualizer.md)
  - [Understand the compiler API model](compiler-api-model.md)
  - [Work with syntax](work-with-syntax.md)
  - [Work with semantics](work-with-semantics.md)
  - [Work with a workspace](work-with-workspace.md)
+
+To get started, you'll need to install the **.NET Compiler Platform SDK**:
+
+[!INCLUDE[interactive-note](~/includes/roslyn-installation.md)]
 
 <!--
 

diff --git a/docs/csharp/roslyn-sdk/media/alias-symbol.png b/docs/csharp/roslyn-sdk/media/alias-symbol.png
diff --git a/docs/csharp/roslyn-sdk/media/constant-value.png b/docs/csharp/roslyn-sdk/media/constant-value.png
diff --git a/docs/csharp/roslyn-sdk/media/converted-type-symbol-properties.png b/docs/csharp/roslyn-sdk/media/converted-type-symbol-properties.png
diff --git a/docs/csharp/roslyn-sdk/media/csharp-syntax-graph.png b/docs/csharp/roslyn-sdk/media/csharp-syntax-graph.png
diff --git a/docs/csharp/roslyn-sdk/media/docking-layout.png b/docs/csharp/roslyn-sdk/media/docking-layout.png
diff --git a/docs/csharp/roslyn-sdk/media/method-symbol.png b/docs/csharp/roslyn-sdk/media/method-symbol.png
diff --git a/docs/csharp/roslyn-sdk/media/symbol-properties.png b/docs/csharp/roslyn-sdk/media/symbol-properties.png
diff --git a/docs/csharp/roslyn-sdk/media/symbol-visual-basic.png b/docs/csharp/roslyn-sdk/media/symbol-visual-basic.png
diff --git a/docs/csharp/roslyn-sdk/media/syntax-visualizer.png b/docs/csharp/roslyn-sdk/media/syntax-visualizer.png
diff --git a/docs/csharp/roslyn-sdk/media/type-symbol-properties.png b/docs/csharp/roslyn-sdk/media/type-symbol-properties.png
diff --git a/docs/csharp/roslyn-sdk/media/visual-basic-syntax-graph.png b/docs/csharp/roslyn-sdk/media/visual-basic-syntax-graph.png
diff --git a/docs/csharp/roslyn-sdk/media/visualize-csharp.png b/docs/csharp/roslyn-sdk/media/visualize-csharp.png
diff --git a/docs/csharp/roslyn-sdk/media/visualize-visual-basic.png b/docs/csharp/roslyn-sdk/media/visualize-visual-basic.png
diff --git a/docs/csharp/roslyn-sdk/syntax-visualizer.md b/docs/csharp/roslyn-sdk/syntax-visualizer.md
@@ -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. 
+
+![The Syntax Visualizer tool window](media/syntax-visualizer.png)
+
+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)
+![Visualizing a C# syntax tree](media/visualize-csharp.png)
+# [Visual Basic](#tab/visual-basic)
+![Visualizing a VB syntax tree](media/visualize-visual-basic.png)
+---
+
+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.
8000
 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:
+
+![Viewing a C# syntax graph](media/csharp-syntax-graph.png)
+
+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:
+
+![Viewing a VB syntax graph](media/visual-basic-syntax-graph.png)
+
+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:
+
+![One docking layout for the visualizer and syntax graph window](media/docking-layout.png)
+
+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**.
+
+![Symbol properties](media/symbol-properties.png)
+
+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`.
+
+![TypeSymbol properties](media/type-symbol-properties.png)
+
+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.
+
+![Converted TypeSymbol properties](media/converted-type-symbol-properties.png)
+
+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`.
+
+![A constant value](media/constant-value.png)
+
+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.
+
+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:
+
+![Symbol properties](media/symbol-visual-basic.png)
+
+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`.
+
+![AliasSymbol properties](media/alias-symbol.png)
+
+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`.
+
+![Viewing symbol for a method declaration](media/method-symbol.png)
+
+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. 
diff --git a/docs/csharp/roslyn-sdk/toc.md b/docs/csharp/roslyn-sdk/toc.md
@@ -3,8 +3,8 @@
 ## [Work with syntax](work-with-syntax.md)
 ## [Work with semantics](work-with-semantics.md)
 ## [Work with a workspace](work-with-workspace.md)
-
-## Quick starts
+## [Explore code with the syntax visualizer](syntax-visualizer.md)
+## Quick Starts
 ### [Syntax analysis](get-started/syntax-analysis.md)
 ### [Semantic analysis](get-started/semantic-analysis.md)
 

diff --git a/includes/roslyn-installation.md b/includes/roslyn-installation.md
@@ -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:
+
+1. Check the box for **DGML editor**. You'll find it under the **Code tools** section.