Qodana for .NET

The Docker image for the Qodana for .NET linter is provided to support different usage scenarios:

Running analyses on a regular basis as part of your continuous integration (CI-based execution)
Single-shot analyses (for example, performed locally).

If you are familiar with Rider code inspections and know what to expect from the static analysis outside the editor, you can skip the following section and continue from Using an existing profile.

If you are just starting in the field, we recommend proceeding with the default setup we provide. You will see the results of the most common checks performed on your code base. Later, you can adjust them to suit your needs better.

You can run the Qodana for .NET linter using two methods. Qodana CLI is the easiest method. If necessary, check the installation page to install Qodana CLI. Alternatively, you can use the Docker commands from the Docker image tab.

Quick start with the recommended profile

Run analysis locally

You can run Qodana CLI in the native mode, which is the recommended method for the Qodana for .NET linter if you are targeting .NET Framework or have private NuGet feeds:

                qodana scan \
                   --ide QDNET
            

Here, the --ide option downloads and uses the JetBrains IDE binary file.

Alternatively, save the following configuration in the qodana.yaml file:

ide: QDNET

Run Qodana using this command:

qodana scan

This is how you can run the Dockerized version of the Qodana for .NET linter:

Pull the image from Docker Hub (only necessary to update to the latest version):
docker pull jetbrains/qodana-dotnet:2024.1
Run the following command:
docker run \ -v <source-directory>/:/data/project/ \ -v <output-directory>/:/data/results/ \ -e QODANA_TOKEN="<cloud-project-token>" \ jetbrains/qodana-dotnet:2024.1
where source-directory and output-directory are full local paths to, respectively, the project source code directory and the analysis results directory. The QODANA_TOKEN variable refers to the project token required by the Ultimate and Ultimate Plus linters.

This command will run the analysis on your source code and start the web server to provide a convenient view of the results. Open Qodana Cloud in your browser to examine inspection results. Here you can also reconfigure the analysis. See the Inspection report for details.

If you don't need the user interface and prefer to study raw data, use the following command:

                    docker run \
                       -v <source-directory>/:/data/project/ \
                       -v <output-directory>/:/data/results/ \
                       -e QODANA_TOKEN="<cloud-project-token>" \
                       jetbrains/qodana-dotnet:2024.1
                

The output-directory will contain all the necessary results. You can further tune the command as described in the technical guide.

If you run the analysis several times in a row, make sure you've cleaned the results directory before using it in docker run again.

You can run Qodana for .NET using private NuGet feeds:

                    docker run \
                       -v <source-directory>/:/data/project/ \
                       -e QODANA_TOKEN="<cloud-project-token>" \
                       -e QODANA_NUGET_URL=<private-NuGet-feed-URL> \
                       -e QODANA_NUGET_USER=<login> \
                       -e QODANA_NUGET_PASSWORD=<plaintext-password> \
                       -e QODANA_NUGET_NAME=<name-of-private-NuGet-feed> \
                       jetbrains/qodana-dotnet:2024.1 \
                       --show-report
                

Configuration examples for using private NuGet feeds are available on the GitHub website.

In the project root directory, run this command to inspect your code and view the inspection report locally:

If you don't need the user interface and prefer to study raw data, use the following command:

                    qodana scan \
                       -e QODANA_TOKEN="<cloud-project-token>" \
                       -l jetbrains/qodana-dotnet:2024.1 \
                       --results-dir <output-directory>
                

The output-directory specifies the directory where the SARIF-formatted report will be saved. The QODANA_TOKEN variable refers to the project token required by the Ultimate and Ultimate Plus linters.

Run analysis in CI

Use the following command as a task in a generic shell executor:

                    docker run \
                       -v <source-directory>/:/data/project/ \
                       -v <output-directory>/:/data/results/ \
                       -e QODANA_TOKEN="<cloud-project-token>" \
                       jetbrains/qodana-dotnet:2024.1
                

where source-directory and output-directory are full paths to, respectively, the project source code directory and the analysis results directory. The QODANA_TOKEN variable refers to the project token required by the Ultimate and Ultimate Plus linters.

Consider using the Quality gate feature to make the build fail when a certain number of problems is reached and the Baseline feature to compare each new Qodana for .NET run to some initial run selected as a baseline. Running as non-root is also supported.

Run this command in the project root directory:

                    qodana scan \
                       -e QODANA_TOKEN="<cloud-project-token>" \
                       -l jetbrains/qodana-dotnet:2024.1 \
                       --results-dir <output-directory>
                

This will save inspection results to the directory specified by output-directory.

You can also apply the Quality gate feature to make the build fail when a certain number of problems is reached by using the --fail-threshold option.

The Baseline feature compares each new Qodana for .NET run to some initial run using the --baseline and --baseline-include-absent options.

Run analysis in GitHub

In GitHub, Qodana is implemented as the Qodana Scan GitHub Action.To configure the Qodana Scan GitHub Action, save the .github/workflows/code_quality.yml file containing the workflow configuration:

                    name: Qodana
                    on:
                      workflow_dispatch:
                      pull_request:
                      push:
                        branches:
                          - main
                          - 'releases/*'

                    jobs:
                      qodana:
                        runs-on: ubuntu-latest
                        steps:
                          - uses: actions/checkout@v3
                            with:
                              fetch-depth: 0
                          - name: 'Qodana Scan'
                            uses: JetBrains/qodana-action@v2022.3.3
                

