Getting started with Roslyn Analyzers

Roslyn-based analyzers use the .NET Compiler SDK (Roslyn APIs) to analyze your project's source code to find issues and suggest corrections. Different analyzers look for different classes of issues, ranging from practices that are likely to cause bugs to security concerns to API compatibility in C# and VB code.

The Roslyn Analyzers build task is included in the Microsoft Security Code Analysis Extension, and is focused on enabling the security analyzers. This page has the steps needed to configure & run the build task as part of your build definition.

Prerequisites:

1. You are using the Azure DevOps Build system.
2. The Microsoft Security Code Analysis Extension installed in your account.
3. Your build definiton includes the built-in MSBuild or VSBuild build task to compile C# (or VB) code. This task relies on the input and output of that specific build task to rerun the MSBuild compilation with Roslyn analyzers enabled.
4. The build agent running this build task has Visual Studio 2017 v15.5 or later installed (compiler version 2.6.x).

Setup:

1. Open your team project from your Azure DevOps Account.
2. Navigate to the Build tab under Build and Release
3. Select the Build Definition into which you wish to add the Roslyn Analyzers build task.
  • New - Click New and follow the steps detailed to create a new Build Definition.
  • Edit - Select the Build Definition. On the subsequent page, click Edit to begin editing the Build Definition.
4. Click + to navigate to the Add Tasks pane.
5. Find the Roslyn Analyzers build task either from the list or using the search box and then click Add.
6. The Run Roslyn Analyzers build task should now be a part of the Build Definition.

Customizing the Roslyn Analyzers Build Task:

1. Click the task Run Roslyn Analyzers to see the different options available.

2. Available options include
  • Ruleset - SDL Required, SDL Recommended, or you can use a custom ruleset of your own.
  • Analyzers Version (Recommended: Latest)
  • Compiler Warnings Suppressions File - A text file with a list of warnings IDs that should be suppressed.
  • Run this task (under Control Options) - Specifies when the task should run. Choose "Custom conditions" to specify more complex conditions.

Important Notes

1. Roslyn analyzers are compiler-integrated and can only be run as part of CSC.exe compilation. Hence, this task requires replaying/rerunning the compiler command that ran earlier in the build. This is done by querying VSTS for the MSBuild build task logs (there is no other way for the task to reliably get the MSBuild compilation command line from the build definition; we did consider adding a freeform textbox to allow users to enter their commandlines, but it would be hard to keep these up-to-date and in sync with the main build). Custom builds require replaying the entire set of commands, not just compiler commands, and it is not trivial/reliable to enable Roslyn analyzers in these cases.
2. Roslyn analyzers are integrated with the compiler and requires the compilation to be invoked. This build task is implemented by recompiling C# projects that were already built using only the MSBuild/VSBuild build task, in the same build / build definition, but in this case, with the Analyzers enabled. If this build task runs on the same agent as the original build task, the output of the original MSBuild/VSBuild build task will be overwritten in the 's' sources folder, by the output of this build task. The build output will be the same, but it is advised that you run MSBuild, copy output to the the artifacts staging directory, and then run Roslyn.

Resources

Roslyn Analyzers on docs.microsoft.com
The analyzer package installed and used by this build task.

  • Error : The project was restored using Microsoft.NETCore.App version x.x.x, but with current settings, version y.y.y would be used instead. To resolve this issue, make sure the same settings are used for restore and for subsequent operations such as build or publish. Typically this issue can occur if the RuntimeIdentifier property is set during build or publish but not during restore:
    • Roslyn analyzers run as part of compilation, so the source tree on the build machine needs to be in a buildable state. A step (probably "dotnet.exe publish") between your main build and Roslyn analyzers may have put the source tree in an unbuildable state. Perhaps duplicating the step that does a Nuget Restore, just before the Roslyn Analyzers step, will put the source tree back in a buildable state.

  • "csc.exe" exited with error code 1 -- An instance of analyzer AAAA cannot be created from C:\BBBB.dll : Could not load file or assembly 'Microsoft.CodeAnalysis, Version=X.X.X.X, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. The system cannot find the file specified.
    • Ensure your compiler supports Roslyn analyzers. "csc.exe /version" should report at least v2.6.x. In some cases, individual .csproj files can override the build machine's Visual Studio installation, by referencing a package from Microsoft.Net.Compilers. If using a specific version of the compiler was unintended, remove references to Microsoft.Net.Compilers. Otherwise, make sure the referenced package is also at least v2.6.x. Try to get the error log, which you can find in the /errorlog: parameter from the csc.exe command line (found in the Roslyn build task's log). It may look something like: /errorlog:F:\ts-services-123\_work\456\s\Some\Project\Code\Code.csproj.sarif

  • The C# compiler is not recent enough (it must be >= 2.6)
    • The latest versions of the C# compiler are released here: https://www.nuget.org/packages/Microsoft.Net.Compilers. To get the installed version you are using: C:\>csc.exe /version 2.10.0.0 (b9fb1610) Ensure that you do not have any reference to a Microsoft.Net.Compilers NuGet package that is < v2.6.

  • MSBuild/VSBuild Logs Not Found
    • Because of how the task works, this task needs to query Azure DevOps for the MSBuild log from the MSBuild build task. If this task runs immediately after the MSBuild build task, the log will not yet be available; Place other build tasks, including SecDevTools build tasks, like Binskim, Antimalware Scan, and others), between the MSBuild build task and the Roslyn Analyzers build task.