You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
17
17
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.
18
18
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.
19
19
20
-
####Integration with the SonarScanner for .NET
20
+
### Integration with the SonarScanner for .NET
21
21
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.
22
22
23
23
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.
24
24
25
-
####Integration with SonarLint for Visual Studio
25
+
### Integration with SonarLint for Visual Studio
26
26
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.
27
27
However, it will **not** automatically configure Visual Studio to execute your custom rules.
28
28
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.
29
29
30
30
See the [SonarLint for Visual Studio documentation](https://docs.sonarsource.com/sonarlint/visual-studio/team-features/connected-mode/) for more information on Connected Mode.
31
31
32
-
### Download latest release
33
-
The latest release version is available [here](https://github.com/SonarSource/sonarqube-roslyn-sdk/releases/latest).
32
+
## Getting started
34
33
35
-
### Compatibility
36
-
v1.0 of the SDK generates plugins that are compatible with SonarQube v4.5.2 -> v6.7.
34
+
1. Download the latest [released version](./releases/latest), or clone and build this repository.
35
+
36
+
1. Run the generator tool `RoslynSonarQubePluginGenerator.exe` specifying the analyzer NuGet package id
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).
41
+
1. Copy the generated `youranalyzernugetpackageid-plugin.1.0.0.jar` into your SonarQube `extensions\plugins` directory.
39
42
40
-
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).
43
+
1. Restart your SonarQube server.
41
44
42
-
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).
45
+
1. Add the rules to a Quality Profile in SonarQube.
43
46
44
-
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).
47
+
1. Configure your SonarQube project to use the new Quality Profile.
45
48
46
-
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.
49
+
1. Run an analysis using the [SonarScanner for .NET](https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/scanners/sonarscanner-for-dotnet/).
47
50
48
-
#### Changes between v1.0 and v2.0
49
-
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.
51
+
You can run `RoslynSonarQubePluginGenerator.exe` without parameters to see all the available command line options.
50
52
51
-
* 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).
52
-
* v2.0 is built against Roslyn 2.8.2, so will work against analyzers that use that version of Roslyn or earlier.
53
-
* v2.0 uses NuGet v4.7, which supports the TLS1.3 security protocol.
53
+
## Compatibility
54
54
55
-
#### Updating Roslyn
55
+
| SDK | Minimal compatible SQ | Tested with SQ |
56
+
|-----|-----------------------|----------------|
57
+
| 1.0 | 4.5.2 | 6.7 |
58
+
| 2.0 | 6.7 | 7.3alpha1 |
59
+
| 3.0 | 7.9.6 | 9.1 |
60
+
| 3.1 | 7.9.6 | 9.7 |
61
+
| 4.0 | 9.9 | 10.5.1 |
56
62
57
-
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).
63
+
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.
58
64
59
-
If you want to use a newer version of Roslyn, you will need to:
60
-
1. update the version in the Directory.Build.props
61
-
1. the latest version of Roslyn can be found [here](https://www.nuget.org/packages/Microsoft.CodeAnalysis)
62
-
2. rebuild the SDK
63
-
3. run the SDK against your analyzer
64
65
65
-
### Target users
66
-
There are two groups of target users:
66
+
## Updating compatible Roslyn version
67
67
68
-
1. Roslyn analyzer authors
69
-
- 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.
68
+
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).
70
69
71
-
2. Roslyn analyzer users
72
-
- 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.
70
+
To support a newer version of Roslyn, follow these steps:
71
+
1. Find the latest version of Roslyn on [NuGet](https://www.nuget.org/packages/Microsoft.CodeAnalysis).
72
+
1. Update the version in the [Directory.Build.props](./Directory.Build.props).
73
+
1. Rebuild the SDK.
74
+
1. Run the SDK against your analyzer.
73
75
74
-
### Getting started
76
+
## Target users
77
+
There are two groups of target users:
75
78
76
-
#### To generate a SonarQube plugin for an analyzer:
77
-
1. Download and install the latest [released version](https://github.com/SonarSource/sonarqube-roslyn-sdk/releases/latest)
78
-
79
-
Alternatively, if you want to build the SDK locally:
80
-
* Clone the repository
81
-
* Build the solution *PluginGenerator.sln* in the repository root
79
+
1. Roslyn analyzer authors
82
80
83
-
2. Run the generator tool
84
-
* Run the generator tool *RoslynSonarQubePluginGenerator.exe* specifying the analyzer NuGet package id
85
-
e.g. *RoslynSonarQubePluginGenerator /a:Wintellect.Analyzers*
81
+
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.
86
82
87
-
It is possible to specify an optional package version
88
-
e.g. */a:Wintellect.Analyzers:1.0.5.0*
83
+
1. Roslyn analyzer users
89
84
90
-
The tool will create a .jar file named after the package name and version in the current directory
91
-
e.g. *wintellectanalyzers-plugin-1.0.5.jar*
92
-
You can specify the output directory with the `/o:PathToOutputDir` command line parameter.
85
+
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.
93
86
94
-
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).
95
-
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.
87
+
## Advanced scenarios
96
88
97
-
####Customizing the rules.xml file
98
-
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.
89
+
### Customizing the rules.xml file
90
+
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.
99
91
100
92
The XML snippet below shows the expected format for tags and debt remediation information.
101
93
@@ -117,26 +109,25 @@ The XML snippet below shows the expected format for tags and debt remediation in
117
109
</rules>
118
110
```
119
111
120
-
####Configuring NuGet feeds
112
+
### Configuring NuGet feeds
121
113
The SDK will look for NuGet.config files in the following locations:
122
-
- in the directory containing *RoslynSonarQubeGenerator.exe*
123
-
- %AppData%\NuGet (i.e. the standard pre-user location)
124
-
- %ProgramData%\NuGet\Config\SonarQube (a custom machine-wide location
125
-
- %ProgramData%\NuGet\Config (i.e. the standard machine-wide location)
114
+
- in the directory containing `RoslynSonarQubeGenerator.exe`
115
+
-`%AppData%\NuGet` - the standard pre-user location)
116
+
-`%ProgramData%\NuGet\Config\SonarQube` - a custom machine-wide location
117
+
-`%ProgramData%\NuGet\Config` - the standard machine-wide location
126
118
127
-
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`
128
-
parameter. This will overwrite the above mentioned NuGet behaviour.
119
+
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.
129
120
130
-
####Generating a jar for an analyzer that is not available from a NuGet feed
131
-
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.
121
+
### Generating a jar for an analyzer that is not available from a NuGet feed
122
+
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.
132
123
133
124
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`.
134
125
135
-
####NuGet packaging information
126
+
### NuGet packaging information
136
127
137
128
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.
138
129
139
-
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>).
130
+
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).
140
131
141
132
The NuGet package properties are mapped to plugin properties as follows:
142
133
@@ -156,7 +147,6 @@ The NuGet package properties are mapped to plugin properties as follows:
156
147
157
148
\*\* This property is assigned heuristically by the NuGet.org website based on the licenseUrl.
158
149
159
-
160
150
### Additional notes for Roslyn analyzer authors
161
151
The SDK caches the NuGet packages it downloads locally under `%temp%\.sonarqube.sdk\.nuget`.
0 commit comments