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
When running the CLI tool from the command line (and after installing analyzers), the minimum console arguments you need to provide is the path to the project file(s) you want to analyze.
⚠️ If you don't provide the `--analyzers-path` argument, it will default to `packages/analyzers`. If you are using Paket with a group called `analyzers`, this default path should work for you.
18
+
19
+
## Viewing Additional Commands
20
+
21
+
You can view the full list of commands available by running:
In order to configure analyzers for VSCode, you will need to update your project's `.vscode/settings.json` file or your user settings. You should need the settings shown below.
📓 Note: Issue created [here](https://github.com/ionide/FsAutoComplete/issues/1350) regarding analyzers & SDK mismatches in the logs
21
+
22
+
After saving your new settings, make sure to restart VSCode. Once VSCode restarts, you should be able to test and see if the analyzers are working by opening a F# file in your workspace and entering the following code
A dotnet CLI tool, called [fsharp-analyzers](https://github.com/ionide/FSharp.Analyzers.SDK/), is used to run analyzers outside the context of an IDE. Add it to your tool-manifest with:
If you are using Nuget as your package manager, add the `PackageReference` pointing to your favorite analyzers to the `.fsproj` file of the project you want to analyze.
If you are using Paket as your package manager, add the package to your `paket.dependencies` file. The example below uses a paket group, but it is not required.
We assume the analyzers you want to use are distributed as a nuget package.
11
+
The path to the analyzer DLL files could be tricky to get right across a wide range of setups. Luckily, we can use a MSBuild custom target to take care of the path construction. Add [FSharp.Analyzers.Build](https://www.nuget.org/packages/FSharp.Analyzers.Build) to your project. This imports a new target to your project file (`AnalyzeFSharpProject`) and will allow us to easily run the analyzers for our project.
12
12
13
-
##Using analyzers in a single project
13
+
### Installing Target via Nuget
14
14
15
-
### Raw command line
16
-
17
-
A dotnet CLI tool, called [fsharp-analyzers](https://www.nuget.org/packages/fsharp-analyzers), is used to run analyzers outside the context of an IDE.
18
-
Add it to your tool-manifest with:
19
-
```shell
20
-
dotnet tool install fsharp-analyzers
21
-
```
22
-
23
-
Next, add the `PackageReference` pointing to your favorite analyzers to the `.fsproj` file of the project you want to analyze:
15
+
If you are using Nuget, add it to your `.fsproj` file:
At the time of writing, the [G-Research analyzers](https://github.com/g-research/fsharp-analyzers)[package](https://www.nuget.org/packages/G-Research.FSharp.Analyzers) contains the only analyzers compatible with the latest CLI tool.
33
-
With the package downloaded, we can run the CLI tool:
24
+
### Installing Target via Paket
34
25
35
-
```shell
36
-
dotnet fsharp-analyzers --project ./YourProject.fsproj --analyzers-path C:\Users\yourusername\.nuget\packages\g-research.fsharp.analyzers\0.4.0\analyzers\dotnet\fs\ --verbosity d
37
-
```
26
+
If you are using Paket, add it to your `paket.dependencies`
38
27
39
-
### Using an MSBuild target
28
+
```paket
29
+
group analyzers
30
+
source https://api.nuget.org/v3/index.json
40
31
41
-
As you can see, the path to the analyzer DLL files could be tricky to get right across a wide range of setups.
42
-
Luckily, we can use an MSBuild custom target to take care of the path construction.
32
+
nuget FSharp.Analyzers.Build
33
+
```
43
34
44
-
Add [FSharp.Analyzers.Build](https://www.nuget.org/packages/FSharp.Analyzers.Build) to your `fsproj`:
35
+
as well as the `paket.references` of your project:
This imports a new target to your project file: `AnalyzeFSharpProject`.
54
-
And will allow us to easily run the analyzers for our project.
42
+
### Configuring the Build Target
55
43
56
44
Before we can run `dotnet msbuild /t:AnalyzeFSharpProject`, we need to specify our settings in a property called `FSharpAnalyzersOtherFlags`:
57
45
@@ -62,21 +50,25 @@ Before we can run `dotnet msbuild /t:AnalyzeFSharpProject`, we need to specify o
62
50
```
63
51
64
52
To locate the analyzer DLLs in the filesystem, we use the variable `$(PkgG-Research_FSharp_Analyzers)`. It's produced by NuGet and normalized to be usable by [MSBuild](https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#generatepathproperty).
65
-
In general, a `Pkg` prefix is added and dots in the package ID are replaced by underscores. But make sure to look at the [nuget.g.props](https://learn.microsoft.com/en-us/nuget/reference/msbuild-targets#restore-outputs) file in the `obj` folder for the exact string.
53
+
In general, a `Pkg` prefix is added and dots in the package ID are replaced by underscores. But make sure to look at the [nuget.g.props](https://learn.microsoft.com/en-us/nuget/reference/msbuild-targets#restore-outputs) file in the `obj` folder for the exact string.
54
+
66
55
The `/analyzers/dotnet/fs` subpath is a convention analyzer authors should follow when creating their packages.
67
56
57
+
### Running the Build Target
58
+
68
59
At last, you can run the analyzer from the project folder:
69
60
70
61
```shell
71
62
dotnet msbuild /t:AnalyzeFSharpProject
72
63
```
73
64
74
-
Note: if your project has multiple `TargetFrameworks` the tool will be invoked for each target framework.
65
+
📓 Note: If your project has multiple `TargetFrameworks` the tool will be invoked for each target framework.
66
+
67
+
## Using Analyzer Build Target in a Solution
75
68
76
-
## Using analyzers in a solution
69
+
Adding the custom target from above to all `.fsproj` files of a solution doesn't scale very well. We can use the MSBuild infrastructure to add the needed package reference and the MSBuild target to all projects in one go.
77
70
78
-
Adding the custom target from above to all `.fsproj` files of a solution doesn't scale very well.
79
-
So we use the MSBuild infrastructure to add the needed package reference and the MSBuild target to all projects in one go.
71
+
### Setting up Directory.Build.props
80
72
81
73
We start with adding the `PackageReference` pointing to your favorite analyzers to the [Directory.Build.props](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory?view=vs-2022) file.
82
74
This adds the package reference to all `.fsproj` files that are in a subfolder of the file location of `Directory.Build.props`:
@@ -94,8 +86,10 @@ This adds the package reference to all `.fsproj` files that are in a subfolder o
94
86
</ItemGroup>
95
87
```
96
88
97
-
Likewise we add the `FSharpAnalyzersOtherFlags` property to the [Directory.Build.targets](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory?view=vs-2022) file.
98
-
This is effectively the same as adding a property to each `*proj` file which exists in a subfolder.
89
+
### Setting up Directory.Build.targets
90
+
91
+
Likewise we add the `FSharpAnalyzersOtherFlags` property to the [Directory.Build.targets](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory?view=vs-2022) file. For first time MSBuild users, this is effectively the same as adding a property to each `*proj` file which exists in a subfolder.
92
+
99
93
```xml
100
94
<Project>
101
95
<PropertyGroup>
@@ -106,34 +100,49 @@ This is effectively the same as adding a property to each `*proj` file which exi
106
100
</Project>
107
101
```
108
102
109
-
⚠️ We are adding the `FSharpAnalyzersOtherFlags` property to our **Directory.Build.targets** and **not to** any **Directory.Build.props** file!
110
-
MSBuild will first evaluate `Directory.Build.props` which has no access to the generated nuget.g.props. `$(PkgG-Research_FSharp_Analyzers)` won't be known at this point. `Directory.Build.targets` is evaluated after the project file and has access to `Pkg` generated properties.
103
+
⚠️ We are adding the `FSharpAnalyzersOtherFlags` property to our **Directory.Build.targets** and **not to** any **Directory.Build.props** file! MSBuild will first evaluate `Directory.Build.props` which has no access to the generated nuget.g.props. `$(PkgG-Research_FSharp_Analyzers)` won't be known at this point. `Directory.Build.targets` is evaluated after the project file and has access to `Pkg` generated properties.
111
104
112
-
### All projects in the solution
105
+
### Run Target for All Projects in the Solution
113
106
114
107
We can run the `AnalyzeFSharpProject` target against all projects in a solution
As we don't want to target all projects in the solution, we create a second custom MSBuild target that calls the project-specific target for all relevant projects.
115
+
As we may not always want to target every project in a solution, we can create a second custom MSBuild target that calls the project-specific target for all relevant projects.
123
116
Add the following custom target to the [Directory.Solution.targets](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-solution-build?view=vs-2022) file to be able to invoke analysis from all selected projects in one simple command:
Note: we passed the `--code-root` flag so that the `*.sarif` report files will report file paths relative to this root. This can be imported for certain editors to function properly.
144
153
145
-
## MSBuild tips and tricks
154
+
## MSBuild Tips and Tricks
146
155
147
156
MSBuild can be overwhelming for the uninitiated. Here are some tricks we've seen in the wild:
148
157
149
-
### Use well-known properties
158
+
### Use Well-Known Properties
150
159
151
160
Checkout the [MSBuild reserved and well-known properties](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-reserved-and-well-known-properties?view=vs-2022) to use existing variables like `$(MSBuildProjectFile)`.
152
161
153
-
### Wrap path arguments in quotes
162
+
### Wrap Path Arguments in Quotes
154
163
155
164
As MSBuild is all XML, you can use `"` to wrap evaluated values in quotes:
156
165
@@ -160,7 +169,7 @@ As MSBuild is all XML, you can use `"` to wrap evaluated values in quotes:
160
169
</PropertyGroup>
161
170
```
162
171
163
-
### Extend `<FSharpAnalyzersOtherFlags>` in multiple lines
172
+
### Extend `<FSharpAnalyzersOtherFlags>` in Multiple Lines
164
173
165
174
You can extend the value of `$(FSharpAnalyzersOtherFlags)` by setting it again in multiple lines:
166
175
@@ -173,7 +182,7 @@ You can extend the value of `$(FSharpAnalyzersOtherFlags)` by setting it again i
173
182
</PropertyGroup>
174
183
```
175
184
176
-
### Verify parameters are present
185
+
### Verify Parameters are Present
177
186
178
187
It can be a bit confusing to find out if a variable contains the value you think it does.
179
188
We often add a dummy target to a project to print out some values:
@@ -186,4 +195,4 @@ We often add a dummy target to a project to print out some values:
186
195
187
196
Run `dotnet msbuild YourProject.fsproj /t:Dump` and verify that `CodeRoot` has a value or not.
0 commit comments