Explorar código com o visualizador de sintaxe Roslyn no Visual Studio
Este artigo oferece uma visão geral sobre a ferramenta de Visualizador de sintaxe que é fornecida como parte do SDK do .NET Compiler Platform ("Roslyn"). O Visualizador de sintaxe é uma janela de ferramentas que ajuda a inspecionar e explorar árvores de sintaxe. É uma ferramenta essencial para compreender os modelos do código que você deseja analisar. Também é um auxílio para depuração ao desenvolver seus próprios aplicativos 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 as árvores de sintaxe.
Instruções de instalação – Instalador do Visual Studio
Há duas maneiras diferentes de encontrar o SDK da .NET Compiler Platform no Instalador do Visual Studio:
Instalar usando o Instalador do Visual Studio – exibição de cargas de trabalho
O SDK da .NET Compiler Platform não é selecionado automaticamente como parte da carga de trabalho de desenvolvimento da extensão do Visual Studio. É necessário selecioná-lo como um componente opcional.
- Execute o Instalador do Visual Studio
- Escolha Mudar
- Marque a carga de trabalho de Desenvolvimento de extensão do Visual Studio.
- Abra o nó Desenvolvimento de extensão do Visual Studio na árvore de resumo.
- Marque a caixa do SDK da .NET Compiler Platform. Você a encontrará por último nos componentes opcionais.
Opcionalmente, você também poderá fazer o Editor DGML exibir gráficos no visualizador:
- Abra o nó Componentes individuais na árvore de resumo.
- Marque a caixa do Editor DGML
Instalar usando o Instalador do Visual Studio – guia Componentes individuais
- Execute o Instalador do Visual Studio
- Escolha Mudar
- Selecione a guia Componentes individuais
- Marque a caixa do SDK da .NET Compiler Platform. Você a encontrará na parte superior, na seção Compiladores, ferramentas de compilação e runtimes.
Opcionalmente, você também poderá fazer o Editor DGML exibir gráficos no visualizador:
- Marque a caixa do Editor DGML. Você a 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 trívia.
Visualizador de sintaxe
O Visualizador de sintaxe permite a inspeção da árvore de sintaxe de arquivo de código C# ou Visual Basic na janela do editor atualmente ativa dentro do IDE do Visual Studio. O visualizador pode ser iniciado ao clicar em Exibir>Outras Janelas>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 deverá aparecer.
Este comando abre o Visualizador de sintaxe como uma janela de ferramentas flutuante. Se você não tiver uma janela de editor de código aberta, a exibição ficará em branco, conforme mostrado na figura a seguir.
Encaixe esta janela de ferramentas 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 Visual Basic ou C#. Quando o Visual Studio abre o arquivo de código principal deste projeto, o visualizador exibe a árvore de sintaxe dele. Você pode abrir qualquer arquivo de C# ou Visual Basic existente nesta instância do Visual Studio e o visualizador exibirá a árvore de sintaxe do arquivo correspondente. Se você tiver vários arquivos de código abertos no 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).
Conforme mostrado nas imagens acima, a janela de ferramentas do visualizador exibe a árvore de sintaxe na parte superior e uma grade de propriedade na parte inferior. A grade de propriedade exibe as propriedades do item atualmente selecionado na árvore, incluindo Type e Kind (SyntaxKind) do .NET 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 estão representados com cores diferentes. Clique no botão "Legenda" para uma visão geral das cores usadas.
Cada item da árvore também exibe sua própria extensão. 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 uma abrangência de cinco caracteres de largura, [0..5). A notação "[..)" significa que o índice inicial faz parte da extensão, mas o índice final não.
Há duas maneiras de navegar na árvore:
- Expandir ou clicar em itens na árvore. O visualizador seleciona automaticamente o texto correspondente à extensão do item no editor de código.
- Clicar ou selecionar texto no editor de código. No exemplo anterior do Visual Basic, se você seleciona a linha que contém "Module Module1" no editor de código, o visualizador navega automaticamente até o nó ModuleStatement correspondente na árvore.
O visualizador realça o item da árvore cuja extensão melhor corresponda com a extensão 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.
Pare de digitar quando já tiver digitado 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 a tela de fundo em rosa. Você pode inspecionar os erros em qualquer item colorido em rosa passando o mouse sobre o item. O visualizador exibe somente erros sintáticos (os erros relacionados à sintaxe do código digitado); erros semânticos não são exibidos.
Gráficos de sintaxe
Clique com o botão direito do mouse em qualquer item da árvore e clique em Exibir gráfico de sintaxe direcionado.
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 gráfico de sintaxe que tem a seguinte aparência:
O visualizador de gráfico de sintaxe tem uma opção para exibir uma legenda para seu esquema de cores. Você também pode passar o mouse sobre itens específicos no gráfico de sintaxe para exibir as respectivas propriedades.
Você pode exibir gráficos de sintaxe de itens diferentes da árvore repetidamente e os gráficos serão sempre exibidos na mesma janela no Visual Studio. Você pode encaixar essa janela em um local conveniente no Visual Studio para não precisar alternar entre as guias para exibir um novo gráfico 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 gráfico de sintaxe em um segundo monitor, em uma configuração de dois monitores.
Inspecionando semântica
O Visualizador de sintaxe possibilita uma 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 nesse AddExpression e clique em Exibir Symbol (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 propriedade do visualizador é atualizada conforme mostrado na figura a seguir: o símbolo da expressão é um SynthesizedIntrinsicOperatorSymbol com Kind = Method.
Experimente Exibir TypeSymbol (se houver) para o mesmo nó AddExpression. A grade de propriedade no visualizador é atualizada, conforme mostrado na figura a seguir, indicando que o tipo da expressão selecionada é Int32.
Experimente Exibir TypeSymbol Convertido (se houver) para o mesmo nó AddExpression. A grade de propriedade é 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 em um Double. Essa conversão satisfaz o tipo Double especificado para a variável x no lado esquerdo do operador de atribuição.
Por fim, experimente Exibir Valor Constante (se houver) para o mesmo nó AddExpression. A grade de propriedade mostra que o valor da expressão é uma constante de tempo de compilação com o 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 esta AddExpression e você verá resultados idênticos.
Examine mais código no Visual Basic. Atualize seu 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 botão direito do mouse nesse nó e clique em Exibir Symbol (se houver). A grade de propriedade mostra que esse identificador é associado com o tipo System.Console, conforme mostrado na figura a seguir:
Experimente Exibir AliasSymbol (se houver) para o mesmo nó IdentifierName. A grade de propriedade mostra que o identificador é um alias com nome C, que é associado com o destino System.Console. Em outras palavras, a grade de propriedade fornece informações sobre o AliasSymbol correspondente ao identificador C.
Inspecione o símbolo correspondente a qualquer tipo, método e propriedade declarados. Selecione o nó correspondente no visualizador e clique em Exibir Symbol (se houver). Selecione o método Sub Main(), incluindo o corpo do método. Clique em Exibir Symbol (se houver) para o nó SubBlock correspondente no visualizador. A grade de propriedade mostra que o MethodSymbol deste SubBlock tem nome Main com o tipo de retorno Void.
Os exemplos de Visual Basic acima podem ser facilmente replicados em C#. Digite using C = System.Console; no lugar de Imports C = System.Console para o alias. As etapas anteriores em C# geram resultados idênticos na janela do visualizador.
As operações de inspeção semântica estão disponíveis somente em nós. 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 em Exibir * Symbol (se houver) mostrará uma grade de propriedade em branco.
Você pode ler mais sobre as APIs para executar análise semântica no documento de visão geral Trabalhar com semântica.
Fechando o visualizador de sintaxe
Você pode fechar a janela do visualizador quando não a estiver usando para examinar o código-fonte. O visualizador de sintaxe atualiza a exibição enquanto você navega pelo código, editando e alterando a origem. Ele poderá se tornar uma distração quando você não estiver usando.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de