The dotnet format command and StyleCop.Analyzers

This article shows how to use the dotnet format command to format your source code according to a specific coding style. The article discusses its limitations and how to overcome them by introducing StyleCop.Analyzers. It also mentions the way to apply StyleCop.Analyzers to all projects in a solution.

About dotnet format

The dotnet format command allows bulk formatting of all source code within a project or solution according to a predefined ruleset. The dotnet format command is included by default in the .NET SDK version 6.0 or later.

To determine the formatting rules, the dotnet format reads one or more rulesets from .editorconfig files located in the target project or solution directory, as well as its ancestor folders. If you format your source code according to the C# Coding Style, you can utilize the .editorconfig file found in the .NET Runtime repository.

When using the dotnet format, it is essential to specify the info level severity to the command. Otherwise, the command will ignore most of the rules.

The provided command formats the following code into the next one.

However, the resulting code does not fully comply with the formatting requirements. For example, the method name retains its camelCase format, and the if statement remains on a single line. There are also unnecessary empty lines.

StyleCop.Analyzers

To achieve more disciplined results, we can use StyleCop.Analyzers. StyleCop.Analyzers provides a way to apply the StyleCop ruleset traditionally provided by an extension called StyleCop for Visual Studio.

To format the source code in a project with StyleCop.Analyzers, you just need to add the StyleCop.Analyzers package to the project as follows. Once added, the dotnet format will seamlessly integrate with StyleCop.Analyzers.

When using StyleCop.Analyzers without any additional configuration, it applies the default ruleset, which doesn't follow the C# coding style. To solve this problem, you can download the default ruleset file from the StyleCop.Analyzers repository and customize it.

By incorporating the following diff to the ruleset file, StyleCop.Analyzers will follow the desired style. For your convenience, you can download the applied file from my repository.

When you save the customized ruleset file as stylecop.ruleset in the project directory, you should add the following lines to the project file to specify the name of the ruleset file for StyleCop.Analyzsers.

To format the source code in the project according to the specified ruleset, simply run the command dotnet format --severity info as shown above. Running this command will give you a much better result than the previous formatting.

Directory.Build.props

If you need to format every project in a solution, you must add the StyleCop.Analyzers package to each project individually. Fortunately, there is a more efficient way to simplify this process using the Directory.Build.props file.

If you place Directory.Build.props in the solution folder, MSBuild will automatically import it at the top of each project file. So you can place the following Directory.Build.props file in the solution folder to make Stylecop.Analyzers available in every project.

You should notice that the MSBuildThisFileDirectory variable has the directory where Directory.Build.props is located. By specifying the ruleset file with this variable, projects in directories of any depth can read the ruleset file.

Conclusion

This article showed how to use the dotnet format in conjunction with StyleCop.Analyzers. You can get more disciplined code formatting results with StyleCop.Analyzers compared to using the dotnet format alone.

In addition, this article introduced the functionality of the Directory.Build.props file. It allows you to format the source code in every project in the solution folder with StyleCop.Analyzsers.