SonarScanner for .NET

The SonarScanner for .NET is the recommended way to launch an analysis for projects built using MSBuild or dotnet. It is the result of a collaboration between SonarSource and Microsoft.

SonarScanner for .NET is distributed as a standalone command line executable, as an extension for Azure DevOps Server, and as a plugin for Jenkins.

It supports .NET Core on every platform (Windows, macOS, Linux).

Prerequisites

• SonarQube 10.4 requires the SonarScanner for .NET 5.14+.
• At least the minimal version of Java supported by your SonarQube server
  • Java 17 is required to run this version of the scanner. If you are running a previous version of Java, you will need a previous version of the scanner.
• The SDK corresponding to your build system:
  • If you are using the .NET Framework version of the scanner you will need .NET Framework v4.6.2 or above. For commercial versions of SonarQube to benefit from security analysis you will need .NET Framework v4.7.2 or above
  • If you are using the .NET version of the scanner or the .NET Core Global Tool you will need .NET Core SDK 3.1 or above
• The minimum supported version for SonarQube is now 8.9.
  • The scanner will fail to start if an older version of SonarQube is detected.

Installation

Standalone executable

• Expand the downloaded file into the directory of your choice. We'll refer to it as <INSTALL_DIRECTORY> in the next steps.
  • On Windows, you might need to unblock the ZIP file first (right-click file > Properties > Unblock).
  • On Linux/OSX you may need to set execute permissions on the files in <INSTALL_DIRECTORY>/sonar-scanner-(version)/bin.
• Uncomment, and update the global settings to point to your SonarQube server by editing <INSTALL_DIRECTORY>/SonarQube.Analysis.xml. Values set in this file will be applied to all analyses of all projects unless overwritten locally.
  Consider setting file system permissions to restrict access to this file.

<SonarQubeAnalysisProperties  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.sonarsource.com/msbuild/integration/2015/1">
  <Property Name="sonar.host.url">http://localhost:9000</Property>
  <Property Name="sonar.token">[my-user-token]</Property>
</SonarQubeAnalysisProperties>

• Add <INSTALL_DIRECTORY> to your PATH environment variable.

.NET Core global tool

dotnet tool install --global dotnet-sonarscanner --version x.x.x

The --version argument is optional. If it is omitted the latest version will be installed. The full list of releases is available on the NuGet page.

.NET Core Global Tool is available from .NET Core 3.1+.

On Linux/OSX, if your SonarQube server is secured

1. Copy the server's CA certs to /usr/local/share/ca-certificates
2. Run sudo update-ca-certificates

Use

There are two versions of the SonarScanner for .NET. In the following commands, you need to pass an authentication token using the sonar.token property.

Any project file accepted by MSBuild.exe or dotnet can be used, for example .sln, .proj, .csproj, or .vbproj.

"Classic" .NET framework invocation

The first version is based on the "classic" .NET Framework. To use it, execute the following commands from the root folder of your project:

SonarScanner.MSBuild.exe begin /k:"project-key" /d:sonar.token="myAuthenticationToken"
MSBuild.exe <path to project file or .sln file> /t:Rebuild
SonarScanner.MSBuild.exe end /d:sonar.token="myAuthenticationToken"

Note: On macOS or Linux, you can also use mono <path to SonarScanner.MSBuild.exe>.

.NET Core and .NET Core global tool invocation

The second version is based on .NET Core which has a very similar usage:

dotnet <path to SonarScanner.MSBuild.dll> begin /k:"project-key" /d:sonar.token="<token>"
dotnet build <path to project file or .sln file> --no-incremental
dotnet <path to SonarScanner.MSBuild.dll> end /d:sonar.token="<token>" 

The .NET Core version can also be used as a .NET Core Global Tool. After installing the Scanner as a global tool as described above it can be invoked as follows:

dotnet tool install --global dotnet-sonarscanner
dotnet sonarscanner begin /k:"project-key" /d:sonar.token="<token>"
dotnet build <path to project file or .sln file> --no-incremental
dotnet sonarscanner end /d:sonar.token="<token>"

