This version of the SonarQube documentation is no longer maintained. It relates to a version of SonarQube that is not active.

SonarScanner for .NET

The SonarScanner for .NET is the recommended way to launch an analysis for projects built using MSBuild or dotnet.

SonarScanner for .NET — 10.3.0.120579 | Issue Tracker

10.3.0.120579 2025-07-16 Support xUnit v3, fix RunDeploymentRoot in trx files, remove sonar.scanner.scanAll analysis warning. Download Release notes

10.2.0.117568 2025-06-03 Fix a vulnerability from embedded scanner-cli. Download Release notes

10.1.2.114627 2025-04-16 Add 'sonar' default truststore passord fallback. Download Release notes

10.1.1.111189 2025-03-25 Maintenance and dependencies updates. Download Release notes

10.1.0 2025-03-19 Maintenance and dependencies updates. Download Release notes

10.0.0 2025-03-13 Fix a vulnerability. Mandate that the truststore password is passed in the end step if used in the begin step. Added support for 7 new languages. Download Release notes

9.2.1 2025-02-25 DEPRECATED. Use system trusted certificate or JVM certificate store. Download Release notes

9.2.0 2025-02-19 DEPRECATED. Support for local trust store for private and self-signed certificates. Download Release notes

9.1.0 2025-02-06 Read new properties for downloading plugins Download Release notes

9.0.2 2024-11-12 sonar.projectBaseDir passed through extraProperties is respected with Azure DevOps extensions. Do not fail during file indexing when a directory cannot be accessed. Download Release notes

9.0.1 2024-10-25 Fix projectBaseDir path detection on Azure DevOps Linux agents. Download Release notes

9.0.0 2024-09-27 Ignore sonar.sources and sonar.tests properties. Download Release notes

8.0.3 2024-09-13 Exclude XML files from the new automatic analysis. Do not crash on mlaformed paths. Make sure server-side exclusions are not overridden. Download Release notes

8.0.2 2024-09-02 Re-enabled sonar.exclusions support. Automatically exclude files passed-in as coverage. Skip transient projects that do not exist after the build. Download Release notes

8.0.1 2024-08-21 Bug fix release which addresses two issues, improvements on messages emmitted during the analysis. Download Release notes

8.0 2024-08-12 The scanner is now supporting multi-language analysis. Files for other languages are automatically picked up (SQL, YAML, XML, JSON, CSS, HTML, JS, TS) Download Release notes

