Explorar o código com o visualizador de sintaxe Roslyn no Visual Studio

Este artigo fornece uma visão geral da ferramenta Visualizador de Sintaxe que é fornecida como parte do SDK do .NET Compiler Platform ("Roslyn"). O Visualizador de Sintaxe é uma janela de ferramentas que ajuda você a inspecionar e explorar árvores de sintaxe. É uma ferramenta essencial para entender os modelos de código que você deseja analisar. Serve também como uma ferramenta de depuração ao desenvolver suas próprias aplicações usando o SDK do .NET Compiler Platform ("Roslyn"). Abra essa ferramenta ao criar seus primeiros analisadores. O visualizador ajuda você a entender os modelos usados pelas APIs. Você também pode usar ferramentas como SharpLab ou LINQPad para inspecionar o código e entender árvores de sintaxe.

Instruções de instalação – Instalador do Visual Studio

Há duas maneiras diferentes de encontrar o SDK do .NET Compiler Platform no Instalador do Visual Studio:

Instalar usando o instalador do Visual Studio – exibição de cargas de trabalho

O SDK do .NET Compiler Platform não é selecionado automaticamente como parte da carga de trabalho de desenvolvimento de extensão do Visual Studio. Você deve selecioná-lo como um componente opcional.

1. Executar o Instalador do Visual Studio
2. Escolha Mudar
3. Verifique a carga de trabalho de desenvolvimento de extensão do Visual Studio .
4. Abra o nó Desenvolvimento de extensão do Visual Studio na árvore de resumo.
5. Marque a caixa do SDK da .NET Compiler Platform. Você o encontrará por último nos componentes opcionais.

Opcionalmente, você também desejará que o editor DGML exiba grafos no visualizador:

1. Abra o nó Componentes individuais na árvore de resumo.
2. Marque a caixa do Editor DGML

Instalar usando a guia Instalador do Visual Studio – Componentes individuais

1. Executar o Instalador do Visual Studio
2. Escolha Mudar
3. Selecione a guia Componentes individuais
4. Marque a caixa do SDK da .NET Compiler Platform. Você o encontrará na parte superior na seção Compiladores, ferramentas de build e runtimes .

Opcionalmente, você também desejará que o editor DGML exiba grafos no visualizador:

1. Marque a caixa do Editor DGML. Você o encontrará na seção Ferramentas de código .

Familiarize-se com os conceitos usados no SDK do .NET Compiler Platform lendo o artigo de visão geral . Ele fornece uma introdução a árvores de sintaxe, nós, tokens e informações acessórias.

Syntax Visualizer

O Visualizador de Sintaxe permite a inspeção da árvore de sintaxe para o arquivo de código C# ou Visual Basic na janela atual do editor ativo dentro do IDE do Visual Studio. O visualizador pode ser iniciado clicando em Exibir>Outros Windows>Visualizador de Sintaxe. Você também pode usar a barra de ferramentas de Início Rápido no canto superior direito. Digite "sintaxe" e o comando para abrir o Visualizador de Sintaxe deve aparecer.

Esse comando abre o Visualizador de Sintaxe como uma janela de ferramenta flutuante. Se você não tiver uma janela do editor de código aberta, a exibição estará em branco, conforme mostrado na figura a seguir.

Encaixe essa janela de ferramenta em um local conveniente dentro do Visual Studio, como o lado esquerdo. O Visualizador mostra informações sobre o arquivo de código atual.

Crie um novo projeto usando o comando Arquivo>Novo Projeto . Você pode criar um projeto do Visual Basic ou do C#. Quando o Visual Studio abre o arquivo de código principal para este projeto, o visualizador exibe a árvore de sintaxe para ele. Você pode abrir qualquer arquivo C#/Visual Basic existente nesta instância do Visual Studio e o visualizador exibe a árvore de sintaxe desse arquivo. Se você tiver vários arquivos de código abertos dentro do Visual Studio, o visualizador exibirá a árvore de sintaxe do arquivo de código atualmente ativo (o arquivo de código que tem o foco do teclado).

C#

Visual Basic