Notes:

• The .NET Core version of the scanner does not support TFS XAML builds and automatic finding/conversion of Code Coverage files. Apart from that, all versions of the Scanner have the same capabilities and command line arguments.

Analysis steps

Begin

The begin step is executed when you add the begin command line argument. It hooks into the build pipeline, downloads SonarQube quality profiles and settings, and prepares your project for analysis.

Begin step command line parameters

• /k:<project-key>
  • [required] Specifies the key of the analyzed project in SonarQube
• /n:<project name>
  • [optional] Specifies the name of the analyzed project in SonarQube. 
  • Adding this argument will overwrite the project name in SonarQube if it already exists.
• /v:<version>
  • [recommended] Specifies the version of your project.
• /d:sonar.token=<token>
  • [recommended] Requires version 5.13+. Use sonar.login for earlier versions.
  • Specifies the authentication token used to authenticate with SonarQube. If this argument is added to the Begin step, it must also be added to the End step.
• /d:sonar.clientcert.path=<ClientCertificatePath>
  • [optional] Specifies the path to a client certificate used to access SonarQube. The certificate must be password protected.
• /d:sonar.clientcert.password=<ClientCertificatePassword>
  • [optional] Specifies the password for the client certificate used to access SonarQube. Required if a client certificate is used. If this argument is added to the Begin step, it must also be added to the End step.
• /d:sonar.verbose=true
  • [optional] Sets the logging verbosity to detailed. Add this argument before sending logs for troubleshooting.
• /d:sonar.dotnet.excludeTestProjects=true
  • [optional] Excludes Test Projects from analysis. Add this argument to improve build performance when issues should not be detected in Test Projects.
• /d:sonar.http.timeout
  • [optional] Specifies the time in seconds to wait before the HTTP requests time out.
• /d:<analysis-parameter>=<value>
  • [optional] Specifies an additional SonarQube analysis parameter, you can add this argument multiple times.
• /s:<custom.analysis.xml>
  • [optional] Overrides the $install_directory/SonarQube.Analysis.xml. You need to give the absolute path to the file.
• /d:sonar.plugin.cache.directory=<path_to_directory>
  • [optional] Requires version 5.15+. Overrides the path where the scanner downloads its plugins. Plugins that are already present will not be downloaded again, unless newer versions are available.
  • You can provide a relative or an absolute path.
  • Defaults to the machine's temporary files directory.

For detailed information about all available parameters, see the Analysis parameters page.

Build

Between the begin and end steps, you need to build your project, execute tests, and generate code coverage data. This part is specific to your needs and it is not detailed here. See .NET test coverage for more information.

The rules configured in your SonarQube Quality Profile are run during the build, and it is expected that analyzing with SonarQube can increase build duration from 4 to 8 times. The impact on duration will vary by project and by what rules are enabled; some rules are simple to execute and others take additional time to have the impact and precision expected of them.

End

The end step is executed when you add the "end" command line argument. It cleans the MSBuild/dotnet build hooks, collects the analysis data generated by the build, the test results, and the code coverage, and then uploads everything to SonarQube. There are only two additional arguments that are allowed for the end step.

End step command line parameters

• /d:sonar.token=<token>
  • This argument is required if it was added to the begin step.
• /d:sonar.clientcert.password=<ClientCertificatePassword>
  • This argument is required if it was added to the begin step. Specifies the password for the client certificate used to access SonarQube.

Known limitations

• MSBuild versions 14 and older are not supported. MSBuild 15 is deprecated and support will be removed in a future version. We recommend using MSBuild 16 as a minimal version.
• Web Application projects are supported. Legacy Web Site projects are not.
• Projects targeting multiple frameworks and using preprocessor directives could have slightly inaccurate metrics (lines of code, complexity, etc.) because the metrics are calculated only from the first of the built targets.

Code coverage

See .NET test coverage for details.

Excluding projects from analysis

Some project types, such as Microsoft Fakes, are automatically excluded from analysis. To manually exclude a different type of project from the analysis, place the following in its .xxproj file.