7.1.1 2024-07-24 Fixed a small issue when not specifying sonar.host.url (defaults to https://sonarcloud.io) Download Release notes

7.1 2024-07-19 Fixed a small issue when not specifying sonar.host.url (defaults to https://sonarcloud.io) Download Release notes

7.0 2024-07-18 This version does not require a JRE to be present on the machine anymore Download Release notes

6.2 2024-02-16 Fixes the failing analysis on macOS with .NET 8.0. New optional sonar.http.timeout command line parameter Download Release notes

6.1 2024-01-29 Drop support for MSBuild 14, deprecate MSBuild 15 Download Release notes

6.0 2023-12-04 Packaging change, drop support for .Net Framework 4.6, Net 2.1, and .Net 3.0. Drop Java 11 support. Drop support of SonarQube versions prior to 8.9 Download Release notes

5.15.1 2024-03-26 Fix analysis on MacOSX with .NET 8 when begin runtime doesn't match with build runtime Download Release notes

5.15 2023-11-20 Add an option to specify the scanner's temporary working directory Download Release notes

5.14 2023-10-02 Support upcoming SonarQube 10.4 API changes Download Release notes

5.13.1 2023-08-14 SonarScanner CLI update Download Release notes

5.13 2023-04-05 Support for sonar.token parameter and improved error messages Download Release notes

5.12 2023-03-17 Fast PR Analysis Support For Azure Devops Download Release notes

5.11 2023-01-27 Fast PR Analysis Compatibility Fix Download Release notes

5.10 2023-01-13 Improved FIPS Compliance Download Release notes

5.9.2 2022-12-14 Bug Fix Release related to PR analysis Download Release notes

5.9.1 2022-12-06 Bug Fix Release Download Release notes

5.9.0 2022-12-01 .NET 7 bug fixes and preparation for fast PR analysis Download Release notes

5.8.0 2022-08-24 Analysis of Azure Functions on Github Actions no longer hard fails with default behavior. See release notes for details. Download Release notes

5.7.2 2022-07-12 Log warning instead of error when not parsing environment variables to avoid hard failure when Newtonsoft does not get resolved Download Release notes

5.7.1 2022-06-21 Bug Fix Release Download Release notes

5.7.0 2022-06-20 Bug Fix Release Download Release notes

5.6.0 2022-05-30 Send warnings to users of versions where support will change Download Release notes

5.5.3 2022-02-14 Support for .NET 6 Web Projects, TLS Version selection logic removed - now responsibility of OS, Fix "MSB3677 Unable to move file" regression Download Release notes

5.5.2 2022-02-10 Support for .NET 6 Web Projects, TLS Version selection logic removed, now responsibility of OS Download Release notes

5.5.1 2022-02-08 Support for .NET 6 Web Projects, support TLS 1.3 where supported by environment Download Release notes

5.5.0 2022-02-07 Support for .NET 6 Web Projects, support TLS 1.3 Download Release notes

5.4.1 2021-12-23 Updated Newtonsoft.Json to latest Download Release notes

5.4 2021-11-26 Updated .NET 5 Version to be forward compatible and support .NET 6 environments Download Release notes

5.3.2 2021-10-28 Added parameters sonar.clientcert.path and sonar.clientcert.password for securing connections to SonarQube Download Release notes

5.3.1 2021-09-01 Update scanner-cli, Compile with .NET Core 2.1 and 3.1, Improve uninstall of targets if multiple builds in the same pipeline Download Release notes

5.2.2 2021-06-24 Fix test assembly detection + mTLS certificate with password Download Release notes

5.2.1 2021-04-30 Update embedded SonarScanner CLI Download Release notes

5.2 2021-04-09 Support for test code analysis Download Release notes

5.1 2021-03-09 Support for .NET 5, support for solo .NET Core project (without .sln) Download Release notes

5.0.4 2020-11-11 Support for .NET 5, support for solo .NET Core project (without .sln) Download Release notes

5.0.3 2020-11-10 Support for .NET 5, support for solo .NET Core project (without .sln) Download Release notes

5.0 2020-11-05 Support for .NET 5, support for solo .NET Core project (without .sln) Download Release notes

4.10 2020-06-29 Support FIPS compliant cryptographic algorithm Download Release notes

4.9 2020-05-05 Improve detection of duplicated coverage reports, fix categorization of fakes projects Download Release notes

4.8 2019-11-06 Enable scanner execution when only .NET Core 3 is installed Download Release notes

4.7.1 2019-09-10 Update SonarScanner to version 4.1 Download Release notes

4.7 2019-09-03 Support dash and forward-slash in dotnet command line arguments, analyze XAML files, add analyzed targets in logs Download Release notes

Beginning with the Sonar Scanner for .NET v8, the way the sonar.projectBaseDir property is automatically detected has changed which has an impact on the files that are analyzed and how relative properties, such as sonar.exclusions and sonar.test.exclusions, are resolved.

To customize the behavior, you can set the sonar.projectBaseDir property to point to a directory that contains all the source code you want to analyze. The path may be relative (to the directory from which the analysis was started) or absolute.

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.

The SonarScanner for .NET is distributed as a .NET Core Global Tool, in the SonarQube extension for Azure DevOps, and and in the Sonar SonarQube extension for Jenkins.

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

Prerequisites

  • SonarQube 10.4 requires the SonarScanner for .NET 5.14+.

  • From version 7.0, Java is no longer required because the scanner will download it automatically.

    • If internet access is limited in your configuration, skip the JRE provisioning and use the Java version installed locally.

    • If you are running a previous version of the scanner you will need at least the minimal version of Java supported by your SonarQube server.

  • The SDK corresponding to your build system:

  • The minimum supported version for SonarQube is now 8.9. We recommend that you upgrade to the 9.9 LTA (or newer) because support for older versions will end in January 2025.

    • The scanner will fail to start if an older version of SonarQube is detected.

The flavor used to compile the Scanner for .NET (either .NET Framework, .NET Core or .NET) is independent of the .NET version the project you want to analyze has been built with. Concretely, you can analyze .NET Core code with the .NET Framework version of the Scanner. It’s only relevant depending on your OS, and on the versions of .NET SDKs that are installed on your build machine.

Installation

.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+.

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.

If your SonarQube server is secured

If your SonarQube server is Securing the server behind a proxy and a self-signed certificate then you must add the self-signed certificate to the trusted CA certificates of the SonarScanner. In addition, if mutual TLS is used then you must define the access to the client certificate at the SonarScanner level.

See Managing TLS certificates on client side.

Use

You can invoke the Scanner using arguments with both dash (-) or forward-slash (/) separators. Either of the following will work:

  • SonarScanner.MSBuild.exe begin /k:"project-key"

  • 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 Generating and using tokens using the sonar.token property. In addition, the default URL points to a SonarCloud 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:

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.

The SonarScanners run on code that is checked out. See Verifying the code checkout step.

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 Introduction page.

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 Generating and using tokens 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>

  • /d:sonar.clientcert.password=<ClientCertificatePassword>

    • [optional] Specifies the password for the client certificate used to access SonarQube Managing TLS certificates on client side. 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 Analysis parameters, 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 Quality profiles 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>

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

In an Azure DevOps / TFS environment, test files are automatically retrieved as follows:

  • A search is done for .trx files in any TestResults folder located under $Build.SourcesDirectory.

  • If no .trx files are found there, then a fallback search is performed under $Agent.TempDirectory.

Once the .trx files have been found, their .coverage counterparts are retrieved and converted to .coveragexml files for upload to SonarCloud.

As stated above, this will work only with the .NET Framework version of the scanner.

See .NET test coverage for more information.

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:

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. As described in the Multi-language article below, some file types are automatically included in the SonarScanner for .NET v8.0 and newer.

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.

Even if you disable multi-file analysis (see below), any files included by an element of the ItemTypes in this list will be analyzed automatically. For example, the following line in your .csproj or .vbproj file will enable the analysis of all JavaScript files in the directory foobecause the content is one of the ItemTypes that are automatically analyzed.

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

Additionally, <Compilation Remove="FileName.ext"/> and <None Remove="FileName.ext"/> attributes in .NET project files (either .csproj or .vbproj) work differently depending on the file type and if the sonar.scanner.scanAll property (the multi-language analysis feature) is enabled or not.

  • C# and VB.NET files will not be analyzed since they are not part of the compilation, and therefore the Roslyn analyzers will not run on them.

  • When the multi-language analysis feature is enabled, additional language file types (such as JavaScript, TypeScript, SQL, etc.) are added to the scope and will be analyzed. To ignore specific language file types, we recommend that you use the sonar.exclusions property. See the Multi-language analysis article (below) for a list of file types automatically picked up by the scanner.

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-project.properties after MSBuild has finished.

File type extensions can be manually excluded from the analysis using sonar.exclusions. See the File exclusion and inclusion article on the Analysis scope page for more details.

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.

Multi-language analysis

The SonarScanner for .NET (starting from v8.0) automatically analyzes these languages using the sonar.scanner.scanAll parameter. These file types are automatically picked up by the scanner:

  • CSS (.css,.less,.scss,.sass)

  • HTML (.html,.xhtml,.cshtml,.vbhtml,.aspx,.ascx,.rhtml,.erb,.shtm, .shtml,.cmp,.twig)

  • Javascript (.js,.jsx,.cjs,.mjs,.vue). See the JavaScript/TypeScript test coverage page for details to adjust your setup.

  • JSON (.json)

  • PLSQL (.sql,.pks,.pkb)

  • SQL (.tsql)

  • TypeScript (.ts,.tsx,.cts,.mts). See the JavaScript/TypeScript test coverage page for details to adjust your setup.

  • YAML (.yaml,.yml)

File type extensions can be found and configured in the SonarQube UI; see the Setting the scope by file type article for more details. Additionally, file types can be manually excluded from the analysis using sonar.exclusions. See the Wildcard patterns article on the Analysis scope page for a list of patterns and examples.

Unless manually excluded, the files linked by the .csproj project file will be analyzed even if the value is false.

Multi-Language analysis is enabled by default. If this was not intended and you have issues such as hitting your LOC limit or analyzing unwanted files, you can set /d:sonar.scanner.scanAll=false in the Begin step to turn off multi-language analysis.

Known issues

I have multiple builds in the same pipeline, each of them getting analyzed even if the Run Code Analysis has already been executed:

The scanner doesn’t uninstall the global ImportBefore targets to support concurrent analyses on the same machine. The main effect is that if you build a solution where a .sonarqube folder is located nearby, then the sonar-dotnet analyzer will be executed along with your build task.

To avoid that, you can disable the targets file by adding a build parameter:

msbuild /p:SonarQubeTargetsImported=true
dotnet build -p:SonarQubeTargetsImported=true

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.

Last updated

Was this helpful?