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.

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" /o:"<organization>" /d:sonar.token="<token>"
MSBuild.exe <path to solution.sln> /t:Rebuild
SonarScanner.MSBuild.exe end /d:sonar.token="<token>"

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" /o:"<organization>" /d:sonar.token="<token>"
dotnet build <path to solution.sln> --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" /o:"<organization>" /d:sonar.token="<token>"
dotnet build <path to solution.sln> --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 will be slightly different according to your DevOps platform integration. Please see the appropriate pages for your platform:

Begin

The begin step is executed when you add the begin command-line argument. It hooks into the build pipeline, downloads SonarCloud 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 SonarCloud.
• /n:<project name>
  • [optional] Specifies the name of the analyzed project in SonarCloud. 
  • Adding this argument will overwrite the project name in SonarCloud if it already exists.
• /v:<version>
  • [recommended] Specifies the version of your project.
• /o:<organization>
  • [required] Specifies the name of the target organization in SonarCloud.
• /d:sonar.token=<token> or <username>
  • [recommended] Specifies the authentication token or username used to authenticate with to SonarCloud. 
  • 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 SonarCloud 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.
• /d:sonar.scanner.scanAll
  • [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.
  • Defaults to true.

For detailed information about all available parameters, see Analysis Parameters.

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 SonarCloud Quality Profile are run during the build, and it is expected that analyzing with SonarCloud 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 SonarCloud. There are only two additional arguments that are allowed for the end step.

End step command line parameters:

• /d:sonar.token=<token> or /d:sonar.token=<username>
  • If this argument is added to the Begin step, it must also be added to the End step.

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