<!-- in .csproj –->
<PropertyGroup>
  <!-- Exclude the project from analysis -->
  <SonarQubeExclude>true</SonarQubeExclude>
</PropertyGroup>

Advanced topics

Analyzing MSBuild 12, 14, and 15 projects with MSBuild 16

The Sonar Scanner for .NET requires your project to be built with MSBuild 16. We recommend installing Visual Studio 2022 or later on the analysis machine in order to benefit from the integration and features provided with the Visual Studio ecosystem (VSTest, MSTest unit tests, etc.).

Projects targeting older versions of the .NET Framework can be built using MSBuild 16 by setting the "TargetFrameworkVersion" MSBuild property as documented by Microsoft:

• How to: Target a Version of the .NET Framework
• MSBuild Target Framework and Target Platform

For example, if you want to build a .NET 3.5 project, but you are using a newer MSBuild version:

MSBuild.exe /t:Rebuild /p:TargetFramework=net35

If you do not want to switch your production build to MSBuild 16, you can set up a separate build dedicated to the SonarQube analysis.

Detection of test projects

You can read a full description of that subject on our wiki here.

Per-project analysis parameters 

Some analysis parameters can be set for a single MSBuild project by adding them to its .csproj file.

<!-- in .csproj -->
<ItemGroup>
  <SonarQubeSetting Include="sonar.stylecop.projectFilePath">
    <Value>$(MSBuildProjectFullPath)</Value>
  </SonarQubeSetting>
</ItemGroup>

Analyzing languages other than C# and VB

For newer SDK-style projects used by .NET Core, .NET 5, and later, the SonarScanner for .NET will analyze all file types that are supported by the project type (for example, esproj), MSBuild, and the available language plugins unless explicitly excluded.

If you have an esproj project type, make sure to use Microsoft.VisualStudio.JavaScript.SDK version 0.5.74-alpha or later to ensure the SonarScanner for .NET recognizes the esproj contents for scanning.

For older-style projects, the scanner will only analyze files that are listed in the .csproj or .vbproj project file. Normally this means that only C# and VB files will be analyzed. To enable the analysis of other types of files, include them in the project file.

More specifically, any files included by an element of one of the ItemTypes in this list will be analyzed automatically. For example, the following line in your .csproj or .vbproj file

<Content Include="foo\bar\*.js" />

will enable the analysis of all JS files in the directory foo\bar because Content is one of the ItemTypes whose includes are automatically analyzed.

You can also add ItemTypes to the default list by following these directions.

You can check which files the scanner will analyze by looking in the file .sonarqube\out\sonar-project.properties after MSBuild has finished.

Using SonarScanner for .NET with a proxy

On build machines that connect to the Internet through a proxy server you might experience difficulties connecting to SonarQube. To instruct the Java VM to use specific proxy settings use the following value:

SONAR_SCANNER_OPTS = "-Dhttp.proxyHost=yourProxyHost -Dhttp.proxyPort=yourProxyPort"

Where yourProxyHost and yourProxyPort are the hostname and the port of your proxy server. There are additional proxy settings for HTTPS, authentication and exclusions that could be passed to the Java VM. For more information, see the following article: https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html.

You also need to set the appropriate proxy environment variables used by .NET. HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY are all supported. You can find more details here.

Installing the server's self-signed certificate

If your SonarQube server is configured with HTTPS and a self-signed certificate then you must install the self-signed certificate into the Java truststore of your CI/CD host machine otherwise the scanner will not be able to connect to the server and the analysis will fail.

Known issues

Excluding files in certain directories

It is known that the SonarScanner for .NET can’t filter the excluded files/folders from the analysis, which happens during the build. The sonar.exclusions property is only used to filter issues sent to SonarQube during the end step.

As a workaround, you can try to add an .editorconfig file in your Migrations folder to override the severity of the Sonar rules:

[*.cs]
dotnet_diagnostic.S1118.severity = none

Unfortunately, you may have to manually do this for every rule.