StyleCop for .Net 5 Projects: Custom Configuration

With your StyleCop installation in place we can now look at how we can customise our StyleCop configuration.

This is part two of my small series of StyleCop for .Net 5 Projects:

• Part 1: StyleCop for .Net 5 Projects: Installation
• Part 2: StyleCop for .Net 5 Projects: Custom Configuration
• Part 3: StyleCop for .Net 5 Projects: Clean-up

 

Change your code or change the StyleCop rules?

This is the main question you need to answer when it comes to customising StyleCop. It all boils down to these two options for every type of warning and only your team can decide what it wants to do.

To get an overview of all problems in your application do this:

1. Compile your application
2. Go to the Error List
3. Activate warnings
4. Order the Error List by Code

You now have a long list of warnings ordered by a code that we will use in a short time. If you hoover your mouse over the Code column you see that it is a link:

For every StyleCop warning you get a page like this one for SA1208 with a detailed explanation of the problem and a section on how to fix it:

This should allow you to decide if this rule is important for you or not. I suggest you go through the whole list and write down which rules you want to disable. Unfortunately, the two configuration files we needed to install for StyleCop are there for a reason and it is not always obvious in which file you need to make a change.

 

Customise StyleCop.ruleset

The StyleCop.ruleset is an XML file in which you can set the severity of a rule (from None to Error). While you can change the file by hand, it may not be the best way to do it. The main challenge, at least for me, is to find the right section to put in an entry. If the code I want to change is already in the file then it is a quick change. Otherwise I suggest a different way.

In the Solution Explorer of Visual Studio, you can expand the Dependencies node to see the list of installed CodeAnalyzers:

You can expand the Analyzers and get a list of all their rules. For the purpose of this post we focus on the StyleCop.Analyzers and its rules. We can select a rule and set the severity through the context menu:

Visual Studio places the entry you modified in the right section of the StyleCop.ruleset, thanks to the reference we made in the installation part. I find this approach much simpler and less challenging than directly changing the StyleCop.ruleset file.

You can now go through the list of rules you want to disable and do that through Visual Studio. All the things you do not find here are probably in the stylecop.json file.

 

Customise stylecop.json

The configuration file stylecop.json is primarily used to configure code formatting and helps you fine-tune some rules like the one to order the using statements. You should read the explanation on GitHub before you try to make changes. The examples there are well documented and help you to understand what is going on.

I only change two sections in the stylecop.json file. One is the orderingRules in which I like to place my usings outside of the namespace and the other is to use 4 spaces for code indentation:

If you need to start namespaces with lowercase letters you should look at the naming rules and the allowedNamespaceComponents section. That helps you to reduce the unnecessary hints in Visual Studio for your accepted naming exceptions.

 

Check if StyleCop got all your changes

If you now recompile your application you should have less warnings than before. Order them once more by code and go through the list to check that all your customisations are detected by StyleCop.

If not, repeat the above steps to ignore the unwanted rules or fine-tune the rules in stylecop.json. Do not proceed to the next step if there are still warnings for rules you do not care. Otherwise they get cleaned-up nonetheless and will be part of the team rules.

 

Does Git find your changes?

If your changes to the StyleCop configuration files do not show up in Git then you need to update your .gitignore file before you can commit your changes.

 

Next

With our customisations in place it is time to do the work and clean-up our code. It seems to be a straightforward task but there are many challenges that need your attention.