Getting started with .NET

Setting up a .NET analysis with Sonar involves different configurations depending on your .NET environment and the CI integration used for your workflow. This page helps you get started by looking at the prerequisites, provides information to identify the version of the .NET scanner you should use, followed by links to setting up your CI environment and concluding with an overview of establishing code coverage to generate reports.

Prerequisites

Knowing which .NET version you are running is important; check this Microsoft documentation to learn which versions you have installed.

The SonarScanner for .NET must be installed in the same environment where you build your application. For example, if you’re building projects locally, the scanner must be installed locally; similarly, if you’re working with Azure Pipelines, you must add SonarScanner tasks to the pipeline. 

The SonarScanner is working during the build process therefore, don't be worried if everything takes a little longer because as mentioned above, the build is now also running an analysis during the build. 

Your environment

SonarQube Server

The SonarScanner for .NET works with supported versions of SonarQube Server and with SonarQube Cloud.

• SonarQube 10.4 and newer requires the SonarScanner for .NET 5.14 or newer. 
• SonarQube 8.9 is deprecated in the SonarScanner for .NET 9.0. The SonarScanner will fail to start if SonarQube 8.8 or older is detected.

Java

Depending on the version of the SonarScanner for .NET and SonarQube Server combination you are using, you might need to install Java. When running SonarQube 10.6 or newer with the scanner version 7.0 or newer, installing a JRE is not required because it will be automatically obtained from the server.

• You can disable JRE auto-provisioning and specify your own version of Java; please check the scanner's page General requirements, when using JRE auto-provisioning.

Otherwise, you must have at least the minimal version of Java supported by your version of SonarQube Server. 

• Before scanner version 6.0, Java 11 or newer is required.
• From and including scanner version 6.0, Java 17 or newer is required.

Select Show more in the SonarScanner for .NET version Update Center box below; then find the scanner version that fits with your version of SonarQube Server and .NET framework to download the correct version.

Identify your SonarScanner version

Each .NET environment is slightly different. Check the appropriate tab for requirements and notes about the installation.

Installing the scanner

SonarQube Server knows which analyzer plugins you need for a given version however, choosing the correct SonarScanner version is up to you according to your .NET environment. You can use any version of the SonarScanner that supports your .NET runtime. For full details, check the Installing the SonarScanner for .NET page for the prerequisites and install instructions. 

Below, choose the SDK corresponding to your build system for a getting started overview:

dotnet tool install --global dotnet-sonarscanner --version x.x.x

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

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

Setting up your pipeline

How you set up the SonarScanner for .NET in your pipeline depends on your production environment. Here we will give a high-level overview, and link to pages with more detail, covering the most common CI environments:

Basic steps

For the most part, your pipeline should include these basic steps to run properly:

1. Install the prerequisites in your environment (Java).
2. Download the correct SonarScanner version for your .NET runtime, and install it on your CI.
3. Then work on your pipeline;
   • specify your Begin step arguments to prepare your project for analysis, 
   • build your project which will generate the analysis data, 
   • and define the End step arguments to collect the analysis data.
4. Finally, focus your analysis as part of your build process by setting up your test coverage using a third-party tool to access important metrics. 

For more details, select the tab box below that matches your CI:

sonarqube-check:
  image: mcr.microsoft.com/dotnet/core/sdk:latest
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"  # Defines the location of the analysis task cache
    GIT_DEPTH: "0"  # Tells git to fetch all the branches of the project, required by the analysis task
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script: 
      - "apt-get update"
      - "apt-get install --yes openjdk-17-jre"
      - "dotnet tool install --global dotnet-sonarscanner"
      - "export PATH=\"$PATH:$HOME/.dotnet/tools\""
      - "dotnet sonarscanner begin /k:\"projectKey" /d:sonar.token=\"$SONAR_TOKEN\" /d:\"sonar.host.url=$SONAR_HOST_URL\" "  #Replace "projectKey" with your project key
      - "dotnet build"
      - "dotnet sonarscanner end /d:sonar.token=\"$SONAR_TOKEN\""
  allow_failure: true
  only:
    - merge_requests
    - master
    - main
    - develop

Managing your analysis

Once your CI pipeline is up and running, you can improve it to integrate pull request analyses and use your quality gate status to prevent merges when the quality gate fails. Each CI, as linked to above, manages pull requests in different ways and you’ll have to check the appropriate tab item for your CI to get the details.

The Introduction to the pull request analysis page provides an overview of how pull requests work in SonarQube Server. The Setting up the pull request analysis page will provide you with information about pull request parameters before pointing you to pages that help configure the quality gate status.

Essentially, the main steps of the analysis process are:

1. Your build or CI pipeline starts the SonarScanner. 
2. The SonarScanner scans the local repository and determines the files to be analyzed according to the configured analysis scope. 
3. The scanner sends an analysis request to the respective language analyzer which retrieves the files to be analyzed from the file system and analyzes them according to the configured quality profile. 
4. The analyzer sends the analysis results (quality measures and issues) to the scanner which forwards them to SonarQube Server in the form of a report. 
5. SonarQube Server computes the analysis results asynchronously to perform the following:
   • It identifies the new issues according to the configured New Code definition and raises them in both the new code and the overall code (It uploads the code as part of the analysis and shows users the code that it raised issues on. Unanalyzed changes in the code are not visible.).
   • It computes the quality gate.
   • It generates reports.

The Test coverage article below explains how SonarQube Server reports work.

Test Coverage

Test coverage reports and test execution reports are important metrics to help you assess the quality of your code. 

• Test coverage reports tell you what percentage of your code is covered by test cases. 
• Test execution reports tell you which tests have been run and their results.

To track code coverage in Sonar, you must use one of the supported coverage tools during your test run before the scanner can pick up the report. For instructions and examples of how to manage code coverage, refer to the .NET test coverage page.

Running a standard project analysis is slightly different than running an analysis on a test project. Please see the .NET Project analysis vs test coverage page for more complete details.

If you're still confused about code coverage and test data, we prepared some Community guides that might be helpful. A full list of guides on the Troubleshooting .NET page.