In version 5.0 of the SonarScanner, we changed the name of the SonarScanner for MSBuild to SonarScanner for .NET.
The documentation is updated with the new name and we will call the scanner SonarScanner for .NET moving forward.
The SonarScanner for .NET is the recommended way to launch an analysis for projects using themsbuild
ordotnet
build tools. It is the result of acollaboration between SonarSource and Microsoft.
SonarScanner for .NET is distributed as a standalone command-line executable, as an extension forAzure DevOps, and as a plugin forJenkins.
It supports .NET Core on every platform (Windows, macOS, Linux).
Prerequisites
- Java 17 or later
- The SDK corresponding to your build system:
- .NET Framework v4.6.2- eitherBuild Tools for Visual Studio 2015 Update 3or theBuild Tools for Visual Studio
- .NET Core SDK 3.1 and above(for .NET Core version of the scanner or if you plan to use.NET Core Global Tool)
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
Standalone executable
- Expand the downloaded file into the directory of your choice. We'll refer to it as
$install_directory
in the following steps.- On Windows, you might need to unblock the ZIP file first (right-clickFile > 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 SonarCloud 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:
- Add
$install_directory
to your PATH environment variable.
.NET Core Global Tool
dotnet tool install --global dotnet-sonarscanner --version x.x.x
The--versionargument is optional. If it is omitted, the latest version will be installed. A complete list of releases is available on theNuGet page
.NET Core Global Tool is available from .NET Core 3.1+.
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 anauthentication tokenusing thesonar.token
property.
"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:
Note: On macOS or Linux, you can also usemono <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:
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:
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
Begin
Thebegin
step is executed when you add thebegin
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:<analysis-parameter>=<value>
- [optional] Specifies an additional SonarCloud analysis parameter.
- You can add this argument multiple times.
For detailed information about all available parameters, seeAnalysis Parameters.
The "begin" step will modify your build like this:
- the active
CodeAnalysisRuleSet
will be updated to match the SonarCloud quality profile WarningsAsErrors
will be turned off
If your build process cannot tolerate these changes we recommend creating a second build job for SonarCloud analysis.
Build
Between thebegin
andend
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 theMSBuild/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>
- This argument is required if it was added to the begin step.
Known limitations
- MSBuild versions older than 15 are not supported.
- 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 anyTestResults
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.
SeeTest Coveragefor more information.
Excluding projects from analysis
Some project types, such asMicrosoft Fakes, are automatically excluded from the analysis. To manually exclude a different type of project from the analysis, place the following in its.xxproj
file.
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 2017 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:
If you do not want to switch your production build to MSBuild 16, you can set up a separate build dedicated to the SonarCloud analysis.
Detection of test projects
You can read a full description of that subject on our wikihere.
Per-project analysis parameters
Some analysis parameters can be set for a single MSBuild project by adding them to its.csproj
file.
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 supported by the available language plugins unless explicitly excluded.
If you have anesproj
project type, make sure to useMicrosoft.VisualStudio.JavaScript.SDKversion 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 listed in the.csproj
or.vbproj
project file. Usually, 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 theItemTypes
inthis listwill 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 directoryfoo\bar
becauseContent
is one of theItemTypes
whose includes are automatically analyzed.
You can also addItemTypes
to the default list by followingthese 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:
WhereyourProxyHostandyourProxyPortare 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
, andNO_PROXY
are all supported. You can find more detailshere.
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.
We don't uninstall the globalImportBefore
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 thesonar-dotnet
analyzer will be executed along with your build task.
To avoid that, you can disable the targets file by adding a build parameter: