Technical Documentation: dotnet/roslyn

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

The .NET Compiler Platform

Roslyn is the open-source implementation of both the C# and Visual Basic compilers with an API surface for building code analysis tools.

C# and Visual Basic Language Feature Suggestions Copy Section

If you want to suggest a new feature for the C# or Visual Basic languages go here:

• dotnet/csharplang for C# specific issues
• dotnet/vblang for VB-specific features
• dotnet/csharplang for features that affect both languages

Contributing Copy Section

All work on the C# and Visual Basic compiler happens directly on GitHub. Both core team members and external contributors send pull requests which go through the same review process.

If you are interested in fixing issues and contributing directly to the code base, a great way to get started is to ask some questions on GitHub Discussions! Then check out our contributing guide which covers the following:

• Coding guidelines
• The development workflow, including debugging and running tests
• Submitting pull requests
• Finding a bug to fix in the IDE or Compiler
• Finding a feature to implement in the IDE or Compiler
• Roslyn API suggestions should go through the API review process

Community Copy Section

The Roslyn community can be found on GitHub Discussions, where you can ask questions, voice ideas, and share your projects.

To chat with other community members, you can join the Roslyn channel on the CSharp Community Discord.

Our Code of Conduct applies to all Roslyn community channels and has adopted the .NET Foundation Code of Conduct.

Documentation Copy Section

Visit Roslyn Architecture Overview to get started with Roslyn’s API’s.

NuGet Feeds Copy Section

The latest pre-release builds are available from the following public NuGet feeds:

• Compiler: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json
• IDE Services: https://pkgs.dev.azure.com/azure-public/vside/_packaging/vssdk/nuget/v3/index.json
• .NET SDK: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet5/nuget/v3/index.json

Continuous Integration status Copy Section

Builds

Desktop Unit Tests

CoreClr Unit Tests

Integration Tests

Misc Tests

.NET Foundation Copy Section

This project is part of the .NET Foundation along with other projects like the .NET Runtime.

README (`docs/README.md`) Copy Section

README

This file is a placeholder. This directory will contain public documentation.

Compilers README (`docs/compilers/README.md`) Copy Section

Roslyn Compiler

Specification Copy Chapter

The compiler specification details the supported (and semi-supported) surface area of the Roslyn VB and C# compilers. This includes

0. Command-line switches and their meaning
1. Breaking changes from previous versions of the compilers
2. Compiler behaviors that are (intentionally) contrary to the specification
3. Compiler features not described by the language specification
   1. COM-specific and other Microsoft-specific features
   2. "Well-known" attributes that affect compiler behavior
   3. The "ruleset" file syntax and semantics
4. Features included for interoperability between C# and VB, for example
   1. Named Indexers use from C#
5. Places where the compiler behavior diverges from the language specification
6. Limitations (e.g. identifier length)
7. History of language changes per version

The language specification itself is not included here.

Platforms Copy Chapter

The compiler is officially supported in the following configurations:

• .NET Framework: x86, x64 and ARM64
• .NET Core:
  • Operating Systems: Windows, macOS, Linux
  • Architectures: x86, x64, and ARM64
• Mono Core: x86 and x64

The compiler takes contributions for other platforms, such as big-endian architectures, but does not officially support the compiler there.

Contributing README (`docs/contributing/README.md`) Copy Section

Contributing

Guides for contributing to this project

• Build, debugging and testing
  • Unix
  • Windows
• Localization in tests
• Nullable Annotations
• Target Framework Strategy
• Bootstrap Builds
• API Review Process
• Developing a Language Feature
• Documentation for IDE CodeStyle analyzers
• IDE Design Process
• Powershell Guidelines
• Codespaces
• Testing for Interactive readiness
• Compiler Test Plan
• IDE Test Plan

Ide README (`docs/ide/README.md`) Copy Section

Recently added productivity features and links to release notes

TOC Copy Chapter

• Dev16
  • Dev 16.9
  • Dev 16.8
  • Dev 16.7
  • Dev 16.6
  • Dev 16.5
  • Dev 16.4
  • Dev 16.3
  • Dev 16.2
  • Dev 16.1
  • Dev16.0
• Dev15
  • Dev 15.9
  • Dev 15.8
  • Dev 15.7
  • Dev 15.6
  • Dev 15.5
  • Dev 15.4

dev16 Copy Chapter

16.9 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.9)) Copy Section

• There is now IntelliSense completion for preprocessor symbols.
• Solution Explorer now displays the new .NET 5.0 Source Generators.
• Go To All won't display duplicate results across netcoreapp3.1 and netcoreapp2.0.
• Quick Info now displays compiler warning IDs or numbers for suppressions.
• Using directives will now automatically get added when copying and pasting types to a new file.
• When pressing ; to accept a method from a completion list, IntelliSense will now automatically insert the parentheses along with a semicolon for object creation and method calls.
• Semantic colorization for C# 9.0 records.
• Refactoring that removes unnecessary discards.
• Refactoring that converts a verbatim and regular string to an interpolated string preserving curly braces that were intended to go in the output.
• Code fix in Visual Basic that removes the shared keyword when you convert methods that are shared to a module.
• A refactoring that suggests using new(…) in non-contentious scenarios
• A code fix that removes redundant equality expressions for both C# and Visual Basic
• The .NET Code Style (IDE) analyzers can now be enforced on build
• The Syntax Visualizer shows the current foreground color for enhanced colors
• A new tooltip when hovering over the diagnostic ID for pragma warnings
• When you type the return key from within a comment the new line is now automatically commented out
• Inline parameter name hints enhancements
• .NET Core Debugging with WSL 2

16.8 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.8)) Copy Section

• Roslyn analyzers are now included in the .NET 5.0 SDK
• Refactoring that introduces the new C# 9 not pattern matching syntax when a suppression operator is present
• Inline method refactoring to help replace usages of static, instance, and extension method within a single statement body
• Code fix to convert instances of typeof to nameof in C# and GetType to NameOf in Visual Basic
• C# and Visual Basic support for inline parameter name hints that inserts adornments for literals, casted literals, and object instantiations prior to each argument in function calls
• Refactoring that extracts members from a selected class to a new base class in both C# and Visual Basic
• Code cleanup has new configuration options that can apply formatting and file header preferences set in your EditorConfig file across a single file or an entire solution
• Code fix to remove the in keyword where the argument should not be passed by reference
• Refactoring that introduces the new C#9 pattern combinators and pattern matching suggestions such as converting == to use is where applicable
• Code fix to make a class abstract when you are trying to write an abstract method in a class that is not abstract
• IntelliSense completion in DateTime and TimeSpan string literals automatically appear when the first quote is typed
• Code fix to remove unnecessary pragma suppressions and unnecessary SuppressMessageAttributes
• Rename and Find All References understands references to symbols within the target string of global SuppressMessageAttributes
• ByVal fades to say it's not necessary along with a code fix to remove the unnecessary ByVal in Visual Basic
• Interactive window support for multiple runtimes, such as .NET Framework and .NET Core.
• Added a new RegisterAdditionalFileAction API that allows analyzer authors to create an analyzer for additional files.

16.7 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.7)) Copy Section

• There is now a warning and code fix when a suppression operator is present but has no effect
• A second code fix suggesting the correct negating expression is also available
• You can now generate properties when generating a constructor in a type
• Quick Info now displays the diagnostic ID along with a help link
• There is now a quick action to add a debugger display attribute to a class
• There is now a code fix for accidental assignments or comparisons to the same variable
• You can now generate comparison operators for types that implement IComparable
• You can now generate IEquatable operators when generating .Equals for structs
• You can now create and assign properties or fields for all unused constructor parameters
• There is now IntelliSense completion in DateTime and TimeSpan string literals
• You can now add a parameter within the Change Signature dialog
• Analyzer authors can now use CompletionProviders for IntelliSense completions when shipping their analyzers with NuGet

16.6 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.6)) Copy Section

• Add explicit cast code fix
• Simplify conditional expressions refactoring
• Convert regular string literals to verbatim string literals (and back) refactoring
• Bulk configure the severity level of analyzer categories directly through the editor
• Quick Info style support for XML comments that contain returns and value tags
• Add file headers to existing files, projects, and solutions with EditorConfig
• Microsoft Fakes support for .NET Core and SDK-style projects

16.5 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.5)) Copy Section

• You can now use System.HashCode to implement the GetHashCode method when System.HashCode is available.
• Refactoring to convert if statements to switch statements or switch expressions.
• IntelliSense completion for unimported extension methods. You will first need to turn this option on in Tools > Options > Text Editor > C# > Intellisense > and select Show items from unimported namespaces.

16.4 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.4)) Copy Section

• You can now configure the severity level of a code style rule directly through the editor (through the Ctrl+. menu) or the error list (right-click on the error, warning, or message). This will also update EditorConfig and works for 3rd party analyzers.
• Find All References now allows you to group by type and member.
• Refactoring make local function static
• Code fix to pass variable explicitly in local static function.
• The Go To Base command can navigate up the inheritance chain. Available in the context (right-click) menu or you can type (Alt+Home).
• Refactoring to add null checks for all parameters.
• Methods that have no XML documentation can now automatically inherit XML documentation from the method it is overriding. Place your cursor over the undocumented method that implements a documented interface method. Quick Info will then display the XML documentation from the interface method.

16.3 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.3)) Copy Section

• Wrap chains of fluent calls with a refactoring
• Introduce a local variable immediately after writing its initializer
• Code Analysis page now in project properties. Right click on the project name within the solution explorer and select properties. Select Code Analysis to install analyzer packages and configure when to run code analysis.
• Now, for users who turn off the completion for unimported types, it's much easier to get it back in the completion list with the new imported type filter added to the IntelliSense toggles.
• There is now Quick Info style support for XML comments. Place the cursor over the method name. Quick Info will then display the supported styles from the XML comments above the code.
• Rename a file when renaming an interface, enum, or class. Place the cursor in the class name and type (Ctrl + R,R) to open the Rename dialogue and check the ‘Rename file’ box.
• There is now Edit and Continue support for multi-targeted projects which includes modules loaded multiple times in the same process on different domains or load contexts. In addition, developers can edit source files even when the containing project is not loaded or the application is running.

16.2 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.2)) Copy Section

• Bring back Sort Usings as a separate command from Remove Usings. Available under Edit > IntelliSense.
• Convert a switch statement to a switch expression (verify you are using C# 8 to get the switch expression feature)
• Generate a parameter
• Test Explorer improvements
  • Significant reduction in memory consumed by the Visual Studio process and faster test discovery for solutions with large numbers of tests
  • Filter buttoms for passed, failed, not run tests
  • Additional buttons for the 'Run Failed Tests' and 'Run Previous Test Run'
  • Customize what columns are displayed in the Test Explorer
  • Specify what is displayed in each tier of the test hierarchy. The default tiers are Project, Namespace, and then Class, but additional options include Outcome or Duration groupings.
  • The test status window (the pane below the test list that displays the messages, output, etc.) is much more usable. Users can copy substrings of text, and the font-width is fixed for more readable output.
  • Playlists can be displayed in multiple tabs and are much easier to create and discard as needed.
  • Live Unit Testing now has its own view in the Test Explorer. It displays all tests currently included in Live Unit Testing (aka. the live test set), so testers can easily keep track of Live Unit Testing results separate from the manually run test results.
  • There is a target framework column that can display multi-targeted test results.

16.1 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.1)) Copy Section

• There is now experimental intellisense completion for unimported types! You now receive intellisense suggestions for types in dependencies in your project even if you have not yet added the import statement to your file. You must turn this option on in Tools > Options > Text Editor > C# > Intellisense.
• Toggle Single Line Comment/Uncomment is now available through the keyboard shortcut (Ctrl+K,/). This command will add or remove a single line comment depending on whether your selection is already commented.
• You can now export naming styles with the “Generate editorconfig” button located in Tools > Options > Text Editor > C# > Code Style.
• You can now use a new editorconfig code style rule to require or prevent usings inside a namespace. This setting will also be exported when you use the “Generate editorconfig” button located in Tools > Options > Text Editor > C# > Code Style.
• The Find All References “Kind” column now has more filter options and is aware of namespaces and types.
• .NET codefixes and Refactorings
  • Split/Merge if
  • Wrap binary expressions
  • Unseal a class
• A regex completion list can now be accessed through the intellisense menu (Ctrl + space) when inside a regex string. These completions also include an in-line description of what the suggestion does.
• You can now use one-click code cleanup for projects and solutions. You can right-click on projects or the solution in the Solution Explorer and select ‘Run Code Cleanup’.
• You can now use a refactoring dialog to move type to namespace or folder. Place your cursor in the class name and type (Ctrl + .) to open the quick actions and refactorings menu and select ‘Move to namespace.’ This launches a dialog where you can select the target namespace you would like to move the type to.
• Toggle Block Comment/Uncomment (Ctrl+Shift+/) or through Edit > Advanced > Toggle Block Comment.
• There is now a codefix for making readonly struct fields writable. Place your cursor in the struct name, type (Ctrl+.) to open the quick actions and refactorings menu, and select ‘Make readonly fields writable.’
• The codefix to add a private field from a constructor and vice versa is easier to discover and will show when any portion of the field name is selected. This refactoring now also offers all possible constructors.

