Skip to content

Latest commit

 

History

History
121 lines (88 loc) · 9 KB

AddingAnalyzers.md

File metadata and controls

121 lines (88 loc) · 9 KB

Adding analyzers to your project

Selecting which analyzer project/package to use

Lombiq .NET Analyzers is split into multiple projects/packages so you can select the one most suitable for your application. Depending on your use case, select one of the following:

You only need to reference a single project; e.g., even though Orchard Core apps are also .NET apps, you only need to use Lombiq.Analyzers.OrchardCore for them.

How to add the analyzers to SDK-style projects from NuGet

If you don't want to stay on the cutting-edge version, nor do you intend to contribute to Lombiq .NET Analyzers, you can use one of the NuGet packages. Install the package suitable for your project, as described above. Check for the latest version number on NuGet.

<PackageReference Include="Lombiq.Analyzers" Version="<latest version>">
    <PrivateAssets>all</PrivateAssets>
</PackageReference>

The <PrivateAssets>all</PrivateAssets> is necessary to prevent the analyzers "leaking" into other projects that may consume yours.

You can also add the package to all projects inside a folder at once from a Directory.Build.props file.

How to add the analyzers to SDK-style projects from a Git submodule

Use this approach if you always want to use the very latest version, or if you'd like to contribute to Lombiq .NET Analyzers.

  1. Add to the following to the .gitmodules file (we use the tools subfolder for the submodule's folder here but feel free to use something else):

    [submodule "Lombiq.Analyzers"]
    path = tools/Lombiq.Analyzers
    url = https://github.com/Lombiq/.NET-Analyzers.git
    branch = dev

    path can target anything but we suggest either the folder where the solution .sln file is located (mostly the repository root) or a "tools" subfolder therein.

  2. Create a Directory.Build.props file in the folder where the solution .sln file is located (mostly the repository root) with the following content, referencing the analyzer project you selected above (if you've put the submodule into a different folder then change the path):

    <Project>
  <Import Project="tools/Lombiq.Analyzers/Build.props" />
</Project>

  3. Since the project's .editorconfig file will be copied into your solution's root you may want to gitignore it:

    /.editorconfig

For at least Visual Studio and JetBrains Rider you don't need any further setup for IDE support. For OmniSharp-integrated editors like Visual Studio Code you'll also need to add an omnisharp.json file to the root of the solution:

{
    "RoslynExtensionsOptions": {
        "enableAnalyzersSupport": true
    },
    "FormattingOptions": {
        "enableEditorConfigSupport": true
    }
}

How to add the analyzers to individual non-SDK-style .NET Framework projects (not solutions)

The key difference compared to .NET projects is that for non-SDK-style .NET Framework projects, you need to add Lombiq .NET Analyzers to each project.

  1. Same as above - add the .NET-Analyzers repository as a Git submodule to your repository or add the NuGet package in the next step.

  2. Create a Directory.Build.props file in a common root folder of your projects, or in every project folder you want to target, next to the .csproj file with the following content, either referencing Lombiq.Analyzers.NetFx or Lombiq.Analyzers.Orchard1:

    <PackageReference Include="Lombiq.Analyzers.NetFx" Version="<latest version>">
    <PrivateAssets>all</PrivateAssets>
</PackageReference>

    Or if you're using a Git submodule (adjust the relative path as suitable):

    <Project>
  <Import Project="../../../tools/Lombiq.Analyzers.NetFx/Build.props" />
</Project>

    If you do this for multiple projects, it's recommended to add your own central props file (like Analyzers.Build.props) where you do the above and import that in each project instead.

  3. Build.props will copy this project's .editorconfig file into every project folder that you've created a Directory.Build.props in, so you might want to gitignore those:

    .editorconfig

Introducing analyzers to an existing project

What to do if you're not starting a green-field project but want to add analyzers to an existing (large) project?

  1. Fix any existing build warnings. Analyzer violations will be surfaced as warnings so it's best to fix build warnings first.

  2. Enable TreatWarningsAsErrors in CI/CD builds to make sure you don't introduce more warnings. Or alternatively, at least you can enable TreatWarningsAsErrors for all projects so during local build it'll fail on any violation. You can do this from the same Directory.Build.props file by adding the following:

    <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>

  3. .NET compatibility:

    • .NET Core and .NET 5 or later projects can use this without anything special.
    • .NET Framework projects:
      • Projects using the new SDK-style csproj format don't need anything special. You can convert projects manually from the non-SDK-style csproj format or automatically with the try-convert utility. You'll also need to manually remove any leftover packages.config files and adjust NuGet.config files.
      • Projects using the legacy, non-SDK-style csproj format should use Lombiq.Analyzers.NetFx as described above, but the including project needs to use PackageReferences. You can convert your packages.config-based project to PackageReferences using this walkthrough.

  4. Now you can add this project to yours as explained above.

  5. Introduce analyzers gradually unless it's a small project and you can fix every analyzer violation at once. To do this, only enable a handful of analyzers first (or enable them just for a couple of projects in a given solution), fix the violations, get used to them, then enable more later. See the docs on configuring analyzers for how to do disable certain analyzers of the default configuration and thus activating analyzers in your code base gradually. We recommend enabling analyzers and fixing violations in at least three stages:

    1. All the simpler rules, i.e. all rules except the ones in the next steps (that means, if you're working with the default configuration, to disable the rules mentioned in the next steps). These are quite straightforward to fix, to an extent can be done even automatically with individual code fixes and dotnet format. It's the best if you group warnings by code in the Error List and fix them one by one, committing to the repository after completing each. It's better to batch this work in a way that you fix a particular type of warning for all projects of a solution at once, as opposed to fixing multiple type of warnings for just selected projects. This is because it's more efficient to just repeat the same kind of fix for all projects (can sometimes even be done automatically) in one go instead of revisiting it in multiple iterations. For tips on how to make fixing violations easier see this page.
    2. "SA1600 Elements should be documented": This will require adding documentation to all interfaces. This and the next step can also be done individually for specific projects, so just have them enabled for certain projects, since these benefit much less from being done in bulk for the whole solution.
    3. "S107 Methods should not have too many parameters", "S134 Control flow statements "if", "for", "while", "switch" and "try" should not be nested too deeply" and "S3776 Cognitive Complexity of functions should not be too high": These analyzer rules will require deeper refactoring of the code base. They're all worth it though.