Skip to end of metadata
Go to start of metadata

NOTE This feature requires:

  • SonarQube 7.4+ / SonarCloud
  • SonarScanner for MSBuild 4.4+
  • SonarC#/SonarVB Analyzers 7.6+

Creating custom rules using Roslyn

The Roslyn code analysis framework from Microsoft makes is easy to author your own C# or VB.NET rules, and many third-party analyzers already exist and are freely available on

The official Microsoft documentation is a good place to start if you are interested in authoring your own rules.

Importing issues raised by other Roslyn analyzers

The SonarQube Scanner for MSBuild automatically imports issues created by the SonarC# and SonarVB analyzers. In addition, issues from third-party Roslyn analyzers (including Roslyn analyzers provided by Microsoft) will be automatically imported into SonarQube/SonarCloud as generic issues.

However, there are differences in how in third-party analyzers are configured and managed, as summarized in the table below:

SonarC#/SonarVBOther Roslyn analyzers
Configuration of rulesUsing Quality Profiles in the SonarQube UI

Manually configured at MSBuild project level using the standard MSBuild ruleset mechanism.

Configuration required for analyzer executionNone requiredMust be manually added as NuGet packages to each project
Suppression of issues

Can be managed in the SonarQube UI
(i.e. closed, marked as Won't Fix, False Positive etc)

Cannot be managed etc through the SonarQube UI

If a third-party analyzer is enabled both as a NuGet in a MSBuild project and as a SonarQube plugin created using the SonarQube Roslyn SDK, the plugin takes precedence over the NuGet and issues from the NuGet are ignored.

Preventing the import of issues from third-party analyzers

The import can be disabled by setting the language-specific properties sonar.cs.roslyn.ignoreIssues and sonar.vbnet.roslyn.ignoreIssues to true. The default values are false. The properties can be set globally or for each SonarQube project.

Mapping between Roslyn and SonarQube concepts

Conceptually the way rules are described in Roslyn and SonarQube are very similar: they have unique ids, descriptions, target a specific language etc. However, there are some differences, for example in the how the severity of a rule is expressed (Roslyn has three levels of severity while SonarQube has five).

This section explains how Roslyn concepts are mapped to their SonarQube equivalents.

Categorization of issues

SonarQube categories issues as code smells, bugs and vulnerabilities. Roslyn rules have a single Category field, but there is not a standard list of well-known category types used across different Roslyn analyzers.

By default, SonarQube will categorize an external issue as a code smell unless the severity is error, in which case it will be classified as a bug. However, you can configure how SonarQube categorizes external issues by setting the following language-specific properties (replace cs with vbnet for the corresponding Visual Basic property):

  • sonar.cs.roslyn.codeSmellCategories
  • sonar.cs.roslyn.bugCategories
  • sonar.cs.roslyn.vulnerabilityCategories

Each property can be set to a multi-value list of strings. The properties can be set globally or at project level.

Severity of issues

The following table show the mapping between Roslyn severity levels and SonarQube severity levels:

Roslyn severitySonar severity

Roslyn issues with severity "Error"

Be careful if you are using Roslyn analyzers that have rules with the severity set to Error, either because this is the default for the rule or because you have increased the severity in a custom ruleset (very few Roslyn analysis rules have the error level set to Error by default). Error level issues will cause the build to fail.

It is not recommended to run the scanner end step if the MSBuild step fails for any MSBuild project (whether due to Roslyn Error analysis issues or for other reasons such as invalid syntax) as this will cause all pre-existing issues in SonarQube for those failed projects to be marked as closed. This is because the scanner end step will not upload any issues for the failed projects, so SonarQube will assume that there are no issues and will mark issues from the previous run as being closed.

  • No labels