Using this workflow, Qodana will run on the main branch, release branches, and on the pull requests coming to your repository.

Because Qodana Scan is experimental, you may need to additionally configure the pr-mode parameter in the with section:

pr-mode: false

By default, Qodana Scan uses the experimental mode of the Qodana for .NET linter. If you are experiencing issues with it, you can report an issue in our bug tracker.

To authorize in Qodana Cloud and forward reports to it, follow these steps:

In the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.
In a GitHub workflow, add this snippet to invoke the Qodana Scan action:
- name: 'Qodana Scan' uses: JetBrains/qodana-action@v2022.3.3 env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

Analyze pull requests

You can run incremental analysis on a change set like merge or pull requests.

For example, if you just finished work within a particular commit and would like to analyse the changes, you can employ the --diff-start option:

            qodana scan \
               -e QODANA_TOKEN="<cloud-project-token>" \
               --diff-start=<GIT_START_HASH>
        

            docker run \
               -v $(pwd):/data/project/ \
               -e QODANA_TOKEN="<cloud-project-token>" \
               jetbrains/qodana-dotnet:2024.1 \
               --diff-start=<GIT_START_HASH>
        

To inspect a set of changes between two commits, employ both --diff-start and --diff-end options:

            qodana scan \
               -e QODANA_TOKEN="<cloud-project-token>" \
               --diff-start=<GIT_START_HASH> \
               --diff-end=<GIT_END_HASH>
        

            docker run \
               -v $(pwd):/data/project/ \
               -e QODANA_TOKEN="<cloud-project-token>" \
               jetbrains/qodana-dotnet:2024.1 \
               --diff-start=<GIT_START_HASH> \
               --diff-end=<GIT_END_HASH>
        

Using an existing profile

This section is intended for users familiar with configuring code analysis via Rider inspection profiles.

You can pass the reference to the existing profile by mapping the profile to /data/profile.xml inside the container:

                    docker run \
                       -p 8080:8080 \
                       -v <source-directory>/:/data/project/ \
                       -v <output-directory>/:/data/results/ \
                       -v <inspection-profile.xml>:/data/profile.xml \
                       jetbrains/qodana-dotnet:2024.1 \
                       --show-report
                

You can pass the reference to the existing profile by mapping the profile inside the container:

                        qodana scan \
                           -l jetbrains/qodana-dotnet:2024.1 \
                           --results-dir <output-directory> \
                           --profile-path <path-to-profile> \
                           --show-report
                    

Configure via qodana.yaml

Qodana automatically recognizes the qodana.yaml file for the analysis configuration, so that you don't need to pass any additional parameters. In the qodana.yaml file, you can save ide: QDNET to run Qodana in the native mode.

The references to the inspection profiles will be resolved in a particular order. To learn about the format, see YAML file.

Analyze specific solution or project

By default, Qodana tries to locate and employ a single solution file, or, if no solution file is present, it tries to find a project file. If your project contains multiple solution files, you need to specify the exact filename using the --solution option and a relative path to a solution file. For example, to make Qodana always analyze the MySolution.sln solution file, you can use:

--property=qodana.net.solution=MySolution.sln

Alternatively, you can specify the solution filename in the qodana.yaml file using the solution option and a relative path to a solution file:

            dotnet:
                solution: MySolution.sln
        

If your project contains no solution files and multiple project files, you need to use the --project option and a relative path to a project file. For example, for the MyProject.csproj project file you can use:

--property=qodana.net.project=MyProject.csproj

Alternatively, you can specify the project filename in the qodana.yaml file using the project option:

            dotnet:
                project: MyProject.csproj
        

Configure a solution

A solution configuration defines which projects in the solution to build, and which project configurations to use for specific projects within the solution.

Each newly created solution includes the Debug and Release configurations, which can be complemented by your custom configurations.

You can switch configurations of the current solution using the --property configuration option. For example, use this to switch to the Release configuration:

--property=qodana.net.configuration=Release

Alternatively, you can specify the configuration in qodana.yaml:

                dotnet:
                  configuration: Release
            

By default, the solution platform is set to Any CPU .You can override this using the --property option:

--property=qodana.net.platform=x86

Alternatively, you can specify the platform in qodana.yaml:

                dotnet:
                  platform: x86
            

Inspect projects using private NuGet repositories

Qodana for .NET does not support authentication for private NuGet repositories using, for example, Windows Authentication. To overcome this limitation, you can place all required packages within the Qodana cache as shown below:

In the local filesystem, create the folder that will contain cache. For example, it can be C:/Temp/QodanaCache.
Run Qodana using the --cache-dir C:/Temp/QodanaCache option.
Copy all NuGet packages contained by default in the %userprofile%\.nuget\packages folder to C:/Temp/QodanaCache/nuget. If you have a custom package folder, copy packages from that folder instead of %userprofile%\.nuget\packages.
Run Qodana using the --cache-dir C:/Temp/QodanaCache once more.

Usage statistics

According to the JetBrains EAP user agreement, we can use third-party services to analyze the usage of our features to further improve the user experience. All data will be collected anonymously. You can disable the reporting of usage statistics by adjusting the options of the Docker command you use. Refer to the technical guide for details.

Last modified: 26 April 2024