Getting started with .NET

Your page to get started setting up a .NET analysis in any edition of SonarQube Server.

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.

.NET

Install your .NET environment

If you are using the .NET version of the scanner or the .NET Global Tool you will need .NET Core SDK 3.1 or above. See this Microsoft page to download .NET.

The SonarScanner for .NET works with .NET environments including .NET Core 3.1 and newer.

.NET FRAMEWORK

Install your .NET Framework environment

If you are using the .NET Framework version of the scanner you will need .NET Framework v4.6.2 or above. For commercial versions of SonarQube Server to benefit from security analysis you will need .NET Framework v4.7.2 or above. See this Microsoft page to download supported versions of .NET Framework.

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 scanner page for the prerequisites and install instructions.

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

.NET

Install scanner for .NET

You can install the SonarScanner for .NET from Nuget using the .NET global tool, or download a standalone file to execute.

.NET global tool

If you are using .NET on an already installed instance of SonarQube Server, the simplest way to install the scanner is to use the dotnet install tool from the command line. The .NET Global Tool is available from .NET Core 3.1+.

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

The --version argument is optional; if omitted, the latest version will be installed. The full list of release versions is available on the NuGet page.

If you can’t use the dotnet install tool, other versions are available for download in the SonarScanner Update Center collapsible (access above, select Show more).

Standalone executable

You can install the SonarScanner for .NET via the .NET Core hyperlink in the Sonar Update Center panel above, or directly from the releases page.

• 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 instance of 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.

Previous versions of the .NET Framework SonarScanner are available on the releases page or found by selecting Show More to expand the Sonar Update Center panel above.

.NET FRAMEWORK

Install scanner for .NET Framework

You can install the SonarScanner for .NET by downloading a standalone file to execute.

Standalone executable

You can install the SonarScanner for .NET via the .NET Framework hyperlink in the Sonar Update Center panel above, or directly from the releases page.

• 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’s instance 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.

Previous versions of the .NET Framework SonarScanner are available on the releases page or found by selecting Show More to expand the Sonar Update Center panel above.

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. Installing the scanner in your environment (Java).

2. Download the correct SonarScanner version for your .NET runtime, and install it on your CI.

3. Then Using the scanner;

   • 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 .NET test coverage using a third-party tool to access important metrics.

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

AZURE

Azure DevOps Pipelines

SonarQube Server can be integrated with both Azure DevOps Server and Azure DevOps Services. To get your analysis up and running, you will need to:

• add an Azure Personal Access Token (PAT) to your instance of SonarQube Server.

• install the SonarQube Server extension from the Visual Studio Marketplace. The Azure DevOps Extension for SonarQube Server embeds the most recent SonarScanner for .NET. Check the extension’s page for more details.

• add a new SonarQube Server service endpoint.

• finally, configure your Azure pipeline to send the analysis results to SonarQube Server.

The .NET project pages have all of the details to complete this process, and a full tutorial is available in the Azure DevOps Labs repository; it’s been some time since the tutorial was updated but the basic steps are the same.

If you’re using SonarQube Cloud, the Analyzing Azure DevOps projects page will help you start the setup process and a full tutorial is available here.

GITHUB

GitHub Actions

SonarQube Server can be integrated with both GitHub Enterprise and GitHub.com repositories. To get your analysis up and running, you will need to:

1. create a GitHub app. Please see GitHub’s documentation on creating a GitHub App.

2. install your GitHub App in your organization. GitHub has documentation on installing GitHub Apps.

3. update your SonarQube Server global settings with your GitHub App information. This information can be found on the Importing GitHub repositories page.

4. finally, configure your .github/workflows/build.yml file so that the SonarScanner and GitHub can talk together to send your analysis results to SonarQube Server.

The Introduction page is your entry point to find all of the details to complete this process.

GITLAB

GitLab integration

SonarQube Server can be integrated with GitLab self-managed and GitLab SaaS subscription repositories. To get your analysis up and running, you will need to:

1. set your environment variables for all pipelines in GitLab’s settings. You’ll need to generate a Sonar Token and define your Sonar Host URL.

2. finally, configure your .gitlab-ci.yml file so that the SonarScanner can be installed and send your analysis results to SonarQube Server. If you’re running SonarQube Commercial editions and GitLab Ultimate, you can report vulnerabilities directly in GitLab.

For more details about completing this process, check out the Adding analysis to GitLab CI/CD pipeline page.

Here is a code sample for your gitlab-ci.yml file:

SonarScanner for .NET

Configure your .gitlab-ci.yml file for .NET

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

JENKINS

Jenkins integration

A SonarQube Server analysis using the SonarScanner for .NET can be triggered from Jenkins using the standard Jenkins Build Steps or the Jenkins Pipeline DSL. To get your analysis up and running, you will need to:

1. Install the Jenkins extension via the Jenkins Update Center.

2. To trigger your analysis, add the SonarScanner for .NET to the Jenkins Global Tool Configuration. Setting up Jenkins provides complete instructions.

3. Finally, construct your Jenkins pipeline, adding a withSonarQubeEnv block that allows you to select SonarQube Server.

Additional configurations are available to manage your pipeline for Setting up Jenkins and Setting up a pipeline pause while the quality gate is computed. The Jenkins extension for SonarQube and Setting up Jenkins pages will have complete details.

BITBUCKET

Bitbucket integration

SonarQube Server integrates well with Bitbucket Cloud. To get your analysis up and running, you will need to:

1. import your Bitbucket Cloud repository into SonarQube Server.

2. finally, set up your pipeline to install the SonarScanner for .NET by Configuring your bitbucket-pipelines.yml file.

It’s possible to configure more details like reporting your quality gate status in Bitbucket Cloud or failing the pipeline when the quality gate fails. Check the Bitbucket Cloud integration page for full details.

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 pull request analysis introduction 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 profiles.

4. The analyzer sends the analysis results to the scanner which forwards them to SonarQube Server in the form of a report. See also Understanding measures and metrics and Issue management solution.

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

   • 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 Specifying test projects 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 page.