Visual Studio 2017 RC introduced code style enforcement and EditorConfig support. We are excited to announce that the update includes more code style rules and allows developers to configure code style via EditorConfig.

What is EditorConfig?

EditorConfig is an open source file format that helps developers configure and enforce formatting and code style conventions to achieve consistent, more readable codebases. EditorConfig files are easily checked into source control and are applied at repository and project levels. EditorConfig conventions override their equivalents in your personal settings, such that the conventions of the codebase take precedence over the individual developer.

The simplicity and universality of EditorConfig make it an attractive choice for team-based code style settings in Visual Studio (and beyond!). We’re excited to work with the EditorConfig community to add support in Visual Studio and extend their format to include .NET code style settings.

EditorConfig with .NET Code Style

In VS2017 RC, developers could globally configure their personal preferences for code style in Visual Studio via Tools>Options. In the update, you can now configure your coding conventions in an EditorConfig file and have any rule violations get caught live in the editor as you type. This means that now, no matter what side you’re on in The Code Style Debate, you can choose what conventions you feel are best for any portion of your codebase—whether it be a whole solution or just a legacy section that you don’t want to change the conventions for—and enforce your conventions live in the editor. To demonstrate the ins-and-outs of this feature, let’s walk through how we updated the Roslyn repo to use EditorConfig.

Getting Started

The Roslyn repo by-and-large uses the style outlined in the .NET Foundation Coding Guidelines. Configuring these rules inside an EditorConfig file will allow developers to catch their coding convention violations as they type rather than in the code review process.

To define code style and formatting settings for an entire repo, simply add an .editorconfig file in your top-level directory. To establish these rules as the “root” settings, add the following to your .editorconfig (you can do this in your editor/IDE of choice):

EditorConfig settings are applied from the top-down with overrides, meaning you describe a broad policy at the top and override it further down in your directory-tree as needed. In the Roslyn repo, the files in the Compilers directory do not use var, so we can just create another EditorConfig file that contains different settings for the var preferences and these rules will only be enforced on the files in the directory. Note that when we create this EditorConfig file in the Compiler directory, we do not want to add root = true (this allows us to inherit the rules from a parent directory, or in this case, the top-level Roslyn directory).

Code Formatting Rules

Now that we have our EditorConfig files in our directories, we can start to define some rules. There are seven formatting rules that are commonly supported via EditorConfig in editors and IDEs: indent_style, indent_size, tab_width, end_of_line, charset, trim_trailing_whitespace, and insert_final_newline. As of VS2017 RC, only the first five formatting rules are supported. To add a formatting rule, specify the type(s) of files you want the rule to apply to and then define your rules, for example:

Code Style Rules

After reaching out to the EditorConfig community, we’ve extended the file format to support .NET code style. We have also expanded the set of coding conventions that can be configured and enforced to include rules such as preferring collection initializers , expression-bodied members, C#7 pattern matching over cast and null checks, and many more!

Let’s walk through an example of how coding conventions can be defined:

The left side is the name of the rule, in this case “csharp_style_var_for_built_in_types”. The right side indicates the rule settings: preference and enforcement level, respectively.

• A preference setting can be either true (meaning, “prefer this rule”) or false (meaning, “do not prefer this rule”).
• The enforcement level is the same for all Roslyn-based code analysis and can be, from least severe to most severe: none, suggestion, warning, or error.

Ultimately, your build will break if you violate a rule that is enforced at the error severity level (however, this is not yet supported in the RC). To see all code style rules available in the VS2017 RC update and the final Roslyn code style rules, see the Roslyn .editorconfig or check out our documentation.

If you need a refresher on the different severity levels and what they do, see below:

Pro-tip: The gray dots that indicate a suggestion are rather drab. To spice up your life, try changing them to a pleasant pink. To do so, go to Tools>Options>Environment>Fonts and Colors>Suggestion ellipses (…) and give the setting the following custom color (R:255, G:136, B:196):

Experience in Visual Studio

When you add an EditorConfig file to an existing repo or project, the files are not automatically cleaned up to conform to your conventions. You must also close and reopen­ any open files you have when you add or edit the EditorConfig file to have the new settings apply. To make an entire document adhere to code formatting rules defined in your settings, you can use Format Document (Ctrl+K,D). This one-click cleanup does not exist yet for code style, but you can use the Quick Actions menu (Ctrl+.) to apply a code style fix to all occurrences in your document/project/solution.

Pro Tip: To verify that your document is using spaces vs tabs, enable Edit>Advanced>View White Space.

How do you know if an EditorConfig file is applied to your document? You should be able to look at the bottom status bar of Visual Studio and see this message:

Note that this means EditorConfig files override any code style settings you have configured in Tools>Options.

Conclusion

Visual Studio 2017 RC is just a stepping stone in the coding convention configuration and enforcement experience. To read more about EditorConfig support in Visual Studio 2017, check out our documentation. Download the VS2017 RC with the update to test out .NET code style in EditorConfig and let us know what you think!

Over ‘n’ out,

Kasey Uhlenhuth, Program Manager, .NET Managed Languages

Known Issues

• Code style configuration and enforcement only works inside the Visual Studio 2017 RC update at this time. Once we make all the code style rules into a separate NuGet package, you will be able to enforce these rules in your CI systems as well as have rules that are enforced as errors break your build if violated.
• You must close and reopen any open files to have EditorConfig settings apply once it is added or edited.
• Only indent_style, indent_size, tab_width, end_of_line, and charset are supported code formatting rules in Visual Studio 2017 RC.
• IntelliSense and syntax highlighting are “in-progress” for EditorConfig files in Visual Studio right now. In the meantime, you can use MadsK’s VS extension for this support.
• Visual Basic-specific rules are not currently supported in EditorConfig beyond the ones that are covered by the dotnet_style_* group.
• Custom naming convention support is not yet supported with EditorConfig, but you can still use the rules available in Tools>Options>Text Editor>C#>Code Style>Naming. View our progress on this feature on the Roslyn repo.
• There is no way to make a document adhere to all code style rules with a one-click cleanup (yet!).