Audacia.CodeAnalysis 2.0.0

Audacia.CodeAnalysis

The Audacia.CodeAnalysis repository contains .NET analyzers and rulesets to provide checks on Audacia's coding standards.

Getting started

There are five analyzer packages available:

• A standard package
• A package with extra analyzers specifically for ASP.NET Core projects
• A package with extra analyzers specifically for Entity Framework Core projects
• A package with analyzer rulesets configured specifically for code libraries.
• A package with analyzer rulesets configured specifically for test projects.

Which one you install depends on the type of project you're working on.

Installing any one of these packages will automatically configure your compiler and IDE workspace with the analyzer rulesets designed for that type of project (via packaged .globalconfig files). It is still possible to override any of the rules by adding your own .editorconfig file. These are typically located at the root of your repo, but can be located anywhere within the folder hierarchy where the file closest to a particular code file being used. See here for more information.

If you have an Entity Framework or Entity Framework Core project, then you may want to add additional suppressions:

• Migrations can be ignored by the analyzer as it is code generated by Entity Framework; this .editorconfig can be added to the Migrations folder to prevent code being analyzed.
• Some rules do not apply to Entity Framework model configuration code; this .editorconfig can be added to the appropriate folder to suppress these rules.

Finally, clean and rebuild your solution (it may take a while first time round). You will probably notice a lot of inspection warnings that were not present before.

.NET Framework Projects

When installing the Audacia.CodeAnalysis NuGet package in .NET Framework projects you may need to do using package manager console with the -IncludePreRelease argument specified explicitly. This is because some of the analyzers referenced are pre-release packages and .NET Framework seems to need you to opt-in to such packages.

IDE Support

You must be using Visual Studio version 17.0+ (Visual Studio 2022) or Rider version 2021.3.2+.

Including Microsoft Code Style Rules in Build

By default, Microsoft's code style rules (prefixed IDE) don't get run during a build: they just run in the IDE itself. To include these code style rules in a build you must add the following to your .csproj file:

<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>

Excluding Generated Code

It's usually a good idea to exclude generated code from analysis, as you may not have control over the code generation process which can lead to unresolvable violations.

If generated code is all located in a particular directory, you can place an .editorconfig file in the root of that directory and it will exclude all source code files from analysis.

The .editorconfig file should look something like this:

# EF Migration Rules
# Description: Ruleset to disable all analysis on EF Migration classes

# Code files
[*.cs]

generated_code = true

Configuring Warnings As Errors

Add the following to your project's .csproj file to make the compiler treat warnings as errors, and stop compilation when a warning is raised:

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

You can configure treating warnings as errors for specific warnings as follows:

<WarningsAsErrors>ACL1005,CS0168</WarningsAsErrors>
<WarningsNotAsErrors>ACL1006,CS0167</WarningsNotAsErrors>

To see warnings as errors for a single compilation without changing your .csproj, pass in the --warnaserror to dotnet build.

More Information on Analyzers

The analyzers used come from a variety of sources.

Audacia Custom Analyzers

Audacia has a set of custom analyzers. See here for more information.

All rules are prefixed ACL.

CSharpGuidelinesAnalyzer

The CSharpGuidelinesAnalyzer implements analyzers for the C# guidelines (found here) that, for a long time have been the basis of Audacia's C# coding standards.

All rules are prefixed AV.

Roslynator

The Roslynator project is a large collection of analyzers covering most areas of C# code.

All rules are prefixed RCS.

Microsoft Analyzers

Microsoft provide a number of analyzers for checking best practice C# and .NET usage. There are quality rules and style rules. The Roslyn analyzers GitHub repo has more information.

Code quality rules are prefixed CA and code style rules are prefixed IDE.

StyleCop

StyleCop provides analyzers for checking formatting, naming, layout and other related areas.

All rules are prefixed SA.

ReflectionAnalyzers

ReflectionAnalyzers provides analyzers for checking correct usage of reflection in C# code.

All rules are prefixed REFL.

** Note the ReflectionAnalyzers package has been temporarily removed from Audacia.CodeAnalysis as the release of Visual Studio 2022 (with the latest version of Roslyn) has caused errors when loading the analyzers. This is being tracked by this GitHub issue and the package will be re-added when the issue is resolved. **

IDisposableAnalyzers

IDisposableAnalyzers provides analyzers for checking correct usage of IDisposable in C# code.

All rules are prefixed IDISP.

DocumentationAnalyzers

DocumentationAnalyzers provides analyzers for checking correct usage in documentation.

All rules are prefixed with DOC.

Entity Framework Core Analyzers

Microsoft.EntityFrameworkCore.Analyzers provides C# analyzers for Entity Framework Core.

All rules are prefixed EF.

Threading Analyzers

Microsoft.VisualStudio.Threading.Analyzers provides analyzers for potential issues regarding threading and async coding.

All rules are prefixed with VSTHRD.

Contributing

We welcome contributions! Please feel free to check our Contribution Guidelines for feature requests, issue reporting and guidelines.

Updating the analyzers to support a new C# version

If any of the dependent analyzer packages are being upgraded to reference a newer version of Microsoft.CodeAnalysis.CSharp.Workspaces that results in a new minimum supported C# version (as per the official Roslyn NuGet-packages.md), the major version of Audacia.CodeAnalysis must be incremented.

The description in the .csproj must be updated to include the minimum version of C#/.NET that is supported.

e.g

    <PropertyGroup>
        <Description>This package supports C# 12 and .NET 8 as a minimum.</Description>
    </PropertyGroup>