Conforme mostrado nas imagens anteriores, a janela de ferramentas do visualizador exibe a árvore de sintaxe na parte superior e uma grade de propriedades na parte inferior. A grade de propriedades exibe as propriedades do item que está selecionado atualmente na árvore, incluindo o Tipo .NET e a Espécie (SyntaxKind) do item.

As árvores de sintaxe incluem três tipos de itens: nós, tokens e trívia. Você pode ler mais sobre esses tipos no artigo Trabalhar com sintaxe . Os itens de cada tipo são representados usando uma cor diferente. Clique no botão 'Legenda' para obter uma visão geral das cores usadas.

Cada item na árvore também exibe seu próprio span. A extensão é composta pelos índices (a posição inicial e final) do nó no arquivo de texto. No exemplo de C# anterior, o token "UsingKeyword [0..5)" selecionado tem um Span com cinco caracteres de largura, [0..5). A notação "[..)" significa que o índice inicial faz parte do intervalo, mas o índice final não é.

Há duas maneiras de navegar na árvore:

• Expanda ou clique em itens na árvore. O visualizador seleciona automaticamente o texto correspondente ao intervalo deste item no editor de código.
• Clique ou selecione o texto no editor de código. No exemplo anterior do Visual Basic, se você selecionar a linha que contém "Módulo Módulo1" no editor de código, o visualizador navegará automaticamente até o nó ModuleStatement correspondente na árvore.

O visualizador realça o item na árvore cujo intervalo melhor corresponde ao intervalo do texto selecionado no editor.

O visualizador atualiza a árvore para corresponder às modificações no arquivo de código ativo. Adicione uma chamada a Console.WriteLine() dentro de Main(). Conforme você digita, o visualizador atualiza a árvore.

Pausar a digitação depois de digitar Console.. A árvore tem alguns itens coloridos em rosa. Neste ponto, há erros (também conhecidos como "Diagnóstico") no código digitado. Esses erros são anexados a nós, tokens e trívia na árvore de sintaxe. O visualizador mostra quais itens têm erros anexados a eles realçando o plano de fundo em rosa. Você pode inspecionar os erros em qualquer item cor de rosa passando o mouse sobre o item. O visualizador exibe apenas erros sintacticos (aqueles erros relacionados à sintaxe do código tipado); não exibe erros semânticos.

Grafos de sintaxe

Clique com o botão direito do mouse em qualquer item na árvore e clique em Exibir Grafo de Sintaxe Direcionada.

C#

O visualizador exibe uma representação gráfica da subárvore com raiz no item selecionado. Repita essas etapas para o nó MethodDeclaration correspondente ao método Main() no exemplo de C#. O visualizador exibe um grafo de sintaxe que tem a seguinte aparência:

Visual Basic

Repita o mesmo para o nó SubBlock correspondente ao método Main() no exemplo anterior do Visual Basic. O visualizador exibe um grafo de sintaxe que tem a seguinte aparência:

O visualizador de grafo de sintaxe tem uma opção para exibir uma legenda para seu esquema de coloração. Você também pode passar o mouse sobre itens individuais no grafo de sintaxe com o mouse para exibir as propriedades correspondentes a esse item.

Você pode exibir grafos de sintaxe para itens diferentes na árvore repetidamente e os grafos sempre serão exibidos na mesma janela dentro do Visual Studio. Você pode encaixar essa janela em um local conveniente dentro do Visual Studio para não precisar alternar entre as guias para exibir um novo grafo de sintaxe. A parte inferior, abaixo das janelas do editor de código, geralmente é conveniente.

Veja o layout de encaixe para usar com a janela de ferramentas do visualizador e a janela do gráfico de sintaxe:

Outra opção é colocar a janela de grafo de sintaxe em um segundo monitor, em uma configuração de monitor duplo.

Inspecionando a semântica

O Visualizador de Sintaxe permite a inspeção rudimentar de símbolos e informações semânticas. Digite double x = 1 + 1; dentro de Main() no exemplo de C#. Em seguida, selecione a expressão 1 + 1 na janela do editor de código. O visualizador realça o nó AddExpression no visualizador. Clique com o botão direito do mouse neste AddExpression e clique em Exibir Símbolo (se houver). Observe que a maioria dos itens de menu tem o qualificador "se houver". O Visualizador de sintaxe inspeciona as propriedades de um Nó, incluindo propriedades que podem não estar presentes em todos os nós.

