Using the SonarScanner for .NET
On this page
Use
You can invoke the Scanner using arguments with both dash (-) or forward-slash (/) separators. For example:
SonarScanner.MSBuild.exe begin /k:"project-key"
or
SonarScanner.MSBuild.exe begin -k:"project-key"
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:
.NET Core and .NET Core Global Tool invocation
The second version is based on .NET Core which has a very similar usage:
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:
In summary, the invocation of the SonarScanner for .NET will depend on the scanner flavor you want to use:
Scanner Flavor | Invocation |
---|---|
.NET Core Global Tool | dotnet sonarscanner begin etc. |
.NET Core 3.1+ | dotnet <path to SonarScanner.MSBuild.dll> etc. |
.NET Framework 4.6.2+ | SonarScanner.MSBuild.exe begin etc. |
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:
See the Analyzing GitHub projects page.
See the Analyzing Bitbucket Cloud projects page.
See the Analyzing GitLab projects page.
See the Analyzing Azure DevOps projects page.
Begin
The begin
step is executed when you add the begin
command-line argument. It hooks into the build pipeline, downloads SonarQube Cloud 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 Cloud.
/n:<project name>
- [optional] Specifies the name of the analyzed project in SonarQube Cloud.
- Adding this argument will overwrite the project name in SonarQube Cloud if it already exists.
/v:<version>
- [recommended] Specifies the version of your project.
/o:<organization>
- [required] Specifies the name of the target organization in SonarQube Cloud.
/d:sonar.token=<token> or <username>
- [recommended] Specifies the authentication token or username used to authenticate with to SonarQube Cloud.
- 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 Cloud analysis parameter, you can add this argument multiple times. Please note that the
sonar.sources
andsonar.tests
parameters are not supported.
- [optional] Specifies an additional SonarQube Cloud analysis parameter, you can add this argument multiple times. Please note that the
/s:<custom.analysis.xml>
- [optional] Overrides the
$install_directory/SonarQube.Analysis.xml
. You need to give the absolute path to the file.
- [optional] Overrides the
/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 Analysis Parameters.
The "begin" step will modify your build like this:
- the active
CodeAnalysisRuleSet
will be updated to match the SonarQube Cloud quality profile WarningsAsErrors
will be turned off
If your build process cannot tolerate these changes we recommend creating a second build job for SonarQube Cloud analysis.
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 Cloud Quality Profile are run during the build, and it is expected that analyzing with SonarQube Cloud 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 Cloud. 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
Was this page helpful?