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).

Figure 1. Rules defined in the top-most EditorConfig file will apply to all projects in the “src” directory except for the rules that are overridden by the EditorConfig file in “src/Compilers”.
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.

Figure 2. Rules set in EditorConfig files apply to generated code and code fixes can be applied to all occurrences in the document, project, or 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
, andcharset
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!).
As I introduce new people to this ecosystem I find myself often saying “this will be fixed in 2017.” Maybe MSFT has in the past, but from my personal perspective _this_ is finally the time when you all have started making tools that I feel are designed for me first and not designed for Microsoft first. I really appreciate your interaction with the community, listening to us seriously too, and hope things only get better from here.
MSFT has definitely gotten better in this regard. Actually they have been quite excellent, the Visual Studio team, especially. Very happy with MSFT these days especially compared with a year or so ago.
As long as I can teach VS to finally stop defaulting to the obscure Allman-style formatting, I’ll be in heaven! I mean, really, who ever thought that Allman-style was a good idea?!? MSFT, you learned to be open, now learn to be cool. K&R all the way! 🙂
You can also do this in 2017 RC, just add this to you editorconfig file:
csharp_new_line_before_open_brace = none
So if you use the “Reset all settings” option, you’ll keep the options that were set in the editorconfig file?
Aye aye. It’s time to finally fix this for the whole .NET ecosystem.
MS, can you please take a stance, eliminate this as a default, and start updating your sample docs / examples EVERYWHERE, as a COMPANY, to leave this legacy style behind?
Let’s drop the baggage and embrace the bright future guys. BIG. THANKS.
Well, some think the same way of the K&R, it’s much easier for readability to use Allman-style when there is multiple levels of stuff, having the opening brace in the end of the line makes it difficult to spot at quick glance which codeblock ends where. But it’s yet again matter of taste, people can argue until the sky falls without finding agreement of this.
Jani – agree wholeheartedly!!
K&R does nothing for readability – sometimes, newer isn’t ‘better’.
Steve Bjorg – sorry, but what’s ‘obscure’ about Allman-style?
I’m really not bothered what ‘style’ is the latest fashion so long as it makes code easier to comprehend at first (or second?) glance. Rather than impose K&R on everyone, just use a preference setting in the IDE?
Choice is a great thing… 🙂
How does this work with Rosyln Analyzers, eg. https://github.com/DotNetAnalyzers/StyleCopAnalyzers? Will they interfere with each other? Should we give up on the Rosyln Analyzers and just use this instead?
You could use stylecop instead and not enable these features for projects if you would like. You could also configure stylecop or editor-config to work cooperatively. You could also rely on this instead of using stylecop, whatever you are into. Worst case there may be conflicting rules but since configurations for both tools can be versioned you can sort that our and share the changes with your co-workers.
Sure, we could make it work – I guess I want to know what are the advantages/disadvantages of each. Is one more powerful than the other? What is the scope of each? Eg. Roslyn ones you can create anything yourself, but the others are all in built and can’t be changed by users?
code style is basically built in roslyn analyzers.
Appears EditorConfig link is broken under What is EditorConfig?
@shaggygi — thanks, should be fixed now!
@shaggygi — thanks, should be fixed now!
Thanks for finally writing about >Code Style Configuration in the VS2017 RC Update |
.NET Blog <Liked it!
I hope trim_trailing_whitespace gets implemented by RTM; it’s one of those features that I frequently wish VS2015 had – especially when I noticed the extra space after committing.
It would be great to see some innovation in this area, making it so that developers can hold onto their individual formatting preferences, while the repo/project still maintains its own. Ultimately, style is a subjective matter and this should not be enforced upon others.
The idea is that code should be seen as a “view” of a universal format, of which StyleCop would be a good foundation.
Using some ingenuity, it is/would be possible for an individual developer to code in tabs and vars, but what gets checked into source control is spaces and types.
Please take a second and vote for this idea here:
https://visualstudio.uservoice.com/forums/121579-visual-studio/suggestions/10020390-enable-roslyn-powered-code-views
Thank you for any consideration and support. 🙂
I was really hoping based on the title that it was about what you propose here, would really solve all these different code style preferences!
Thank you for your support, _KP! Happy Holidays out there. 🙂
What about StyleCop? StyleCop works with CI and has a lot more rules. Is this eventually going to be a replacement for StyleCop?
We do not recommend any particular coding style in our 2+ million line c# project. Work cycles are better spent on producing well written algorithms, clean signatures for each class and most importantly a better breakdown of code along business functionality.
Automating it with the cost of maintaining either the built in or third party add-in costs much more over the lifespan of a project in production for 8+ years greatly outweighs the benefit of micro level style enforcement like spacing around operators.
No business case could be made as to the cost savings or productivity gains from a third party style tool to allow it to get past our IT council.
Jeff, your purely financial analysis forgets the people who need to touch and work with the code every single day: the developers. Would you rather like a clean or a messy desk? In which environment can you work better, or are more motivated to produce good results? I, for once, am much more productive in clean (also stylistically) code.
This returns 404: https://blogs.msdn.microsoft.com/dotnet/2016/12/15/code-style-configuration-in-the-vs2017-rc-update/.NET%20Foundation%20Coding%20Guidelines
maybe try this?
https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md#c-coding-style
Great news!
Just in case you can’t imagine what I’ve meant with my previous comments, here’s a screenshot of how your post looks like. This is really a bit hard to read when the superbold letters touch each other.
http://imgur.com/a/1N4q3
(Red highlighting by me to point to critical parts)
Beginning of new era
Will any of this be available with C++?
WHAT IS C++??? IS IT SOMETHING THAT I INSTALL WITH C#????
yeah… sure
My first though upon reading the blurb about this on the VS2015 Start Page was “Oh, please NO!”. Am I really the only one NOT in favor of enforcing code style? There are probably at least twice as many code style preferences as there people who write code.
We can probably all agree on some basic guidelines. For example, people who eschew any and all indentation are probably a very small minority. Personally, I find 1TBS with a “cuddly else” very difficult to read, while my friend and colleague the next cubicle over advocates that style over all others. I despise “ragged” member field declaration blocks. My buddy is entirely apathetic about “ragged” versus “aligned”.
I have had the misfortune of having code style enforced upon me at several jobs. Without exception, the only consensus among the developers became that the enforced code style simply took the fun out of writing code. And I can honestly say that the actual code quality was rarely impacted (if anything it would tend to decline).
Bottom line, though… IMHO, (especially) with the advent of Roslyn, individual code style should be entirely irrelevant. Define a single style to be used in source control storage. My IDE should be perfectly capable of letting me edit a re-styled view (according to my personal preferences) while maintaining the “source control style” in the actual file. A Roslyn-based diff/merge tool should be able to do the same.
> We can probably all agree on some basic guidelines.
Let me stop you right there. 😉
Not even MSFT agrees on a “standard” style. Even the “defacto standard” of StyleCop is widely ignored by a great many teams/groups. Heck I am not even sure StyleCop is adopted by *any* group?
In any case, this continues to be a thorn in the side of development, but for once is not specific to .NET. MSFT has an opportunity to innovate here, and should.
hi welcome to this blog. really you have post an informative blog. it will be really helpful to many peoples. thank you for sharing this blog.
What about “Don’t format my code under any circumstance” ? Will there be that option there or will it be skipped like you’ve done with VS2015?
FYI csharp_new_line_before_open_brace does not seem to work correctly. See https://github.com/madskristensen/EditorConfigLanguage/issues/11
Was it seriously that hard to implement trim_trailing_whitespace and insert_final_newline? They’re one of the most useful features we have. I also heard it doesn’t work with XML, why? The original editorconfig plugin worked really well, why couldn’t it just get integrated directly into this update. Makes zero sense.
This is awesome!
I’m setting lots of naming rules, but I’m having trouble finding IDE support for naming rules for local variables. Is this supported?
Also, is this dialog documented in docs.microsoft.com? I looked but didn’t find anything.
Oh, I found the documentation 🙂 https://docs.microsoft.com/en-us/visualstudio/ide/code-styles-and-quick-actions
Kasey, in case you’re still monitoring comments on this post: any progress on being able to enforce code style rules in CI / break builds?