16.0 ([release notes](https://docs.microsoft.com/visualstudio/releases/2019/release-notes-v16.0)) Copy Section

• .NET refactorings and codefixes:
  • Sync Namespace and Folder Name
  • Pull members up refactoring with dialog options
  • Wrap/indent/align lists of parameters/arguments
  • Convert anonymous type to tuple
  • Use expression/block body for lambda
  • Invert conditional expressions and logical operations
  • Convert to compound assignment
  • Automatically close block comment on “/”
  • Convert to compound assignment
  • Fix Implicitly-typed variables cannot be constant
  • Auto-fixer to replace @$" with $@" when typing interpolated verbatim string
  • Completion for #nullable enable|disable
  • Fix for unused expression values and parameters
  • Fix for allowing Extract Interface to remain in the same file
  • For cases where "await" is implied but omitted, there is now a compiler warning.
  • Convert a local function to a method.
  • Convert a tuple to a named-struct.
  • Convert an anonymous type to a class.
  • Convert an anonymous type to a tuple.
  • For a foreach loop to LINQ query or to LINQ method.
  • Generate deconstruct method
• Categorize references by Read/Write in Find All References window.
• Add Editorconfig when_multiline option for csharp_prefer_braces.
• New classification colors are available from the .NET Compiler Platform SDK (aka Roslyn). New default colors, similar to the Visual Studio Code colors, are gradually being rolled out. You can adjust these colors in Tools > Options > Environment > Fonts and Colors or turn them off in Environment > Preview Features by unchecking the Use enhanced colors check box. We’d appreciate hearing feedback on how this change affects your workflow.
• Configure code cleanup (settings formally a part of Format Document)
• Format document global tool can be run from the command-line
• Use code metrics with .NET Core projects with our added compatibility.
• Export editor settings to an Editorconfig file through Tools > Options > Text Editor > C# > Code Style with the button "Generate .editorconfig file from settings".
• Use C# and Visual Basic's new Regex parser support. Regular expressions are now recognized, and language features are enabled on them. Regex strings are either recognized when a string is passed to the Regex constructor or when a string is immediately preceded with a comment containing the string language=regex. The language features included in this release are classification, brace matching, highlight references, and diagnostics.
• You can now use dead code analysis for unused private members with an optional code fix to remove unused member declaration.
• The Find References feature on an accessor now only returns results for that accessor.
• "Using" statements can be added when code is pasted into a file. A code fix appears after pasting recognized code that prompts you to add relevant missing imports.
• You can now use Find All References (Shift-F12) and CodeLens to show results from Razor (.cshtml) files in .NET Core projects. You can then navigate to the identified code in the relevant Razor files.
• You will now receive a warning when running code analysis using FxCop. .NET Compiler analyzers are the recommended way to perform code analysis going forward. Read more on migrating to .NET compiler platform analyzers.

dev15 Copy Chapter

dev15 Summary Copy Section

• Visual Studio-based code cleanup via Format Document
• Refactorings: InvertIf, add parameter from method callsite, remove unnecessary parentheses, convert if-else assignment, completion for attributes and return to ternary conditional.
• .editorconfig “refresh” such that changes will be automatically applied without file reload
• IOperation APIs RTW
• Portable PDB format to enable cross-platform debugging scenarios

15.9 Copy Section

None

15.8 ([release notes](https://docs.microsoft.com/visualstudio/releasenotes/vs2017-relnotes-v15.8#productivity)) Copy Section

• Format Document (Ctrl + K, D or Ctrl + E, D) for C# development.
• .NET refactorings and codefixes:
  • Invert If
  • Add parameter from method callsite
  • Remove unnecessary parentheses
  • Use ternary conditionals in assignments and return statements
• Go to Enclosing Block (Ctrl + Alt + UpArrow)
• Go to Next/Previous Issue (Alt + PgUp/PgDn) skip to error, squiggle, lightbulb.
• Go to Member (Ctrl + T, M) is now scoped to the file by default
• Multi-caret: Insert carets with Ctrl + Alt + LeftMouseClick.
• Multi-caret: Add a selection and caret at next location that matches current selection with Shift + Alt + Ins.
• Access a contextual navigation menu with Alt + `.
• Visual Studio Code and ReSharper (Visual Studio) keybindings

15.7 ([release notes](https://docs.microsoft.com/visualstudio/releasenotes/vs2017-relnotes-v15.7#dotnet_productivity)) Copy Section

• .NET refactorings and codefixes:
  • For-to-foreach, and vice versa.
  • Make private fields readonly.
  • Toggle between var and the explicit type, regardless of your code style preferences.
• Go To Definition (F12) is now supported for LINQ query clauses and deconstructions.
• Quick Info shows captures on lambdas and local functions, so you can see what variables are in scope.
• Change Signature refactoring (Ctrl+. on signature) works on local functions.
• You can edit .NET Core project files in-place, so opening containing folder, restoring tabs, and other Editor features are fully supported. IDE changes, such as adding a linked file, will be merged with unsaved changes in the editor.

15.6 ([release notes](https://docs.microsoft.com/visualstudio/releasenotes/vs2017-relnotes-v15.6#productivity)) Copy Section

• Navigate to decompiled sources (must enable in Tools > Options > Text Editor > C# > Advanced > Enable navigation to decompiled sources)
• .NET EditorConfig options: dotnet_prefer_inferred_tuple_names
• .NET EditorConfig options: dotnet_prefer_inferred_anonymous_type_member_names
• Ctrl + D to Duplicate text
• Expand Selection command that allows you to successively expand your selection to the next logical block. You can use the shortcuts Shift+Alt+= to expand and Shift+Alt+- to contract the current selection.

15.5 Copy Section

None

15.4 ([release notes](https://docs.microsoft.com/visualstudio/releasenotes/vs2017-relnotes-v15.4#editor)) Copy Section

• Editor: Control Click Go To Definition

Roslyn Analyzers README (`docs/roslyn-analyzers/README.md`) Copy Section

Roslyn Analyzers

Microsoft.CodeAnalysis.Analyzers Copy Chapter

Latest stable version:

Latest pre-release version: here

This package contains rules for correct usage of APIs from the Microsoft.CodeAnalysis NuGet package, i.e. .NET Compiler Platform ("Roslyn") APIs. These are primarily aimed towards helping authors of diagnostic analyzers and code fix providers to invoke the Microsoft.CodeAnalysis APIs in a recommended manner. More info about rules in this package

Roslyn.Diagnostics.Analyzers Copy Chapter

Latest stable version:

Latest pre-release version: here

This package contains rules that are very specific to the .NET Compiler Platform ("Roslyn") project, i.e. dotnet/roslyn repo. This analyzer package is not intended for general consumption outside the Roslyn repo. More info about rules in this package

Microsoft.CodeAnalysis.BannedApiAnalyzers Copy Chapter

Latest stable version:

Latest pre-release version: here

This package contains customizable rules for identifying references to banned APIs. More info about rules in this package

For instructions on using this analyzer, see Instructions.

Microsoft.CodeAnalysis.PublicApiAnalyzers Copy Chapter

Latest stable version:

Latest pre-release version: here

This package contains rules to help library authors monitoring change to their public APIs. More info about rules in this package

For instructions on using this analyzer, see Instructions.

Wiki README (`docs/wiki/README.md`) Copy Section

Getting Started

• Roslyn Overview
• Samples and Walkthroughs
• Roadmap
• Labels used for issues
• Building, Testing, and Debugging
• Contributing
• FAQ
• Documentation

Language Design

• C# Language Design repo
• VB Language Design repo
• Language Feature Status
• Language Feature Overview for C# 6 and Visual Basic 14

Tools

• Performance considerations for large solutions
• Syntax Visualizer
• Syntax Quoter, Source
• Enhanced source view, powered by Roslyn

API Changelist

• VS 2015 CTP5 Changelist
• VS 2015 CTP6 Changelist
• VS 2015 RC Changelist

Other Topics

• Project Overview
• Project Roadmap
• Labels used for Issues
• Performance considerations for large solutions
• Other documentation in the repo

Contributors Copy Chapter

• Building, Testing, and Debugging
• Contributing Code

Tool Authors Copy Chapter

• Getting Started
• Samples and Walkthroughs
• FAQ
• API Changelist

Status Copy Chapter

• Language feature status
• Edit-and-Continue Supported Edits

.NET Core Copy Chapter

• Runtime Code Generation

Interactive and Scripting Copy Chapter

• Interactive Window Documentation
• Scripting API Samples
• C# Interactive Walkthrough

Testing Copy Chapter

• Manual Testing
• How to Investigate CI Test Failures

Wiki Roslyn Overview (`docs/wiki/Roslyn-Overview.md`) Copy Section

.NET Compiler Platform ("Roslyn") Overview

Download in PDF

Contents

• Introduction
• Exposing the Compiler APIs
  • Compiler Pipeline Functional Areas
  • API Layers
    • Compiler APIs
    • Workspaces APIs
• Working with Syntax
  • Syntax Trees
  • Syntax Nodes
  • Syntax Tokens
  • Syntax Trivia
  • Spans
  • Kinds
  • Errors
• Working with Semantics
  • Compilation
  • Symbols
  • Semantic Model
• Working with a Workspace
  • Workspace
  • Solutions, Projects and Documents

Summary

Introduction Copy Chapter

Traditionally, compilers are black boxes -- source code goes in one end, magic happens in the middle, and object files or assemblies come out the other end. As compilers perform their magic, they build up deep understanding of the code they are processing, but that knowledge is unavailable to anyone but the compiler implementation wizards. The information is promptly forgotten after the translated output is produced.

For decades, this world view has served us well, but it is no longer sufficient. Increasingly we rely on integrated development environment (IDE) features such as IntelliSense, refactoring, intelligent rename, “Find all references,” and “Go to definition” to increase our productivity. We rely on code analysis tools to improve our code quality and code generators to aid in application construction. As these tools get smarter, they need access to more and more of the deep code knowledge that only compilers possess. This is the core mission of Roslyn: opening up the black boxes and allowing tools and end users to share in the wealth of information compilers have about our code. Instead of being opaque source-code-in and object-code-out translators, through Roslyn, compilers become platforms—APIs that you can use for code related tasks in your tools and applications.

The transition to compilers as platforms dramatically lowers the barrier to entry for creating code focused tools and applications. It creates many opportunities for innovation in areas such as meta-programming, code generation and transformation, interactive use of the C# and VB languages, and embedding of C# and VB in domain specific languages.

Roslyn SDK Preview includes the latest drafts of new language object models for code generation, analysis, and refactoring. We hope to include drafts of API support for scripting and interactive use of C# and Visual Basic in a future preview. This document provides a conceptual overview of Roslyn. Further details can be found in the walkthroughs and samples included in the SDK Preview.

Exposing the Compiler APIs Copy Chapter

Compiler Pipeline Functional Areas Copy Section

Roslyn exposes the C# and Visual Basic compiler’s code analysis to you as a consumer by providing an API layer that mirrors a traditional compiler pipeline.

Each phase of this pipeline is now a separate component. First the parse phase, where source is tokenized and parsed into syntax that follows the language grammar. Second the declaration phase, where declarations from source and imported metadata are analyzed to form named symbols. Next the bind phase, where identifiers in the code are matched to symbols. Finally, the emit phase, where all the information built up by the compiler is emitted as an assembly.

Corresponding to each of those phases, an object model that allows access to the information at that phase is surfaced. The parsing phase is exposed as a syntax tree, the declaration phase as a hierarchical symbol table, the binding phase as a model that exposes the result of the compiler’s semantic analysis and the emit phase as an API that produces IL byte codes.

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

To ensure that the public Compiler APIs are sufficient for building world-class IDE features, the language services that will be used to power the C# and VB experiences in Visual Studio vNext have been rebuilt using them. For instance, the code outlining and formatting features use the syntax trees, the Object Browser and navigation features use the symbol table, refactorings and Go to Definition use the semantic model, and Edit and Continue uses all of these, including the Emit API. These experiences may be previewed on Visual Studio 2013 through the “Roslyn” End-User Preview. This preview is required in order to build and test applications build on top of Roslyn SDK meant for integration into Visual Studio though Roslyn APIs can be used in your own applications independently of Visual Studio without requiring the End-User Preview.

API Layers Copy Section

Roslyn consists of two main layers of APIs – the Compiler APIs and Workspaces APIs.

Compiler APIs

The compiler layer contains the object models that correspond with information exposed at each phase of the compiler pipeline, both syntactic and semantic. The compiler layer also contains an immutable snapshot of a single invocation of a compiler, including assembly references, compiler options, and source code files. There are two distinct APIs that represent the C# language and the Visual Basic language. These two APIs are similar in shape but tailored for high-fidelity to each individual language. This layer has no dependencies on Visual Studio components.

Diagnostic APIs

As part of their analysis the compiler may produce a set of diagnostics covering everything from syntax, semantic, and definite assignment errors to various warnings and informational diagnostics. The Compiler API layer exposes diagnostics through an extensible API allowing for user-defined analyzers to be plugged into a Compilation and user-defined diagnostics, such as those produced by tools like StyleCop or FxCop, to be produced alongside compiler-defined diagnostics. Producing diagnostics in this way has the benefit of integrating naturally with tools such as MSBuild and Visual Studio which depend on diagnostics for experiences such as halting a build based on policy, showing live squiggles in the editor and suggesting code fixes.

Scripting APIs

As a part of the compiler layer, the team created hosting/scripting APIs for executing code snippets and accumulating a runtime execution context. The REPL uses these APIs.

Workspaces APIs

The Workspaces layer contains the Workspace API, which is the starting point for doing code analysis and refactoring over entire solutions. It assists you in organizing all the information about the projects in a solution into single 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.

In addition, the Workspaces layer surfaces a set of commonly used APIs used when implementing code analysis and refactoring tools that function within a host environment like the Visual Studio IDE, such as the Find All References, Formatting, and Code Generation APIs.

This layer has no dependencies on Visual Studio components.

Working with Syntax Copy Chapter

The most fundamental data structure exposed by the Compiler APIs is the syntax tree. These trees represent the lexical and syntactic structure of source code. They serve two important purposes:

1. To allow tools - such as an IDE, add-ins, code analysis tools, and refactorings - to see and process the syntactic structure of source code in a user’s project.
2. To enable tools - such as refactorings and an IDE - to create, modify, and rearrange source code in a natural manner without having use direct text edits. By creating and manipulating trees, tools can easily create and rearrange source code.

Syntax Trees Copy Section

Syntax trees are the primary structure used for compilation, code analysis, binding, refactoring, IDE features, and code generation. No part of the source code is understood without it first being identified and categorized into one of many well-known structural language elements.

Syntax trees have three key attributes. The first attribute is that syntax trees hold all the source information in full fidelity. This means that the syntax tree contains every piece of information found in the source text, every grammatical construct, every lexical token, and everything else in between including whitespace, comments, and preprocessor directives. For example, each literal mentioned in the source is represented exactly as it was typed. The syntax trees also represent errors in source code when the program is incomplete or malformed, by representing skipped or missing tokens in the syntax tree.

This enables the second attribute of syntax trees. A syntax tree obtained from the parser is completely round-trippable back to the text it was parsed from. From any syntax node, it is possible to get the text representation of the sub-tree rooted at that node. This means that syntax trees can be used as a way to construct and edit source text. By creating a tree you have by implication created the equivalent text, and by editing a syntax tree, making a new tree out of changes to an existing tree, you have effectively edited the text.

The third attribute of syntax trees is that they are immutable and thread-safe. This means that after a tree is obtained, it is a snapshot of the current state of the code, and never changes. This allows multiple users to interact with the same syntax tree at the same time in different threads without locking or duplication. Because the trees are immutable and no modifications can be made directly to a tree, factory methods help create and modify syntax trees by creating additional snapshots of the tree. The trees are efficient in the way they reuse underlying nodes, so the new version can be rebuilt fast and with little extra memory.

A syntax tree is literally a tree data structure, where non-terminal structural elements parent other elements. Each syntax tree is made up of nodes, tokens, and trivia.

Syntax Nodes Copy Section

Syntax nodes are one of the primary elements of syntax trees. These nodes represent syntactic constructs such as declarations, statements, clauses, and expressions. Each category of syntax nodes is represented by a separate class derived from SyntaxNode. The set of node classes is not extensible.

All syntax nodes are non-terminal nodes in the syntax tree, which means they always have other nodes and tokens as children. As a child of another node, each node has a parent node that can be accessed through the Parent property. Because nodes and trees are immutable, the parent of a node never changes. The root of the tree has a null parent.

Each node has a ChildNodes method, which returns a list of child nodes in sequential order based on its position in the source text. This list does not contain tokens. Each node also has a collection of Descendant methods - such as DescendantNodes, DescendantTokens, or DescendantTrivia - that represent a list of all the nodes, tokens, or trivia that exist in the sub-tree rooted by that node.

In addition, each syntax node subclass exposes all the same children through strongly typed properties. For example, a BinaryExpressionSyntax node class has three additional properties specific to binary operators: Left, OperatorToken, and Right. The type of Left and Right is ExpressionSyntax, and the type of OperatorToken is SyntaxToken.

Some syntax nodes have optional children. For example, an IfStatementSyntax has an optional ElseClauseSyntax. If the child is not present, the property returns null.

Syntax Tokens Copy Section

Syntax tokens are the terminals of the language grammar, representing the smallest syntactic fragments of the code. They are never parents of other nodes or tokens. Syntax tokens consist of keywords, identifiers, literals, and punctuation.

For efficiency purposes, the SyntaxToken type is a CLR value type. Therefore, unlike syntax nodes, there is only one structure for all kinds of tokens with a mix of properties that have meaning depending on the kind of token that is being represented.

For example, an integer literal token represents a numeric value. In addition to the raw source text the token spans, the literal token has a Value property that tells you the exact decoded integer value. This property is typed as Object because it may be one of many primitive types.

The ValueText property tells you the same information as the Value property; however this property is always typed as String. An identifier in C# source text may include Unicode escape characters, yet the syntax of the escape sequence itself is not considered part of the identifier name. So although the raw text spanned by the token does include the escape sequence, the ValueText property does not. Instead, it includes the Unicode characters identified by the escape.

Syntax Trivia Copy Section

Syntax trivia represent the parts of the source text that are largely insignificant for normal understanding of the code, such as whitespace, comments, and preprocessor directives.

Because trivia are not part of the normal language syntax and can appear anywhere between any two tokens, they are not included in the syntax tree as a child of a node. Yet, because they are important when implementing a feature like refactoring and to maintain full fidelity with the source text, they do exist as part of the syntax tree.

You can access trivia by inspecting a token’s LeadingTrivia or TrailingTrivia collections. When source text is parsed, sequences of trivia are associated with tokens. In general, a token owns any trivia after it on the same line up to the next token. Any trivia after that line is associated with the following token. The first token in the source file gets all the initial trivia, and the last sequence of trivia in the file is tacked onto the end-of-file token, which otherwise has zero width.

Unlike syntax nodes and tokens, syntax trivia do not have parents. Yet, because they are part of the tree and each is associated with a single token, you may access the token it is associated with using the Token property.

Like syntax tokens, trivia are value types. The single SyntaxTrivia type is used to describe all kinds of trivia.

Spans Copy Section

Each node, token, or trivia knows its position within the source text and the number of characters it consists of. A text position is represented as a 32-bit integer, which is a zero-based Unicode character index. A TextSpan object is the beginning position and a count of characters, both represented as integers. If TextSpan has a zero length, it refers to a location between two characters.

Each node has two TextSpan properties: Span and FullSpan.

The Span property is the text span from the start of the first token in the node’s sub-tree to the end of the last token. This span does not include any leading or trailing trivia.

The FullSpan property is the text span that includes the node’s normal span, plus the span of any leading or trailing trivia.

For example:

if (x > 3)
      {
||        // this is bad
          |throw new Exception("Not right.");|  // better exception?||
      }

The statement node inside the block has a span indicated by the single vertical bars (|). It includes the characters +throw new Exception(“Not right.”);+. The full span is indicated by the double vertical bars (||). It includes the same characters as the span and the characters associated with the leading and trailing trivia.

Kinds Copy Section

Each node, token, or trivia has a RawKind property, of type System.Int32, that identifies the exact syntax element represented. This value can be cast to a language-specific enumeration; each language, C# or VB, has a single SyntaxKind enumeration that lists all the possible nodes, tokens, and trivia elements in the grammar. This conversion can be done automatically by accessing the CSharpSyntaxKind() or VisualBasicSyntaxKind() extension methods.

The RawKind property allows for easy disambiguation of syntax node types that share the same node class. For tokens and trivia, this property is the only way to distinguish one type of element from another.

For example, a single BinaryExpressionSyntax class has Left, OperatorToken, and Right as children. The Kind property distinguishes whether it is an AddExpression, SubtractExpression, or MultiplyExpression kind of syntax node.

Errors Copy Section

Even when the source text contains syntax errors, a full syntax tree that is round-trippable to the source is exposed. When the parser encounters code that does not conform to the defined syntax of the language, it uses one of two techniques to create a syntax tree.

First, if the parser expects a particular kind of token, but does not find it, it may insert a missing token into the syntax tree in the location that the token was expected. A missing token represents the actual token that was expected, but it has an empty span, and its IsMissing property returns true.

Second, the parser may skip tokens until it finds one where it can continue parsing. In this case, the skipped tokens that were skipped are attached as a trivia node with the kind SkippedTokens.

Working with Semantics Copy Chapter

Syntax trees represent the lexical and syntactic structure of source code. Although this information alone is enough to describe all the declarations and logic in the source, it is not enough information to identify what is being referenced.

For example, many types, fields, methods, and local variables with the same name may be spread throughout the source. Although each of these is uniquely different, determining which one an identifier actually refers to often requires a deep understanding of the language rules.

There are program elements represented in source code, and programs can also refer to previously compiled libraries, packaged in assembly files. Although no source code is available for assemblies and therefore no syntax nodes or trees, programs can still refer to elements inside them.

In addition to a syntactic model of the source code, a semantic model encapsulates the language rules, giving you an easy way to make these distinctions.

Compilation Copy Section

A compilation is a representation of everything needed to compile a C# or Visual Basic program, which includes all the assembly references, compiler options, and source files.

Because all this information is in one place, the elements contained in the source code can be described in more detail. The compilation represents each declared type, member, or variable as a symbol. The compilation contains a variety of methods that help you find and relate the symbols that have either been declared in the source code or imported as metadata from an assembly.

Similar to syntax trees, compilations are immutable. After you create a compilation, it cannot be changed by you or anyone else you might be sharing it with. However, you can create a new compilation from an existing compilation, specifying a change as you do so. For example, you might create a compilation that is the same in every way as an existing compilation, except it may include an additional source file or assembly reference.

Symbols Copy Section

A symbol represents a distinct element declared by the source code or imported from an assembly as metadata. Every namespace, type, method, property, field, event, parameter, or local variable is represented by a symbol.

A variety of methods and properties on the Compilation type help you find symbols. For example, you can find a symbol for a declared type by its common metadata name. You can also access the entire symbol table as a tree of symbols rooted by the global namespace.

Symbols also contain additional information that the compiler determined from the source or metadata, such as other referenced symbols. Each kind of symbol is represented by a separate interface derived from ISymbol, each with its own methods and properties detailing the information the compiler has gathered. Many of these properties directly reference other symbols. For example, the ReturnType property of the IMethodSymbol class tells you the actual type symbol that the method declaration referenced.

Symbols present a common representation of namespaces, types, and members, between source code and metadata. For example, a method that was declared in source code and a method that was imported from metadata are both represented by an IMethodSymbol with the same properties.

Symbols are similar in concept to the CLR type system as represented by the System.Reflection API, yet they are richer in that they model more than just types. Namespaces, local variables, and labels are all symbols. In addition, symbols are a representation of language concepts, not CLR concepts. There is a lot of overlap, but there are many meaningful distinctions as well. For instance, an iterator method in C# or Visual Basic is a single symbol. However, when the iterator method is translated to CLR metadata, it is a type and multiple methods.

Semantic Model Copy Section

A semantic model represents all the semantic information for a single source file. You can use it to discover the following:

• The symbols referenced at a specific location in source.
• The resultant type of any expression.
• All diagnostics, which are errors and warnings.
• How variables flow in and out of regions of source.
• The answers to more speculative questions.

Working with a Workspace Copy Chapter

The Workspaces layer is the starting point for doing code analysis and refactoring over entire solutions. Within this layer, the Workspace API assists you in organizing all the information about the projects in a solution into single object model, offering you direct access to compiler layer object models like source text, syntax trees, semantic models and compilations without needing to parse files, configure options or manage inter-project dependencies.

Host environments, like an IDE, provide a workspace for you corresponding to the open solution. It is also possible to use this model outside of an IDE by simply loading a solution file.

Workspace Copy Section

A workspace is an active representation of your solution as a collection of projects, each with a collection of documents. A workspace is typically tied to a host environment that is constantly changing as a user types or manipulates properties.

The workspace provides access to the current model of the solution. When a change in the host environment occurs, the workspace fires corresponding events, and the CurrentSolution property is updated. For example, when the user types in a text editor corresponding to one of the source documents, the workspace uses an event to signal that the overall model of the solution has changed and which document was modified. You can then react to those changes by analyzing the new model for correctness, highlighting areas of significance, or by making a suggestion for a code change.

You can also create stand-alone workspaces that are disconnected from the host environment or used in an application that has no host environment.

Solutions, Projects, Documents Copy Section

Although a workspace may change every time a key is pressed, you can work with the model of the solution in isolation.

A solution is an immutable model of the projects and documents. This means that the model can be shared without locking or duplication. After you obtain a solution instance from the Workspace’s CurrentSolution property, that instance will never change. However, like with syntax trees and compilations, you can modify solutions by constructing new instances based on existing solutions and specific changes. To get the workspace to reflect your changes, you must explicitly apply the changed solution back to the workspace.

A project is a part of the overall immutable solution model. It represents all the source code documents, parse and compilation options, and both assembly and project-to-project references. From a project, you can access the corresponding compilation without needing to determine project dependencies or parse any source files.

A document is also a part of the overall immutable solution model. A document represents a single source file from which you can access the text of the file, the syntax tree, and the semantic model.

The following diagram is a representation of how the Workspace relates to the host environment, tools, and how edits are made.

Summary Copy Chapter

Roslyn exposes a set of Compiler APIs and Workspaces APIs that provides rich information about your source code and that has full fidelity with the C# and Visual Basic languages. The transition to compilers as a platform dramatically lowers the barrier to entry for creating code focused tools and applications. It creates many opportunities for innovation in areas such as meta-programming, code generation and transformation, interactive use of the C# and VB languages, and embedding of C# and VB in domain specific languages.

Compilers CSharp Readme (`docs/compilers/CSharp/readme.md`) Copy Section

Breaking changes (newest release on top):

• .NET 6 and Visual Studio 2022
• Minor releases following .NET 5 and Visual Studio 2019 version 16.9
• .NET 5 and Visual Studio 2019 version 16.9
• Minor releases following Visual Studio 2019 version 16.0
• Visual Studio 2019 version 16.0
• Minor releases following Visual Studio 2017 version 15.0
• Visual Studio 2017 version 15.0
• Visual Studio 2015 version 14.0

Compilers Design README (`docs/compilers/Design/README.md`) Copy Section

Design Docs

This directory is a place for design documents for the Roslyn compilers.

Adding Optional Parameters In Public API (`docs/Adding Optional Parameters in Public API.md`) Copy Section

Adding optional parameters to public methods

Roslyn has strict requirements for maintaining source and binary API compatibility across minor version releases.
Adding overloads of existing methods can be an effective way of adding to the public API without breaking
backwards compatibility. However, overloads involving optional parameters can be tricky to make both source
and binary compatible. The following steps should be followed when adding optional parameters to public methods.

Steps for adding optional parameters to an existing method Copy Chapter

1. Check to see if there is already a method marked with the comment

   text Copy

   // <Previous release> BACKCOMPAT OVERLOAD -- DO NOT TOUCH

2. If it does not:

   1. Copy the method and make any existing optional parameters mandatory.
   2. Change the body to call the original method.
   3. Add the comment // BACKCOMPAT OVERLOAD -- DO NOT TOUCH.
      This method provides binary compatibility with assemblies compiled against the previous APIs.

3. Add your new parameter with a default value to the end of the original method.
   This provides source compatibility to consumers of the previous API.

Examples Copy Chapter

Before:

public void O(string o1 = null, string o2 = null)
    {
    }

After:

public void O(string o1 = null, string o2 = null, bool o3 = false)
    {
    }

    // 1.0 BACKCOMPAT OVERLOAD -- DO NOT TOUCH
    public void O(string o1, string o2)
    {
        O(o1, o2, o3: false);
    }

Things to avoid Copy Chapter

DO NOT add a parameter in the middle of existing optional parameters

public void O(string o1 = null, bool o4 = false, string o2 = null, bool o3 = false, bool o5 = false)
    {
    }

This breaks source compat when certain arguments to a method call are skipped, like O(null, null, o5: true);

DO NOT add multiple overloads with optional parameters

public void O(string o1 = null, string o2 = null, bool o3 = false)
    {
    }

    // 1.0 BACKCOMPAT OVERLOAD -- DO NOT TOUCH
    public void O(string o1 = null, string o2 = null)
    {
         O(o1, o2, o3: false);
    }

Aside from the fact that this is often ambiguous and it won’t compile, it makes verifying
compatibility much harder.

End Result Copy Chapter

The resulting code should 1) have only one overload with optional parameters, which 2) has the
most parameters of all the overloads, and 3) all previous overloads should still exist,
properly commented with their release version, and contain only mandatory parameters.

NOTE Copy Chapter

After this change, if Public API Analyzer complains about it, you should copy the entry for your change from PublicAPI.Shipped.txt and then put that entry in PublicAPI.Unshipped.txt with *REMOVED* prefix.

PublicAPI.Shipped.txt

Example.O(string o1 = null, string o2 = null) -> void

PublicAPI.Unshipped.txt

*REMOVED*Example.O(string o1 = null, string o2 = null) -> void

Breaking API Changes (`docs/Breaking API Changes.md`) Copy Section

API Breaking Changes

Version 1.1.0

Removed VisualBasicCommandLineParser.ctor Copy Section

During a toolset update we noticed the constructor on VisualBasicCommandLineParser was public. This in turn made many of the protected members of CommandLineParser a part of the API surface as it gave external customers an inheritance path.

It was never the intent for these members to be a part of the supported API surface. Creation of the parsers is meant to be done via the Default singleton properties. There seems to be little risk that we broke any customers here and hence we decided to remove this API.

PR: https://github.com/dotnet/roslyn/pull/4169

Changed Simplifier methods to throw ArgumentNullExceptions Copy Section

Changed Simplifier.ReduceAsync, Simplifier.ExpandAsync, and Simplifier.Expand methods to throw ArgumentNullExceptions if any non-optional, nullable arguments are passed in. Previously the user would get a NullReferenceException for synchronous methods and an AggregateException containing a NullReferenceException for asynchronous methods.

PR: https://github.com/dotnet/roslyn/pull/5144

Version 1.3.0

Treat a method marked with both public and private flags as private Copy Section

The scenario is loading an assembly where some methods, fields or nested types have accessibility flags set to 7 (all three bits set), which mean public AND private.
After the fix, such flags are loaded to mean private.
The compat change is we’re trading a compile-time success and runtime failure (native compiler) against a compile-time error (restoring the behavior of v1.2).

Details below:

• The native compiler successfully compiles the method and field case (those only yield runtime error System.TypeLoadException: Invalid Field Access Flags) and reported an accessibility error on the nested type.
• The 1.2 compiler generated errors:

error BC30390: 'C.Private Overloads Sub M()' is not accessible in this context because it is 'Private'.
error BC30389: 'C.F' is not accessible in this context because it is 'Private'.
error BC30389: 'C.C2' is not accessible in this context because it is 'Protected Friend'.
error BC30390: 'C2.Private Overloads Sub M2()' is not accessible in this context because it is 'Private'.

• The 1.3 compiler crashes.
• After fix, the same errors as 1.2 are generated again.

PR: https://github.com/dotnet/roslyn/pull/11547

Don't emit bad DateTimeConstant, and load bad BadTimeConstant as default value instead Copy Section

The change affects compatibility in two ways:

• When loading an invalid DateTimeConstant(-1), the compiler will use default(DateTime) instead, whereas the native compiler would produce code that fails to execute.
• DateTimeConstant(-1) will still count when we check that you don’t specify two default values. The compiler will produce an error, instead of succeeding (and producing IL with two attributes).

PR: https://github.com/dotnet/roslyn/pull/11536

Version 4.1.0

Can no longer inherit from CompletionService and CompletionServiceWithProviders Copy Section

The constructors of Microsoft.CodeAnalysis.Completion and Microsoft.CodeAnalysis.Completion.CompletionServiceWithProviders are now internal.
Roslyn does not support implementing completion for arbitrary languages.

Version 4.2.0

Can no longer inherit from QuickInfoService Copy Section

The constructors of Microsoft.CodeAnalysis.QuickInfoService are now internal.
Roslyn does not support implementing completion for arbitrary languages.

`Microsoft.CodeAnalysis.CodeStyle.NotificationOption` is now immutable Copy Section

All property setters now throw an exception.

Version 4.4.0

Workspace.OnWorkspaceFailed is no longer called when an error occurs while reading source file content from disk.

The Workspace and DocumentId parameters of TextLoader.LoadTextAndVersionAsync(Workspace, DocumentId, CancellationToken) are deprecated.
The method now receives null Workspace and DocumentId.

Version 4.5.0

SymbolDisplayFormat.CSharpErrorMessageFormat and CSharpShortErrorMessageFormat now include parameter names by default if used on a standalone IParameterSymbol.
For example, parameter p in void M(ref int p) was previously formatted as "ref int" and now it is formatted as "ref int p".

Version 4.7.0

`SymbolDisplayFormat` includes parameter name when invoked on `IParameterSymbol` Copy Section

All SymbolDisplayFormats (predefined and user-created) now include parameter names by default if used on a standalone IParameterSymbol for consistency with predefined formats (see the breaking change for version 4.5.0 above).

Changed `IncrementalStepRunReason` when a modified input produced a new output Copy Section

IncrementalGeneratorRunStep.Outputs previously contained IncrementalStepRunReason.Modified as Reason
when the input to the step was modified in a way that produced a new output.
Now the reason will be reported more accurately as IncrementalStepRunReason.New.

Version 4.8.0

Changed `Assembly.Location` behavior in non-Windows Copy Section

The value of Assembly.Location previously held the location on disk where an analyzer or source generator was loaded from. This could be either the original location or the shadow copy location. In 4.8 this will be "" in certain cases when running on non Windows platforms. This is due the compiler server loading assemblies using AssemblyLoadContext.LoadFromStream instead of loading from disk.

This could already happen in other load scenarios but this change moves it into mainline build scenarios.

Deprecation warning for SyntaxNode serialization Copy Section

The ability to serialize/deserialize a SyntaxNode to/from a Stream has been deprecated. The code for this still exists in Roslyn, but attempting to call the APIs to perform these functions will result in 'Obsolete' warnings being reported. A future version of Roslyn will remove this functionality entirely. This functionality could only work for a host that wrote out the nodes to a stream, and later read it back in within the same process instance. It could not be used to communicate across processes, or for persisting nodes to disk to be read in at a later time by a new host sessions. This functionality originally existed for the days when Roslyn was hosted in 32bit processes with limited address space. That is no longer a mainline supported scenario. Clients can get similar functionality by persisting the text of the node, and parsing it back out when needed.

PR: https://github.com/dotnet/roslyn/pull/70365

Version 4.9.0

Obsoletion and removal of SyntaxNode serialization. Copy Section

Continuation of the deprecation that happened in 4.8.0 (see information above). In 4.9.0 this functionality is now entirely removed, and will issue both an obsoletion error, and will throw at runtime if the APIs are used.

PR: https://github.com/dotnet/roslyn/pull/70277

Changes in `Microsoft.CodeAnalysis.Emit.EmitBaseline.CreateInitialBaseline` method Copy Section

A new required parameter Compilation has been added. Existing overloads without this parameter no longer work and throw NotSupportedException.

Changes in `Microsoft.CodeAnalysis.Emit.SemanticEdit` constructors Copy Section

The value of preserveLocalVariables passed to the constructors is no longer used.

Version 5.11.0

Changed the `default` value of `Microsoft.CodeAnalysis.CSharp.Conversion` Copy Section

The default value of Microsoft.CodeAnalysis.CSharp.Conversion struct now returns false for all boolean properties. Previously the Exists and IsExplicit properties returned true:

using System;
using Microsoft.CodeAnalysis.CSharp;

var conv = default(Conversion);
Console.WriteLine(conv.Exists); // Previously was 'True', now 'False'
Console.WriteLine(conv.IsExplicit); // Previously was 'True', now 'False'

PR: https://github.com/dotnet/roslyn/pull/84628

Language Feature Status (`docs/Language Feature Status.md`) Copy Section

Language Feature Status

This document reflects the status, and planned work in progress, for the compiler team. It is a live document
and will be updated as work progresses, features are added / removed, and as work on feature progresses.
This is not an exhaustive list of our features but rather the ones which have active development
efforts behind them.

The "Feature" column contains a link to the championed proposal or doc for the feature.
The "State" column contains a link to the test plan issue for the feature. The test plan should have a "Feature - XYZ" label, which is also used on PRs and issues for the feature.
To add a new feature entry (along with its test plan issue and label), use the new-compiler-feature skill.

Working Set C#

Merged features should be in the bottom portion of the table (below the break), while in-progress features should be in the top portion of the table.
When a feature is merged to the main branch, its entry should be moved to the very bottom of the table and its "State" value should be updated to record the relevant version number.

Working Set VB

C# 15.0

C# 14.0

VB in .NET 10

C# 13.0

C# 12.0

C# 11.0

C# 10.0

VB 17.0

VB 16.9

C# 9

C# 8.0

VB 16.0

C# 7.3

C# 7.2 fixes

C# 7.2

C# 7.1

FAQ

• Is target version a guarantee?: No. It's explicitly not a guarantee. This is just the planned and ongoing work to the best of our knowledge at this time.
• Where are these State values defined?: Take a look at the Developing a Language Feature document.

Layering (`docs/Layering.md`) Copy Section

Roslyn Architecture - Project Layering

Arrows point from a project up to its dependencies.

/* Detailed source-code truncated for AI context efficiency. */

TestAccessor Pattern (`docs/TestAccessor Pattern.md`) Copy Section

The `TestAccessor` Pattern

Prefer testing observable behavior through existing product entry points. Do not
introduce a TestAccessor for exhaustive unit testing or to assert a class's
specific implementation. When a scenario is critical to cover and cannot be
adequately tested through existing observable behavior, the TestAccessor
pattern allows production code to expose the minimum required internal
functionality without making it available to other production code.

The pattern has two primary components:

1. A TestAccessor type, which contains the functionality available only for testing
2. A GetTestAccessor() method, which returns an instance of TestAccessor

The pattern relies on enforcement of a simple rule that no production code is allowed to call a GetTestAccessor() method. This is enforceable either through code reviews or through an analyzer. This pattern has many advantages over alternatives:

• The pattern does not require expanded accessibility (e.g. internal instead of private) for the purpose of testing
• The pattern is self-documenting: all properties and methods within a TestAccessor type are intended only for use in test code
• The pattern is consistent enough to enforce through static analysis (analyzers)
• The pattern is simple enough to enforce manually (code reviews)

The `TestAccessor` Type Copy Chapter

The TestAccessor type is typically defined as a nested structure. In the following example, the SomeProductionType.TestAccessor.PrivateStateData property allows test code to read and write the value of the private field SomeProductionType._privateStateData without exposing the _privateStateData field to other production code.

internal class SomeProductionType
{
  private int _privateStateData;

  internal readonly struct TestAccessor
  {
    private readonly SomeProductionType _instance;

    internal TestAccessor(SomeProductionType instance)
    {
      _instance = instance;
    }

    internal ref int PrivateStateData => ref _instance._privateStateData;
  }
}

The `GetTestAccessor()` Method Copy Chapter

The GetTestAccessor() method is always defined as follows:

internal TestAccessor GetTestAccessor()
  => new TestAccessor(this);

Area Owners (`docs/area-owners.md`) Copy Section

Pull Requests Tagging

If you need to tag folks on an issue or PR, you will generally want to tag the owners (not the lead) for area to which the change or issue is closest to.

Areas Copy Chapter

Roslyn Language Server Copilot Plugin (`docs/roslyn-language-server-copilot-plugin.md`) Copy Section

Roslyn Language Server - Copilot Plugin

The roslyn-language-server is a .NET tool that provides C# language intelligence (go-to-definition, find references, diagnostics, etc.) to AI coding agents via the Language Server Protocol (LSP). It is distributed as a plugin through the dotnet/skills marketplace, enabling automatic installation and use in tools like GitHub Copilot CLI.

Quick Start Copy Chapter

For this repository specifically, the dotnet skill from the dotnet-agent-skills marketplace is checked in at .github/copilot/settings.json, which includes the appropriate lsp.json. The .vscode/settings.json points the server at Roslyn.slnx. That means opening this repo in Copilot CLI is enough to have the C# LSP configured automatically.

Install the plugin Copy Section

In your agent (Copilot CLI, etc.), add the marketplace and install the dotnet plugin:

/plugin marketplace add dotnet/skills
/plugin install dotnet@dotnet-agent-skills

Restart the agent to load the plugin. Once installed, the agent will automatically have access to C# language intelligence for .cs files through the LSP.

What it provides Copy Section

With the plugin active, the agent gains LSP-powered capabilities for C# code:

• Go to Definition — navigate to where a symbol is defined
• Find References — find all usages of a symbol
• Hover — get type information and documentation
• Diagnostics — see compiler errors and warnings
• Document Symbols — list all symbols in a file
• And more — any LSP feature supported by the Roslyn language server

Prerequisites Copy Chapter

• .NET 10 SDK must be installed and available on PATH. Your project can still use an older, supported SDK.

Automatic Project Loading Copy Chapter

The server is configured to automatically discover and load projects via either the --autoLoadProjects [maximum] CLI flag (defaults to a maximum of 500 projects if value omitted) or LSP initializationOptions in the Copilot lsp.json as defined below.

// lsp.json
{
  "initializationOptions": { "autoLoadProjects": 500 }
}

For how the server chooses which solution or projects to load, and how to control it, see Automatic project loading.

Troubleshooting Copy Chapter

Verify LSP configuration is found Copy Section

• In Copilot CLI, running the /lsp show should show the server configured for C#:

Plugin-configured servers:
    • csharp: (.cs) [from dotnet]

Viewing LSP Logs Copy Section

Copilot CLI writes LSP server logs to the .copilot/logs/ directory in your home folder. To inspect the language server's output:

• macOS / Linux: ~/.copilot/logs/
• Windows: %USERPROFILE%\.copilot\logs\

Look for log files related to csharp or roslyn-language-server. These contain the server's startup output, project loading progress, and any errors encountered. This is the first place to check when the language server isn't behaving as expected.

The tool isn't being found Copy Section

• Ensure dotnet is on your PATH.
• Check for a nuget.config (repo, user, or machine-level) that restricts package sources; dnx uses NuGet sources to resolve tools.
• Verify nuget.org (or an other feed that mirrors roslyn-language-server) is enabled, for example with dotnet nuget list source.
• Try installing the tool manually: dotnet tool install -g roslyn-language-server --prerelease.

Project load issues Copy Section

If the LSP logs show failures loading projects

• Verify that a compatible .NET SDK is installed by running dotnet --version.
• Check that your project builds successfully with dotnet build before using the language server.
• For large repositories with multiple solutions, configure dotnet.defaultSolution in .vscode/settings.json to specify which solution to load.

Performance Copy Section

• Loading a solution with many projects may take some time. The server reports progress to the client during loading.
• For large repositories, prefer loading a specific solution (via dotnet.defaultSolution) rather than relying on individual project discovery, which may load test projects and other projects you don't need.

Related Links Copy Chapter

• dotnet/skills repository — Plugin marketplace for .NET agent skills

How It Works Copy Chapter

The plugin is configured in the dotnet/skills repository via plugins/dotnet/lsp.json:

When the agent opens a workspace containing .cs files, it will:

1. Install and run the roslyn-language-server .NET tool on-the-fly using dotnet dnx (which downloads and caches the tool automatically; --yes skips confirmation and --prerelease allows prerelease versions).
2. Communicate over stdio (--stdio) using the Language Server Protocol.
3. Automatically discover and load projects (--autoLoadProjects) so that the agent immediately has full semantic understanding of the codebase.

Command-Line Options Copy Section

Analyzers Analyzer Actions Semantics (`docs/analyzers/Analyzer Actions Semantics.md`) Copy Section

Definitions:

• Session: For batch compilation, a single compilation. For a hosted environment, an arbitrary duration potentially encompassing many compilations. In particular, for VS, a session shares the lifetime and scope of an analyzer reference, which may correspond to a loaded project, a loaded solution, or the VS process.
• Analyzer: An instance of a type derived from DiagnosticAnalyzer.
• Action: A method instance registered via a Register***Action method of an instance of a ***Context class, to be automatically applied as appropriate. Every action is associated with an analyzer and has a kind (which is one of compilation start, syntax tree, symbol, code block start, syntax node, code block, code block end, semantic model, compilation, compilation end).
• Operation block: A single unit of executable code containing operation nodes, e.g. a method body, parameter default value, field initializer, etc. Operation blocks are primarily used for semantic analysis of executable code using the IOperation APIs.
• Code block: A single unit of executable code containing syntax nodes, e.g. a method body, parameter default value, field initializer, etc. Code blocks are primarily used for syntax and/or semantic analysis of executable code using the language specific Syntax APIs. However, it is recommended that analyzers use Operation block and IOperation API for semantic analysis of executable code for improved performance and simpler, language-agnostic implementation.
• Symbol members: List of zero or member symbols for a given ISymbol. For a namespace or type symbol, these are the members returned by INamespaceOrTypeSymbol.GetMembers API, which include nested symbols. Method, field, event and property symbols have no member symbols.

Axioms:

• Two different analyzers are assumed not to share state. No actions of a single analyzer execute concurrently, unless they explicitly configure concurrent execution in the DiagnosticAnalyzer.Initialize method by invoking AnalysisContext.EnableConcurrentExecution. Actions of different analyzers may execute concurrently. (This is likely to be refined as we develop more sophisticated concurrency strategies, but it will remain true that actions will generally not require locks to avoid races.)
• The context used to register an action affects the lifetime of the registration but does not otherwise affect the semantics of applying the action.
• If an analyzer has multiple applicable actions of any given kind, all of those actions are applied in an arbitrary order.

Ordering of actions:

The DiagnosticAnalyzer.Initialize method of an analyzer is invoked before any actions of an analyzer can be applied. The actions registered by Initialize methods form the initial set of actions used for each compilation. Initialize method may be invoked multiple times on an analyzer instance in a session, but is guaranteed to be invoked only once for any given compilation.

The following rules related to action invocation apply per compilation or per any environmental change that invalidates prior analysis (e.g. changes to analyzer options or changes to non-compiled documents used by analyzers). For purposes of this specification, such environmental changes act as if they create a new compilation.

There are no ordering constraints for the invocations of any actions, except those introduced by start and end actions (compilation start, compilation end, symbol start, symbol end, operation block start, operation block end, code bock start, and code block end actions). Invocations of actions of one kind may be interleaved with invocations of actions of another kind. A given host environment might appear to provide a predictable order—for example, invoking syntax tree actions before semantic model actions, or symbol actions before code block actions, but depending on such an ordering is not safe.

• A compilation start action is invoked once, before any of the analyzer’s other kinds of actions are invoked. Actions registered by a compilation start action apply to that compilation only.
• A syntax tree action is invoked once per source document. A syntax tree action can be expected to be invoked as early as possible after a document is parsed, but this is not guaranteed.
• A symbol action is invoked once per complete semantic processing of a declaration of a type or type member, provided that symbol has a kind matching one of the kinds supplied when the action was registered.
• A symbol start action is invoked exactly once for every symbol of registered SymbolKind, before any of the analyzer’s other kinds of actions are invoked on the symbol or the symbol's members. A symbol start action can register following actions:
  • Actions for syntax and operation nodes within the symbol and its members: Operation action, operation block action, operation block start action, syntax node action, code block action and code block start action.
  • Symbol end action for the symbol, after all other applicable actions of an analyzer have been invoked on the symbol and its members.
• An operation block start action is invoked once per operation block, before any operation node actions applicable to nodes within the block. Actions registered by a operation block start action apply to that operation block only.
• An operation action is invoked once per operation node, provided that the operation node has a kind matching one of the kinds supplied when the action was registered.
• An operation block action is invoked once per operation block.
• An operation block end action is invoked once per operation block, after invoking any operation node actions applicable to nodes within the block and any operation block actions for the block.
• A code block start action is invoked once per code block, before any syntax node actions applicable to nodes within the block. Actions registered by a code block start action apply to that code block only.
• A syntax node action is invoked once per syntax node, provided that the syntax node has a kind matching one of the kinds supplied when the action was registered.
• A code block action is invoked once per code block.
• A code block end action is invoked once per code block, after invoking any syntax node actions applicable to nodes within the block and any code block actions for the block.
• A semantic model action is invoked once per source document.
• A compilation action is invoked once.
• A compilation end action is invoked once, after all other applicable actions of an analyzer have been invoked.

Summarizing the ordering rules:

• For a given compilation, compilation start actions run first and compilation end actions run last.
• For a given symbol, symbol start actions run before operation/syntax/symbol actions on a symbol and its members, and these operation/syntax/symbol actions run before the symbol end actions.
• For a given operation block, operation block start actions run before operation node actions, and operation node actions run before the operation block end actions.
• For a given code block, code block start actions run before syntax node actions, and syntax node actions run before code block end actions.
• Otherwise, there are no ordering guarantees for action invocation.

Implementation freedom:

If an implementation determines that a given action will have equivalent effects in two compilations within a session, it can omit invoking the action for the second compilation and instead retain the effects of invoking it for the first compilation. For example, in an IDE, edits to a source document will not necessarily cause actions to be invoked for unrelated symbols etc. defined in other documents.

A host environment may delay invocation of actions arbitrarily and indefinitely. For example, an IDE might delay invoking some actions until a significant pause in editing activity, during which time several compilations might be initiated. Some actions might not execute at all for the interim compilations, because they will be cancelled when the next compilation begins. In such cases, it is possible for a compilation start action to run without its corresponding compilation end actions ever running for a given compilation, and likewise a code block start action can run without its corresponding code block end actions ever running. Therefore, end actions cannot be relied upon to free resources acquired by start actions.

Analyzers Analyzer Samples (`docs/analyzers/Analyzer Samples.md`) Copy Section

Samples Location:

Sample analyzers to demonstrate recommended implementation models for different analysis scenarios have been added to Samples.sln.

Description:

Analyzers have been broadly categorized into the following three buckets based on the kind of analysis performed:

1. Stateless analyzers: Analyzers that report diagnostics about a specific code unit, such as a symbol, syntax node, code block, compilation, etc. Most analyzers would fall into this bucket.
   These analyzers register one or more actions, that:
   1. Do not require maintaining state across analyzer actions and are
   2. Independent of the order of execution of individual analyzer actions.
2. Stateful analyzers: Analyzers that report diagnostics about a specific code unit, but in context of an enclosing code unit such as a code block or a compilation. These represent slightly more complicated analyzers that require more powerful and wider analysis and hence need careful design to achieve efficient analyzer execution without memory leaks.
   These analyzers require at least one of the following kind of state manipulation for analysis:
   1. Access to immutable state object(s) for the enclosing code unit, such as a compilation or the code block. For example, access to certain well known types defined in a compilation.
   2. Perform analysis over the enclosing code unit, with mutable state defined and initialized in a start action for the enclosing code unit, intermediate actions that access and/or update this state, and an end action to report diagnostic on the individual code units.
3. Additional File analyzers: Analyzers that read data from non-source text files included in the project.

Contents:

Following sample analyzers, with simple unit tests, are provided:

1. Stateless analyzers:
   1. SymbolAnalyzer: Analyzer for reporting symbol diagnostics.
   2. SyntaxNodeAnalyzer: Analyzer for reporting syntax node diagnostics.
   3. CodeBlockAnalyzer: Analyzer for reporting code block diagnostics.
   4. CompilationAnalyzer: Analyzer for reporting compilation diagnostics.
   5. SyntaxTreeAnalyzer: Analyzer for reporting syntax tree diagnostics.
   6. SemanticModelAnalyzer: Analyzer for reporting syntax tree diagnostics, that require some semantic analysis.
2. Stateful analyzers:
   1. CodeBlockStartedAnalyzer: Analyzer to demonstrate code block wide analysis.
   2. CompilationStartedAnalyzer: Analyzer to demonstrate analysis within a compilation, for example analysis that depends on certain well-known symbol(s).
   3. CompilationStartedAnalyzerWithCompilationWideAnalysis: Analyzer to demonstrate compilation-wide analysis.
3. Additional File analyzers:
   1. SimpleAdditionalFileAnalyzer: Demonstrates reading an additional file line-by-line and using the data in analysis.
   2. XmlAdditionalFileAnalyzer: Demonstrates writing an additional file out to a Stream so that it can be read back as a structured document (in this case, XML).

Analyzers DiagnosticSuppressorDesign (`docs/analyzers/DiagnosticSuppressorDesign.md`) Copy Section

Feature Request

https://github.com/dotnet/roslyn/issues/30172: Programmatic suppression of warnings

Provide an ability for platform/library authors to author simple, context-aware compiler extensions to programmatically suppress specific instances of reported analyzer and/or compiler diagnostics, which are always known to be false positives in the context of the platform/library.

Programmatically Suppressible Diagnostic

An analyzer/compiler diagnostic would be considered a candidate for programmatic suppression if all of the following conditions hold:

1. Not an error by default: Diagnostic's DefaultSeverity is not DiagnosticSeverity.Error.
2. Must be configurable: Diagnostic is not tagged with WellKnownDiagnosticTags.NotConfigurable custom tag, indicating that its severity is configurable.
3. No existing source suppression: Diagnostic is not already suppressed in source via pragma/suppress message attribute.

Core Design

1. For platform/library authors: Expose a new "DiagnosticSuppressor" public API for authoring such compiler extensions. API contract for the suppressors (detailed API with doc comments in the last section):
   1. Declaratively provide all the analyzer and/or compiler diagnostic IDs that can be suppressed by it.
   2. For each such suppressible diagnostic ID, provide a unique suppression ID and justification. These are required to enable proper diagnosis and configuration of each suppression (covered in detail later).
   3. Register callbacks for reported analyzer and/or compiler diagnostics with these suppressible diagnostic IDs. The callback can analyze the syntax and/or semantics of the diagnostic location and report a suppression for it.
   4. DiagnosticSuppressors would not be able to register any other analysis callbacks, and hence cannot report any new diagnostics.
2. For end users:
   1. Seamless development experience when targeting such a platform/library, whereby the users do not see false positives from analyzers/compiler in their development context.
   2. End users do not need to manually add and/or maintain source suppressions through pragmas/SuppressMessageAttributes for such context-specific false positives.
   3. End users still have the ultimate control over suppressors (specifics covered in later section):
      1. Audit: Diagnostic suppressions are logged as "Info" diagnostics on the command line, so the end users can audit each suppression in the verbose build log or msbuild binlog. Additionally, they are also logged in the /errorlog SARIF file as suppressed diagnostics.
      2. Configuration: Each diagnostic suppression has an associated suppression ID. This is clearly indicated in the logged "Info" diagnostics for suppressions, and the end users can disable the bucket of suppressions under any specific suppression ID with simple command line argument or ruleset entries.
3. For analyzer driver:
   1. Order of execution between analyzers/compiler and suppressors: For command line builds, all diagnostic suppressors will run after all the analyzer and compiler diagnostics have been computed. For live analysis in Visual Studio, diagnostic suppressors may be invoked with a subset of the full set of reported diagnostics, as an optimization for supporting incremental and partial analysis scenarios.
   2. Order of execution between individual suppressors: Execution of diagnostic suppressors would be independent of other suppressors. Diagnostic suppressions reported by one suppressor would not affect the input set of reported diagnostics passed to any other suppressor. Each diagnostic might be programmatically suppressed by more than one suppressor, so the analyzer driver will union all the reported suppressions for each diagnostic. Command line compiler will log one suppression diagnostic per-suppression for each programmatically suppressed diagnostic.

Development Experience Example

Let us consider the core example for UnityEngine covered in https://github.com/dotnet/roslyn/issues/30172:

using UnityEngine;

class BulletMovement : MonoBehaviour
{
    [SerializeField] private float speed;

    private void Update()
    {
         this.transform.position *= speed;
    }
}

Serialization frameworks and tools embedding .NET Core or Mono often set the value of fields or call methods outside of user code. Such code is not available for analysis to the compiler and analyzers, leading to false reports such as following:

1. CS0649: Field 'speed' is never assigned to, and will always have its default value 0
2. IDE0044 dotnet_style_readonly_field: Make field 'speed' readonly

New experience with screenshots: Copy Chapter

1. For platform/library authors: UnityEngine can selectively suppress instances of such diagnostics by writing a simple SerializedFieldDiagnosticSuppressor extension based on the DiagnosticSuppressor API and packaging it along with the Unity framework SDK/library.
2. For end users:
   1. Users do not see above false positives in the IDE live analysis or command line build. For example, see the below screenshots with and without the SerializedFieldDiagnosticSuppressor:
      1. Without the suppressor: See image here
      2. With the suppressor: See image here
   2. Audit suppressions:
      1. Command line build: End users will see "Info" severity suppression diagnostics in command line builds, see image here
         info SPR0001: Diagnostic 'CS0649' was programmatically suppressed by a DiagnosticSuppressor with suppresion ID 'SPR1001' and justification 'Field symbols marked with SerializedFieldAttribute are implicitly assigned by UnityEngine at runtime and hence do not have its default value'
         These diagnostics will always be logged in the msbuild binlog. They would not be visible in the console output for regular msbuild invocations, but increasing the msbuild verbosity to detailed or diagnostic will emit these diagnostics.
      2. Visual Studio IDE: Users can see the original suppressed diagnostic in the Visual Studio Error List when they change the default filter for the "Suppression State" column in the error list to include "Suppressed" diagnostics, see image here. In future, we also plan to add a new error list column, possibly named "Suppression Source", which will display the suppression ID and justification associated with each programmatic suppression.
   3. Disable suppressors: End users can disable specific suppression IDs from an analyzer package using the following two mechanisms:
      1. /nowarn:<%suppression_id%>: See image here for disabling the suppression ID from the project property page, which in turn generates the nowarn command line argument.
      2. Ruleset entry: See image here for disabling the suppression ID using a CodeAnalysis ruleset

Open Questions:

1. Should the DiagnsoticSuppressor feature be Opt-in OR on-by-default: This was brought up few times in the past, especially with the concern with on-by-default behavior being that an end user would not see any indication in the command line that diagnostic suppressors were executed as part of their build. I think we have following options:

   1. Opt-in:
      1. Keep the feature behind a new, permanent feature flag: This way the command line arguments will always indicate if diagnostic suppressors were involved in the build.
      2. Add a new command line switch to enable suppressors
   2. On-By-default: No command line argument indicating suppressors are involved in a build, but users can look at binlogs and/or verbose msbuild output logs to determine the same.

   The draft PR for this feature currently puts the feature being a feature flag. If we decide to take the on-by-default route, I can revert the changes adding the feature flag. Otherwise, if we decide that we should make it opt-in with a new command line compiler switch, I would like to propose that we keep the feature flag for the initial PR, and then have a follow-up PR to add the command line switch.

   Update: We have decided to keep the feature being a temporary feature flag for initial release, which will be removed once we are confident about the feature's performance, user experience, etc.

2. Message for the "Info" suppression diagnostic: I have chosen the below message format (with 3 format arguments), but any suggested changes are welcome:
   Diagnostic 'CS0649' was programmatically suppressed by a DiagnosticSuppressor with suppresion ID 'SPR1001' and justification 'Field symbols marked with SerializedFieldAttribute are implicitly assigned by UnityEngine at runtime and hence do not have its default value'

3. What should be the diagnostic ID for the "Info" suppression diagnostic?: We have following options:

   1. Use a CSxxxx/BCxxxx diagnostic ID for the suppression diagnostic so it is evident that the diagnostic is coming from the core compiler.
   2. Use a distinct diagnostic prefix, such as 'SPR0001', similar to the way we report 'AD0001' diagnostics for analyzer exceptions. This provides a separate bucketing/categorization for these special suppression diagnostics.
      The draft PR chooses the second approach with 'SPR0001' as the diagnostic ID.

   Update: We have decided the diagnostic ID would be SP0001.

Draft PR implementing the above proposal:

https://github.com/dotnet/roslyn/pull/36067

Detailed API proposal with documentation comments from the Draft PR

/* Detailed source-code truncated for AI context efficiency. */

Analyzers FixAllProvider (`docs/analyzers/FixAllProvider.md`) Copy Section

Introduction

This document covers the following:

• Introductory definitions
• What is a FixAll occurrences code fix?
• How is a FixAll occurrences code fix computed?
• Adding FixAll support to your code fixer
• Selecting an Equivalence key for code actions
• Spectrum of FixAll providers
• Built-in FixAllProvider and its limitations
• Implementing a custom FixAllProvider

Definitions

• Analyzer: An instance of a type derived from DiagnosticAnalyzer that reports diagnostics.
• Code fixer: An instance of a type derived from CodeFixProvider that provides code fixes for compiler and/or analyzer diagnostics.
• Code refactoring: An instance of a type derived from CodeRefactoringProvider that provides source code refactorings.
• Code action: An action registered by CodeFixProvider.RegisterCodeFixesAsync that performs a code fix OR an action registered by CodeRefactoringProvider.ComputeRefactoringsAsync that performs a code refactoring.
• Equivalence Key: A string value representing an equivalence class of all code actions registered by a code fixer or refactoring. Two code actions are treated as equivalent if they have equal EquivalenceKey values and were generated by the same code fixer or refactoring.
• FixAll provider: An instance of a type derived from FixAllProvider that provides a FixAll occurrences code fix. A FixAll provider is associated with a corresponding code fixer by CodeFixProvider.GetFixAllProvider method.
• FixAll occurrences code fix: A code action returned by FixAllProvider.GetFixAsync, that fixes all or multiple occurrences of diagnostics fixed by the corresponding code fixer, within a given FixAllScope.

What is a FixAll occurrences code fix?

In layman terms, a FixAll occurrences code fix means: I have a code fix 'C', that fixes a specific instance of diagnostic 'D' in my source and I want to apply this fix to all instances of 'D' across a broader scope, such as a document or a project or the entire solution.

In more technical terms: Given a particular code action registered by a code fixer to fix one or more diagnostics, a corresponding code action registered by its FixAll provider, that applies the original trigger code action across a broader scope (such as a document/project/solution) to fix multiple instances of such diagnostics.

How is a FixAll occurrences code fix computed?

Following steps are used to compute a FixAll occurrences code fix:

• Given a specific instance of a diagnostic, compute the set of code actions that claim to fix the diagnostic.
• Select a specific code action from this set. In the Visual Studio IDE, this is done by selecting a specific code action in the light bulb menu.
• The equivalence key of the selected code action represents the class of code actions that must be applied as part of a FixAll occurrences code fix.
• Given this code action, get the FixAll provider corresponding to the code fixer that registered this code action.
• If non-null, then request the FixAll provider for its supported FixAllScopes.
• Select a specific FixAllScope from this set. In the Visual Studio IDE, this is done by clicking on the scope hyperlink in the preview dialog.
• Given the trigger diagnostic(s), the equivalence key of the trigger code action, and the FixAll scope, invoke FixAllProvider.GetFixAsync to compute the FixAll occurrences code fix.

Adding FixAll support to your code fixer

Follow the below steps to add FixAll support to your code fixer:

• Override the CodeFixProvider.GetFixAllProvider method and return a non-null instance of a FixAllProvider. You may either use our built-in FixAllProvider or implement a custom FixAllProvider. See the following sections in this document for determining the correct approach for your fixer.
• Ensure that all the code actions registered by your code fixer have a non-null equivalence key. See the following section to determine how to select an equivalence key.

Selecting an Equivalence key for code actions

Each unique equivalence key for a code fixer defines a unique equivalence class of code actions. Equivalence key of the trigger code action is part of the FixAllContext and is used to determine the FixAll occurrences code fix.
Normally, you can use the 'title' of the code action as the equivalence key. However, there are cases where you may desire to have different values. Let us take an example to get a better understanding.

Let us consider the C# SimplifyTypeNamesCodeFixProvider that registers multiple code actions and also has FixAll support. This code fixer offers fixes to simplify the following expressions:

• this expressions of the form 'this.x' to 'x'.
• Qualified type names of the form 'A.B' to 'B'.
• Member access expressions of the form 'A.M' to 'M'.

This fixer needs the following semantics for the corresponding FixAll occurrences code fixes:

• this expression simplification: Fix all should simplify all this expressions, regardless of the member being accessed (this.x, this.y, this.z, etc.).
• Qualified type name simplification: Fix all should simplify all qualified type names 'A.B' to 'B'. However, we don't want to simplify all qualified type names, such as 'C.D', 'E.F', etc. as that would be too generic a fix, which is not likely intended by the user.
• Member access expressions: Fix all should simplify all member access expressions 'A.M' to 'M'.

It uses the below equivalence keys for its registered code actions to get the desired FixAll behavior:

• this expression simplification: Generic resource string "Simplify this expression", which explicitly excludes the contents of the node being simplified.
• Qualified type name simplification: Formatted resource string "Simplify type name A.B", which explicitly includes the contents of the node being simplified.
• Member access expressions: Formatted resource string "Simplify type name A.M", which explicitly includes the contents of the node being simplified.

Note that 'this expression simplification' fix requires a different kind of an equivalence class from the other two simplifications. See method GetCodeActionId for the actual implementation.

To summarize, use the equivalence key that best suits the category of fixes to be applied as part of a FixAll operation.

Spectrum of FixAll providers

When multiple fixes need to be applied to documents, there are various ways to do it:

• Sequential approach: One way to do it is to compute diagnostics, pick one, ask a fixer to produce a code action to fix that, apply it. Now for the resulting new compilation, recompute diagnostics, pick the next one and repeat the process. This approach would be very slow but would lead to correct results (unless it doesn't converge where one fix introduces a diagnostic that was just fixed by a previous fix). We chose to not implement this approach.
• Batch fix approach: Another way is to compute all the diagnostics, pick each diagnostic and give it to a fixer and apply it to produce a new solution. If there were 'n' diagnostics, there would be 'n' new solutions. Now just merge them all together in one go. This may produce incorrect results (when different fixes change the same region of code in different ways) but it is very fast. We have one implementation of this approach in WellKnownFixAllProviders.BatchFixer
• Custom approach: Depending on the fix, there may be a custom solution to fix multiple issues. For example, consider an analyzer that simply needs to generate one file as the fix for any instance of the issue. Instead of generating the same file over and over using the previous two approaches, one could write a custom FixAllProvider that simply generates the file once if there were any diagnostics at all.

Since there are various ways of fixing all issues, we've implemented a framework and provided the one general implementation that we think is useful in many cases.

Built-in FixAllProvider

We provide a default BatchFixAllProvider implementation of a FixAll provider that uses the underlying code fixer to compute the FixAll occurrences code fixes.
To use the batch fixer, you should return the static WellKnownFixAllProviders.BatchFixer instance in the CodeFixProvider.GetFixAllProvider override.
NOTE: See the following section on 'Limitations of the BatchFixer' to determine if the batch fixer can be used by your code fixer.

Given a trigger diagnostic, a trigger code action, the underlying code fixer and the FixAll scope, the BatchFixer computes FixAll occurrences code fix with the following steps:

• Compute all instances of the trigger diagnostic across the FixAll scope.
• For each computed diagnostic, invoke the underlying code fixer to compute the set of code actions to fix the diagnostic.
• Collect all the registered code actions that have the same equivalence key as the trigger code action.
• Apply all these code actions on the original solution snapshot to compute new solution snapshots. The batch fixer only batches code action operations of type ApplyChangesOperation present within the individual code actions, other types of operations are ignored.
• Sequentially merge the new solution snapshots into a final solution snapshot. Only non-conflicting code actions whose fix spans don't overlap the fix spans of prior merged code actions are retained.

Limitations of the BatchFixer

The BatchFixer is designed for a common category of fixers where fix spans for diagnostics don't overlap with each other. For example, assume there is a diagnostic that spans a particular expression, and a fixer that fixes that expression. If all the instances of this diagnostic are guaranteed to have non-overlapping spans, then their fixes can be computed independently and this batch of fixes can be subsequently merged together.

However, there are cases where the BatchFixer might not work for your fixer. Following are some such examples:

• Code fixer registers code actions without an equivalence key or with a null equivalence key.
• Code fixer registers non-local code actions, i.e. a code action whose fix span is completely distinct from diagnostic span. For example, a fix that adds a new declaration node. Multiple such fixes are likely to have overlapping spans and hence could be conflicting.
• Diagnostics to be fixed as part of FixAll occurrences have overlapping spans. It is likely that fixes for such diagnostics will have overlapping spans too, and hence would conflict with each other.
• Code fixer registers code actions with operations other than ApplyChangesOperation. BatchFixer ignores such operations and hence may produce unexpected results.

Implementing a custom FixAllProvider

For cases where you cannot use the BatchFixer, you must implement your own FixAllProvider. It is recommended that you create a singleton instance of the FixAll provider, instead of creating a new instance for every CodeFixProvider.GetFixAllProvider invocation.
Following guidelines should help in the implementation:

• GetFixAsync: Primary method to compute the FixAll occurrences code fix for a given FixAllContext. You may use the set of 'GetXXXDiagnosticsAsync' methods on the FixAllContext to compute the diagnostics to be fixed. You must return a single code action that fixes all the diagnostics in the given FixAll scope.
• GetSupportedFixAllScopes: Virtual method to get all the supported FixAll scopes. By default, it returns all the three supported scopes: document, project and solution scopes. Generally, you need not override this method. However, you may do so if you wish to support a subset of these scopes.
• GetSupportedFixAllDiagnosticIds: Virtual method to get all the fixable diagnostic ids. By default, it returns the underlying code fixer's FixableDiagnosticIds. Generally, you need not override this method. However, you may do so if you wish to support FixAll only for a subset of these ids.

See DeclarePublicAPIFix for an example implementation of a custom FixAllProvider.

Analyzers Localizing Analyzers (`docs/analyzers/Localizing Analyzers.md`) Copy Section

Introduction

This document covers the following:

• Setting up your project to use localized resources
• Using localized resources in Analyzers
• Using localized resources in Code Fixes
• Producing localized resource assemblies
• Packaging resource assemblies in NuGet packages and VSIXes
• Testing the localization at the command line and in VS

Setting up the Project

You'll need to create a .resx file to hold your localizable resources. For the purposes of this document, we'll assume you are putting them in a file named 'AnalyzerResources.resx'.

Using Localized Resources in Analyzers Copy Chapter

Normally, .NET applications can simply access the resource through the type generated from the .resx file:

string message = AnalyzerResources.Message;

and the framework will use the culture specified in System.Globalization.CultureInfo.CurrentUICulture to automatically find and return the appropriately localized resource.

However, the C# and VB compilers provide the /preferreduilang switch to specify the use of resources for a different culture from that in CurrentUICulture. Because of that accessing AnalyzerResources.Message directly within an analyzer will not return the correct resource.

Instead you need to access these resources through the LocalizableResourceString type. For example:

LocalizableResourceString message = new LocalizableResourceString(nameof(AnalyzerResources.Message), AnalyzerResources.ResourceManager, typeof(AnalyzerResources));

Using Localized Resources in Code Fixes Copy Chapter

Code Fixes, on the other hand, are not affected by the /preferreduilang switch. Resources in Code Fixes should be accessed in the standard way:

string codeFixMessage = AnalyzerResources.CodeFixMessage;

Producing Localized Resource Assemblies

To create resource assemblies, you simply need to add additional .resx files with the desired language name in the file name. For example, if you wanted to create a resource assembly with German strings, you would add AnalyzerResources.de.resx. For Japanese, you add AnalyzerResources.ja.resx, and so on.

Inside these files you add items where the names match those in AnalyzerResources.resx and the values have the localized content. If AnalyzerResources.resx contains the following:

Then AnalyzerResources.de.resx should contain this:

Now when you build resource assemblies are automatically produced in language-specific sub folders:

• bin\Debug\
  • MyAnalyzer.dll
  • MyAnalyzer.pdb
  • de\
    • MyAnalyzer.resources.dll
  • ja\
    • MyAnalyzer.resources.dll

This layout is also what the CLR expects at runtime: for a given assembly Foo.dll, the localized resources should be in language-specific folders next to the assembly.

Packaging Resource Assemblies

NuGet Copy Chapter

NuGet packaging is straight-forward, as you simply need to duplicate the structure of the build output:

<files>
  <file src="MyAnalyzer.dll" target="tools\analyzers" />
  <file src="de\MyAnalyzer.resources.dll" target="tools\analyzers\de" />
  <file src="ja\MyAnalyzer.resources.dll" target="tools\analyzers\ja" />
  ...
</files>

VSIX Copy Chapter

Extension projects automatically incorporate satellite assemblies into the resulting .vsix file.

Testing Analyzer Localization

At the command line Copy Chapter

Once the NuGet package is installed, you can force the build to use localized resources by passing the /preferreduilang flag to csc.exe or vbc.exe:

csc.exe /preferreduilang:de /t:library /analyzer:... Foo.cs

Alternatively, you can pass it to MSBuild as a property:

msbuild /p:PreferredUILang=de

or set it as a property in the *proj file itself:

de

In VS Copy Chapter

In VS analyzers use the selected UI language. This can be changed by selecting "Options..." from the "Tools" menu, and navigating to Environment -> International Settings.

Analyzers Report Analyzer Format (`docs/analyzers/Report Analyzer Format.md`) Copy Section

Introduction

The C# and Visual Basic compilers support a /reportanalyzer switch on
the command line to report additional analyzer information, such as execution time.

The output contains the total wall clock time spent in executing the analyzers and
the relative execution times per-analyzer.
Note that the elapsed time may be less than analyzer execution time because
analyzers can run concurrently. One should use this data only for comparative analysis to
identify any outlier analyzer which takes signinficantly more time than other analyzers.

MSBuild command

Use the following msbuild command line to get the analyzer performance report:

msbuild.exe /v:d /p:reportanalyzer=true <%project_file%>

Output Format

Total analyzer execution time: XYZ seconds.
NOTE: Elapsed time may be less than analyzer execution time because analyzers can run concurrently.

Example

Following is an example output from a project built with analyzers:

/* Detailed source-code truncated for AI context efficiency. */

Analyzers Using Additional Files (`docs/analyzers/Using Additional Files.md`) Copy Section

Introduction

This document covers the following:

• Uses of Additional Files
• Passing Additional Files on the command line
• Specifying an individual item as an AdditionalFile in an MSBuild project
• Specifying an entire set of items as AdditionalFiles in an MSBuild project
• Accessing and reading additional files through the AnalyzerOptions type
• Includes sample analyzers that read additional files

Uses

Sometimes an analyzer needs access to information that is not available through normal compiler inputs--source files, references, and options. To support these scenarios the C# and Visual Basic compilers can accept additional, non-source text files as inputs.

For example, an analyzer may enforce that a set of banned terms is not used within a project, or that every source file has a certain copyright header. The terms or copyright header could be passed to the analyzer as an additional file, rather than being hard-coded in the analyzer itself.

On the Command Line

On the command line, additional files can be passed using the /additionalfile option. For example:

csc.exe alpha.cs /additionalfile:terms.txt

In a Project File

Passing an Individual File Copy Chapter

To specify an individual project item as an additional file, set the item type to AdditionalFiles:

<ItemGroup>
  <AdditionalFiles Include="terms.txt" />
</ItemGroup>

Passing a Group of Files Copy Chapter

Sometimes it isn't possible to change the item type, or a whole set of items need to be passed as additional files. In this situation you can update the AdditionalFileItemNames property to specify which item types to include. For example, if your analyzer needs access to all .resx files in the project, you can do the following:

<PropertyGroup>
  
  <AdditionalFileItemNames>$(AdditionalFileItemNames);EmbeddedResource</AdditionalFileItemNames>
</PropertyGroup>
<ItemGroup>
  
  <EmbeddedResource Include="Terms.resx">
    ...
  </EmbeddedResource>
</ItemGroup>

Accessing Additional Files

The set of additional files can be accessed via the Options property of the context object passed to a diagnostic action. For example:

CompilationAnalysisContext context = ...;
ImmutableArray<AdditionalText> additionFiles = context.Options.AdditionalFiles;

From an AdditionalText instance, you can access the path to the file or the contents as a SourceText:

AdditionText additionalFile = ...;
string path = additionalFile.Path;
SourceText contents = additionalFile.GetText();

Samples

Reading a File Line-by-Line Copy Chapter

This sample reads a simple text file for a set of terms--one per line--that should not be used in type names.

/* Detailed source-code truncated for AI context efficiency. */

Converting a File to a Stream Copy Chapter

In cases where an additional file contains structured data (e.g., XML or JSON) the line-by-line access provided by the SourceText may not be desirable. One alternative is to convert a SourceText to a string, by calling ToString() on it. This sample demonstrates another alternative: converting a SourceText to a Stream for consumption by other libraries. The terms file is assumed to have the following format:

<Terms>
  <Term>frob</Term>
  <Term>wizbang</Term>
  <Term>orange</Term>
</Terms>

/* Detailed source-code truncated for AI context efficiency. */

Compilers Boolean Representation (`docs/compilers/Boolean Representation.md`) Copy Section

Representation of Boolean Values

The C# and VB compilers represent true (True) and false (False) bool (Boolean) values with the single byte values 1 and 0, respectively, and assume that any boolean values that they are working with are restricted to being represented by these two underlying values. The ECMA 335 CLI specification permits a "true" boolean value to be represented by any nonzero value. If you use boolean values that have an underlying representation other than 0 or 1, you can get unexpected results. This can occur in unsafe code in C#, or by interoperating with a language that permits other values. To avoid these unexpected results, it is the programmer's responsibility to normalize such incoming values.

See also https://github.com/dotnet/roslyn/issues/24652

Compilers Co Located Core Types (`docs/compilers/Co-located core types.md`) Copy Section

Co-located core types

Customer Scenario and Context Copy Chapter

The ECMA 335 spec indicates that a few types, such as System.Object, or System.Int16, can be referenced in metadata as an integer value rather than a type ref token (built-in types). Additionally, the spec indicates that certain conversions are allowed between these types and a small set of token-referenced types – we shall refer to these as special types. Finally, a few types have special runtime treatment without being referenced like the other built-in types.

Scenarios

1. A compiler needs to find the type definition for a built-in type, given a reference to it. Given that the reference is not a type token, the compiler needs to know the assembly containing the def

2. A compiler encounters two definitions for a built-in type

3. A compiler is asked to type check two references to a built-in type, one of which is originating from a library compiled to an incompatible definition of core types

Design Copy Chapter

Compilers may assume that there is exactly one assembly representing the "core assembly". This core assembly is either referenced or is currently being compiled. The core assembly must not reference any other assemblies.

The core assembly contains the type definitions for the subset of built-in and special types supported on a platform.

References to types having the same name as built-in types but found outside the core assembly are made via type tokens.

An assembly A referencing only built-in types may exclude (as per ECMA spec) a reference to the core library. In the case A is further referenced by the compiler when compiling a second assembly B, the references to the built-in types in A are resolved by the compiler based on the core library used for compiling B.

A platform implementation may choose to define a core assembly with only a subset of the built-in and special types. Compilation in such a scenario succeeds, as long as built-in or special types outside of the subset are not referenced, directly (by user code) or indirectly (by compiler features). This means that, while the compiler can safely assume that all built-in and special types are co-located in the same assembly, they may not all be present.

If a later version of the platform introduces more built-in or special types, they must do so in the core assembly.

Correspondingly, a runtime for such a platform need only support the subset in the corresponding core assembly.

The list of co-located types is exactly the following:

• System.Object
• System.Enum
• System.MulticastDelegate
• System.Delegate
• System.ValueType
• System.Void
• System.Boolean
• System.Char
• System.SByte
• System.Byte
• System.Int16
• System.UInt16
• System.Int32
• System.UInt32
• System.Int64
• System.UInt64
• System.Decimal
• System.Single
• System.Double
• System.String
• System.IntPtr
• System.UIntPtr
• System.Array
• System.DateTime
• System.Collections.IEnumerable
• System.Collections.Generic.IEnumerable<>
• System.Collections.Generic.IList<>
• System.Collections.Generic.ICollection<>
• System.Collections.Generic.IEnumerator<>
• System.Collections.IEnumerator
• System.Nullable<>
• System.Runtime.CompilerServices.IsVolatile
• System.IDisposable
• System.TypedReference
• System.IAsyncResult
• System.AsyncCallback
• System.Collections.Generic.IReadOnlyList<>
• System.Collections.Generic.IReadOnlyCollection<>

We continue to assume that references to System.Type are made by-enumeration value when the reference is made in a custom attribute, and as a regular reference when not. Note the departure from the ECMA spec which included System.Type. System.Type and other reflection types are intentionally not in the core library. Since System.Type may be referenced as a built-in type, the compiler may assume that there is at most one definition for this type available in the compilation context, and treat as an error the case where there is more than one. No definition should be accepted as long as there is no reference.

Language features relying on APIs not in the list should not assume any particular assembly location for the definition of such APIs. Compilers should either use heuristics, or require explicit specification of the location of such APIs.

Compilers Compiler Server (`docs/compilers/Compiler Server.md`) Copy Section

Compiler Server

As a performance optimization, the Roslyn C# and VB compilers support using a
server process to execute compilations instead of executing the compilation
in-process. Engineering has focused on three performance benefits from the server:

1. Re-using a single process to do compilation amortizes the cost of JITing the
   compiler code. This is usually the single largest performance benefit.
2. Roslyn requires assembly references to be hydrated into a rich object
   model to perform compilation. The compiler server holds a fixed-size cache of
   metadata symbols, which can help compilation times if most compilations share
   a sizable portion of metadata references (e.g., mscorlib).
3. On Windows process creation itself is expensive, so dispatching compilations
   directly from MSBuild saves creations of csc.exe.

Usage Copy Chapter

The primary way to use the compiler server is via the
Microsoft.Build.Tasks.CodeAnalysis MSBuild task, which ships in both the
dotnet SDK and Visual Studio. The build task contains a build client which,
rather than executing the csc.exe or vbc.exe, creates the
VBCSCompiler.exe process and dispatches the command line arguments to the
server directly.

If you're not using MSBuild, there's also a flag, /shared which can be
passed directly to csc.exe, which causes csc.exe to behave as a client
and dispatches the actual compilation to the server process. In this mode
csc.exe doesn't perform any computation itself, it just dispatches the
command line to the server process (starting one if one does not already
exist), and then reports the results of the compilation (including any
warnings/errors produced).

Importantly, the server is a performance optimization. If server compilation
fails for any reason, the compiler will fall back to stand-alone compilation.
For MSBuild, this means creating a standard csc.exe process. For /shared
this means continuing the compilation in-process, as though /shared were
not passed. No diagnostics are produced in this case, as there are very
common environmental reasons for any given server compilation to fail.

This also implies that it is always safe to kill the compiler server process,
as the client will always recover gracefully.

Architecture Copy Chapter

Roslyn supports a client-server protocol where multiple clients can dispatch
to multiple servers and multiple servers can run concurrently on the machine.
The client and server must run on the same machine, as the client and server
only exchange a command line, not real assets.

Troubleshooting Copy Chapter

To diagnose problems with the server compilation, you can enable an
environment variable that writes a diagnostic log file:

(UNIX): export RoslynCommandLineLogFile=/path/to/log/file
(Windows CMD, using directory path): setx RoslynCommandLineLogFile="C:\path\to\log"
(Windows CMD, using file path): setx RoslynCommandLineLogFile="C:\path\to\log\file.log"

This file contains diagnostic logging for both the client and server,
which you can distinguish using the PID tag for each diagnostic line.
Sample output should look something like this:

--- PID=90433 TID=16 Ticks=1048119217: Attempt to open named pipe 'angocke.F.MW9E3dnrZddlsgI8MNFfpJyup'
--- PID=90433 TID=16 Ticks=1048119217: Attempt to connect named pipe 'angocke.F.MW9E3dnrZddlsgI8MNFfpJyup'
--- PID=90436 TID=1 Ticks=244465170: Keep alive timeout is: 600000 milliseconds.
--- PID=90436 TID=1 Ticks=244465182: Constructing pipe 'angocke.F.MW9E3dnrZddlsgI8MNFfpJyup'.
--- PID=90436 TID=1 Ticks=244465182: Successfully constructed pipe 'angocke.F.MW9E3dnrZddlsgI8MNFfpJyup'.

Here PID 90433 is the client, as it's attempting to open a connection
(named pipe), while PID 90436 is the server, as it is constructing the
named client. If it succeeds, the result looks something like:

--- PID=90436 TID=8 Ticks=244476082: ****C# Compilation complete.
****Return code: 0
****Output:
Microsoft (R) Visual C# Compiler version 2.9.0.63018 (e3fa7d6a)
Copyright (C) Microsoft Corporation. All rights reserved.

Otherwise, you may be able to discover what's going wrong from other output,
like exception messages.

Compilers Compiler Toolset NuPkgs (`docs/compilers/Compiler Toolset NuPkgs.md`) Copy Section

Compiler Toolset NuPkgs

Summary Copy Chapter

The compiler produces the Microsoft.Net.Compilers.Toolset NuPkg
from all of Roslyn's main branches. When this NuPkg is installed it will
override the compiler that comes with MSBuild with the version from the branch
it was built in.

This package is meant to support the following scenarios:

1. Allows compiler team to provide rapid hot fixes to customers who hit a blocking
   issue. This package can be installed until the fix is available in .NET SDK or
   Visual Studio servicing.
2. Serves as a transport mechanism for the Roslyn binaries in the greater .NET
   SDK build process.
3. Allows customers to conduct experiments on various Roslyn builds, many of
   which aren't in an official shipping product yet.

This package is not meant to support using newer compiler versions in an
older version of MSBuild. For example using Microsoft.Net.Compilers.Toolset
3.5 (C# 8) inside MSBuild 15 is explicitly not a supported scenario.

Customers who want to use the compiler as a part of their supported build
infrastructure should use the Visual Studio Build Tools SKU
) or .NET SDK

NuPkg Installation Copy Chapter

To install the NuPgk run the following:

> nuget install Microsoft.Net.Compilers.Toolset   # Install C# and VB compilers

Daily NuGet builds of the project are also available in our Azure DevOps feed:

https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json

Microsoft.Net.Compilers Copy Chapter

The Microsoft.Net.Compilers
NuPkg is deprecated. It is a .NET Desktop specific version of
Microsoft.Net.Compilers.Toolset and will not be produced anymore after the
3.6.0 release. The Microsoft.Net.Compilers.Toolset package is a drop in
replacement for it for all supported scenarios.

Compilers Deterministic Inputs (`docs/compilers/Deterministic Inputs.md`) Copy Section

Deterministic Inputs

The C# and VB compilers are fully deterministic when the /deterministic option is specified (this is the default in the .NET SDK). This means that the "same inputs" will cause the compilers to produce the "same outputs" byte for byte.

The following are considered inputs to the compiler for the purpose of determinism:

• The sequence of command-line parameters (order is important)
• The precise version of the compiler used and the files included in its deployment: reference assemblies, rsp, etc ...
• Current full directory path (you can reduce this to a relative path; see https://github.com/dotnet/roslyn/issues/949)
• (Binary) contents of all files explicitly passed to the compiler, directly or indirectly, including
  • source files
  • referenced assemblies
  • referenced modules
  • resources
  • the strong name key file
  • @ response files
  • Analyzers
  • Generators
  • Rulesets
  • "additional files" that may be used by analyzers and generators
• The current culture if /preferreduilang is not specified (for the language in which diagnostics and exception messages are produced).
• The current OS code page if /codepage is not specified and any of the input source files do not have BOM and are not UTF-8 encoded.
• The existence, non-existence, and contents of files on the compiler's search paths (specified, e.g. by /lib or /recurse)
• The CLR platform on which the compiler is run:
  • The result of double arithmetic performed for constant-folding may use excess precision on some platforms.
  • The compiler uses Unicode tables provided by the platform.
• The version of the zlib library that the CLR uses to implement compression (when /embed or /debug:embedded is used).
• The value of %LIBPATH%, as it can affect reference discovery if not fully qualified and how the runtime handles analyzer / generator dependency loading.
• The full path of source files although /pathmap can be used to normalize this between compiles of the same code in different root directories.

At the moment the compiler also depends on the time of day and random numbers for GUIDs, so it is not deterministic unless you specify /deterministic.

Debugging Determinism Failures Copy Chapter

When investigating determinism issues where the same code produces different outputs, you can use several techniques to identify the cause:

1. Generate a Deterministic Key File Copy Section

Build with /p:Features="debug-determinism" to generate a .key file that documents all inputs to the compiler:

dotnet build /p:Features="debug-determinism"

This creates an additional output file (e.g., MyAssembly.dll.key) in the output directory (typically in the obj directory for intermediate builds). The key file is a JSON document containing:

• Compiler version and runtime information
• All source file paths and content checksums
• Referenced assemblies with their MVIDs (Module Version IDs)
• Compilation options
• Parse options
• Emit options
• Analyzer and generator information

Compare the .key files from two supposedly identical builds to identify which inputs differ:

# Unix/Linux/Mac
diff build1/MyAssembly.dll.key build2/MyAssembly.dll.key

# Windows (using fc)
fc build1\MyAssembly.dll.key build2\MyAssembly.dll.key

Note: If the .key files are identical but the output assemblies differ, this indicates a compiler determinism bug. Please report such cases to the Roslyn team with a reproduction so the issue can be investigated.

2. Compare Metadata Using metadata-tools Copy Section

Install the mdv (MetaData Viewer) tool from the dotnet/metadata-tools repository:

dotnet tool install mdv -g --prerelease --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json

Generate metadata dumps for your assemblies and compare them:

# Generate metadata output for each DLL
mdv MyAssembly1.dll > assembly1.txt
mdv MyAssembly2.dll > assembly2.txt

# Compare the outputs
diff assembly1.txt assembly2.txt

The metadata dump shows detailed information about types, methods, fields, attributes, and other metadata in the assembly. Differences in the metadata can help identify what changed between builds.

3. Compare Embedded Resources Copy Section

If your assembly contains embedded resources, verify they are identical. The recommended approach is to use ILSpy, which has an easy "Save" button to export resources from the DLL for comparison. Other tools like dnSpy or ildasm can also be used to extract and inspect embedded resources.

Example using ildasm to disassemble and extract embedded .res files:

# Disassemble and generate .res files
ildasm /out=assembly1.il MyAssembly1.dll
ildasm /out=assembly2.il MyAssembly2.dll

# Compare the generated .res files
diff assembly1.res assembly2.res

4. Binary Diff of the DLL Copy Section

As a last resort, perform a hex dump comparison of the actual DLL files:

# Unix/Linux/Mac - using xxd or hexdump
xxd MyAssembly1.dll > assembly1.hex
xxd MyAssembly2.dll > assembly2.hex
diff assembly1.hex assembly2.hex

# Windows - using fc with /b flag for binary comparison
fc /b MyAssembly1.dll MyAssembly2.dll

# Or using Format-Hex in PowerShell
Format-Hex MyAssembly1.dll | Out-File assembly1.hex
Format-Hex MyAssembly2.dll | Out-File assembly2.hex
Compare-Object (Get-Content assembly1.hex) (Get-Content assembly2.hex)

A hex diff shows the exact bytes that differ, which can help identify non-deterministic data like timestamps, GUIDs, or other embedded values.

Common Causes of Non-Determinism Copy Section

When debugging, look for these common issues:

• Missing /deterministic flag: Ensure /deterministic is enabled
• Absolute paths: Use /pathmap to normalize file paths
• Timestamps: Check if PDBs or other files embed build times
• Different compiler versions: Verify same compiler version is used
• Different reference assembly versions: Check MVIDs (Module Version IDs) in .key files
• Environment variables: Variables like %LIBPATH% can affect output
• Source file encoding: Ensure consistent encoding (UTF-8 with BOM recommended)
• Generator/analyzer differences: Verify same versions are loaded

Compilers Error Log Format (`docs/compilers/Error Log Format.md`) Copy Section

The C# and Visual Basic compilers support a /errorlog: switch on
the command line to log all diagnostics in a structured, JSON format.

The log format is SARIF (Static Analysis Results Interchange Format):
See https://sarifweb.azurewebsites.net/ for the format specification,
JSON schema, and other related resources.

SARIF v2 format Copy Chapter

This section provides a high level overview of the contents of the SARIF v2 error log file generated by the C# and Visual Basic compilers. A more formal and detailed schema specification for the SARIF v2 format is specified at http://json.schemastore.org/sarif-2.1.0.

1. schema and version information: The first two lines of the error log file specifies the SARIF schema and version information. For example:

"$schema": "http://json.schemastore.org/sarif-2.1.0",
"version": "2.1.0",

2. runs information: The core entry in the error log file is the runs section with a single run entry within it for the build. The run entry has the following main parts:
   1. results section: This section contains an array of result entries, where each result corresponds to information about a reported compiler or analyzer Diagnostic. More details in Result format for each compiler or analyzer Diagnostic instance.
   2. properties section: This section contains custom key-value properties associated with the run. Following properties are currently emitted:
      1. analyzerExecutionTime: Execution time in seconds for execution of all analyzers, as reported with the /reportAnalyzer compiler switch.
   3. tools section: This section contains information about the compiler build and version. Additionally, it contains a rules array, where each rule entry corresponds to metadata or DiagnosticDescriptor information about each reported analyzer diagnostic. More details in Rule format for each analyzer supported DiagnosticDescriptor instance
   4. invocations section: This section contains information about the end user specified configurations for the rules for compiler invocation/run. We emit this section only if at least one rule had one or more severity configuration overrides for a part or whole of the compilation via options. More details in Rule Configuration Override format for each rule severity override.
   5. columnKind section: This section contains information about the unit in which the tool measures columns. C# and Visual Basic compilers uses utf16 code units.

Example runs section, with stripped off results, rules and ruleConfigurationOverrides sections:

"runs": [
{
  "results": [
  ],
  "properties": {
    "analyzerExecutionTime": "x.xxx"
  },
  "tool": {
    "driver": {
      "name": "Microsoft (R) Visual C# Compiler",
      "version": "4.4.0-dev (<developer build>)",
      "dottedQuadFileVersion": "42.42.42.42",
      "semanticVersion": "42.42.42",
      "language": "en-US",
      "rules": [
      ]
    }
  },
  "invocations": [
    {
      "executionSuccessful": true,
      "ruleConfigurationOverrides": [
      ]
    }
  ],
  "columnKind": "utf16CodeUnits"
}
]

`Result` format for each compiler or analyzer `Diagnostic` instance Copy Section

The results section contains an array of result entries, where each result corresponds to information about a reported compiler or analyzer Diagnostic. It contains the below data:

1. ruleId: Rule ID or diagnostic ID for the diagnostic.
2. ruleIndex: Index into the rules section for the underlying DiagnosticDescriptor for the diagnostic. See Rule format for each analyzer supported DiagnosticDescriptor instance for more details.
3. level: Severity level for the diagnostic, such as error, warning, note, etc.
4. message: User facing message for the diagnostic.
5. suppressions: For each diagnostic instance that is suppressed with a pragma directive, SuppressMessageAttribute or via a DiagnosticSuppressor, the result entry contains suppressions section with the following data:
   1. kind information: C# and Visual Basic compilers support a single inSource suppression kind.
   2. justification information: Justification pertaining to the suppression. Currently, this field is populated only for SuppressMessageAttribute based suppression, with a non-null justification argument.
   3. suppressionType property with one of these three values: Pramga Directive, SuppressMessageAttribute, or DiagnosticSuppressor. This data helps analyze the preferred in-source suppression mechanisms in a code base.
6. locations: One or more locations associated with the diagnostic.
7. properties: One or more custom key-value string pairs associated with the diagnostic.

Example result entry:

{
  "ruleId": "CA1822",
  "ruleIndex": 97,
  "level": "warning",
  "message": {
    "text": "Member 'M2' does not access instance data and can be marked as static"
  },
  "suppressions": [
  {
    "kind": "inSource",
    "justification": "<Pending>",
    "properties": {
      "suppressionType": "SuppressMessageAttribute"
    }
  }
  ],
  "locations": [
  {
    "physicalLocation": {
      "artifactLocation": {
        "uri": "file:///C:/source/repos/ClassLibrary1/Class1.cs"
      },
      "region": {
        "startLine": 13,
        "startColumn": 10,
        "endLine": 13,
        "endColumn": 12
      }
    }
  }
  ],
  "properties": {
    "warningLevel": 1
  }
}

`Rule` format for each analyzer supported `DiagnosticDescriptor` instance Copy Section

The rules section contains a rule entry that corresponds to metadata or DiagnosticDescriptor information about supported descriptors for each analyzer. We report the DiagnosticDescriptor info for all analyzers that were provided to the compilation, regardless of whether or not they executed on the entire compilation, part of the compilation or were disabled for the entire compilation. A rule entry contains the below data:

1. id: Rule ID or Diagnostic ID associated with the descriptor.
2. shortDescription: User facing short description or Title associated with the descriptor.
3. fullDescription: User facing full description or Description associated with the descriptor.
4. defaultConfiguration: Default severity level for the diagnostics reported for the descriptor, such as error, warning, note, etc.
5. helpUri: Help uri for help information associated with the descriptor.
6. properties: One or more custom properties associated with the descriptor. It includes the following:
   1. category: Category associated with the descriptor, such as, Design, Performance, Security, etc.
   2. isEverSuppressed and suppressionKinds: If a rule had either a source suppression or was disabled for part or whole of the compilation via options, the rule metadata contains a special flag isEverSuppressed = true and an array suppressionKinds with either or both of the below suppression kinds:
      1. inSource suppression kind for one or more reported diagnostic(s) that were suppressed through pragma directive, SuppressMessageAttribute or a DiagnosticSuppressor.
      2. external suppression kind for diagnostic ID that is disabled either for the entire compilation (via global options such as /nowarn, ruleset, globalconfig, etc.) or for certain files or folders in the compilation (via editorconfig options).
   3. executionTimeInSeconds: Execution time in seconds associated with the analyzer, as reported with the /reportAnalyzer compiler switch. Values less than 0.001 seconds are reported as <0.001.
   4. executionTimeInPercentage: Execution time in percentage associated with the analyzer, as reported with the /reportAnalyzer compiler switch. Values less than 1 are reported as <1.
   5. tags: An array of one of more CustomTags associated with the descriptor.

Example rule entry:

{
  "id": "CA1001",
  "shortDescription": {
    "text": "Types that own disposable fields should be disposable"
  },
  "fullDescription": {
    "text": "A class declares and implements an instance field that is a System.IDisposable type, and the class does not implement IDisposable. A class that declares an IDisposable field indirectly owns an unmanaged resource and should implement the IDisposable interface."
  },
  "defaultConfiguration": {
    "level": "note"
  },
  "helpUri": "https://docs.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1001",
  "properties": {
    "category": "Design",
    "isEverSuppressed": "true",
    "suppressionKinds": [
      "external"
    ],
    "executionTimeInSeconds": "x.xxx",
    "executionTimeInPercentage": "xx",
    "tags": [
      "PortedFromFxCop",
      "Telemetry",
      "EnabledRuleInAggressiveMode"
    ]
  }
}

`Rule Configuration Override` format for each rule severity override Copy Section

The ruleConfigurationOverrides section contains an array of entries, with an entry for every rule severity configuration override for the whole or part of the compilation via options, i.e. editorconfig, globalconfig, command line options, ruleset, etc. Each rule configuration override entry contains the following information:

1. descriptor: Property containing information to map back to the relevant descriptor or the rule in the rules section. Currently, it contains the below child properties:
   1. id: Rule id string for the rule or diagnostic.
   2. index: A zero-based integral index value into the rules array for the rule mapping.
2. configuration: Configuration property for the effective overridden severity for the rule. Currently, it may include one of the below child properties:
   1. enabled: A boolean property indicating if the rule has been explicitly disabled or enabled with the configuration override entry.
   2. level: Property for the effective severity of the rule, such as error, warning or note. Note that this property is not emitted for rules disabled with configuration override, we instead emit enabled: false for them.

Note that we can have multiple ruleConfigurationOverride entries for the same descriptor if the rule is configured to fire at different severities across different parts of the compilation. For example, editorconfig based severity configurations can specify different effective severity for the same rule ID for different files or folders in a project.

Example ruleConfigurationOverride entry:

{
  "descriptor": {
    "id": "CA1000",
    "index": 0
  },
  "configuration": {
    "level": "error"
  }
},
{
  "descriptor": {
    "id": "CA1000",
    "index": 0
  },
  "configuration": {
    "enabled": false
  }
},
{
  "descriptor": {
    "id": "CA1001",
    "index": 1
  },
  "configuration": {
    "level": "warning"
  }
}

Compilers Extension Methods In Aliased Assemblies (`docs/compilers/Extension Methods in Aliased Assemblies.md`) Copy Section

Extension Methods in the Global Namespace

If you create a compilation in which an imported library is assigned an alias (instead of the default "global" alias), the Roslyn compilers do not automatically see extension methods in the (unnamed top-level) global namespace in that library. You would have to import the library in your code using the alias for these methods to be treated as extension methods.

Previous versions of the compiler would treat such methods as extension methods despite not being imported.

See also https://github.com/dotnet/roslyn/issues/1079.

Compilers IOperation Test Hook (`docs/compilers/IOperation Test Hook.md`) Copy Section

IOperation Test Hook

The compiler has a test hook designed to ensure that IOperation nodes and scenarios match up with information that can be retrieved from the semantic model,
and to help ensure that we have code coverage that ensures IOperation will not fail or violate invariants for scenarios we don't have direct testing on. This
works by running a hook whenever the test framework creates a Compilation object: for every syntax tree in the compilation, we enumerate every syntax node
and verify that GetOperation does not crash, and returns information that matches up with the SemanticModel (ie, GetTypeInfo matches the IOperation type,
for example). We also fetch and verify the control flow graph for every member body in the compilation and run the CFG verifier to ensure that all invariants
are presevered.

Feature Development Copy Chapter

For feature development, this means that as we shift around BoundNodes, introduce new nodes, or enable code that didn't exist before, the hook may hit failures
because the IOperation machinery doesn't handle that particular node, or had logic that now triggers a Debug.Assert because the new code violates some pre-existing
assumption of the factories. For fixing these issues, there are a couple of options:

1. Implement the IOperation changes in the same PR. This is the only acceptable way to do this in a production branch.
2. Add the new BoundKind to the catch-all switch case at the bottom of CSharpOperationFactory/VisualBasicOperationFactory.Create, with a prototype comment
   to ensure that support is implemented before the feature branch is merged back to a production branch. Sometimes, the test hits other failure spots, such as
   SemanticModel failures or mismatches. For these, the test can be marked with ConditionalFact(typeof(NoIOperationValidation)) to skip the test in the test
   hook. When doing so, please mark with a prototype comment (either as a comment above or as the reason string for ConditionalFactAttribute) so that it is fixed
   before merging to production.

Replicating Failures Copy Chapter

In order to replicate test failures, there are 2 options:

1. Uncomment src/Compilers/Test/Core/Compilation/CompilationExtensions.cs:7, which defines ROSLYN_TEST_IOPERATION, and run your tests. Do not check this in, as it
   will enable the test hook for every test in every project and significantly slow down regular test runs.
2. Set the ROSLYN_TEST_IOPERATION environment variable and restart VS with it set.
3. Set a breakpoint at the start of ValidateIOperations, in src/Compilers/Test/Core/Compilation/CompilationExtensions.cs. When it breaks, use VS's jump to location or
   drag the instruction pointer past the early check and return on EnableVerifyIOperation, which will run the code for the current test run.

In either case, after this has been done all tests will run the hook as part of running the test, and you can set breakpoints as normal. It is often helpful to
run until an exception has been hit and then see what nodes were being processed, as most tests have multiple methods and understanding the specific context is
useful for figuring out the earlier steps that may have gone wrong.

When a test failure is isolated, please add a dedicated IOperation test for this to make it easier to avoid future regressions. Preferrably, don't replicate
the entire original test, just enough to hit the bug to ensure that it's protected against regressions.

Compilers Interactive Imports (`docs/compilers/Interactive Imports.md`) Copy Section

Imports in Scripts/Interactive

Guiding principles Copy Chapter

Files includes by #load are each in a separate lexical scope.
Declarations (including aliases) take precedence over usings (including using static) because they express intent.

Process Copy Chapter

Compilers Rule Set Format (`docs/compilers/Rule Set Format.md`) Copy Section

Introduction

This document, in conjunction with the Rule Set Schema, describes the structure of .ruleset files used by the C# and Visual Basic compilers to turn diagnostic analyzers on and off and to control their severity.

This document only discusses the required and common parts of .ruleset files; for a full set, please see the schema file.

Sample

The following demonstrates a small but complete example of a .ruleset file.

<RuleSet Name="Project WizBang Rules"
         ToolsVersion="12.0">
  <Include Path="..\OtherRules.ruleset" 
           Action="Default" />
  <Rules AnalyzerId="System.Runtime.Analyzers"
         RuleNamespace="System.Runtime.Analyzers">
    <Rule Id="CA1027" Action="Warning" />
    <Rule Id="CA1309" Action="Error" />
    <Rule Id="CA2217" Action="Warning" />
  </Rules>
  <Rules AnalyzerId="System.Runtime.InteropServices.Analyzers"
         RuleNamespace="System.Runtime.InteropService.Analyzers">
    <Rule Id="CA1401" Action="None" />
    <Rule Id="CA2101" Action="Error" />
  </Rules>
</RuleSet>

Passing Rule Sets to the Compiler

Command Line Copy Chapter

Rule set files can be passed to csc.exe and vbc.exe using the /ruleset switch, which takes an absolute or relative file path. For example:

vbc.exe /ruleset:ProjectRules.ruleset ...
vbc.exe /ruleset:..\..\..\SolutionRules.ruleset ...
vbc.exe /ruleset:D:\WizbangCorp\Development\CompanyRules.ruleset ...

MSBuild Projects Copy Chapter

Within MSBuild project files the rule set can be specified via the CodeAnalysisRuleSet property. For example:

<PropertyGroup>
  <CodeAnalysisRuleSet>ProjectRules.ruleset</CodeAnalysisRuleSet>
</PropertyGroup>

Note that because the rule set is specified via a property rather than an item, IDEs like Visual Studio will not show the rule set as a file in your project by default. For this reason it is common to explicitly include the file as an item as well:

<ItemGroup>
  <None Include="ProjectRules.ruleset" />
</ItemGroup>

Elements

`RuleSet` Copy Chapter

The RuleSet is the root element of the file.

Attributes:

• Name (required): A short, descriptive name for the file.
• Description (optional): A longer description of the purpose of the rule set file.
• ToolsVersion (required): This attribute is required for backwards compatibility with other tools that use .ruleset files. In practice it is the version of Visual Studio that produced this .ruleset file. When in doubt, simply use "12.0".

Children: Include, Rules

`Include` Copy Chapter

Pulls in the settings from the specified rule set file. Settings in the current file override settings in the included file.

Parent: RuleSet

Attributes:

• Path (required): An absolute or relative path to another .ruleset file.
• Action (required): Specifies the effective action of the included rules. Must be one of the following values:
• Default - The rules use the actions specified in the included file.
• Error - The included rules are treated as though their action values were all "Error".
• Warning - The included rules are treated as though their actions values were all "Warning".
• Info - The included rules are treated as though their actions values were all "Info".
• Hidden - The included rules are treated as though their actions values were all "Hidden".
• None - The included rules are treated as though their actions values were all "None".

Children: None.

`Rules` Copy Chapter

Hold settings for rules from a single diagnostic analyzer.

Parent: RuleSet

Attributes:

• AnalyzerId (required): The name of the analyzer. In practice this is the simple name of the assembly containing the diagnostics.
• RuleNamespace (required): This attribute is required for backwards compatibility with other tools that use .ruleset files. In practice it is generally the same as the AnalyzerId.

Children: Rule

`Rule` Copy Chapter

Specifies what action to take for a given diagnostic rule.

Parent: Rules

Attributes:

• Id (required): The ID of the diagnostic rule.
• Action (required): One of the following values:
• Error - Instances of this diagnostic are treated as compiler errors.
• Warning - Instances of this diagnostic are treated as compiler warnings.
• Info - Instances of this diagnostic are treated as compiler messages.
• Hidden - Instances of this diagnostic are hidden from the user.
• None - Turns off the diagnostic rule.

Children: None.

Notes:

Within a Rules element, a Rule with a given Id may only appear once. The C# and Visual Basic compilers impose a further constraint: if multiple Rules elements contain a Rule with the same Id they must all specify the same Action value.

The difference between the Hidden and None actions is subtle but important. When a diagnostic rule is set to Hidden instances of that rule are still created, but aren't displayed to the user by default. However, the host process can access these diagnostics and take some host-specific action. For example, Visual Studio uses a combination of Hidden diagnostics and a custom editor extension to "grey out" dead or unnecessary code in the editor. A diagnostic rule set to None, however, is effectively turned off. Instances of this diagnostic may not be produced at all; even if they are suppressed rather than being made available to the host.

Compilers Analyzer Config (`docs/compilers/analyzer-config.md`) Copy Section

Compiler Support for AnalyzerConfig

AnalyzerConfig is an EditorConfig-superset (https://editorconfig.org/) file
format recognized by the Roslyn command line compiler. The options specified
in analyzer config files are recognized by the compiler in two ways: option
keys following the pattern dotnet_diagnostic.<diagnostic-id>.severity = <value> are parsed and interpreted by the compiler to configure the severity
of compiler diagnostics. <diagnostic-id> represents the diagnostic ID
matched by the compiler, case-insensitively, to be configured. <value> must
be the name of a member of the
ReportDiagnostic
enum, also case-insensitive. These settings are then applied on a
per-SyntaxTree to each of the files whose path matched the AnalyzerConfig
name specification in the compilation.

Any properties which do not have the aforementioned pattern are considered
analyzer options and are placed in a PerTreeOptionsProvider on the
AnalyzerOptions
type for
use by analyzers.

AnalyzerConfig files can be passed to the command-line compiler through the
/analyzerconfig:<file-path> parameter.

Compilers Terrapin (`docs/compilers/terrapin.md`) Copy Section

.NET and Terrapin Process

The Terrapin system is concerned with validating the provenance of NuPkgs in the .NET ecosystem. Specifically it needs to verify that DLLs in a NuPkg can be rebuilt using publicly available artifacts.

This document describes the workflow that will be used by Terrapin for validating the provenance of .NET binaries, responsibilities of each team, as well as the tools the .NET team will deliver to enable the service to be successful.

.NET Tools Copy Chapter

The .NET Team will deliver a set of tools to the Terrapin team to provide the necessary validation. The idea in providing a series of tools here vs. a single all in one tool is to help better separate out the different responsibilities involved here and letting the appropriate team handle them:

1. Providing the list of artifacts necessary for validation to succeed (owned by .NET)
2. Acquiring the artifacts necessary for validation (owned by Terrapin)
3. Performing validation and making a determination of provenance (owned by .NET)

It's possible in the future we will end up providing a "all in one" experience tool but for the short term we'll be focusing on keeping these responsibilities and tools separate.

dotnet-build-manifest-generator Copy Section

This is global tool which takes in a DLL / PDB file combination and will generate an artifacts manifest file which lists the set of artifacts necessary to perform a validation. This includes the version of dotnet-build-validator which needs to be used to perform the validation.

This tool is meant to work with binaries produced by earlier versions of the .NET compiler. Every time the contents of the PDB provenance metadata change a new version of this tool will be produced that can account for the metadata. The expectation is that Terrapin will always have the latest version of this tool installed on their service.

dotnet-build-validator Copy Section

A global tool which takes in the following arguments: the PE file to validate, its accompanying PDB and a directory containing the artifacts gathered from the artifacts manifest file. The tool will then return whether the provided PDB file can have it's provenance validated.

The tool will have three output states:

1. Validation succeeded
2. Validation failed because the binaries do not match
3. Validation failed because a binary could not be produced

This tool will be sim-shipped with the compiler: every time there is a new compiler, there will be a new version of this tool that uses those compiler binaries. This is important because the compiler does not guarantee deterministic output between versions of the compiler. Even minor version differences of the compiler can produce different IL for the same source code if the code intersects a bug fix or optimization. In order for the validator to function with high fidelity Terrapin must use the version that sim-shipped with the compiler.

The expectation is that Terrapin will install this as a local tool for a given validation event. That will allow for every validation event to use a different version of dotnet-build-validator without having to worry about version conflicts as it would if it were installed as a global tool.

The Terrapin Service Workflow Copy Chapter

The Terrapin service will validate a DLL by going through the following workflow for every DLL in a NuPkg file:

1. Execute dotnet-build-manifest-generator on the DLL + PDB combination.
2. Setup the environment for validation:
   1. Transfer execution to the appropriate operating system listed in the manifest. All future actions are expected to run on this machine.
   2. Install the correct .NET Runtime on the target machine (if necessary)
3. Download the artifacts listed in the artifact manifest file as well as the specified version of dotnet-build-validator.
4. Execute dotnet-build-validator providing the DLL, PDB and the directory where the artifacts were downloaded too.

The Terrapin service will download the artifacts into a directory created by Terrapin. The directory will have two directories to store source files and references respectively: sources and references. The name of the artifacts in those directories will be specified in the manifest file. That will put the burden of avoiding collisions and dealing with file path fixup on the compiler team.

Artifacts Manifest File Copy Chapter

The goal of dotnet-build-manifest-generator is to provide a manifest file to the Terrapin service which lists all of the artifacts necessary for a validation to be completed as well as the environment needed to run the validation. The set of artifacts that are necessary include:

1. The source files used in the compilation.
2. The reference DLLs used in the compilation.

At this time the expectation is Terrapin will need to recreate much of the environment used to create the binaries in order to perform provenance validation. This includes having a matching .NET Runtime version and operating system. This is because OS dependencies, like zip compression version, can impact the deterministic output of the compiler. It's possible our experiments in Terrapin will cause us to re-evaluate how these play into determinism but for now the design is to build validation on top of our existing assumptions here.

To facilitate this the artifact manifest file will include all of the necessary environment information. This will include the OS RID, the .NET Runtime version and whether a desktop or NET Core runtime was used to run the compiler.

The artifacts manifest file will be a JSON file with the following format:

{
    "sources": [
        { 
            "uri": "https://github.com/dotnet/roslyn/blob/f5517311e37a3883e09dc6daa5069bbc4f44c882/src/Compilers/Shared/Csc.cs",
            "destFileName": "c6fea380dac7392b945fa6c63466746f830c5cc3"
        }
    ],
    "references": [
        {
            "name": "System.Reflection.Metadata.dll",
            "mvid": "51ef3ce0-5a89-4325-b094-8a5970acc676",
            "destFileName": "51ef3ce0-5a89-4325-b094-8a5970acc676",
        }
    ],
    "environment": {
        "compiler-language": "csharp",
        "compiler-version": "3.8.0",
        "os": "windows",
        "os-version": "...",
        "dotnet-runtime": "net5.0.0"
    }
}

Phases of validation Copy Chapter

There are still many open questions surrounding this effort like the impact of code pages, line endings as well as how strongly .NET runtime versions impact determinism of our outputs. The best way to answer these questions is to be pushing real customer code through the service to prove out the real impact of these problems. There are also just general process issues we need to work out between like cadence of delivery as well as just making sure all the pieces fit together.

To help solve both of these we will be breaking this effort up into a series of milestones that increase in complexity. Each one moving us closer to our goals around provenance of all major NuPkgs in the ecosystem:

The milestones are:

• Roslyn can successfully validate dotnet/roslyn on a machine that just built dotnet/roslyn. This will give us confidence the underlying provenance checks are achievable. All of the artifacts necessary to perform validation will be located on the machine in well known locations hence that will allow us to separate out "acquisition of artifacts"
• Roslyn will produce versions of dotnet-build-manifest-generator and dotnet-build-validator for Terrapin and they will validate that they can use them on projects they are hosting locally.
• Rebuild of DLLs on Windows: the target of this milestone is NuPkgs produced on Windows using the .NET Framework compiler. The goal is for us to be able to rebuild the DLLs, whether validation succeeds or fails. This will help us ensure that we have the right process in place between Terrapin and .NET as well that the PDBs do truly contain enough information for us to recreate compilations.
• Validation of DLLs on Windows: the target of this milestone is NuPkgs produced on Windows using the .NET Framework compiler. The goal is for us to validate the provenance of these binaries as well as find common reasons why provenance validation fails. This will let us begin the conversation with .NET customers on how to change their build to make it provenance friendly.
• Validation of DLLs on Windows Part 2: the target of this milestone is NuPkgs produced on Windows using the .NET Core compiler. This will require Terrapin to take the extra environment setup step of installing the correct .NET Core runtime and using that to drive the installation process.
• Validate binaries produced on Linux / Mac: the target of this milestone is NuPkgs produced on Linux / Mac. This will require Terrapin to involve multiple machines in the validation process. It will also help us understand the true impact of OS sub-versions in our ability to do provenance validation.

FAQ Copy Section

What about binaries produced before VS 16.7 was released? Copy Section

The provenance validation process depends on extra metadata included in the PDB that the compiler uses to generate the artifacts manifest file as well as recreate the compilation. That extra information was first added into PDBs in the Visual Studio 16.7 release. That means any binaries produced before then will fail provenance validation.

This is a known issue and the understanding is such older NuPkgs will not be supported for provenance validation.

How do we handle source generators? Copy Section

The provenance validation will occur using the output of source generators rather than re-running source generators as part of the validation. This will simplify the process as well as remove the issue of determinism in source generators (customer defined tools that don't have our level of rigor) from the process.

Open Issues Copy Chapter

Running the validator on .NET Framework Copy Section

The expectation is that for Windows we should be able to use .NET Core to run the validator for binaries that were produced using the .NET Framework compiler. The runtime differences we are worried about for Unix operating systems don't have the same problems on Windows. Hence any .NET Runtime which can execute the compiler should be able to do provenance validation.

It's possible we will find differences here though in the real world. In which case we will need to have a mode for dotnet-build-validator where by it will shell out to a .NET Framework process to do the validation.

Line ending issues Copy Section

In order for validation to succeed it is important for dotnet-build-validator to receive source files that have the same line endings as the one's provided to the original compilation. These factor into items like the checksum of source files stored in PDBs, the content of string literals, etc ...

It's possible that the information provided by source link is not sufficient to properly recreate files with correct line endings. Consider that a .gitattributes file could change how line endings are used on different operating systems.

This is a problem the debugger team hits today and has solved with a simple algorithm we can replicate here. Essentially if the file has consistent LF or CRLF line endings and the SHA don't match, flip the line endings. If that matches then use that version.

Future expansions Copy Section

This document is written to describe how validation will work for the C# and VB compilers but those are not the only tools in the .NET SDK which create or modify DLLs. Other tools include, but is not limited to, the F# compiler and IL trimmer.

The expectation is these tools can be on boarded with minimal changes to the process outlined here. For example the artifact manifest file can be expanded to include new artifact types, new tools can be consumed by Terrapin to do the validation of various phases of the build.

What names should we call the tools Copy Section

As a rule, @jaredpar is terrible at picking names. Should we pick better names for the tools?

Contributing API Review Process (`docs/contributing/API Review Process.md`) Copy Section

API Review Process

.NET has a long-standing history of taking API usability extremely seriously. Thus, we generally review every single API that is added to the product. This page discusses how we conduct design reviews for the Roslyn components.

Which APIs should be reviewed? Copy Chapter

The rule of thumb is that we (dotnet/roslyn) review every public API that is being added to this repository in the CodeAnalysis (compiler), Workspaces, Features, and EditorFeatures libraries. APIs in the LanguageServices dlls are not usually reviewed as they are not intended for general consumption; they are for use in Visual Studio, and we don't have a compat bar for these APIs.

Steps Copy Chapter

1. Requester files an issue. The issue description should contain a speclet that represents a sketch of the new APIs, including samples on how the APIs are being used. The goal isn't to get a complete API list, but a good handle on how the new APIs would roughly look like and in what scenarios they are being used. Please use this template. The issue should have the labels Feature Request and Concept-API. Here is a good example of a strong API proposal.

2. We assign an owner. We'll assign a dedicated owner from our side that sponsors the issue. This is usually the area owner for which the API proposal or design change request was filed.

3. Discussion. The goal of the discussion is to help the assignee to decide whether we want to pursue the proposal or not. In this phase, the goal isn't necessarily to perform an in-depth review; rather, we want to make sure that the proposal is actionable, i.e. has a concrete design, a sketch of the APIs and some code samples that show how it should be used. If changes are necessary, the owner will set the label api-needs-work. To make the changes, the requester should edit the top-most issue description. This allows folks joining later to understand the most recent proposal. To avoid confusion, the requester can maintain a tiny change log, like a bolded "Updates:" followed by a bullet point list of the updates that were being made. When you the feedback is addressed, the requester should notify the owner to re-review the changes.

4. Owner makes decision. When the owner believes enough information is available to make a decision, they will update the issue accordingly:

   • Mark for review. If the owner believes the proposal is actionable, they will label the issue with api-ready-for-review.
   • Close as not actionable. In case the issue didn't get enough traction to be distilled into a concrete proposal, the owner will close the issue.
   • Close as won't fix as proposed. Sometimes, the issue that is raised is a good one but the owner thinks the concrete proposal is not the right way to tackle the problem. In most cases, the owner will try to steer the discussion in a direction that results in a design that we believe is appropriate. However, for some proposals the problem is at the heart of the design which can't easily be changed without starting a new proposal. In those cases, the owner will close the issue and explain the issue the design has.
   • Close as won't fix. Similarly, if proposal is taking the product in a direction we simply don't want to go, the issue might also get closed. In that case, the problem isn't the proposed design but in the issue itself.

5. API gets reviewed. The group conducting the review is called RAR, which stands for Roslyn API Reviewers. In the review, we'll take notes and provide feedback. After the review, we'll publish the notes in the API Review repository and at the end of the relevant issue. Multiple outcomes are possible:

   • Approved. In this case the label api-ready-for-review is replaced with api-approved.
   • Needs work. If we believe the proposal isn't ready yet, we'll replace the label api-ready-for-review with api-needs-work.
   • Rejected. If we believe the proposal isn't a direction we want to pursue, we'll simply write a comment and close the issue.

Review schedule Copy Chapter

There are three methods to get an API review (this section applies to API area owners, but is included for transparency into the process):

• Get into the backlog. Generally speaking, filing an issue in dotnet/roslyn and applying the label api-ready-for-review on it will make your issue show up during API reviews. The downside is that we generally walk the backlog oldest-newest, so your issue might not be looked at for a while. Progress of issues can be tracked via https://apireview.net/backlog?g=Roslyn.
• Fast track. If you need to bypass the backlog apply both api-ready-for-review and blocking. All blocking issues are looked at before we walk the backlog.
• Dedicated review. If an issue you are the area owner for needs an hour or longer, send an email to roslynapiowners and we book dedicated time. We also book dedicated time for language feature APIs: any APIs added as part of a new language feature need to have a dedicated review session. Rule of thumb: if the API proposal has more than a dozen APIs, the APIs have complex policy, or the APIs are part of a feature branch, then you need 60 min or more. When in doubt, send mail to roslynapiowners.

The API review board currently meets every 2 weeks.

Pull requests Copy Chapter

Pull requests against dotnet/roslyn that add new public API shouldn't be submitted before getting approval. Also, we don't want to get work in progress (WIP) PR's. The reason being that we want to reduce the number pending PRs so that we can focus on the work the community expects we take action on.

If you want to collaborate with other people on the design, feel free to perform the work in a branch in your own fork. If you want to track your TODOs in the description of a PR, you can always submit a PR against your own fork. Also, feel free to advertise your PR by linking it from the issue you filed against dotnet/roslyn in the first step above.

For dotnet/roslyn team members, PRs are allowed to be submitted and merged before a full API review session, but you should have sign-off from the area owner, and the API is expected to be covered in a formal review session before being shipped. For such issues, please work with the API area owner to make sure that the issue is marked blocking appropriately so it will be covered in short order.

Contributing Building, Debugging, And Testing On Unix (`docs/contributing/Building, Debugging, and Testing on Unix.md`) Copy Section

Building, Debugging and Testing on Unix

This guide is meant to help developers setup an environment for debugging / contributing to Roslyn from Linux.
Particularly for developers who aren't experienced with .NET Core development on Linux.

Working with the code Copy Chapter

1. Ensure the commands git and curl are available
2. Clone [email protected]:dotnet/roslyn.git
3. Run ./build.sh --restore
4. Run ./build.sh --build

Working in Visual Studio Code Copy Chapter

1. Install VS Code
   • After you install VS Code, install the C# extension
   • Important tip: You can look up editor commands by name by hitting Ctrl+Shift+P, or by hitting Ctrl+P and typing a > character. This will help you get familiar with editor commands mentioned below. On a Mac, use ⌘ instead of Ctrl.
2. Install the .NET SDK which matches the sdk.version property in global.json
3. You can build from VS Code by running the Run Build Task command, then selecting an appropriate task such as build or build current project (the latter builds the containing project for the current file you're viewing in the editor).
4. You can run tests from VS Code by opening a test class in the editor, then using the Run Tests in Context and Debug Tests in Context editor commands. You may want to bind these commands to keyboard shortcuts that match their Visual Studio equivalents (Ctrl+R, T for Run Tests in Context and Ctrl+R, Ctrl+T for Debug Tests in Context).
5. You can launch a new VS Code instance with the language server from your current code by running the "launch vscode with language server" task.

Running Tests Copy Chapter

After building, the unit tests can be executed by running ./test.sh, which runs the already-built test assemblies via src/Tools/RunTests.

For a combined build and test run, use ./build.sh --test, ./build.sh --testSet:compiler, ./build.sh --testKind:ioperation, or ./build.sh --testFramework:core (single-hyphen spellings are also accepted). Each test option independently requests testing. These shortcuts forward the build configuration and any supplied set, kind, and framework values to RunTests; RunTests selects and validates the tests. For example, ./build.sh --configuration Release --testSet:compiler --testFramework:core --testKind:usedassemblies builds and tests Release compiler binaries with used-assembly validation. Direct calls to ./eng/build.sh use already-built binaries unless --build is also specified.

Repeat --testFramework:<name> to forward multiple framework selections, for example --testFramework:core --testFramework:desktop; do not combine them into a comma-separated value. RunTests determines which frameworks are supported on the current platform.

Pass other test options to test.sh. For example, ./test.sh --testFramework:core --testConfiguration Release --testSet:compiler tests the Release compiler binaries. Use --testKind:ioperation, --testKind:runtimeasync --testFramework:core, or --testKind:usedassemblies for additional validation, and --env:KEY=VALUE to set an environment variable in test processes. Runtime-async validation requires Core-only selection; the default selection includes desktop and is rejected. Run ./test.sh --help for all options.

To run all tests in a single project, it's recommended to use the dotnet test path/to/project command.

GitHub Copy Chapter

The best way to clone and push is to use SSH. On Windows you typically use HTTPS and this is not directly compatible
with two factor authentication (requires a PAT). The SSH setup is much simpler and GitHub has a great HOWTO for
getting this setup.

https://help.github.com/articles/connecting-to-github-with-ssh/

Debugging test failures Copy Chapter

The best way to debug is using lldb with the SOS plugin. This is the same SOS as used in WinDbg and if you're familiar
with it then lldb debugging will be pretty straight forward.

The dotnet/diagnostics repo has more information:

• Getting LLDB
• Installing SOS
• Using SOS

CoreCLR also has some guidelines for specific Linux debugging scenarios:

• https://github.com/dotnet/coreclr/blob/main/Documentation/botr/xplat-minidump-generation.md
• https://github.com/dotnet/coreclr/blob/main/Documentation/building/debugging-instructions.md#debugging-core-dumps-with-lldb.

Corrections:

• LLDB and createdump must be run as root
• dotnet tool install -g dotnet-symbol must be run from $HOME

Core Dumps Copy Section

The CoreClr does not used the standard core dumping mechanisms on Linux. Instead you must specify via
environment variables that you want a core dump to be produced. The simplest setup is to do the following:

> export COMPlus_DbgEnableMiniDump=1
> export COMPlus_DbgMiniDumpType=4

This will cause full memory dumps to be produced which can then be loaded into LLDB.

A preview of dotnet-dump is also available for interactively creating and analyzing dumps.

GC stress failures Copy Section

When you suspect there is a GC failure related to your test then you can use the following environment variables
to help track it down.

> export COMPlus_HeapVerify=1
> export COMPlus_gcConcurrent=1

The COMPlus_HeapVerify variable causes GC to run a verification routine on every entry and exit. Will crash with
a more actionable trace for the GC team.

The COMPlus_gcConcurrent variable removes concurrency in the GC. This helps isolate whether this is a GC failure
or memory corruption outside the GC. This should be set after you use COMPLUS_HeapVerify to determine it is
indeed crashing in the GC.

Note: this variables can also be used on Windows as well.

Ubuntu 18.04 Copy Chapter

The recommended OS for developing Roslyn is Ubuntu 18.04. This guide was written using Ubuntu 18.04 but should be
applicable to most Linux environments. Ubuntu 18.04 was chosen here due to it's support for enhanced VMs in Hyper-V.
This makes it easier to use from a Windows machine: full screen, copy / paste, etc ...

Hyper-V Copy Section

Hyper-V has a built-in Ubuntu 18.04 image which supports enhanced mode. For more information, see a tutorial for creating such an image.

When following this make sure to:

1. Click Installation Source and uncheck "Windows Secure Boot"
2. Complete the Ubuntu installation wizard. Full screen mode won't be available until this is done.

Overall this takes about 5-10 minutes to complete.

Source Link Copy Section

Many of the repositories that need to be built use source link and it crashes on Ubuntu 18.04 due to dependency changes.
To disable source link add the following to the Directory.Build.props file in the root of the repository.

<EnableSourceControlManagerQueries>false</EnableSourceControlManagerQueries>
<EnableSourceLink>false</EnableSourceLink>
<DeterministicSourcePaths>false</DeterministicSourcePaths>

Prerequisites Copy Section

Make sure to install the following via apt install

• clang
• lldb
• cmake
• xrdp

Troubleshooting Copy Chapter

See the Troubleshooting section
in the Windows doc, which is not Windows-specific (use rm -rf in place of Remove-Item).

Contributing Building, Debugging, And Testing On Windows (`docs/contributing/Building, Debugging, and Testing on Windows.md`) Copy Section

Building, Debugging and Testing on Windows

Working with the code Copy Chapter

Using the command line, Roslyn can be developed using the following pattern:

1. Clone https://github.com/dotnet/roslyn
2. Run Restore.cmd
3. Run Build.cmd
4. Run Test.cmd

Recommended version of .NET Framework Copy Chapter

The minimal required version of .NET Framework is 4.7.2.

Developing with Visual Studio Copy Chapter

1. Use latest Visual Studio Insiders
   • Ensure Visual Studio extension development is included in the selected workloads
   • Ensure C# and Visual Basic, MSBuild, and .NET Core are included in the selected individual components
   • Restart Visual Studio
2. Install the .NET SDK which matches the sdk.version property in global.json
3. PowerShell 5.0 or newer. If you are on Windows 10 or newer, you are fine; you'll only need to upgrade if you're on earlier versions of Windows. The download link is under the "Upgrading existing Windows PowerShell" heading.
4. Run Restore.cmd
5. Open Roslyn.slnx

Developing with Visual Studio Code Copy Chapter

See the Building, Debugging, and Testing on Unix documentation to get started developing Roslyn using Visual Studio Code.

Running Tests Copy Chapter

There are a number of options for running the core Roslyn unit tests:

Command Line Copy Section

The Test.cmd script runs unit tests on already-built test binaries via src/Tools/RunTests. Run Build.cmd separately before testing, and pass test options to Test.cmd.

For a combined build and test run, use Build.cmd -test, Build.cmd -testSet:compiler, Build.cmd -testKind:ioperation, or Build.cmd -testFramework:core. Each test option independently requests testing. These shortcuts forward the build configuration and any supplied set, kind, and framework values to RunTests; RunTests selects and validates the tests. For example, Build.cmd -configuration Release -testSet:compiler -testFramework:core -testKind:usedassemblies builds and tests Release compiler binaries with used-assembly validation. Direct calls to eng\build.ps1 use already-built binaries unless -build is also specified. Other test options belong on Test.cmd.

To select multiple frameworks from PowerShell, pass an array: .\eng\build.ps1 -build -testFramework:core,desktop. Each array element is forwarded as a separate RunTests framework option; do not repeat the named PowerShell parameter.

1. Run the "Developer PowerShell for VS Insiders" or "Developer Command Prompt for VS Insiders" from your start menu, alternatively launch it from Visual Studio, it can be found at "Tools -> Command Line -> Developer Powershell/Developer Command Prompt".
2. Navigate to the directory of your Git clone.
3. Run Test.cmd in the command prompt.

Pass options directly to Test.cmd: --testFramework:desktop selects .NET Framework, while --testFramework:core selects .NET. Repeat --testFramework to run both. Use --testConfiguration Release to test Release binaries and --testPlatform x86 to select x86. Run Test.cmd --help for all options.

Visual Studio integration tests have a separate entry point: run eng\test-vsi.ps1 -configuration Debug after building.

The results of the tests can be viewed in the artifacts/TestResults directory.

Test Explorer Copy Section

Tests can be run and debugged from the Test Explorer window. For best performance, we recommend the following:

1. Open Tools → Options... → Test
   1. Check the box for Discover tests in real time from source files
   2. Uncheck the box for Additionally discover tests from build assemblies...
2. Use the Search box of Test Explorer to narrow the scope of visible tests to the feature(s) you are working on
3. When you are not actively running tests, set the search query to __NonExistent__ to hide all tests from the UI

Testing in Linux using WSL

Tests can be run and debugged under WSL. This requires a bit of setup the first time. After that, it is as easy as selecting WSL as the active environment in Test Explorer.

1. Install WSL by running wsl --install (details)

2. In the VS installer, install ".NET Debugging with WSL" as an individual component

3. In Test Explorer, go into "Configure Remote Test Environments" (under the gear icon) and uncomment the wsl/Ubuntu environment:

4. Select that test environment from Test Explorer drop-down:

5. Run a test from Test Explorer test list. This will prompt you to install some dotnet bits into the WSL environment the first time.

6. Debug a test. This will prompt you to install some remote debugging bits into the WSL environment the first time.

More details

WPF Test Runner Copy Section

To debug through tests, you can right click the test project that contains your
tests and choose Set as Startup Project. Then press F5. This will run the
tests under the command line runner. Some members of the team have been
working on a GUI runner that allows selection of individual tests, etc. Grab
the source from
xunit.runner.wpf, build it and
give it a try.

Trying Your Changes in Visual Studio Copy Chapter

Deploying with command-line (recommended method) Copy Section

You can build and deploy with the following command:
.\Build.cmd -Restore -Configuration Release -deployExtensions -launch.

Then you can launch the RoslynDev hive with devenv /rootSuffix RoslynDev.

Deploying with F5 Copy Section

The Rosyln solution is designed to support easy debugging via F5. Several of our
projects produce VSIX which deploy into Visual Studio during build. The F5 operation
will start a new Visual Studio instance using those VSIX which override our installed
binaries. This means trying out a change to the language, IDE or debugger is as
simple as hitting F5. Note that for changes to the compiler, out-of-process builds won't use the privately built version of the compiler.

The startup project needs to be set to RoslynDeployment. This should be
the default but in some cases will need to be set explicitly. To set it, right-click
the RoslynDeployment project in Solution Explorer and select "Set as Startup Project".

RoslynDeployment is a container project located in the src/Deployment folder that
bundles and deploys all the main Roslyn extensions together. When you press F5 with
RoslynDeployment set as the startup project, it will deploy all of the following extensions
at once, giving you a complete debugging experience with all Roslyn components.

If you're working on a specific area and want to optimize build times by deploying only
the relevant extension, you can set one of the individual projects below as your startup
project instead:

• Roslyn.VisualStudio.Setup: this project can be found inside the VisualStudio\Setup folder
  from the Solution Explorer, and builds Roslyn.VisualStudio.Setup.vsix. It
  contains the core language services that provide C# and VB editing. It also
  contains the copy of the compiler that is used to drive IntelliSense and
  semantic analysis in Visual Studio. Although this is the copy of the compiler
  that's used to generate squiggles and other information, it's not the
  compiler used to actually produce your final .exe or .dll when you do a
  build. If you're working on fixing an IDE bug, this is the project you want
  to use.
• Roslyn.Compilers.Extension: this project can be found inside the Compilers\Extension folder
  from the Solution Explorer, and builds Roslyn.Compilers.Extension.vsix.
  This deploys a copy of the command line compilers that are used to do actual
  builds in the IDE. It only affects builds triggered from the Visual Studio
  experimental instance it's installed into, so it won't affect your regular
  builds. Note that if you install just this, the IDE won't know about any
  language features included in your build. If you're regularly working on new
  language features, you may wish to consider building both the
  CompilerExtension and VisualStudioSetup projects to ensure the real build and
  live analysis are synchronized.
• ExpressionEvaluatorPackage: this project can be found inside the
  ExpressionEvaluator\Package folder from the Solution Explorer, and builds
  ExpressionEvaluatorPackage.vsix. This deploys the expression evaluator and
  result providers, the components that are used by the debugger to parse and
  evaluate C# and VB expressions in the Watch window, Immediate window, and
  more. These components are only used when debugging.

The experimental instance used by Roslyn is an entirely separate instance of
Visual Studio with it's own settings and installed extensions. It's also, by
default, a separate instance than the standard "Experimental Instance" used by
other Visual Studio SDK projects. If you're familiar with the idea of Visual
Studio hives, we deploy into the RoslynDev root suffix.

Deploying with VSIX and Nuget package Copy Section

If you want to try your extension in your day-to-day use of Visual Studio, you
can find the extensions you built in your Binaries folder with the .vsix
extension. You can double-click the extension to install it into your main
Visual Studio hive. This will replace the base installed version. Once it's
installed, you'll see it marked as "Experimental" in Tools > Extensions and
Updates to indicate you're running your experimental version. You can uninstall
your version and go back to the originally installed version by choosing your
version and clicking Uninstall.

If you only install the VSIX, then the IDE will behave correctly (ie. new compiler
and IDE behavior), but the Build operation or building from the command-line won't.
To fix that, add a reference to the Microsoft.Net.Compilers.Toolset you built into
your csproj. As shown below, you'll want to (1) add a nuget source pointing to your local build folder,
(2) add the package reference, then (3) verify the Build Output of your project with a
#error version included in your program.

Trying Your Changes in Visual Studio Code Copy Chapter

See VSCode docs.

Various other tips Copy Chapter

Referencing bootstrap compiler Copy Section

If you made changes to a Roslyn compiler and want to build any projects with it, you can either
use the Visual Studio hive where your CompilerExtension is installed, or from
command line, run msbuild with /p:BootstrapBuildPath=YourBootstrapBuildPath.
YourBootstrapBuildPath could be any directory on your machine so long as it had
csc and vbc inside it. You can check the cibuild.cmd and see how it is used.

Troubleshooting your setup Copy Section

To confirm what version of the compiler is being used, include #error version in your program
and the compiler will produce a diagnostic including its own version as well as the language
version it is operating under.

You can also attach a debugger to Visual Studio and check the loaded modules, looking at the folder
where the various CodeAnalysis modules were loaded from (the RoslynDev should load them somewhere
under AppData, not from Program File).

Testing on the [dotnet/runtime](https://github.com/dotnet/runtime) repo Copy Section

1. Make sure that you can build the runtime repo as baseline (run build.cmd libs+libs.tests, which should be sufficient to build all C# code, installing any prerequisites if prompted to, and perhaps git clean -xdf and build.cmd -restore initially - see runtime repo documentation for specific prerequisites and build instructions)
2. build.cmd -pack -c Release on your roslyn repo
   • Note that -c Debug can also be used (along with changing Release to Debug in RestoreAdditionalProjectSources property value below). This will allow checking the compiler's debug assertions when building the runtime.
   • It's good for us to investigate scenarios where compiling the runtime libraries causes the compiler's debug assertions to fail. However, assertion failures can obscure whether or not the compiler ultimately succeeds at building the runtime and producing correct binaries. So, if the goal is to only check for "functional breaks", then using a Release mode compiler to start with can be preferable.
3. Find the compiler toolset in your NuGet package cache (its location is likely %NUGET_PACKAGES%\microsoft.net.compilers.toolset or %userprofile%\.nuget\packages\microsoft.net.compilers.toolset).
4. If there is a toolset version in the NuGet cache with the same version as the toolset you just packed in Roslyn, delete the toolset version from the cache. This allows NuGet to pick up the new packages you just created locally instead of using a stale cached version.
5. Modify your local enlistment of runtime similarly to this commit then build again
   • add <RestoreAdditionalProjectSources>\artifacts\packages\Release\Shipping\</RestoreAdditionalProjectSources> using the local path to your roslyn repo to Directory.Build.props
   • add true and <MicrosoftNetCompilersToolsetVersion>5.3.0-dev</MicrosoftNetCompilersToolsetVersion> with the package version you just packed (look in above artifacts folder) to eng/Versions.props

Testing a VS insertion Copy Section

See internal documentation for that process here.

Testing with extra IOperation validation Copy Section

Run Test.cmd --testFramework:core --testSet:compiler --testKind:ioperation, which sets the ROSLYN_TEST_IOPERATION environment variable to true in the test processes.
For running those tests in an IDE, the easiest is to find the //#define ROSLYN_TEST_IOPERATION directive and uncomment it.
See more details in the IOperation test hook doc.

Replicating Failures in the Used Assemblies leg Copy Section

In order to replicate test failures in that leg, there are a few options:

1. Uncomment src/Compilers/Test/Core/Compilation/CompilationExtensions.cs:9, which defines ROSLYN_TEST_USEDASSEMBLIES, and run your tests. Do not check this in, as it
   will enable the test hook for every test in every project and significantly slow down regular test runs.
2. Set the ROSLYN_TEST_USEDASSEMBLIES environment variable and restart VS with it set.
3. Set a breakpoint at the start of CSharpTestBase.VerifyUsedAssemblyReferences in src/Compilers/Test/Utilities/CSharp/CSharpTestBase.cs. When it breaks, use VS's jump to location or
   drag the instruction pointer past the early check and return on EnableVerifyUsedAssemblies.

When a test failure is isolated, please add a dedicated test for this (ie. failing even when the Used Assemblies validation isn't enabled) to make it easier to avoid future regressions.
Preferrably, don't replicate the entire original test, just enough to hit the bug to ensure that it's protected against regressions.
Before pushing a relevant fix to CI, validate locally using Test.cmd --testFramework:core --testSet:compiler --testKind:usedassemblies.

Running the PublicAPI fixer Copy Section

1. Restore and build Compilers.slnf. This is necessary to ensure the source generator project is built and we can load the generator assembly when running dotnet format.
   ps1 Copy

   C:\Source\roslyn> .\restore.cmd
   C:\Source\roslyn> .\build.cmd

2. Invoke dotnet format (the one included in .NET SDK, not the global tool dotnet-format which is deprecated). Running only the analyzers subcommand and fixing only the "missing Public API signature" diagnostic. We must also pass the --include-generated flag to include source generated documents in the analysis.
   ps1 Copy

   C:\Source\roslyn> cd ..
   C:\Source> dotnet format analyzers .\roslyn\Compilers.slnf --diagnostics=RS0016 --no-restore --include-generated -v diag

Troubleshooting Copy Chapter

If you hit an unexpected build failure, especially one that doesn't reproduce on a clean
clone, a good first step is to delete the artifacts folder and rebuild. If that doesn't
help, the bigger hammer is git clean -xdfn (dry run) followed by git clean -xdf. Note
that this also deletes the locally-provisioned .dotnet SDK, forcing a full restore and
rebuild, so prefer just deleting artifacts first.

For example, renaming or moving your clone can leave stale cached files under
artifacts\obj\...\*.xlf\ referencing the old path, which causes Build.cmd to fail with
errors like:

error MSB3103: Invalid Resx file. Could not find a part of the path
'<OLD-PATH>\src\RoslynAnalyzers\Text.Analyzers\Core\Dictionary.dic'. [Text.Analyzers.csproj]

Deleting artifacts and rebuilding should fix the issue.
See
dotnet/arcade issue 17061
for details.

Contributing Copy Chapter

Please see Contributing Code for details on contributing changes back to the code.

Contributing Compiler Test Plan (`docs/contributing/Compiler Test Plan.md`) Copy Section

Compiler Test Plan

This document provides guidance for thinking about language interactions and testing compiler changes.

General concerns Copy Chapter

• Completeness of the specification as a guide for testing (is the spec complete enough to suggest what the compiler should do in each scenario?)
• Ping for new breaking changes and general ping for partner teams (Bill, Kathleen, Mads, IDE, Razor)
• Help review external documentation
• Backward and forward compatibility (interoperation with previous and future compilers, each in both directions)
• Error handling/recovery (missing libraries, including missing types in mscorlib; errors in parsing, ambiguous lookup, inaccessible lookup, wrong kind of thing found, instance vs static thing found, wrong type for the context, value vs variable)
• BCL (including mono) and other customer impact
• Determinism
• Loading from metadata (source vs. loaded from metadata)
• VB/F# interop
• C++/CLI interop (particularly for metadata format changes, e.g. DIMs, static abstracts in interfaces, or generic attributes)
• Performance and stress testing
• Can build VS
• Check that Obsolete is honored for members used in binding/lowering
• LangVersion
• IL verification (file issue on runtime repo as needed and track here)
• Does the feature use cryptographic hashes in any way? (examples: metadata names of file-local types, extension types, assembly strong naming, PDB document table, etc.)
  • Consider using non-cryptographic hash such as XxHash128 instead.
  • If you must use a cryptographic hash in the feature implementation, then use SourceHashAlgorithms.Default, and not any specific hash.
  • A cryptographic hash must never be included in a public API name. Taking a change to the default crypto algorithm would then change public API surface, which would be enormously breaking.
    • DO NOT allow using the value of a crypto hash in a field, method or type name
    • DO allow using the value of a crypto hash in attribute or field values
  • Any time the compiler reads in metadata containing crypto hashes, even if it's an attribute value, ensure the crypto hash algorithm name is included in the metadata (e.g. prefixing it to the hash value), so that it can be changed over time and the compiler can continue to read both metadata using both the old and new algorithms.

Public APIs Copy Chapter

• Public compiler APIs (including semantic model and other APIs listed below):
  • GetDeclaredSymbol
  • GetEnclosingSymbol
  • GetSymbolInfo
  • GetSpeculativeSymbolInfo
  • GetTypeInfo
  • GetSpeculativeTypeInfo
  • GetMethodGroup
  • GetConstantValue
  • GetAliasInfo
  • GetSpeculativeAliasInfo
  • LookupSymbols
  • AnalyzeStatementsControlFlow
  • AnalyzeStatementControlFlow
  • AnalyzeExpressionDataFlow
  • AnalyzeStatementsDataFlow
  • AnalyzeStatementDataFlow
  • ClassifyConversion
  • GetOperation (IOperation)
  • GetCFG (ControlFlowGraph), including a scenario with some nested conditional
  • DocumentationCommentId APIs
• All newly added APIs are experimental
  • Tracking issue for marking APIs as non-experimental
  • APIs are marked with [Experimental(RoslynExperiments.PreviewLanguageFeatureApi, UrlFormat = "link to tracking issue")]
  • APIs have gone through API review

Type and members Copy Chapter

See also types and members lists below.

• Access modifiers (public, protected, internal, protected internal, private protected, private), static, ref
• type declarations
  • class with or without primary constructor
  • record class/struct with or without positional members
  • struct with or without primary constructor
  • union
  • interface
  • type parameter
• file-local types
• methods
• constructors (static, instance, primary)
• destructors
• fields (required and not)
• fixed-sized buffers
• properties (including get/set/init accessors, required and not)
• events (including add/remove accessors)
• Parameter modifiers: ref, out, in, ref readonly, params (for array, for non-array)
• Attributes (including generic attributes and security attributes)
  • Compiler-recognized attributes should not have any effect in earlier LangVersions,
    except a LangVersion error should be reported when functionality depending on the attribute is used
    (for example, InlineArray conversion to Span).
• Generics (type arguments, variance, constraints including class, struct, new(), unmanaged, notnull, allows ref struct, types and interfaces with nullability)
• Default and constant values
• Partial classes
• Literals
• Enum (implicit vs. explicit underlying type)
• Expression trees
• Iterators
• Initializers (object, collection, dictionary)
• Array (single- or multi-dimensional, jagged, initializer, fixed)
• Expression-bodied methods/properties/...
• Extension methods
• Partial method
• Named and optional parameters
• String interpolation
• Raw strings (including interpolation)
• Properties (read-write, read-only, init-only, write-only, auto-property, expression-bodied)
• Interfaces (implicit vs. explicit interface member implementation)
• Delegates
• Multi-declaration
• NoPIA
• Dynamic
• Ref structs, Readonly structs
• Readonly members on structs (methods, property/indexer accessors, custom event accessors)
• SkipLocalsInit
• Method override or explicit implementation with where T : { class, struct, default }
• extension blocks (emitted with content-based names):
  • methods
  • operators (except conversion operators)
  • properties and indexers (including get/set/init accessors)

Code Copy Chapter

• Operators (see Eric's list below)
• Lambdas (capture of parameters or locals, target typing)
• Execution order
• Target typing (var, lambdas, integrals)
• Conversions (boxing/unboxing)
• Nullable (wrapping, unwrapping)
• Overload resolution, override/hide/implement (OHI)
  • OverloadResolutionPriorityAttribute
• Inheritance (virtual, override, abstract, new)
• Anonymous types
• Tuple types and literals (elements with explicit or inferred names, long tuples), tuple equality
• Range literals (1..2) and Index operator (^1)
• Deconstructions
• Local functions
• Unsafe code
• LINQ
• Async (task-like types) and async-iterator methods
• Lvalues: the synthesized fields are mutable
  • Ref / out parameters
  • Compound operators (+=, /=, etc ..)
  • Assignment exprs
• Ref return, ref readonly return, ref ternary, ref readonly local, ref local re-assignment, ref foreach
• Ref fields
• scoped parameters and locals
• this = e; in struct .ctor
• Stackalloc (including initializers)
• Patterns (constant, declaration, var, positional, property and extended property, discard, parenthesized, type, relational, and/or/not, list, slice, constant string matching Span<char>)
• Switch expressions
• With expressions (on record classes and on value types)
• Nullability annotations (?, attributes) and analysis
• Definite assignment analysis and auto-default struct fields
• If you add a place an expression can appear in code, make sure SpillSequenceSpiller handles it. Test with a switch expression or stackalloc in that place.
• If you add a new expression form that requires spilling, test it in the catch filter.
• If you add a new expression that can be nested inside itself, test deeply nesting it. Potentially cut off direct nesting.
• extension based Dispose, DisposeAsync, GetEnumerator, GetAsyncEnumerator, Deconstruct, GetAwaiter etc.
• UTF8 String Literals (string literals with 'u8' or 'U8' type suffix).
• Inline array element access and slicing.
• Collection expressions, spread-elements (.. expr), and with-elements ([with(...)]).

Misc Copy Chapter

• reserved keywords (sometimes contextual)
• pre-processing directives
• COM interop
• modopt and modreq
• CompilerFeatureRequiredAttribute
• CompilerLoweringPreserveAttribute
• ref assemblies
• extern alias
• UnmanagedCallersOnly
• telemetry

Testing in interaction with other components Copy Chapter

Interaction with IDE, Debugger, and EnC should be worked out with relevant teams. A few highlights:

• IDE

  • Colorization and formatting
  • Typing experience and dealing with incomplete code
  • Intellisense (squiggles, dot completion)
  • "go to", Find All References, and renaming
  • F1 help (for new keywords)
  • cref comments
  • UpgradeProject code fixer
  • More: IDE Test Plan

• Debugger / EE

  • Stepping, setting breakpoints
  • Displaying Locals/Autos windows
    • Type and Value display
    • Expanding instance members
    • Locals/parameters/this in closure classes
    • Attributes on locals and expressions (e.g.: [Dynamic], [TupleElementNames])
  • Compiling expressions in Immediate/Watch windows or hovering over an expression
  • Compiling expressions in [DebuggerDisplay("...")]
  • Assigning values in Locals/Autos/Watch windows

• Edit-and-continue

• Live Unit Testing (instrumentation)

• Engage with VS Templates team (if applicable)

Statements Copy Chapter

{ … }
;
label : …
T x = whatever; // including `using` and `await` using variants
M();
++x;
x++;
--x;
x--;
a?.M(); // conditional access / null-propagating operator
a?[b] = c;
a?.b = c;
a?[b] = c;
a?.b += c; // and other compound assignment cases
var x = a?.M(); // similar "value is used" versions of the above '?.' cases
new C();
if (…) … else …
switch(…) { … case (…) when (…): … }
while(…) …
do … while(…);
for( … ; … ; … ) …
foreach(…) … // including `await` variant
fixed(…) … // (plain, or custom with `GetPinnableReference`)
goto … ;
throw … ;
return … ;
try { … } catch (…) when (…) { … } finally { … }
checked { … }
unchecked { … }
lock(…) … // including variant on an instance of the `System.Threading.Lock` type
using (…) … // including `await` variant
yield return …;
yield break;
break;
continue;
break label;
continue label;

Expression classifications Copy Chapter

Every expression can be classified as exactly one of these:

• Value
• Variable
• Namespace
• Type
• Method group
• Null literal
• Default literal
• Anonymous function
• Property
• Indexer
• Event
• Void-returning method call
• Array initializer (*)
• __arglist (*)

(*) Technically not an expression according to the spec.

Note that only values, variables, properties, indexers and events have a type.

Variable classifications Copy Chapter

A variable is a storage location. These are all the different ways to refer to a storage location:

• Static field
• Instance field
• Array element
• Formal param, value
• Formal param, ref
• Formal param, out
• Local variable
• Pointer dereference
• __refvalue
• Inline array access

Operators Copy Chapter

x.y
f( )
a[e]
x++ (including instance user defined)
x-- (including instance user defined)
new X()
new()
typeof(T)
default(T)
default
checked(e)
unchecked(e)
delegate ( ) { }
+x
-x
!x
~x
^x
++x (including instance user defined)
--x (including instance user defined)
(X)x
x * y
x / y
x % y
x + y
x - y
x << y
x >> y
x >>> y
x < y
x > y
x <= y
x >= y
x is X
x as X
x == y
x != y
x & y
x ^ y
x | y
x && y
x || y
x ?? y
x ? : y : z
x = y
x *= y (including instance user defined)
x /= y (including instance user defined)
x %= y (including instance user defined)
x += y (including instance user defined)
x -= y (including instance user defined)
x <<= y (including instance user defined)
x >>= y (including instance user defined)
x >>>= y (including instance user defined)
x &= y (including instance user defined)
x ^= y (including instance user defined)
x |= y (including instance user defined)
x ??= y
x => { }
sizeof( )
*x
& x
x->y
e is pattern
e switch { ... }
await x
__arglist( )
__refvalue( x, X )
__reftype( x )
__makeref( x )

Explicit conversions Copy Chapter

• Numeric
• Enum
• Nullable
• Reference
• Unboxing
• Dynamic
• Type parameter
• User defined
• Pointer to pointer
• Pointer to integral
• Integral to pointer
• Tuple literal
• Tuple

Implicit conversions Copy Chapter

• Identity
• Numeric
• Literal zero to enum (we actually do constant zero, not literal zero)
• Nullable
• Null literal
• Reference
• Boxing
• Dynamic
• Constant
• Type parameter
• User defined
• Union
• Anonymous function
• Method group
• Pointer to void pointer
• Null literal to pointer
• Interpolated string
• Tuple literal
• Tuple
• Default literal
• Implicit object creation (target-typed new)
• Function type (in type inference comparing function types of lambdas or method groups)
• UTF8 String Literal (string constant value to byte[], Span<byte>, or ReadOnlySpan<byte> types)
• Inline arrays (conversions to Span and ReadOnlySpan)
• Collection expression conversions
• Span conversions (from array to (ReadOnly)Span, or from string or (ReadOnly)Span to ReadOnlySpan)

Types Copy Chapter

• Class
• Interface
• Delegate
• Struct
• Union
• Enum
• Nullable
• Pointer
• Type parameter

Members Copy Chapter

• Class
• Struct
• Union
• Interface
• Enum
• Delegate
• Namespace
• Property
• Event
• Constructor
• Destructor
• Method
• Interface method
• Field
• User-defined indexer
• User-defined operator (including checked, including instance increment/decrement and compound assignment)
• User-defined conversion (including checked)

Patterns Copy Chapter

• Discard Pattern
• Var Pattern
• Declaration Pattern
• Constant Pattern
• Constant string matching Span<char>
• Recursive Pattern
• Parenthesized Pattern
• and Pattern
• or Pattern
• not Pattern
• Relational Pattern
• Type Pattern
• Union matching rules

Metadata table numbers / token prefixes Copy Chapter

If you look at a 32 bit integer token as a hex number, the first two digits identify the “table number” and the last six digits are an offset into that table. The table numbers are:

00 Module
01 TypeRef
02 TypeDef
03 FieldPtr
04 Field
05 MethodPtr
06 Method
07 ParamPtr
08 Param
09 InterfaceImpl
0A MemberRef
0B Constant
0C CustomAttr
0D FieldMarshal
0E DeclSecurity
0F ClassLayout
10 FieldLayout
11 StandAloneSig
12 EventMap
13 EventPtr
14 Event
15 PropertyMap
16 PropertyPtr
17 Property
18 MethodSemantics
19 MethodImpl
1A ModuleRef
1B TypeSpec
1C ImplMap
1D FieldRVA
1E ENCLog
1F ENCMap
20 Assembly
21 AssemblyProcessor
22 AssemblyOS
23 AssemblyRef
24 AssemblyRefProcessor
25 AssemblyRefOS
26 File
27 ExportedType
28 ManifestResource
29 NestedClass
2A GenericParam
2B MethodSpec
2C GenericConstraint

Contributing Developing A Language Feature (`docs/contributing/Developing a Language Feature.md`) Copy Section

Developing a Language Feature

Adding a new feature to C# or VB is a very serious undertaking that often takes several iterations to complete for even the (seemingly) simplest of features. This is due to both the inherent complexity of changing languages and the need to consider the effects of new features in all layers of the Roslyn codebase: IDE, debugging, scripting, etc. As such, language work occurs in a separate branch until the feature reaches a point when we are ready to merge it into the main compiler.

This page discusses the process by which language feature implementations are considered, prototyped, and fully accepted into the language. This process is intended to be used by the compiler team and community.

Process Copy Chapter

1. Feature specification filed: The speclet should be filed as a GitHub issue and contain:

   text Copy

   * A description of the feature (including any syntax changes involved)
    * Discussions about impacted areas, such as overload resolution and type inference. Think through the major areas of the language specification while determine the potential impacts
    * Proposed changes to the API surface area.

   A feature speclet is different from a language design discussion. Discussions are very open-ended and often for features that simply won't work in the language. A feature speclet is a declaration of intent to do the feature as proposed. In many cases, this will come out of a language design discussion.

   Linking to an early prototype of the proposed feature is highly encouraged. It gives the Language Team a clear understanding of the design intent of the feature and can often serve as the initial commit in the feature branch.

   Note: The goal is not to have a 100%-complete design but instead a general understanding of how the language feature is intended to work.

2. Discussion: The goal of the discussion is to help clarify the design and determine if the Language Team wants to sanction the proposal. As the discussion evolves the author is encouraged to update the speclet to incorporate the changing design. This allows folks who join later to understand the most recent proposal by reading the top of the thread.

3. Language team makes a decision: When the Language Team believes enough information is available they will update the issue accordingly:

   • Ready for prototype: The feature is worth pursuing as a prototype for the language. Work continues in the "Prototype" phase.
   • Not actionable: The discussion didn't lead to a design that was actionable by the team.
   • Declined as proposed: The proposal is overall a good idea but the proposed implementation details are not as efficient as they could be. In most cases, the language team will attempt to steer the discussion to a cleaner design but understand that it may be simpler to close and start over with a new issue.
   • Backlog: The feature is a good idea with an acceptable design but the Language Team simply can't allocate the resources at this time for this work.
   • Won't Fix: The feature isn't taking the language in a direction the Language Team is interested in pursuing.

   A Language Team member will be paired with a community-driven feature when it is deemed 'Ready for prototype'. This team member will act as the primary source of contact for the community and will help drive the feature to completion.

4. Prototype phase: All features are initially prototyped in a separate branch. The name of the branch is features/<feature name>. These branches are created when a feature speclet is marked as 'Ready for prototype', language team member champions the feature, and a developer is assigned to implement the feature. The developer is responsible for keeping an up-to-date speclet of the feature at docs/features/<feature name>.md throughout the development.

   When starting work on a new feature, use the new-compiler-feature Copilot skill (in .github/skills/new-compiler-feature/) to set up tracking: it creates a test plan issue, a Feature - <name> label, updates the Language Feature Status page, and links related PRs. Run it from a PR that implements (part of) the feature.

   All features should be off by default until fully accepted into the language. A new feature should only be enabled when explicitly included in the /features:<feature-name> compiler option. This helps ensure the language is always in a shippable state no matter what prototypes are in the current branch.

5. Prototype decision: When the prototype phase ends, the Language Team will make a decision on the feature:

   • Ready to integrate: The feature implementation revealed no blocking issues, has a healthy set of test suites, and is sufficiently complete in the compiler, IDE, debugger, etc. to integrate into the main tree on a selected branch. The test suites need to focus both on the feature in isolation and when combined with other areas of the language.
   • Iterate: Experience with the prototype has produced valuable feedback suggesting modifications to the
     speclet. Work reverts to the Discussion state, which may lead to speclet and prototype
     changes (or even abandoning the feature!). This typically occurs either when the original speclet
     left some language details unspecified, to be resolved based
     on implementation experience, or when experience with the prototype suggests that some language design
     decisions should be reconsidered.
   • Closed: The feature hit unforeseen design issues, implementation roadblocks, etc. that caused it to be removed.

6. Finishing: Once a feature is integrated into the main tree, it's time to lock down and finish the implementation. This includes any remaining areas not completed in the prototype, and completing all of the corner cases and tests (lots and lots of tests!).

   Features which are in the main tree but not tied to a langversion switch are referred to as experimental. They can be pulled or changed at any time.

7. Acceptance: When the Language Team feels a feature is complete it will be accepted into the language. The corresponding feature flag will be removed and the feature will be tied to the appropriate /langversion option.

It's important to note there are no guarantees about a feature being a part of the language until it has reached the 'Acceptance' state and shipped in an official build. Features in any other state--no matter how complete--can be pulled at the last minute if the Language Team deems it's necessary to do so.

Pulling a feature after the prototype phase completes is not a decision the Language Team takes lightly; however, in the past, unforeseen circumstances have caused us to do so. The best example of this was the decision to pull parameterless struct constructors very late in the C# 6.0 timeframe.

Community Contributions Copy Chapter

The intent of this document is to codify the process used by the Language Team to implement language features so that the community can contribute implementations. Community members can contribute to ongoing prototypes or in some cases be the primary driver of the prototype.

Community members who wish to drive a particular feature can request so by commenting on an accepted feature speclet. Even when driven by a community member, a language prototype will occupy a non-trivial amount of time by the Language Team. Hence we will likely only grant this request to community members who have been actively contributing to the project in smaller areas.

Frequently Asked Questions Copy Chapter

• Can feature branches be rebased?: This is left to the discretion of the developer working on the feature. Once the feature is merged into a main branch (main, feature) then rebasing is no longer allowed.

• Why was my language feature PR closed?: Language features will not be accepted as direct PRs to a main branch. Even simple features are too involved for senior Language Team members to complete in this fashion. Features need to follow the above process in order to be incorporated into the language.

• Why are features disabled by default?: Language features spend a considerable amount of time in the same branch as our shipping product which is often main. The main branch of Roslyn is kept in a ship ready state at all times. To facilitate this all features which haven't been fully accepted into the language must be disabled.

• What is the difference between the feature and main branches?: The main branch represents code which will ship in updates to the current version of the compiler. The feature branches represent features that are still in progress, therefore not merged yet.

• Why weren't speclets filed for early features?: Features such as tuples and local functions were done before this process was fully developed. Their speclets were considered internally and eventually became the docs/feature/<feature name.md> file.

• Why the high bar to create a feature branch?: Language features, even when driven by the community, require a substantial long term resource investment by the language team. The team must do regular code reviews, provide guidance, help with architectural issues, contribute, etc ...

Contributing Documentation For IDE CodeStyle Analyzers (`docs/contributing/Documentation for IDE CodeStyle analyzers.md`) Copy Section

Documentation for IDE CodeStyle analyzers

Overview Copy Chapter

1. Official documentation for all IDE analyzer diagnostic IDs is added to dotnet/docs repo at https://github.com/dotnet/docs/tree/main/docs/fundamentals/code-analysis/style-rules.

2. Each IDE diagnostic ID has a dedicated documentation page. For example:

   1. Diagnostic with code style option: https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/ide0011
   2. Diagnostic without code style option: https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/ide0004
   3. Multiple diagnostic IDs sharing the same option(s): https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/ide0003-ide0009. In this case, a redirection for all diagnostic IDs must be added.

3. We have tabular indices for IDE diagnostic IDs and code style options for easier reference and navigation:

   1. Primary index (rule ID + code style options): https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/
   2. Secondary index (code style options only): https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/language-rules#net-style-rules
   3. Indices for each preference/option group. For example:
      1. Modifier preferences: https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/modifier-preferences
      2. Expression-level preferences: https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/expression-level-preferences

Action items when adding or updating IDE analyzers Copy Chapter

Roslyn IDE team (@dotnet/roslyn-ide) is responsible for ensuring that the documentation for IDE analyzers is up-to-date. Whenever we add a new IDE analyzer, add new code style option(s) OR update semantics of existing IDE analyzers the following needs to be done:

1. Action required in dotnet/docs repo:

   1. If you creating a Roslyn PR for an IDE analyzer:
      1. Please follow the steps at Contribute docs for 'IDExxxx' rules to add documentation for IDE analyzers to dotnet/docs repo.
      2. Ideally, the documentation PR should be created in parallel to the Roslyn PR or immediately following the approval/merge of Roslyn PR.
   2. If you are reviewing a Roslyn PR for an IDE analyzer:
      1. Please ensure that the analyzer author is made aware of the above doc contribution requirements, especially if it is a community PR.
      2. If the documentation PR in is not being created in parallel to the Roslyn PR, please ensure that a new doc issue is filed in dotnet/docs repo to track this work.

2. No action required in Roslyn repo: Help links have been hooked up to IDE code style analyzers in Roslyn repo in the base analyzer types, so every new IDE analyzer diagnostic ID will automatically have https://docs.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/ideXXXX as its help link. There is no action required on the Roslyn PR to ensure this linking.

If you feel any of the existing IDE rule docs have insufficient or incorrect information, please submit a PR to dotnet/docs repo to update the documentation.

Contributing IDE Test Plan (`docs/contributing/IDE Test Plan.md`) Copy Section

This resource has moved to ../wiki/Manual-Testing.md

Contributing Localization In Compiler Tests (`docs/contributing/Localization In Compiler Tests.md`) Copy Section

Localization in Compiler Tests

The compiler tests are structured such that they can be run on a machine using any locale. This
both serves as a tool to ensure the compiler does not have any localization errors but also to
ensure that developers from any locale can contribute to the project. The ability to build and
execute tests should not be limited to English speaking developers.

Our infrastructure runs the compiler test suite on es-ES machines for both .NET Core and .NET
Framework. This helps us ensure that compiler tests can be authored and executed on non-English
machines without issues.

How it works Copy Chapter

To ensure that our tests run on any locale there is a general approach that is followed in the vast
majority of our tests.

1. All expected baselines are expressed in invariant culture. That means that say decimal values are expressed using . separators not ,.
2. All generated baselines, usually via Console.Writeline inside CompileAndVerify, must be generated such that they produce output in invariant culture.
3. Diagnostic tests use the VerifyDiagnostics helpers using en-US values for the messages. The implementation of VerifyDiagnostics will request the diagnostic message in the en-US culture.
   This helps ensure the compiler has no localization product issues by forcing a consistent culture no matter the current culture of the system.

The largest source of friction that developers encounter when authoring tests is passing values to
Console.WriteLine that have locale dependent representations. For example double and decimal
values.

decimal d = 1.2;
Console.WriteLine(d);

The above code will print 1.2 on en-US but 1,2 on es-ES machines. To fix this issue the value needs to be explicitly formatted with invariant culture.

using System.Globalization;
...

decimal d = 1.2;
Console.WriteLine(d.ToString(CultureInfo.InvariantCulture));

This will consistently print 1.2.

Exceptions Copy Chapter

There are a few cases where it is very difficult to avoid locale dependent values. These include:

1. When a diagnostic includes a message from a thrown exception.
2. When a diagnostic includes a message from the underlying OS.
3. When a message is generated by a tool such as msbuild.

In those cases the message is likely to be locale dependent. Tests that have these values should be
marked is [ConditionalFact(typeof(IsEnglishLocal))] so they run on en-US machines only.

Infrastructure Copy Chapter

Windows Copy Section

The Spanish Windows machines used in our infrastructure execute with CurrentCulture set to es-ES but
CurrentUICulture set to en-US. This configuration means that roughly string formatting happens
with es-ES but resource lookups happen with en-US. This setup doesn't fully test our code base
so our test infrastructure will force the CurrentUICulture to be CurrentCulture when the two
differ.

This is done in the TestBase constructor, which all compiler test classes inherit from. When CurrentUICulture does not equal CurrentCulture, the constructor saves the original CurrentUICulture
and sets CurrentUICulture to CurrentCulture. The original value is restored in Dispose so the
change is scoped to the lifetime of each test instance. This ensures that on a Windows machine configured
with CurrentCulture = es-ES and CurrentUICulture = en-US, resource string lookups also happen in
es-ES, fully exercising the localization paths.

Linux Copy Section

The Spanish Linux machines used in our infrastructure run on Ubuntu with the LC_ALL environment
variable set to es_ES.UTF-8. On .NET running on Linux, LC_ALL determines both CurrentCulture
and CurrentUICulture. This means that unlike the Windows configuration, both string formatting and
resource lookups will use es-ES. Because both culture values are already
the same, the test infrastructure does not need to force CurrentUICulture to CurrentCulture on
these machines.

Contributing Nullable Annotations (`docs/contributing/Nullable Annotations.md`) Copy Section

Nullable Annotations

This document describes how nullable annotations should be approached in the
Roslyn code base. The default is to simply follow the same guidance
as the dotnet/runtime repository. This document
serves to detail the places where the guidance differs for Roslyn and
re-emphasize rules that come up frequently.

Annotation Guidance Copy Chapter

• DO annotate all new code
• DO use the null suppression operator in places where a method body has
  ensured a value cannot be null but the compiler is unable to track it.
  Example:

struct SyntaxTrivia {
    void Example() {    
        if (this.HasStructure) {
            Use(this.GetStructure()!);
        }
    }
}

• DO use explicit validation such as Debug.Assert or
  Contract.ThrowIfNull to capture internal program invariants.

void M1(SyntaxNode node) {
    Debug.Assert(node.Parent is object);
    ...
    M2(node.Parent);
}

• AVOID annotating and refactoring code in the same commit. This can
  significantly increase the cost of reviewing. Prefer instead to separate
  annotations and significant refactorings into separate commits. Small changes,
  and modernizing style (change default(SyntaxToken) to default) are
  acceptable.
• DO NOT be concerned with the validity of annotations after an object has
  been disposed or otherwise entered into an invalid state. For example
  manipulating a pooled object after it's been freed. This is a violation of the
  objects contract and annotations aren't meaningful here.
• DO NOT be concerned with the validity of an enumerator's Current
  annotations when used before MoveNext has been called or after MoveNext has
  returned false. As with Dispose, such use is considered invalid, and we don't
  want to harm the correct consumption of Current by catering to incorrect
  consumption.
• DO use the adjective Require when defining a member that exist only
  to provide a non-null returning version of a method that returns a nullable
  reference type. For example: GetRequiredSemanticModel model returns a non-null
  value from GetSemanticModel

Breaking Change Guidance Copy Chapter

Roslyn is a large code base and it will take significant time for us to fully
annotate the code base. This will likely take several releases for our larger
libraries to complete. During this time those libraries will not consider
nullable annotations to be a part of the compatibility bar. That is
nullable annotations will change without an entry in the breaking change
document, no compat review, etc ...

Once the nullable annotations in a given library reach critical mass we will
begin tracking nullable annotations as a part of our compatibility bar. The
Roslyn team still reserves the right to change annotations if the language or
underlying platforms we build on effectively require us to do so. However such
changes will have a higher degree of scrutiny and will need approval from
members of the API compat council.

As specific libraries complete their nullable annotations then the annotations
will be tracked in API files
and the library names will be added to this document as being complete.

Contributing Powershell Guidelines (`docs/contributing/Powershell Guidelines.md`) Copy Section

Powershell Guidelines

Powershell is primarily used in this repo as the backbone of our infrastructure. As such
Powershell scripts need to be portable, reliable and take advantage of stop on error
approaches. The guidelines below are meant to push scripts to this mindset of execution.

Coding Style Copy Chapter

1. Opening braces always go at the end of an expression / statement.
2. Closing braces always occur on an otherwise empty line.
3. We use two space indentation.
4. Use Pascal casing for functions and where possible follow the Verb-Name convention.
5. Use Camel casing for all other identifier.
6. Use full command names instead of aliases. For example Get-Content vs. gc. Aliases can be
   overridden by the environment and hence are not considered portable.

General Guidelines Copy Chapter

Script Template Copy Section

All Powershell scripts that execute in CI need to conform to the following template.

[CmdletBinding(PositionalBinding=$false)]
param (
    [switch]$ci = $false,
    [string]$configuration = "Debug")

Set-StrictMode -version 2.0
$ErrorActionPreference="Stop"

try { 
  . (Join-Path $PSScriptRoot "build-utils.ps1")
  $prepareMachine = $ci

  # Body of Powershell script goes here

  ExitWithExitCode 0
}
catch {
  Write-Host $_
  Write-Host $_.Exception
  Write-Host $_.ScriptStackTrace
  ExitWithExitCode 1
}

The rationale for these parts are:

• Set-StrictMode: forces Powershell into a stricter mode of interpretation and
  swaps out the "On Error Resume Next" approach for an "On Error Stop" model. Both of these
  help with our goals of reliability as it makes errors hard stops (unless specifically stated otherwise)
• $prepareMachine = $ci: is necessary to ensure ExitWithExitCode properly exits all
  build processes in CI environments (conforming to arcade guidelines).
• ExitWithExitCode: arcade standard for exiting a script that deals with process management
• PositionalBinding=$false: alerts callers when they have incorrect parameters invoking a
  script

Coding Guidelines Copy Section

Use Exec-* functions to execute programs or dotnet commands. This adds automatic
error detection on invocation failure, incorrect parameters, etc ...

# DO NOT
& msbuild /v:m /m Roslyn.slnx
& dotnet build Roslyn.slnx

# DO
Exec-Command "msbuild" "/v:m /m Roslyn.slnx"
Exec-DotNet "build Roslyn.slnx"

Scripts that have many executions of dotnet commands can store the dotnet command in a variable
and use Exec-Command instead.

Call Test-LastExitCode after invoking a powershell script to make sure failure is not ignored.

# DO NOT
& eng/make-bootstrap.ps1
Write-Host "Done with Bootstrap"

# DO
& eng/make-bootstrap.ps1
Test-LastExitCode
Write-Host "Done with Bootstrap"

Whenever comparing with $null always make sure to put $null on the left hand side of the
operator. For non-collection types this doesn't really affect behavior. For collection types though
having a collection on the left hand side changes the meaning of -ne and -eq. Instead of checking for $null it will instead compare collection contents.

# DO NOT
if ($e -ne $null) { ... }
# DO
if ($null -ne $e) { ... }

Powershell vs. pwsh Copy Section

The Roslyn infrastructure should use powershell for execution not pwsh. The general .NET infra
still uses Powershell and calls into our scripts. Moving to pwsh in our scripts creates errors
in source and unified build. Until that moves to pwsh our scripts need to stay on Powershell.

pwsh is permitted in cases which are not part of our infrastructure. i.e., scripts that are not under the eng/ folder, and not expected to be run by the build process.
This is necessary in scenarios where the script needs to run cross-platform, such as:

• VS Code helper scripts
• AI skills

Supporting .cmd file Copy Section

Consider adding a .cmd file that calls the .ps1 file. This is to support users who are not
running a powershell shell. It also helps with ensuring the script is run locally the same it is
run in CI by controlling the powershell used to invoke the script.

test.cmd

@echo off
set PSMODULEPATH=
powershell -noprofile -ExecutionPolicy Unrestricted -file "%~dp0\test.ps1" %*

Note: the PSMODULEPATH is cleared to ensure a pwsh shell does not interfere
with launching powershell.

Contributing Testing For Interactive Readiness (`docs/contributing/Testing for Interactive readiness.md`) Copy Section

Compiler debugging/EnC checklist

1. Sequence points are emitted correctly and corresponding syntax nodes are recognized as breakpoint spans by the IDE
   • Verify manually by launching VS with the new compiler bits and step through and place breakpoints on all syntax nodes that should allow breakpoint
   • Add regression compiler tests that check emitted IL with sequence points (VerifyIL with sequencePoints)
   • Add IDE test via src\EditorFeatures\CSharpTest\EditAndContinue\BreakpointSpansTests.cs (implementation src\Features\CSharp\Portable\EditAndContinue\BreakpointSpans.cs, which deals with mapping syntax to sequence points)
2. Sequence points in relationship with closure allocations and other hidden code (for any syntax that produces sequence points)
   • The debugger supports manually moving the current IP (instruction pointer) using “Set Next Statement Ctlr+Shift+F10” command.
   • The statement can be set to any sequence point in the current method.
   • Need to make sure that sequence points are emitted so that the right hidden code gets executed.
   • For example, the sequence point on an opening brace of a block that allocates a closure needs to precede the closure allocation instructions, so that when the IP is set to this sequence point the closure is properly allocated.

{               // closure allocated here
   var x = 1;
   F(() => x);
}

3. Conditional branching has to use stloc/ldloc pattern in DEBUG build
   • Check the instructions and sequence points emitted for e.g. an if statement in debug build. Instead of straightforward brtrue/brfalse we allocate a temp local, store the result of the condition evaluation to that local, emit hidden sequence point, load the result from the local and then branch. This supports EnC function remapping. Only need to think about this when implementing a feature that emits conditional branches with conditions that may contain arbitrary expressions. I believe there are helpers in the lowering phase that emit conditions in general, so it should be done automatically as long as the right helpers are used. But something to be aware of.
4. Closure and lambda scopes (PDB info)
   • If new syntax is introduced that represents some kind of lambda (anonymous methods, local functions, LINQ queries, etc.) update helpers in src\Compilers\CSharp\Portable\Syntax\LambdaUtilities.cs accordingly
   • If a new scope is introduce that can declare variables that can be lifted into a closure
     • The bound node that represents the scope needs to be associated with syntax node recognized by helpers in src\Compilers\CSharp\Portable\Syntax\LambdaUtilities.cs (specifically IsClosureScope).
     • This requirement is enforced by an assertion in SynthesizedClosureEnvironment constructor.
   • Lambda and closure syntax offsets must be emitted to the PDB (encLambdaMap custom debug information)
     • The offset attribute of closure identifies the syntax node that's associated with the closure. This offset must be unique.
5. When a new symbol is introduced symbol matcher might need to be updated
   • Symbol matcher maps a symbol from one compilation to another.
   • Synthesized symbols like closures, state machines, anonymous types, lambdas, etc. also has to be mapped.
   • Impl: src\Compilers\CSharp\Portable\Emitter\EditAndContinue\CSharpSymbolMatcher.cs
   • Tests: src\Compilers\CSharp\Test\Emit\Emit\EditAndContinue\SymbolMatcherTests.cs
6. When a new syntax is introduced that may declare a user local variable or emits long lived synthesized variables (ie. state that survives between breakpoints, not just a temp within expression)
   • Validate that the variable slots can be mapped from new to previous compilation
   • This is implemented by EncVariableSlotAllocator using syntax offsets stored in PDB (encLocalSlotMap and encLambdaMap custom debug info).
   • The current mechanism might not be sufficient to support the mapping, in which case raise the issue with the IDE team to design additional PDB info to support the mapping.
7. Each new language feature should be covered by a test in Emit tests under Emit/EditAndContinue.
   • Some features might just need a single test others multiple tests depending on impact on EnC.
   • PDB tests validate these scopes. (look for <scope> in PDB XML). LocalsTests.cs EE tests also validate the scoping.
8. When a new syntax is introduced that may declare a scope for local variables the corresponding IL scopes need to be emitted correctly in the PDB
   • These are used by the EE to determine which variables are in scope.
9. Test debugging experience of the feature
   • Is useful info displayed in Watch window?
   • Can I evaluate expressions using this feature in Watch window?
   • Some features might require adding more custom PDB information to make the debug experience good (e.g. async, iterators, dynamic, etc).
   • Design experience improvement and custom PDB info with IDE team.

Contributing Bootstrap Builds (`docs/contributing/bootstrap-builds.md`) Copy Section

Bootstrap Builds

The build correctness leg ensures that the latest code in dotnet/roslyn can be used to build dotnet/roslyn. Essentially our compiler can bootstrap itself.

Why? Copy Chapter

The reason we go through so much effort is failures of this nature are incredibly hard to track down after the fact. The compiler is a complex tool and dotnet/roslyn is a large code base. It can take significant time to work out which of the ~300 commits since the last successful bootstrap is causing the current one to fail.

In the past we used to run a bootstrap exercise roughly once a month. Every time there was a failure to build dotnet/roslyn with the latest compiler and it often took weeks for us to understand what change caused the failure. That resulted in a lot of wasted time and almost caused us to slip several releases.

The build correctness jobs was introduced to solve this problem. The compiler verifies it can bootstrap on every change which means we find the failures immediately.

Process Copy Chapter

The build correctness job works by first building the Microsoft.Net.Compilers.Toolset package. This gives us a functioning compiler with the latest changes. This build occurs using the /define:BOOTSTRAP which allows the compiler to make failures more actionable. This is primarily leveraged in the following ways:

• Inserts a ExitingTraceListener into the process trace listeners. This means any Debug.Assert failure will result in the compilation failing with an actionable stack trace.
• Defines a ValidateBootstrap. This lets us validate that the compiler used in the bootstrap build is actually the one we built vs. the default. This helps protect against build authoring changes which could inadvertently cause the default compiler to be used in a bootstrap build.

The job then cleans out all of the artifacts from the build and starts a normal build of Roslyn.slnx but specifies /p:BootstrapBuildPath=.... This causes two files to be loaded:

• Bootstrap.props: loads the bootstrap compiler over the default one
• Bootstrap.targets: verifies the bootstrap compiler was actually used

This leg also ensures that the binary log and the build server log are captured in the set of published artifacts to allow for easy investigations.

Investigating Copy Chapter

The first step for investigating a correctness build failure is downloading the log files. These are available in the published artifacts

The two most interesting files are:

1. Build.Server.log: this is the text log of the compilation process. All stack traces and server error messages will be present in this file
2. Build.binlog: this is the binary log that results from building dotnet/roslyn with a bootstrap compiler.

The build server log file will contain the reason why the particular request to the compiler failed. In most cases searching for one of two terms will take you straight to the failure.

The first term to search for is "Debug.Assert" (no quotes). The most common cause of a bootstrap failure is a Debug.Assert call failing during compilation. This will result in an exception being added to the log with the full stack trace. For example:

/* Detailed source-code truncated for AI context efficiency. */

These failures are almost always due to changes being tested. Essentially the change updated compiler logic in such a way that it caused an Assert to fail. On occasion this will also fail because an IDE change introduces a coding pattern that sets of a latent bug in the compiler or analyzer but this is certainly the rare case.

The next term to search for is "Error " (no quotes but keep the space). This will be added to the log every the server hits an error and needs to shut down.

ID=MSBuild 60300 TID=3: Error Error: 'EndOfStreamException' 'Reached end of stream before end of read.' occurred during 'Reading response for d2c3aeac-bd8a-4251-bde0-2e11bbc57d13'
Stack trace:
   at Microsoft.CodeAnalysis.CommandLine.BuildProtocolConstants.<ReadAllAsync>d__4.MoveNext() in C:\Users\jaredpar\code\wt\ros2\src\Compilers\Core\CommandLine\BuildProtocol.cs:line 641
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at System.Runtime.CompilerServices.ConfiguredTaskAwaitable.ConfiguredTaskAwaiter.GetResult()
   at Microsoft.CodeAnalysis.CommandLine.BuildResponse.<ReadAsync>d__5.MoveNext() in C:\Users\jaredpar\code\wt\ros2\src\Compilers\Core\CommandLine\BuildProtocol.cs:line 342
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at System.Runtime.CompilerServices.ConfiguredTaskAwaitable`1.ConfiguredTaskAwaiter.GetResult()
   at Microsoft.CodeAnalysis.CommandLine.BuildServerConnection.<<RunServerBuildRequestAsync>g__tryRunRequestAsync|7_1>d.MoveNext() in C:\Users\jaredpar\code\wt\ros2\src\Compilers\Shared\BuildServerConnection.cs:line 288

These type of errors, when not paired with a Debug.Assert failure, are almost always bugs in the compiler server. Please contact the compiler team to help track down such failures.

Note: when you encounter a case where the log file does not have an actionable description of why a build failed, strongly consider sending a PR that fixes this. This approach is why the log is such a valuable tool for tracking down bootstrap failures.

Reproducing locally Copy Section

Locally reproducing and attaching a debugger to a bootstrap build failure is fairly simple with use of src/Tools/Replay, which can replay a binlog with the checked-out Roslyn compiler source. To do this, run a build locally with the -bl flag to get a binary log, then use replay to replay the binary log:

Windows

.\build.ps1 -bl
dotnet run --framework net10.0 --project src\Tools\Replay\ artifacts\log\Debug\Build.binlog -w

Linux

./build.sh -bl
dotnet run --framework net10.0 --project src/Tools/Replay/ artifacts/log/Debug/Build.binlog -w

The -w flag will cause replay to print the process ID of the compiler and wait until you hit a key, so that you can attach a debugger to the process and set breakpoints for exceptions you are interested in.

Debugging Copy Chapter

To debug a bootstrap build failure locally do the following.

The first step is disabling the ExitingTraceListener. This is important for CI where the compiler needs to crash on a Debug.Assert failure vs. popping up a dialog that would hang CI. When debugging locally though developers want the Debug.Assert pops up a dialog behavior. To disable the ExitingTraceListener comment out the following line:

https://github.com/dotnet/roslyn/blob/d73d31cbccb9aa850f3582afb464b709fef88fd7/src/Compilers/Server/VBCSCompiler/VBCSCompiler.cs#L22

Next just run the bootstrap build locally, wait for the Debug.Assert to trigger which pops up a dialog. From there you can attach to the VBCSCompiler process and debug through the problem

> Build.cmd -bootstrap

Contributing Codespaces (`docs/contributing/codespaces.md`) Copy Section

Codespaces

This repository provides a GitHub Codespaces configuration for full-repository Roslyn work.

Available configuration Copy Chapter

The configuration uses .devcontainer/Dockerfile, which starts from the .NET 10 SDK image and then installs the exact SDK pinned by global.json.

Lifecycle choices Copy Chapter

The repo uses .devcontainer/restore-workspace.sh <solution> in updateContentCommand.

That placement is intentional:

• updateContentCommand runs during Codespaces prebuild creation.
• postCreateCommand does not run during prebuild creation.
• Keeping restore in updateContentCommand allows GitHub Codespaces to cache the expensive first-run restore step.

The configuration also installs gh and pwsh through dev container features so the container matches common Roslyn command-line workflows more closely.

Recommended repository-level GitHub settings Copy Chapter

These settings live in the repository's Settings > Codespaces page rather than in the repo itself.

1. Enable a prebuild for the default branch using .devcontainer/devcontainer.json.
2. Start with the On configuration change trigger to keep storage and Actions usage under control.
3. Keep retained prebuild versions at 2 unless you have a clear need for a longer rollback window.
4. Limit prebuild regions to the regions your team actually uses.

Validation checklist Copy Chapter

After changing Codespaces settings or the devcontainer configuration:

1. Create a fresh codespace from .devcontainer/devcontainer.json.
2. Confirm the expected default solution loads in VS Code.
3. Confirm gh --version and pwsh --version work in the terminal.
4. Confirm the restore step completes successfully for the selected solution.

Contributing Ide Design Process (`docs/contributing/ide_design_process.md`) Copy Section

IDE Team Design Process

Discussions / Issues Copy Chapter

The goal is that contributors can create and discuss feature suggestions without needing to have everything fully figured out. Feel free to file a new Github issue or start a discussion. These conversations can continue at their own pace until contributors feel ready to make a more formal proposal.

Proposals Copy Chapter

Adding a proposal Copy Section

For a feature proposal to be reviewed, a Github issue needs to be created that has the following items in its description. If these aren't there to start they eventually need to be appended as a comment to the issue before its brought up for discussion.

• Summary: Brief summary of what this proposal is about.
• Background and Motivation: What is the problem we are solving and in what context did you encounter it?
• Proposed Feature: How the proposed solution solves the problem?
• Alternative Designs: Were there other options you considered? How does this compare to features in other editors?

Once you've added the details for your feature tag a member of the Roslyn-IDE team and they will add the "Feature Request" label to your Github issue.

Getting the issue championed by the IDE team Copy Section

A member of Roslyn-IDE will need to decide to "champion" that feature proposal and bring it for discussion by adding it to the "On Deck" tab in the IDE Design Review project. Behind the scenes the IDE Team generally meets once a week to discuss these issues.

Contributing Target Framework Strategy (`docs/contributing/target-framework-strategy.md`) Copy Section

Target Framework Strategy

Layers Copy Chapter

The roslyn repository produces components for a number of different products that push varying ship and TFM constraints on us. A summary of some of our dependencies are:

• Build Tools: requires us to ship compilers on net472
• .NET SDK: requires us to ship compilers on current servicing target framework (presently net10.0)
• Repository Source build: requires us to ship $(NetCurrent) and $(NetPrevious) in workspaces and below (presently net10.0 and net9.0 respectively). This is because the output of repository source build is an input to other repository source build and those could be targeting either $(NetCurrent) or $(NetPrevious).
• Full Source build: requires us to ship $(NetCurrent)
• Visual Studio: requires us to ship net472 for base IDE components and $(NetVisualStudio) (presently net10.0) for private runtime components.
• Visual Studio Code: expects us to ship against the same runtime as DevKit (presently net10.0) to avoid two runtime downloads.
• MSBuildWorkspace: requires us to ship a process that must be usable on the lowest supported SDK (presently net8.0)
• Microsoft.RoslynTools: remains compatible with the lowest runtime supported by Roslyn infrastructure automation (presently net8.0).

It is not reasonable for us to take the union of all TFM and multi-target every single project to them. That would add several hundred compilations to any build operation which would in turn negatively impact our developer throughput. Instead we attempt to use the TFM where needed. That keeps our builds smaller but increases complexity a bit as we end up shipping a mix of TFM for binaries across our layers.

Picking the right TargetFramework Copy Chapter

Projects in our repository should include the following values in <TargetFramework(s)> based on the rules below:

1. $(NetRoslynSourceBuild): code that needs to be part of source build. This property will change based on whether the code is building in a source build context or official builds.
   a. In official builds this will include the TFMs for $(NetVSShared)
   b. In source builds this will include $(NetRoslyn)
2. $(NetVS): code that needs to execute on the private runtime of Visual Studio.
3. $(NetVSCode): code that needs to execute in DevKit host
4. $(NetVSShared): code that needs to execute in both Visual Studio and VS Code but does not need to be source built.
5. $(NetRoslyn): code that needs to execute on .NET but does not have any specific product deployment requirements. For example utilities that are used by our infra, compiler unit tests, etc ... This property also controls which of the frameworks the compiler builds against are shipped in the toolset packages. This value will potentially change in source builds.
6. $(NetRoslynAll): code, generally test utilities, that need to build for all .NET runtimes that we support. Note: $(NetRoslynBuildHostNetCoreVersion) is excluded from this set because the BuildHost is an isolated executable.
7. $(NetRoslynWindowsTests): test projects that use $(NetRoslyn) but can only run on Windows. These tests will be automatically excluded when running on Unix/Linux because the -windows OS-specific TFM suffix tells the .NET SDK and the test runner to skip them on non-Windows platforms.
8. $(NetRoslynBuildHostNetCoreVersion): the target used for the .NET Core BuildHost process used by MSBuildWorkspace. This may lag behind other properties as it must target the lowest supported .NET SDK (presently net8.0 until .NET 8 EOL in November 2026).
9. $(NetRoslynNext): code that needs to run on the next .NET Core version. This is used during the transition to a new .NET Core version where we need to move forward but don't want to hard code a .NET Core TFM into the build files.
10. $(NetRoslynTools): the target used by the Microsoft.RoslynTools infrastructure tool. This may lag behind $(NetRoslyn) so build and insertion automation can run the tool on older supported machines.

This properties $(NetCurrent), $(NetPrevious) and $(NetMinimum) are not used in our project files because they change in ways that make it hard for us to maintain correct product deployments. Our product ships on VS and VS Code which are not captured by arcade $(Net...) macros. Further as the arcade properties change it's very easy for us to end up with duplicate entries in a <TargetFrameworks> setting. Instead our repo uses the above values and when inside source build or VMR our properties are initialized with arcade properties.

DO NOT hard code .NET Core TFMs in project files. Instead use the properties above as that lets us centrally manage them and structure the properties to avoid duplication. It is fine to hard code other TFMs like netstandard2.0 or net472 as those are not expected to change.

DO NOT use $(NetCurrent) or $(NetPrevious) in project files. These should only be used inside of TargetFrameworks.props to initialize the above values in certain configurations.

Require consistent API across Target Frameworks Copy Chapter

It is important that our shipping APIs maintain consistent API surface area across target frameworks. That is true whether the API is public or internal.

The reason for public is standard design pattern. The reason for internal is a combination of the following problems:

• Our repository makes use of InternalsVisibleTo which allows other assemblies to directly reference signatures of internal members.
• Our repository ships a mix of target frameworks. Typically workspaces and below will ship more recent TFMs than the layers above it. Compiler has to ship newer TFM for source build while IDE is constrained by Visual Studio's private runtime hence adopts newer TFM slower.
• Our repository invests in polyfill APIs to make compiling against multiple TFMs in the same project a seamless experience.

Taken together though this means that our internal surface area in many cases is effectively public when it comes to binary compatibility. For example a consuming project can end up with net7.0 binaries from workspaces layer and net6.0 binaries from IDE layer. Because there is InternalsVisibleTo between these binaries the internal API surface area is effectively public. This requires us to have a consistent strategy for achieving binary compatibility across TFM combinations.

Consider a specific example of what goes wrong when our internal APIs are not consistent across TFM:

• Workspaces today targets net6.0 and net7.0 and it contains our EnumerableExtensions.cs which polyfills many extensions methods on IEnumerable<T>. In net7.0 the Order extension method is not needed because it was put into the .NET core libraries.
• Language Server Protocol targets net6.0 and consumes the Order polyfill from Workspaces

Let's assume for a second that we #if the Order method such that it's not present in net7.0. Locally this all builds because we compile the net6.0 versions against each other so they're consistent. However if an external project which targets net7.0 and consumes both Workspaces and Language Server Protocol then it will be in a broken state. The Protocol binary is expecting Workspaces to contain a polyfill method for Order but it does not since it's at net7.0 and it was #if out. As a result this will fail at runtime with missing method exceptions.

This problem primarily comes from our use of polyfill APIs. To avoid this we employ the following rule:

When there is a #if directive that matches the regex #if !?NET.* that declares a non-private member, there must be an #else that defines an equivalent binary compatible symbol

This comes up in two forms:

Pattern for types Copy Section

When creating a polyfill for a type use the #if !NET... to declare the type and in the #else use a TypeForwardedTo for the actual type.

Example:

#if NET6_0_OR_GREATER

using System.Runtime.CompilerServices;

#pragma warning disable RS0016 // Add public types and members to the declared API (this is a supporting forwarder for an internal polyfill API)
[assembly: TypeForwardedTo(typeof(IsExternalInit))]
#pragma warning restore RS0016 // Add public types and members to the declared API

#else

using System.ComponentModel;

namespace System.Runtime.CompilerServices
{
    internal static class IsExternalInit
    {
    }
}

#endif

Pattern for extension methods Copy Section

When creating a polyfill for an extension use the #if NET... to declare the extension method and the #else to declare the same method without this. That will put a method with the expected signature in the binary but avoids it appearing as an extension method within that target framework.

#if NET7_0_OR_GREATER
        public static IOrderedEnumerable<T> Order<T>(IEnumerable<T> source) where T : IComparable<T>
#else
        public static IOrderedEnumerable<T> Order<T>(this IEnumerable<T> source) where T : IComparable<T>
#endif

Transitioning to new .NET SDK Copy Chapter

As the .NET team approaches releasing a new .NET SDK the Roslyn team will begin using preview versions of that SDK in our build. This will often lead to test failures in our CI system due to underlying behavior changes in the runtime. These failures will often not show up when running in Visual Studio due to the way the runtime for the test runner is chosen.

To ensure we have a simple developer environment such project should be moved to to the $(NetRoslynNext) target framework. That ensures the new runtime is loaded when running tests locally.

When the .NET SDK RTMs and Roslyn adopts it all occurrences of $(NetRoslynNext) will be moved to simply $(NetRoslyn).

DO NOT include both $(NetRoslyn) and $(NetRoslynNext) in the same project unless there is a very specific reason that both tests are adding value. The most common case is that the runtime has changed behavior and we simply need to update our baselines to match it. Adding extra TFMs for this just increases test time for very little gain.

Checklist for updating TFMs (once a year) Copy Chapter

• Update TargetFrameworks.props.
  • Ensure we have the correct TFM for VS / VSCode (usually not the latest TFM).
• Might need updating MicrosoftNetCompilersToolsetVersion in eng\Versions.props to consume latest compiler features.
• Change $(NetRoslynNext) references to $(NetRoslyn) in project files.
• Update TFMs in code/scripts/pipelines (search for the old netX.0 and replace with the new netY.0).
• Replace #if NET7_0_OR_GREATER corresponding to the no longer used TFM (net7.0 in this example) with the lowest used TFM (e.g., net8.0: #if NET8_0_OR_GREATER) and similarly the negated variant #if !NET7_0_OR_GREATER with #if !NET8_0_OR_GREATER. See https://github.com/dotnet/roslyn/issues/75453#issuecomment-2405500584.
• Check that the same number of tests still run in CI (they are not unintentionally filtered out by TFM).
• Try an official build, a VS insertion.

Features CheckedUserDefinedOperators (`docs/features/CheckedUserDefinedOperators.md`) Copy Section

Checked user-defined operators

C# should support defining checked variants of the following user-defined operators so that users can opt into or out of overflow behavior as appropriate:

• The ++ and -- unary operators (https://github.com/dotnet/csharplang/blob/main/spec/expressions.md#postfix-increment-and-decrement-operators and https://github.com/dotnet/csharplang/blob/main/spec/expressions.md#prefix-increment-and-decrement-operators).
• The - unary operator (https://github.com/dotnet/csharplang/blob/main/spec/expressions.md#unary-minus-operator).
• The +, -, *, and / binary operators (https://github.com/dotnet/csharplang/blob/main/spec/expressions.md#arithmetic-operators).
• Explicit conversion operators.

Proposal:

• https://github.com/dotnet/csharplang/issues/4665
• https://github.com/dotnet/csharplang/blob/main/proposals/checked-user-defined-operators.md

Feature branch: https://github.com/dotnet/roslyn/tree/features/CheckedUserDefinedOperators

Test plan: https://github.com/dotnet/roslyn/issues/59458

Features DefaultInterfaceImplementation (`docs/features/DefaultInterfaceImplementation.md`) Copy Section

Default Interface Implementation

The Default Interface Implementation feature enables a default implementation of an interface member to be provided as part of the interface declaration.

Here is a link to the proposal https://github.com/dotnet/csharplang/blob/main/proposals/csharp-8.0/default-interface-methods.md.

What is supported:

• Supplying an implementation along with declaration of a regular interface method and recognizing that implementation as default implementation for the method when a type implements the interface.
  Here is an example:

public interface I1
{
    void M1() 
    {
        System.Console.WriteLine("Default implementation of M1 is called!!!");
    }
}

class Test1 : I1
{
    static void Main()
    {
        I1 x = new Test1();
        x.M1();
    }
}