# Using the scanner

{% hint style="warning" %}
The SonarScanner for .NET version 9.2 [has been deprecated](https://github.com/SonarSource/sonar-scanner-msbuild/releases/tag/9.2.0.110275) and should not be used.
{% endhint %}

## Use <a href="#use" id="use"></a>

{% hint style="info" %}
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`
{% endhint %}

There are two versions of the SonarScanner for .NET. In the following commands, you need to pass an authentication token using the `sonar.token` property. To manage your tokens, see:

* From the Team plan: [scoped-organization-tokens](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/administering-sonarcloud/managing-organization/scoped-organization-tokens "mention").
* With the Free plan: [managing-tokens](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/managing-your-account/managing-tokens "mention").

Any project file accepted by MSBuild.exe or dotnet can be used, for example *.sln*, *.proj*, *.csproj*, or *.vbproj*.

### "Classic" .NET Framework invocation <a href="#classic-net-framework-invocation" id="classic-net-framework-invocation"></a>

The first version is based on the "classic" .NET Framework. To use it, execute the following commands from the root folder of your project:

```bash
SonarScanner.MSBuild.exe begin /k:project-key /o:<organization> /d:sonar.token=<token>  
MSBuild.exe <path to solution.sln> /t:Rebuild
SonarScanner.MSBuild.exe end /d:sonar.token=<token>
```

{% hint style="success" %}
Add `/d:sonar.region=us` to the begin step each time you want to connect to an organization in the US region. See the instructions about establishing your [#server-connection](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analysis-parameters/parameters-not-settable-in-ui#server-connection "mention") for more details.
{% endhint %}

### .NET Core and .NET Core Global Tool invocation <a href="#net-core-and-net-core-global-tool-invocation" id="net-core-and-net-core-global-tool-invocation"></a>

The second version is based on .NET Core which has a very similar usage:

```bash
dotnet <path to SonarScanner.MSBuild.dll> begin /k:project-key /o:<organization> /d:sonar.token=<token>
dotnet build <path to solution.sln> --no-incremental
dotnet <path to SonarScanner.MSBuild.dll> end /d:sonar.token=<token>
```

{% hint style="success" %}
Add `/d:sonar.region=us` to the begin step each time you want to connect to an organization in the US region. See the instructions about establishing your [#server-connection](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analysis-parameters/parameters-not-settable-in-ui#server-connection "mention") for more details.
{% endhint %}

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:

```bash
dotnet tool install --global dotnet-sonarscanner
dotnet sonarscanner begin /k:project-key /o:<organization> /d:sonar.token=<token>
dotnet build <path to solution.sln> --no-incremental
dotnet sonarscanner end /d:sonar.token=<token>
```

{% hint style="success" %}
Add `/d:sonar.region=us` to the begin step each time you want to connect to an organization in the US region. See the instructions about establishing your [#server-connection](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analysis-parameters/parameters-not-settable-in-ui#server-connection "mention") for more details.
{% endhint %}

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.

## Passing properties to the SonarScanner <a href="#passing-properties" id="passing-properties"></a>

When passing properties (like `sonar.verbose=true`) to the SonarScanner for .NET, the prefix required for the property name depends on how you are invoking the scanner.

If you are calling the `begin` command directly, you need the `/d:` prefix, for example `/d:sonar.verbose=true`. However, if you are using a higher-level tool such as an Azure DevOps task like `SonarCloudPrepare@X`, the task acts as a layer that invokes the scanner on your behalf. In this case, pass properties "bare" (without any prefix) to the task's dedicated parameter, for example in the `extraProperties` parameter of the ADO task. For other SonarScanners (not the SonarScanner for .NET), the `-D` prefix is generally used when passing properties directly.

Both `-` and `/` are valid separators and can be used interchangeably. For example, `/d:sonar.verbose=true` and `-d:sonar.verbose=true` are equivalent.

### Shorthand prefixes

The shorthand prefixes are designed to follow common CLI conventions and are not OS-dependent when using the SonarScanner for .NET:

| Prefix | Stands for      | Notes                                                                   |
| ------ | --------------- | ----------------------------------------------------------------------- |
| `/k:`  | Project key     | One of the three primary project coordinates in SonarQube               |
| `/n:`  | Project name    | One of the three primary project coordinates in SonarQube               |
| `/v:`  | Project version | One of the three primary project coordinates in SonarQube               |
| `/o:`  | Organization    | SonarQube Cloud only; not used with SonarQube Server or Community Build |
| `/s:`  | Settings file   | Overrides the default `SonarQube.Analysis.xml`                          |
| `/d:`  | Define property | Passes any `sonar.xxx` property that has no dedicated shorthand         |

## Analysis steps <a href="#analysis-steps" id="analysis-steps"></a>

The construction of your pipeline will be slightly different according to your DevOps platform integration. Please see the appropriate pages for your platform:

{% tabs %}
{% tab title="GITHUB" %}
See the [github](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/getting-started/github "mention") page.
{% endtab %}

{% tab title="BITBUCKET CLOUD" %}
See the [bitbucket-cloud](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/getting-started/bitbucket-cloud "mention") page.
{% endtab %}

{% tab title="GITLAB" %}
See the [gitlab](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/getting-started/gitlab "mention") page.
{% endtab %}

{% tab title="AZURE DEVOPS" %}
See the [azure-devops](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/getting-started/azure-devops "mention") page.
{% endtab %}
{% endtabs %}

### Begin <a href="#begin" id="begin"></a>

The `begin` step is executed when you add the `begin` command-line argument. It hooks into the build pipeline, downloads SonarQube Cloud 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 Cloud.
* `/n:<project name>`
  * **\[optional]** Specifies the name of the analyzed project in SonarQube Cloud.
  * Adding this argument will overwrite the project name in SonarQube Cloud if it already exists.
* `/v:<version>`
  * **\[recommended]** Specifies the version of your project.
* `/o:<organization>`
  * **\[required]** Specifies the name of the target organization in SonarQube Cloud.
* `/d:sonar.token=<token>`
  * **\[required]** Specifies the authentication token be used to authenticate with to SonarQube Cloud.
    * This property replaces `sonar.login` and `sonar.password` properties which are deprecated.
  * If this argument is added to the begin step, it must also be added to the end step.
* `/d:sonar.region=us`
  * **\[optional]** If you use the US instance, you must set the `sonar.region` property to `us` on the CI/CD host. More detail is available in the [#server-connection](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analysis-parameters/parameters-not-settable-in-ui#server-connection "mention") article.
  * Do not use if you are connecting to an organization in the EU region.
* `/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 Cloud analysis parameter, 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-analysis](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analyzing-source-code/scanners/configuring#multi-language-analysis "mention") 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
* `/d:sonar.cs.analyzeRazorCode=<value>`
  * **\[optional]** If set to "true", .razor and .cshtml files will be fully analyzed, this may increase the analysis time. If set to "false", .cshtml files will be analyzed for taint vulnerabilities only.
  * **Caution**: Defining this in your begin step overrides the value set in SonarQube (Server, Cloud).
* `/d:sonar.scanner.useSonarScannerCLI=true`
  * **\[optional]** If set to `true`, the [sonarscanner-cli](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analyzing-source-code/scanners/sonarscanner-cli "mention") will be used in the end step. Without this parameter, the end step will use the scanner engine downloaded from SonarQube Cloud. Use this setting if you encounter failures in the end step or incomplete analysis results with the SonarScanner for .NET version 10.4 or higher.

**Default**: true

For detailed information about all available parameters, see the [analysis-parameters](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analyzing-source-code/analysis-parameters "mention") page.

{% hint style="warning" %}
The "begin" step will modify your build like this:

* the active `CodeAnalysisRuleSet` will be updated to match the SonarQube Cloud quality profile
* `WarningsAsErrors` will be turned off

If your build process cannot tolerate these changes we recommend creating a second build job for SonarQube Cloud analysis.
{% endhint %}

### Build <a href="#build" id="build"></a>

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 the [dotnet-test-coverage](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analyzing-source-code/test-coverage/dotnet-test-coverage "mention") page for more information.

The rules configured in your quality profile are run during the build, and it is expected that analyzing with SonarQube Cloud 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 expected impact and precision. See the [understanding-quality-profiles](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/standards/managing-quality-profiles/understanding-quality-profiles "mention") page for information about managing those rules.

### End <a href="#end" id="end"></a>

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 Cloud. There are only two additional arguments that are allowed for the end step.

**End step command line parameters:**

* `/d:sonar.token=<token>`
  * If this argument is added to the Begin step, it must also be added to the End step.

{% hint style="success" %}
Because most values that are required in both the begin and end steps are *persisted on disk* *between those steps*, they typically don’t need to be supplied twice. But secrets are an exception...

Parameters such as secrets, must be added to the [#end](#end "mention") step if they are included in the [#begin](#begin "mention") step (for example `sonar.token`).

*Passwords and tokens must not be persisted to disk*, therefore they won’t be available when the end step runs. Provide them again in the End step to ensure they are available without being stored.
{% endhint %}

### Known limitations <a href="#known-limitations" id="known-limitations"></a>

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

## Related pages <a href="#related-pages" id="related-pages"></a>

* [introduction](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analyzing-source-code/scanners/sonarscanner-for-dotnet/introduction "mention")
* [installing](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/analyzing-source-code/scanners/sonarscanner-for-dotnet/installing "mention")
* [getting-started-in-us-region](https://docs.sonarsource.com/sonarqube-cloud/~/changes/1027/getting-started/getting-started-in-us-region "mention")