使用 Visual Studio 中的 Roslyn 语法可视化工具浏览代码
本文概述了 .NET Compiler Platform(“Roslyn”)SDK 附带的语法可视化工具。 语法可视化工具是一种帮助用户检查和浏览语法树的工具窗口。 如果要理解想要分析的代码模型,该工具必不可少。 在使用 .NET Compiler Platform(“Roslyn”)SDK 开发应用程序时,它还可以提供调试帮助。 在首次创建分析器时打开该工具。 该可视化工具可帮助你理解 API 所使用的模型。 你也可以使用类似 SharpLab 或 LINQPad 这样的工具来检查代码和理解语法树。
安装说明 - Visual Studio 安装程序
在“Visual Studio 安装程序”中查找“.NET Compiler Platform SDK”有两种不同的方法:
使用 Visual Studio 安装程序进行安装 - 工作负荷视图
Visual Studio 扩展开发工作负荷中不会自动选择 .NET Compiler Platform SDK。 必须将其作为可选组件进行选择。
- 运行“Visual Studio 安装程序”
- 选择“修改”
- 检查“Visual Studio 扩展开发”工作负荷。
- 在摘要树中打开“Visual Studio 扩展开发”节点。
- 选中“.NET Compiler Platform SDK”框。 将在可选组件最下面找到它。
还可使“DGML 编辑器”在可视化工具中显示关系图:
- 在摘要树中打开“单个组件”节点。
- 选中“DGML 编辑器”框
使用 Visual Studio 安装程序进行安装 - 各组件选项卡
- 运行“Visual Studio 安装程序”
- 选择“修改”
- 选择“单个组件”选项卡
- 选中“.NET Compiler Platform SDK”框。 将在“编译器、生成工具和运行时”部分最上方找到它。
还可使“DGML 编辑器”在可视化工具中显示关系图:
- 选中“DGML 编辑器”框。 将在“代码工具”部分下找到它。
通过阅读本概述文章,熟悉 .NET Compiler Platform SDK 中用到的概念。 其中介绍了语法树、节点、标记和琐事。
语法可视化工具
使用“语法可视化工具”可以检查 Visual Studio IDE 当前活动的编辑器窗口中的 C# 或 Visual Basic 代码文件的语法树 。 通过单击“视图”>“其他窗口”>“语法可视化工具”,可以启动可视化工具 。 还可以使用右上角的“快速启动”工具栏 。 键入“语法”,然后应该会显示用于开启语法可视化工具的命令 。
此命令会以浮动工具窗口的形式打开语法可视化工具。 如果没有打开代码编辑器窗口,则显示为空白,如下图所示。
将此工具窗口停靠在 Visual Studio 中方便操作的位置,例如左侧。 可视化工具显示关于当前代码文件的信息。
使用 File>New Project 命令新建项目 。 可以创建 Visual Basic 项目或 C# 项目。 当 Visual Studio 打开此项目的主代码文件时,可视化工具会显示它的语法树。 可以打开此 Visual Studio 实例中的任何现有 C#/Visual Basic 文件,可视化工具会显示该文件的语法树。 如果在 Visual Studio 中打开了多个代码文件,可视化工具会显示当前活动的代码文件(键盘焦点所在的代码文件)的语法树。
- C#
- Visual Basic
如前面的图像所示,可视化工具窗口在顶部显示语法树,在底部显示属性网格。 属性网格显示当前在树中选中的项的属性,包括项的 .NET 类型和种类(SyntaxKind) 。
语法树包含三种类型的项:节点、标记和琐事 。 可以在使用语法一文中阅读更多关于这些类型的内容。 每个类型的项都会用不同的颜色表示。 单击“图例”按钮,概览所使用的颜色。
树中的每个项还会显示各自的范围 。 范围就是文本文件中的节点的索引(起始位置和结束位置) 。 在前面的 C# 示例中,所选择的“UsingKeyword [0..5)”标记的范围宽度为 5 个字符,即 [0..5) 。 “[..)”表示起始索引是范围的一部分,而结束索引并不包含在内。
在树中进行导航有两种方式:
- 展开或单击树中的项。 可视化工具自动选择与代码编辑器中的项的范围对应的文本。
- 单击或选择代码编辑器中的文本。 在前面的 Visual Basic 示例中,如果在代码编辑器中选择了包含“Module Module1”的那一行,则可视化工具会在树中自动导航至对应的 ModuleStatement 节点。
可视化工具会突出显示树中的项,该项的范围与编辑器中所选择的文本的范围最匹配。
可视化工具会刷新树,以匹配活动代码文件中的修改。 将调用添加至 Main()
.中的 Console.WriteLine()
。 键入内容时,可视化工具会刷新树。
请在键入 Console.
后暂停键入。 树中有一些粉色的项。 这说明在所键入的代码中存在错误(通常也成为“诊断”)。 这些错误会附加到语法树的节点、标记和琐碎内容中。 可视化工具会显示哪些项存在错误,并用粉色突出显示其背景。 将鼠标悬停在该项上可以查看任何粉色项的错误。 可视化工具只显示语法错误(这些错误与键入代码的语法相关);不会显示任何语义错误。
语法关系图
右键单击树中的任何项,然后单击“查看定向语法关系图” 。
- C#
- Visual Basic
可视化工具会以图解形式显示以所选项为根的关系子树。 针对 C# 示例中对应于 Main()
方法的 MethodDeclaration 节点,尝试以下步骤 。 可视化工具显示如下所示的语法关系图:
语法关系图查看器中有一个选项,可用于显示其着色方案的图例。 还可以将鼠标悬停在语法关系图中的每个项上,以查看该项对应的属性。
可以重复查看树中不同项的语法关系图,这些关系图会始终显示在 Visual Studio 的同一窗口中。 可以将此窗口停靠在 Visual Studio 中方便操作的位置,这样在查看新的语法关系图时就不需要在选项卡之间切换了。 通常放在底部(代码编辑器窗口的下面)会比较方便。
下面是可视化工具窗口以及语法关系图窗口所采用的停靠布局:
另一种选择在双监视器配置中,将语法关系图窗口放在第二个监视器上。
检查语义
语法可视化工具可以对符号和语义信息进行基本检查。 在 C# 示例中的 Main() 内键入 double x = 1 + 1;
。 然后在代码编辑器窗口中选择表达式 1 + 1
。 可视化工具突出显示了 AddExpression 节点 。 右键单击 AddExpression,然后单击“查看符号(如果有)” 。 请注意,大部分菜单项都带有“如果有”这个限定条件。 语法可视化工具检查节点的属性,包括不是所有节点都有的属性。
可视化工具中的属性网格更新如下图所示:该表达式的符号是 SynthesizedIntrinsicOperatorSymbol ,其中种类 = 方法 。
针对同一个 AddExpression 节点,请尝试“查看 TypeSymbol (如果有)” 。 如下图所示,可视化工具中的属性网格已更新,指示所选表达式的类型为 Int32
。
针对同一个 AddExpression 节点,请尝试“查看转换后的 TypeSymbol (如果有)” 。 属性网格的更新内容指示虽然表达式的类型为 Int32
,但转换后的表达式类型为 Double
,如下图所示。 此节点包含转换后的类型符号信息,因为 Int32
表达式所在的上下文要求必须转换为 Double
型。 此转换满足了为赋值运算符左侧的变量 x
指定的类型为 Double
型的要求。
最后,针对同一 AddExpression 节点,尝试“查看常数值(如果有)” 。 属性网格显示该表达式的值是一个值为 2
的编译时常数。
在 Visual Basic 中也可以重复上述示例。 在 Visual Basic 文件中键入 Dim x As Double = 1 + 1
。 在代码编辑器窗口中选择表达式 1 + 1
。 可视化工具突出显示了对应的 AddExpression 节点 。 对此 AddExpression 节点重复前面所述的步骤,应该能看到相同的结果 。
检查 Visual Basic 中的更多代码。 使用以下代码更新主 Visual Basic 文件:
Imports C = System.Console
Module Program
Sub Main(args As String())
C.WriteLine()
End Sub
End Module
此代码引入了映射到文件顶部的 System.Console
类型的 C
别名,并在 Main()
内使用此别名。 选择在 Main()
方法的 C.WriteLine()
中使用此别名 C
。 可视化工具会选择对应的 IdentifierName 节点 。 右键单击此节点,并单击“查看符号(如果有)” 。 属性网格指示此标识符绑定至 System.Console
类型,如下图所示:
针对同一 IdentifierName 节点,尝试“查看 AliasSymbol (如果有)” 。 属性网格指示该标识符为绑定至 System.Console
目标的别名 C
。 换而言之,属性网格会提供对应于标识符 C
的 AliasSymbol 的相关信息 。
检查对应于任何声明的类型、方法和属性的符号。 在可视化工具中选择对应节点,单击“查看符号(如果有)” 。 选择 Sub Main()
方法,包括该方法的正文。 针对可视化工具中对应的 SubBlock 节点,单击“查看符号(如果有)” 。 属性网格显示此 SubBlock 节点的 MethodSymbol 的名称为 Main
,返回类型为 Void
。
在 C# 中可以轻松重复上述 Visual Basic 示例。 为别名键入 using C = System.Console;
以代替 Imports C = System.Console
。 在 C# 中完成的上述步骤会在可视化工具窗口中产生相同的结果。
语义检查操作只能用于节点。 不能用于标记和琐事。 并非所有节点都有相关的语义信息可供检查。 如果某个节点不具备相关的语义信息,单击“查看 * 符号(如果有)”会显示空白的属性网格。
可阅读使用语义概述文档,详细了解执行语义分析的 API。
关闭语法可视化工具
在不使用可视化工具窗口检查源代码时,可以关闭该窗口。 当你在浏览代码、编辑和更改源时,语法可视化工具会更新显示的内容。 在你没有使用它的时候,这种情况会分散人的注意力。