Code Style Configuration in the VS2017 RC Update

Kasey

December 15th, 2016

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