Compilers process the code you write following structured rules that oftendiffer from the way humans read and understand code. A basic understandingof the model used by compilers is essential to understanding the APIsyou use when building Roslyn-based tools.

Compiler pipeline functional areas

The .NET Compiler Platform SDK exposes the C# and Visual Basic compilers' code analysis to youas a consumer by providing an API layer that mirrors a traditional compilerpipeline.

Each phase of this pipeline is a separate component. First, theparse phase tokenizes and parses source text into syntax that followsthe language grammar. Second, the declaration phase analyzes source andimported metadata to form named symbols. Next, the bind phase matches identifiersin the code to symbols. Finally, the emit phase emits an assembly withall the information built up by the compiler.

Corresponding to each of those phases, the .NET Compiler Platform SDK exposes anobject model that allows access to the information at that phase. The parsingphase exposes a syntax tree, the declaration phase exposes a hierarchicalsymbol table, the binding phase exposes the result of the compiler's semanticanalysis, and the emit phase is an API that produces IL byte codes.

Each compiler combines these components together as a single end-to-end whole.

These APIs are the same ones used by Visual Studio. For instance, the codeoutlining and formatting features use the syntax trees, theObject Browser,and navigation features use the symbol table, refactoringsandGo to Definition use the semantic model, andEdit and Continue uses all ofthese, including the Emit API.

API layers

The .NET compiler SDK consists of several layers of APIs: compilerAPIs, diagnostic APIs, scripting APIs, and workspaces APIs.

Compiler APIs

The compiler layer contains the object models that correspond toinformation exposed at each phase of the compiler pipeline, both syntacticand semantic. The compiler layer also contains an immutable snapshot of asingle invocation of a compiler, including assembly references, compileroptions, and source code files. There are two distinct APIs that representthe C# language and the Visual Basic language. The two APIs are similarin shape but tailored for high-fidelity to each individual language. Thislayer has no dependencies on Visual Studio components.

Diagnostic APIs

As part of its analysis, the compiler may produce a set of diagnosticscovering everything from syntax, semantic, and definite assignment errorsto various warnings and informational diagnostics. The Compiler API layerexposes diagnostics through an extensible API that allows user-definedanalyzers to be plugged into the compilation process. It allows user-defineddiagnostics, such as those produced by tools like StyleCop, to beproduced alongside compiler-defined diagnostics. Producing diagnostics in thisway has the benefit of integrating naturally with tools such as MSBuildand Visual Studio, which depend on diagnostics for experiences such ashalting a build based on policy and showing live squiggles in the editorand suggesting code fixes.

Scripting APIs

Hosting and scripting APIs are built on top of the compiler layer. Youcan use the scripting APIs to run code snippets and accumulate a runtimeexecution context. The C# interactive REPL (Read-Evaluate-Print Loop)uses these APIs. The REPL enables you to use C# as a scripting language,running the code interactively as you write it.

Workspaces APIs

The Workspaces layer contains the Workspace API, which is the startingpoint for doing code analysis and refactoring over entire solutions. Itassists you in organizing all the information about the projects in asolution into a single object model, offering you direct access to the compilerlayer object models without needing to parse files, configure options, ormanage project-to-project dependencies.

In addition, the Workspaces layer surfaces a set of APIs usedwhen implementing code analysis and refactoring tools that function withina host environment like the Visual Studio IDE. Examples include the Find All References,Formatting, and Code Generation APIs.

This layer has no dependencies on Visual Studio components.