A grade de propriedades no visualizador é atualizada conforme mostrado na figura a seguir: O símbolo da expressão é um SynthesizedIntrinsicOperatorSymbol com Kind = Method.

Clique com o botão direito do mouse no mesmo nó AddExpression e selecione Exibir TypeSymbol (se houver). A grade de propriedades no visualizador é atualizada conforme mostrado na figura a seguir, indicando que o tipo da expressão selecionada é Int32.

Clique com o botão direito do mouse no mesmo nó AddExpression e selecione Exibir TypeSymbol Convertido (se houver). A grade de propriedades é atualizada indicando que, embora o tipo da expressão seja Int32, o tipo convertido da expressão é Double conforme mostrado na figura a seguir. Esse nó inclui informações de símbolo de tipo convertido porque a expressão Int32 ocorre em um contexto em que deve ser convertida para um Double. Essa conversão satisfaz o tipo especificado Double para a variável x no lado esquerdo do operador de atribuição.

Por fim, clique com o botão direito do mouse no mesmo nó AddExpression e selecione Exibir Valor Constante (se houver). A grade de propriedades mostra que o valor da expressão é uma constante de tempo de compilação com valor 2.

O exemplo anterior também pode ser replicado no Visual Basic. Digite Dim x As Double = 1 + 1 em um arquivo do Visual Basic. Selecione a expressão 1 + 1 na janela do editor de código. O visualizador realça o nó AddExpression correspondente no visualizador. Repita as etapas anteriores para este AddExpression e você deverá ver resultados idênticos.

Examine mais código no Visual Basic. Atualize o arquivo principal do Visual Basic com o seguinte código:

Imports C = System.Console

Module Program
    Sub Main(args As String())
        C.WriteLine()
    End Sub
End Module

Esse código introduz um alias chamado C que mapeia para o tipo System.Console na parte superior do arquivo e usa esse alias em Main(). Selecione o uso desse alias, o C em C.WriteLine(), dentro do método Main(). O visualizador seleciona o nó IdentifierName correspondente no visualizador. Clique com o botão direito do mouse neste nó e clique em Exibir Símbolo (se houver). A grade de propriedades indica que esse identificador está associado ao tipo System.Console , conforme mostrado na figura a seguir:

Clique com o botão direito do mouse no mesmo nó IdentifierName e selecione Exibir AliasSymbol (se houver). A grade de propriedades indica que o identificador é um alias com o nome C associado ao System.Console destino. Em outras palavras, a grade de propriedades fornece informações sobre o AliasSymbol correspondente ao identificador C.

Inspecione o símbolo correspondente a qualquer tipo declarado, método, propriedade. Selecione o nó correspondente no visualizador e clique com o botão direito do mouse para acessar o Símbolo de Exibição (se houver). Selecione o método Sub Main(), incluindo o corpo do método. Clique com o botão direito do mouse no nó SubBlock correspondente no visualizador e selecione Símbolo de Exibição (se houver). A grade de propriedades mostra que o MethodSymbol para este SubBlock possui o nome Main e tipo de retorno Void.

Os exemplos acima do Visual Basic podem ser facilmente replicados em C#. Digite using C = System.Console; no lugar de Imports C = System.Console como apelido. As etapas anteriores no C# produzem resultados idênticos na janela do visualizador.

As operações de inspeção semântica só estão disponíveis em nós da rede. Elas não estão disponíveis em tokens nem trívia. Nem todos os nós têm informações semânticas interessantes para inspecionar. Quando um nó não tem informações semânticas interessantes, clicar com o botão direito do mouse e selecionar Exibir * Símbolo (se houver) mostra uma grade de propriedades em branco.

Você pode ler mais sobre APIs para executar análise semântica no documento de visão geral trabalho com semântica .

Fechando o visualizador de sintaxe

Você pode fechar a janela do visualizador quando não estiver usando-a para examinar o código-fonte. O visualizador de sintaxe atualiza sua exibição à medida que você navega pelo código, editando e alterando a origem. Pode ser um fator de distração quando não está em uso.