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 thecsproj
:
<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 typeRS0030
,RS0031
orRS0035
. 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! 🎉🎉
Top comments (0)