Improving your code for style, quality, maintainability, design... with Roslyn Analyzers

Roslyn Analyzers analyze your code for style, quality and maintainability, design and other issues.

I stumbled upon Roslyn Analyzers while contributing to an issue to the Microsoft Bicep repository, where I found a BannedSymbols.txt file where it appeared that System.Console.Write and System.Console.WriteLine where being targeted and pointing to not use them for logging purposes.

That triggered my interest, as I tried to put a simple Console.WriteLine statement and an alert similar as the image above appeared in Visual Studio.

I thought that these kind of "custom rules" combined with the csproj TreatWarningsAsErrors option (<TreatWarningsAsErrors>true</TreatWarningsAsErrors>) could be a very great solution to maintain dotnet projects code quality, maintainability, design and style in a nice way. In my opinion, more useful and necessary in OSS projects or projects with lots of people working on it.

Using BannedApiAnalyzers in a dotnet project

Using BannedApiAnalyzers in a dotnet project is easy:

• First of all, install the Microsoft.CodeAnalysis.BannedApiAnalyzers NuGet in the project you want to use this feature.

• Place a BannedSymbols.txt file in the project and mark to include it in the project. For example modifying the csproj:
  

<ItemGroup>
  <AdditionalFiles Include="BannedSymbols.txt" />
</ItemGroup>

Or with Visual Studio, specifying the file properties:

• Include your own custom rules to ban a symbol with the following format (description text is optional and will be displayed as description in diagnostics):

{Documentation Comment ID string for the symbol}[;Description Text]

• That's all! The fields in the BannedSymbols.txt file will be processed and mark as warnings the use of the specified banned symbols. These warnings are of type RS0030, RS0031 or RS0035. More info can be found in the roslyn analyzers repo.

Take into account that we could use a BannedSymbols.txt file per project or a Solution wide one, including the same BannedSymbols.txt file in all projects.

How to specify the rules

As explained above, the entries in BannedSymbols.txt must have the following format:

{Documentation Comment ID string for the symbol}[;Description Text]

For details on the ID string format, they recommend to take a look at "Documentation Comments" docs.

Nevertheless, we have a awesome example in the "How to use Microsoft.CodeAnalysis.BannedApiAnalyzers" docs.

Taking this example, considering the following code:

namespace N
{
    class BannedType
    {
        public BannedType() {}

        public int BannedMethod() {}

        public void BannedMethod(int i) {}

        public void BannedMethod<T>(T t) {}

        public void BannedMethod<T>(Func<T> f) {}

        public string BannedField;

        public string BannedProperty { get; }

        public event EventHandler BannedEvent;
    }

    class BannedType<T>
    {
    }
}

We can ban different symbols regarding the code above, taking a look to the following table:

Symbol in Source	Sample Entry in BannedSymbols.txt
class BannedType	T:N.BannedType;Don't use BannedType
class BannedType	T:N.BannedType`1;Don't use BannedType
BannedType()	M:N.BannedType.#ctor
int BannedMethod()	M:N.BannedType.BannedMethod
void BannedMethod(int i)	M:N.BannedType.BannedMethod(System.Int32);Don't use BannedMethod
void BannedMethod(T t)	M:N.BannedType.BannedMethod1(`0)
void BannedMethod(Func f)	M:N.BannedType.BannedMethod1(System.Func{`0})
string BannedField	F:N.BannedType.BannedField
string BannedProperty { get; }	P:N.BannedType.BannedProperty
event EventHandler BannedEvent;	E:N.BannedType.BannedEvent

One of the main caveats which I found when using this feature and banning symbols was the use of wildcards... For example if you want to ban all System.Console.Write methods in a project, you must specify all variants of the methods, as you can see in the Project Bicep example.

I made a demo project where I played around in a project with these banning tools, so you can watch how to use them and you can try things:

piraces / BannedApiAnalyzersDemo

A basic demo on how to use BannedApiAnalyzers in a .NET Core project

How this work when working with IDEs or without them

In Visual Studio, this analyzer works out-of-the-box, as you can see in the following image:

And if we enable the TreatWarningsAsErrors option:

Regarding other IDEs, JetBrains Rider also works out-of-the-box with this analyzer:

Regardless of the IDE, the dotnet CLI will show the warnings (or errors) when building or running the project, which is also awesome:

More on Roslyn Analyzers

Microsoft created a set of analyzers called Microsoft.CodeAnalysis.FxCopAnalyzers (which is now deprecated) that contains the most important "FxCop" rules from static code analysis, converted to Roslyn analyzers. These analyzers check your code for security, performance, and design issues, among others. Check out how to use them.

These analyzers have been consolidated in different packages.

The BannedApiAnalyzers is one of them, but there are others also as useful as this one:

• Microsoft.CodeAnalysis.NetAnalyzers: Included by default for .NET 5+. For earlier targets see this.

• Microsoft.CodeAnalysis.PublicApiAnalyzers: Helps library authors monitor changes to their public APIs (more info).

Check out the Roslyn Analyzers repository for more information.

Conclusion

I found this analyzer very useful and I personally will make use of it in my projects to improve the code quality and maintainability.

I think Roslyn analyzers are very powerful and can provide very useful features in our dotnet projects. It is worth trying it out in my opinion.

What do you think?

Happy coding! 🎉🎉