Skip to content

Commit

Permalink
Reorganize ReadMe.md (#218)
Browse files Browse the repository at this point in the history
  • Loading branch information
@pavel-mikula-sonarsource
pavel-mikula-sonarsource authored May 17, 2024
1 parent 770af29 commit bacf199
Showing 1 changed file with 53 additions and 63 deletions.
116 changes: 53 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Welcome to the SonarQube Roslyn SDK project
# Welcome to the SonarQube Roslyn SDK project

### License
## License

Copyright 2015-2024 SonarSource.

Expand All @@ -12,90 +12,82 @@ Licensed under the [GNU Lesser General Public License, Version 3.0](http://www.g

[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=sonarqube-roslyn-sdk&metric=coverage&token=5bf9d3f65527e95102fd8af7b5226c50dba35d66)](https://sonarcloud.io/dashboard?id=sonarqube-roslyn-sdk)

### Overview
## Overview
This repo contains tools to help integrate Roslyn analyzers with SonarQube so that issues detected by the Roslyn analyzers are reported and managed in SonarQube.
Specifically, the tools will generate a Java SonarQube plugin that registers the rules with SonarQube. The generated plugin works with the [C# plugin](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/languages/csharp/), [VB.NET plugin](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/languages/vb-dotnet/) and the [SonarScanner for .NET](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner-for-dotnet/) to handle executing the analyzer and uploading any issues.
See this [blog post](https://devblogs.microsoft.com/devops/sonarqube-scanner-for-msbuild-v2-0-released-support-for-third-party-roslyn-analyzers/) for more information.

#### Integration with the SonarScanner for .NET
### Integration with the SonarScanner for .NET
The [SonarScanner for .NET](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner-for-dotnet/) will automatically execute your custom rules as part of an analysis build using the configuration you have defined in the Quality Profile. There is no need to manually reference your analyzer NuGet package in the MSBuild projects you want to analyse.

The SonarScanner for .NET can also import issues from Roslyn analyzers that do not have plugins created using this SDK. However, they will be imported as "external issues" and are handled differently in SonarQube. See [External .NET issues](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/importing-external-issues/external-analyzer-reports/#external-dotnet-issues) for more information.

#### Integration with SonarLint for Visual Studio
### Integration with SonarLint for Visual Studio
If you define a Quality Profile that references your custom rules then [SonarLint for Visual Studio](https://github.com/sonarsource/sonarlint-visualstudio) in *Connected Mode* will include those rules in the ruleset it generates.
However, it will **not** automatically configure Visual Studio to execute your custom rules.
If you want your customer rules to be executed inside Visual Studio then you will need reference your analyzer NuGet package from your MSBuild projects, or install your analyzer VSIX on each developer machine.

See the [SonarLint for Visual Studio documentation](https://docs.sonarsource.com/sonarlint/visual-studio/team-features/connected-mode/) for more information on Connected Mode.

### Download latest release
The latest release version is available [here](https://github.com/SonarSource/sonarqube-roslyn-sdk/releases/latest).
## Getting started

### Compatibility
v1.0 of the SDK generates plugins that are compatible with SonarQube v4.5.2 -> v6.7.
1. Download the latest [released version](./releases/latest), or clone and build this repository.

1. Run the generator tool `RoslynSonarQubePluginGenerator.exe` specifying the analyzer NuGet package id
```
RoslynSonarQubePluginGenerator.exe /a:YourAnalyzerNugetPackageId
```

v2.0 generates plugins that are compatible with versions of SonarQube from v6.7 (tested with the latest available version at time of release i.e. v7.3alpha1).
1. Copy the generated `youranalyzernugetpackageid-plugin.1.0.0.jar` into your SonarQube `extensions\plugins` directory.

v3.0 generates plugins that are compatible with versions of SonarQube from v7.9.6 (tested with the latest available version at time of release i.e. v9.1).
1. Restart your SonarQube server.

v3.1 generates plugins that are compatible with versions of SonarQube from v7.9.6 (tested with the latest available version at time of release i.e. v9.7).
1. Add the rules to a Quality Profile in SonarQube.

v4.0 generates plugins that are compatible with versions of SonarQube from v9.9 (tested with the latest available version at time of release i.e. v10.5.1).
1. Configure your SonarQube project to use the new Quality Profile.

If you have an existing plugin that was generated with v1.0 of the SDK and want to use the plugin with SonarQube 7.0 or later, you will need to create a new plugin using v2.0 of the SDK. If you customized the _SQALE.xml_ file for your v1.0 plugin, you will need to move the remediation information to the _rules.xml_ file for the v2.0 plugin.
1. Run an analysis using the [SonarScanner for .NET](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner-for-dotnet/).

#### Changes between v1.0 and v2.0
The full list of changes is contained is available on the [release page](https://github.com/SonarSource/sonarqube-roslyn-sdk/releases/tag/2.0). The main changes are described in more detail below.
You can run `RoslynSonarQubePluginGenerator.exe` without parameters to see all the available command line options.

* in v1.0, it was not possible to customize the _rules.xml_ file, although debt remediation information could be supplied in a separate _sqale.xml_ file. SQALE has been deprecated in SonarQube, and the format of the _rules.xml_ file has been extended to support debt remediation information. As a result, v2.0 of the SDK no longer supports providing a _sqale.xml_ file. Instead, it is now possible to manually edit the _rules.xml_ that describes the rule. This means debt remediation data can be added, and it also means that the rest of the metadata describing the rules can be edited to (e.g. to change the severity or classification or the rules, or to add tags).
* v2.0 is built against Roslyn 2.8.2, so will work against analyzers that use that version of Roslyn or earlier.
* v2.0 uses NuGet v4.7, which supports the TLS1.3 security protocol.
## Compatibility

#### Updating Roslyn
| SDK | Minimal compatible SQ | Tested with SQ |
|-----|-----------------------|----------------|
| 1.0 | 4.5.2 | 6.7 |
| 2.0 | 6.7 | 7.3alpha1 |
| 3.0 | 7.9.6 | 9.1 |
| 3.1 | 7.9.6 | 9.7 |
| 4.0 | 9.9 | 10.5.1 |

The SDK is compatible with analyzer targeting Roslyn from version 1.0.0 up to the version specified in [Directory.Build.props](./Directory.Build.props#L9).
Plugins generated with a specific SDK version will not work with SonarQube versions older than the minimal compatible version. The latest version available for testing at the time of the SDK release is indicated in the *Tested with SQ* column.

If you want to use a newer version of Roslyn, you will need to:
1. update the version in the Directory.Build.props
1. the latest version of Roslyn can be found [here](https://www.nuget.org/packages/Microsoft.CodeAnalysis)
2. rebuild the SDK
3. run the SDK against your analyzer

### Target users
There are two groups of target users:
## Updating compatible Roslyn version

1. Roslyn analyzer authors
- Analyzer authors will be able to use the tools during development to provide additional metadata about their rules (e.g. SonarQube severity, tags, a richer description, ...) and generate the SonarQube plugin. See below for additional notes if you are developing your analyzer and running the SDK against the generated NuGet repeatedly on the same development machine.
The SDK is compatible with analyzer targeting Roslyn from version 1.0.0 up to the version specified in [Directory.Build.props](./Directory.Build.props#L10).

2. Roslyn analyzer users
- If the analyzer author has not provided a SonarQube plugin for their analyzer then users will be able to generate a plugin from an analyzer NuGet package, although they won't be able to provide such rich metadata.
To support a newer version of Roslyn, follow these steps:
1. Find the latest version of Roslyn on [NuGet](https://www.nuget.org/packages/Microsoft.CodeAnalysis).
1. Update the version in the [Directory.Build.props](./Directory.Build.props).
1. Rebuild the SDK.
1. Run the SDK against your analyzer.

### Getting started
## Target users
There are two groups of target users:

#### To generate a SonarQube plugin for an analyzer:
1. Download and install the latest [released version](https://github.com/SonarSource/sonarqube-roslyn-sdk/releases/latest)

Alternatively, if you want to build the SDK locally:
* Clone the repository
* Build the solution *PluginGenerator.sln* in the repository root
1. Roslyn analyzer authors

2. Run the generator tool
* Run the generator tool *RoslynSonarQubePluginGenerator.exe* specifying the analyzer NuGet package id
e.g. *RoslynSonarQubePluginGenerator /a:Wintellect.Analyzers*
Analyzer authors will be able to use the tools during development to provide additional metadata about their rules (e.g. SonarQube severity, tags, a richer description, ...) and generate the SonarQube plugin. See below for additional notes if you are developing your analyzer and running the SDK against the generated NuGet repeatedly on the same development machine.

It is possible to specify an optional package version
e.g. */a:Wintellect.Analyzers:1.0.5.0*
1. Roslyn analyzer users

The tool will create a .jar file named after the package name and version in the current directory
e.g. *wintellectanalyzers-plugin-1.0.5.jar*
You can specify the output directory with the `/o:PathToOutputDir` command line parameter.
If the analyzer author has not provided a SonarQube plugin for their analyzer then users will be able to generate a plugin from an analyzer NuGet package, although they won't be able to provide such rich metadata.

The generated jar can be installed to SonarQube as normal (e.g. by dropping it in the SonarQube server *extensions\plugins* folder and restarting the SonarQube server).
You will see a new repository containing all the rules defined by the analyzer. The rules can be added to Quality Profiles just like any other SonarQube rule.
## Advanced scenarios

#### Customizing the rules.xml file
To customize the _rules.xml_ file, run the generator once against the NuGet package. The generator will produce a template _rules.xml_ for the analyzers found in the package as well as producing the .jar file. Edit the _rules.xml_ file then run the generator tool again, this time providing the _/rules_ parameter to point to the edited _rules.xml_ file.
### Customizing the rules.xml file
To customize the `rules.xml` file, run the generator once against the NuGet package. The generator will produce a template `rules.xml` for the analyzers found in the package as well as producing the .jar file. Edit the `rules.xml` file then run the generator tool again, this time providing the `/rules` parameter to point to the edited `rules.xml` file.

The XML snippet below shows the expected format for tags and debt remediation information.

Expand All @@ -117,26 +109,25 @@ The XML snippet below shows the expected format for tags and debt remediation in
</rules>
```

#### Configuring NuGet feeds
### Configuring NuGet feeds
The SDK will look for NuGet.config files in the following locations:
- in the directory containing *RoslynSonarQubeGenerator.exe*
- %AppData%\NuGet (i.e. the standard pre-user location)
- %ProgramData%\NuGet\Config\SonarQube (a custom machine-wide location
- %ProgramData%\NuGet\Config (i.e. the standard machine-wide location)
- in the directory containing `RoslynSonarQubeGenerator.exe`
- `%AppData%\NuGet` - the standard pre-user location)
- `%ProgramData%\NuGet\Config\SonarQube` - a custom machine-wide location
- `%ProgramData%\NuGet\Config` - the standard machine-wide location

If the analyzer you want to package is available in a private NuGet feed then you will need to create an appropriate NuGet.config file to point to the private feed. Alternatively you can use the `/customnugetrepo:file:///PathToRepo`
parameter. This will overwrite the above mentioned NuGet behaviour.
If the analyzer you want to package is available in a private NuGet feed then you will need to create an appropriate `NuGet.config` file to point to the private feed. Alternatively you can use the `/customnugetrepo:file:///PathToRepo` parameter. This will overwrite the above mentioned NuGet behaviour.

#### Generating a jar for an analyzer that is not available from a NuGet feed
If you want to create a jar for Roslyn analyzer that is not available from a NuGet feed (e.g. an analyzer you have created on your local machine) you can specify a package source that points at a local directory containing the *.nupkg* file created by the standard Roslyn templates. See the [NuGet docs](https://docs.nuget.org/create/hosting-your-own-nuget-feeds) for more information.
### Generating a jar for an analyzer that is not available from a NuGet feed
If you want to create a jar for Roslyn analyzer that is not available from a NuGet feed (e.g. an analyzer you have created on your local machine) you can specify a package source that points at a local directory containing the *.nupkg* file created by the standard Roslyn templates. See the [NuGet docs](https://learn.microsoft.com/en-us/nuget/hosting-packages/overview) for more information.

By default, the [NuGet.config](./RoslynPluginGenerator/NuGet.config#L16) file shipped with the RoslynSonarQubeGenerator has a local package source configured that points to `C:\LocalNugetFeed`.

#### NuGet packaging information
### NuGet packaging information

The SDK uses information from the NuGet package to populate the fields in the generated plugin that affect how the plugin is described in the Update Centre in the SonarQube UI. It is not currently possible to customise these values.

The NuGet package properties are documented [here](http://docs.nuget.org/Create/Nuspec-Reference) and the SonarQube plugin properties are documented [here](https://docs.sonarsource.com/sonarqube/latest/extension-guide/developing-a-plugin/plugin-basics/#advanced-build-properties>).
The NuGet package properties are documented [here](https://learn.microsoft.com/en-us/nuget/reference/nuspec#required-metadata-elements) and the SonarQube plugin properties are documented [here](https://docs.sonarsource.com/sonarqube/latest/extension-guide/developing-a-plugin/plugin-basics/#advanced-build-properties).

The NuGet package properties are mapped to plugin properties as follows:

Expand All @@ -156,7 +147,6 @@ The NuGet package properties are mapped to plugin properties as follows:

\*\* This property is assigned heuristically by the NuGet.org website based on the licenseUrl.


### Additional notes for Roslyn analyzer authors
The SDK caches the NuGet packages it downloads locally under `%temp%\.sonarqube.sdk\.nuget`.

Expand Down

0 comments on commit bacf199

Please sign in to comment.