Using the SonarScanner for .NET

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. In addition, the default URL points to a SonarQube Cloud path therefore, you must also direct the invocation to your /d:sonar.host.url.

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="<token>" /d:sonar.host.url="http://localhost:9000"
MSBuild.exe <path to project file or .sln file> /t:Rebuild
SonarScanner.MSBuild.exe end /d:sonar.token="<token>"

.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>" /d:sonar.host.url="http://localhost:9000"
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>" /d:sonar.host.url="http://localhost:9000"
dotnet build <path to project file or .sln file> --no-incremental
dotnet sonarscanner end /d:sonar.token="<token>"

In summary, the invocation of the SonarScanner for .NET will depend on the scanner flavor you want to use:

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

The construction of your pipeline may vary slightly based on your DevOps platform integration. Please see the appropriate pages for your platform:

• GitHub integration 
• Bitbucket Cloud integration 
• Adding the SonarQube Server analysis to your GitLab CI/CD pipeline 
• Azure DevOps integration 

Begin

The begin step is executed when you add the begin command line argument. It hooks into the build pipeline, downloads SonarQube Server 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 Server.
• /n:<project name>
  • [optional] Specifies the name of the analyzed project in SonarQube Server. 
  • Adding this argument will overwrite the project name in SonarQube Server 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 Server. 
  • 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 Server if mutual TLS is used. The certificate must be password-protected.
• /d:sonar.clientcert.password=<ClientCertificatePassword>
  • [optional] Specifies the password for the client certificate used to access SonarQube Server if mutual TLS 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=60
  • [optional] Specifies the time in seconds to wait before the HTTP requests time out.
• /d:<analysis-parameter>=<value>
  • [optional] Specifies an additional SonarQube Server analysis parameter, you can add this argument multiple times. Please note that the sonar.sources and sonar.tests parameters are not supported.
• /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.
• /d:sonar.scanner.scanAll=true
  • [optional] Enables and Disables the analysis of multiple file types. See the Multi-language support article for the full details. Unless manually excluded, the files linked by the .csproj project file will be analyzed even if the value is false.
  • Default: true

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 Server Quality Profile are run during the build, and it is expected that analyzing with SonarQube Server 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 Server. 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 Server if mutual TLS is used.

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.

Related pages

Introduction to the SonarScanner for .NET

Installing the SonarScanner for .NET

Configuring the SonarScanner for .NET