Roslyn & You (Part II): APIs

Landing Roslyn

From an operational point of view we can identify the following stages during compilation execution pipeline

Roslyn APIs 1
Roslyn APIs 1

For each of them we are going to introduce corresponding Compilation API which provides an operational object model with the information corresponding to each stage, something similar to :

Roslyn APIs 2
Roslyn APIs 2

From a high perspective, we can summarize the compilation pipeline in the following way: ·

  • At the first stage, the Parser will get the user code and it will be converted in a collection of hierarchical tokens that will be part of special structure called SyntaxTree. The compilation process starts by creating a sequence of position-based tokens (spans) for each element in code, these tokens can be mapped to different elements like identifiers


  • Next step involves symbols and metadata imports; the execution looks for all the compilation references and opens up them in order to know types that are defined in metadata containers. As part of this process all symbols will be identified


  • Next phase will be Binding in which all identifiers will be assigned to the right symbols


  • Finally, IL Emitter will be the responsible for creating the bytecode (IL instructions) and packed them into an assembly


Basis on these Compilation APIs a rich collection of language services can be created and integrated into Visual Studio; by using the Syntax Tree API we can provide code formatting, syntax highlighting, provide colour to special keywords, outlining, etc…

Symbols APIs allow us to find the exact locations of identifiers for providing functionality like “Navigate To” and  Object Browsing (for instance, when we click F2 in Visual Studio) which show us hierarchical views for namespaces, types, members, etc… ;

Binding and Flow Analysis API is the responsible for providing a lot of languages features like : “Go To Definition”, “Rename”, “Find All References”, ”Extract Method”, etc..

Emit API is the responsible of language services like “Edit and Continue”, expression evaluator used in Visual Studio Immediate Window

Roslyn APIs 3
Roslyn APIs 3

Roslyn APIs

In addition to Compiler APIs, Roslyn provides Diagnostic APIs, Workspace APIs and Scripting APIs, let´s detail each of them briefly:

Diagnostic APIs

Diagnostic APIs provides an object model for controlling all aspects related with informational diagnosis of syntax and semantic code analysis; this allows developers to create custom analyzers which can be easily integrated with tools like Visual Studio for just-in time information at editors: things like red squiggles, code fixes. Refactorings are also cover by these APIs, which need a more ample context than local code fixes for performing operations

Workspace APIs

Workspace API exposes an object model for modelling items like solutions, projects and files for providing coverage to general operations like Formatting, Find All Reference and Code Generation (for instance when we click “Add” new file, or when we rename a file), etc…

According to Roslyn main page, Workspace API is the basis for doing code analysis over entire solutions. It helps us in organizing all the information about the projects in a solution into centralized object model, offering you direct access to the compiler layer object models without needing to parse files, configure options or manage project to project dependencies

Getting Ready for Use

At time of this writing I´m using VS2015 for samples, so in order to use Roslyn (and according to Roslyn site) we need to:

  1. Install Visual Studio 2015 SDK
  2. Install SDK Templates VSIX package
  3. Install Syntax Visualizer VSIX package

Or we can get the last version of NuGet Roslyn Compiler Package, by running Install-Package Microsoft.CodeAnalysis –Pre at Nuget Package manager console. VS2015 is the first visual studio version in which we can use Roslyn for creating VS extensions. We can also use the Nuget Manager IDE directly

Roslyn APIs 4
Roslyn APIs 4

If we run a console application and run “where csc.exe” command, we will see that two instances of C# compiler are found :

Roslyn APIs 5
Roslyn APIs 5

The first one corresponds to Roslyn compiler and the second one to the previous version of C# compiler, as we can see below

Roslyn APIs 6
Roslyn APIs 6

Now we have seen the basics of Roslyn let´s deep into more details and explore some implementations

That´s all by now

See you on the road !