Defining formatting rules in .NET with EditorConfig

Introduction

When working with other people and multiple editors/IDEs, it is common to have different editor settings, losing consistency in formatting styles of the code. For example:

Using tabs/spaces and different sizes of indentation, making your code harder to read;
Using different encoding between files, causing hard to find bugs at runtime (showing invalid characters) and breaking automated tests.

In this post I’ll show how to maintain a standard for everyone who works in the code, no matter the editor used, and in a next post I’ll show how to enforce these (and other) rules on build and in the continuous integration pipeline.

Enter the EditorConfig file

The EditorConfig file is used by editors and IDEs to define editor preferences for the project. Without it, IDEs and editors will use their general configuration, causing divergences in the files edited on them.

Many editors and IDEs support the EditorConfig file by default, and others have plugins to support it. Here are some:

Visual Studio (Built-in);
JetBrains Rider (Built-in);
GitHub (Built-in);
VS Code (Plugin);
Vim (Plugin);
Emacs (Plugin);
Sublime (Plugin);

It has a default name of .editorconfig and is an INI file where sections are filename filters, for instance:

[*.cs] for .cs files;
[scripts/**.js] for javascript files inside the scripts folder and subdirectories;
[{package.json}] for the package.json file only.

More details here

The EditorConfig can be put in any directory and be overridden by EditorConfig files in child directories, but for better visibility, they should be in the same directory as the .NET solution file.

Adding an EditorConfig to your project

To include an EditorConfig to your project, just create a file named .editorconfig in the same directory of your solution file (.sln) with the content below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# Top-most EditorConfig file.
root = true

# Section for C# files
# All rules below apply only to .cs files
[*.cs]

#### Core EditorConfig Options ####

# Indentation and spacing
indent_style = space
indent_size = 4

# New line preferences
end_of_line = crlf
insert_final_newline = false
trim_trailing_whitespace = true

# Charset preference
charset = utf-8

This file set these rules:

root: No editorconfig file in parent directories will be read;
indent_style: Indentation should use space;
indent_size: Indentation should use 4 space characters;
end_of_line: Lines should end with CR+LF characters;
insert_final_newline: Do not automatically insert empty lines at the end of the files;
trim_trailing_whitespace: Empty lines should have no space characters;
charset: Files should be encoded with UTF-8 format.

More details here.

⚠️ GIT can change the line ends to LF on pushes to the repository and change it back to CRLF on checkouts. Then, the end_of_line settings can be safely set to CRLF. GIT for Windows suggests this configuration by default at installation. Details on how to configure are here.
⚠️ UTF-8 with BOM is not required nor recommended, according to the Unicode standard. More here.
ℹ️ In .NET, the EditorConfig file can also be used to define analyzers rules and severities specific to the .NET environment. In a next post, I’ll show how to configure these rules.

Appling the new formatting rules to code

When we change the formatting rules for an existing project, the changes are not applied automatically. We need to manually trigger an auto-format.

Visual Studio

First, we have to include the Format document fixer to a Code Cleanup profile.

1 - Navigate to Analyze > Code Cleanup > Configure Code Cleanup.

2 - Include the Format document fixer for the profile you wish to run on save.

Including the Format document fixer in Code Cleanup profile

3 - On the menu, select Analyze > Code Cleanup > Run Code Cleanup (Yout Profile) on Solution.

⚠️ Visual Studio’s format document doesn’t change the file encoding. You have to use the dotnet-format or another tool for that.

VS Code

VS Code doesn’t have a feature to format all files at once. You have to use the Format Files extension.

1 - Install the Format Files extension.

2 - Navigate to View > Command Palette or press Ctrl+Shift+P.

3 - Select the Start Format Files: Workspace or Start Format Files: From Glob option.

JetBrains Rider

Select Code > Reformat Code or press Ctrl+Alt+Enter.

Format on save

When we create an EditorConfig file, the supported editors will also use the configurations for their auto-format features.

Here I show how to enable the auto-format on file save in some editors.

Format on save in Visual Studio

Visual Studio 2022 doesn’t have a format on save feature, but it can run a Code Cleanup on save. This way we can configure a Code Cleanup profile to run a Format document and use it on save.

ℹ️ For Visual Studio 2019, there is an extension that enables the same feature.

1 - Configure your Code Cleanup profile to run the Format document fixer, as shown in the previous section of this post.

2 - Navigate to Tools > Options > Text Editor > Code Cleanup.

3 - Check the Run Code Cleanup profile on Save option and select the Code Cleanup profile to run on save.

Run Code Cleanup profile on Save

Now Visual Studio will format your files on every save.

Formatting on save

Format on save in VS Code

1 - Navigate to File > Preferences > Settings.

2 - Navigate to Text Editor > Formatting or search for editor.formatOnSave.

Format on save option

3 - Check the Editor: Format On Save option.

Format on save in JetBrains Rider

1 - Navigate to File > Settings > Tools > Actions on Save.

2 - Check the Reformat and Cleanup Code option.

3 - Select the Reformat Code profile.

Reformat and Cleanup Code on save