{"id":7745,"date":"2016-12-15T11:40:18","date_gmt":"2016-12-15T19:40:18","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/dotnet\/?p=7745"},"modified":"2021-09-30T10:32:10","modified_gmt":"2021-09-30T17:32:10","slug":"code-style-configuration-in-the-vs2017-rc-update","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/code-style-configuration-in-the-vs2017-rc-update\/","title":{"rendered":"Code Style Configuration in the VS2017 RC Update"},"content":{"rendered":"<p><a href=\"http:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/catsandDogs.jpg\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/catsandDogs-1024x559-1.jpg\" alt=\"Fighting like Cats and Dogs\" width=\"879\" height=\"480\" class=\"alignnone size-large wp-image-7795\" \/><\/a> Visual Studio 2017 RC introduced code style enforcement and EditorConfig support. We are excited to announce that <a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/updating-visual-studio-2017-release-candidate\/\">the update<\/a> includes more code style rules and allows developers to configure code style via EditorConfig.<\/p>\n<h2>What is EditorConfig?<\/h2>\n<p><a href=\"http:\/\/editorconfig.org\/\">EditorConfig<\/a> 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\u2019re excited to work with the EditorConfig community to add support in Visual Studio and extend their format to include .NET code style settings.<\/p>\n<h2>EditorConfig with .NET Code Style<\/h2>\n<p>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\u2019re on in The Code Style Debate, you can choose what conventions you feel are best for any portion of your codebase\u2014whether it be a whole solution or just a legacy section that you don\u2019t want to change the conventions for\u2014and enforce your conventions live in the editor. To demonstrate the ins-and-outs of this feature, let\u2019s walk through how we updated the<\/p>\n<p><a href=\"https:\/\/github.com\/dotnet\/roslyn\">Roslyn repo<\/a> to use EditorConfig.<\/p>\n<h2>Getting Started<\/h2>\n<p>The Roslyn repo by-and-large uses the style outlined in the <a href=\"https:\/\/github.com\/dotnet\/corefx\/blob\/master\/Documentation\/coding-guidelines\/coding-style.md#c-coding-style\">.NET Foundation Coding Guidelines<\/a>. 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.<\/p>\n<p>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 \u201croot\u201d settings, add the following to your .editorconfig (you can do this in your editor\/IDE of choice):<\/p>\n<p><script src=\"https:\/\/gist.github.com\/kuhlenh\/291cb95269d365b1cd49154ce021e504.js\"><\/script> 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 <code>var<\/code>, so we can just create another EditorConfig file that contains different settings for the <code>var<\/code> 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 <em>not<\/em> want to add <code>root = true<\/code> (this allows us to inherit the rules from a parent directory, or in this case, the top-level Roslyn directory). <figure id=\"attachment_7785\" aria-labelledby=\"figcaption_attachment_7785\" class=\"wp-caption alignnone\" ><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfigDirectories-1024x711-1.png\" alt=\"EditorConfig File Hierarchy\" width=\"879\" height=\"610\" class=\"size-large wp-image-7785\" \/><figcaption id=\"figcaption_attachment_7785\" class=\"wp-caption-text\">]<a href=\"http:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfigDirectories.png\">6<\/a> <strong>Figure 1<\/strong>. Rules defined in the top-most EditorConfig file will apply to all projects in the &#8220;src&#8221; directory except for the rules that are overridden by the EditorConfig file in \u201csrc\/Compilers\u201d.<\/figcaption><\/figure><\/p>\n<h2>Code Formatting Rules<\/h2>\n<p>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:<\/p>\n<p><code>indent_style<\/code>, <code>indent_size<\/code>, <code>tab_width<\/code>, <code>end_of_line<\/code>, <code>charset<\/code>, <code>trim_trailing_whitespace<\/code>, and <code>insert_final_newline<\/code>. 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:<\/p>\n<p><script src=\"https:\/\/gist.github.com\/kuhlenh\/53709da47507ec312e3b1a95419444b8.js\"><\/script><\/p>\n<h2>Code Style Rules<\/h2>\n<p>After reaching out to the EditorConfig community, we\u2019ve 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 <strong><a href=\"https:\/\/msdn.microsoft.com\/en-us\/library\/bb384062.aspx\">collection initializers<\/a><\/strong> , <strong><a href=\"https:\/\/blogs.msdn.microsoft.com\/csharpfaq\/2014\/11\/20\/new-features-in-c-6\/\">expression-bodied members<\/a><\/strong>, <strong><a href=\"https:\/\/blogs.msdn.microsoft.com\/dotnet\/2016\/08\/24\/whats-new-in-csharp-7-0\/\">C#7 pattern matching over cast and null checks<\/a><\/strong>, and many more!<\/p>\n<p>Let\u2019s walk through an example of how coding conventions can be defined: <script src=\"https:\/\/gist.github.com\/kuhlenh\/a126a1b342c929e9f3375a0857d7b48b.js\"><\/script><\/p>\n<p>The left side is the <strong>name<\/strong> of the rule, in this case &#8220;csharp_style_var_for_built_in_types&#8221;. The right side indicates the rule settings: <strong>preference<\/strong> and <strong>enforcement<\/strong> <strong>level<\/strong>, respectively. * A preference setting can be either <strong>true<\/strong> (meaning, \u201cprefer this rule\u201d) or <strong>false<\/strong> (meaning, \u201cdo not prefer this rule\u201d). * The enforcement level is the same for all Roslyn-based code analysis and can be, from least severe to most severe: <strong>none<\/strong>, <strong>suggestion<\/strong>, <strong>warning<\/strong>, or <strong>error<\/strong>. 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<\/p>\n<p><a href=\"https:\/\/github.com\/dotnet\/roslyn\/blob\/master\/.editorconfig\">the Roslyn .editorconfig<\/a> or check out <a href=\"https:\/\/docs.microsoft.com\/en-us\/visualstudio\/ide\/editorconfig-code-style-settings-reference\">our documentation<\/a>. If you need a refresher on the different severity levels and what they do, see below: <a href=\"http:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_Table.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_Table-1024x199.png\" alt=\"Table of code analysis severity levels\" width=\"879\" height=\"171\" class=\"alignnone size-large wp-image-7755\" srcset=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_Table-1024x199.png 1024w, https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_Table-300x58.png 300w, https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_Table-768x150.png 768w, https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_Table.png 1885w\" sizes=\"(max-width: 879px) 100vw, 879px\" \/><\/a><\/p>\n<p><u>Pro-tip<\/u>: 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 (\u2026) and give the setting the following custom color (R:255, G:136, B:196): <a href=\"http:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_SuggestionColor.png\"><img decoding=\"async\" src=\"http:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_SuggestionColor.png\" alt=\"R:255, G:136, B:196\" width=\"500\" height=\"83\" class=\"alignnone size-mediumlarge wp-image-7756\" srcset=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_SuggestionColor.png 600w, https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_SuggestionColor-300x50.png 300w\" sizes=\"(max-width: 500px) 100vw, 500px\" \/><\/a><\/p>\n<h2>Experience in Visual Studio<\/h2>\n<p>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<\/p>\n<p><em>close and reopen\u00ad<\/em> 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 <strong>Format Document<\/strong> (<code>Ctrl+K,D<\/code>). This one-click cleanup does not exist yet for code style, but you can use the <strong>Quick Actions menu<\/strong> (<code>Ctrl+.<\/code>) to apply a code style fix to all occurrences in your document\/project\/solution.<\/p>\n<p><figure id=\"attachment_7775\" aria-labelledby=\"figcaption_attachment_7775\" class=\"wp-caption alignnone\" ><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_UsePatternMatch.png\" alt=\"Fix all violations of a code style rule\" width=\"794\" height=\"367\" class=\"size-full wp-image-7775\" srcset=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_UsePatternMatch.png 794w, https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_UsePatternMatch-300x139.png 300w, https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_UsePatternMatch-768x355.png 768w\" sizes=\"(max-width: 794px) 100vw, 794px\" \/><figcaption id=\"figcaption_attachment_7775\" class=\"wp-caption-text\">]<a href=\"http:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfig_UsePatternMatch.png\">14<\/a><strong>Figure 2<\/strong>. Rules set in EditorConfig files apply to generated code and code fixes can be applied to all occurrences in the document, project, or solution.<\/figcaption><\/figure><\/p>\n<p><u>Pro Tip<\/u>: 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: <a href=\"http:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfigStatusBar.png\"><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfigStatusBar.png\" alt=\"Visual Studio status bar\" width=\"462\" height=\"65\" class=\"alignnone size-full wp-image-7765\" srcset=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfigStatusBar.png 462w, https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2016\/12\/EditorConfigStatusBar-300x42.png 300w\" sizes=\"(max-width: 462px) 100vw, 462px\" \/><\/a><\/p>\n<p>Note that this means EditorConfig files override any code style settings you have configured in Tools>Options.<\/p>\n<h2>Conclusion<\/h2>\n<p>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<\/p>\n<p><a href=\"https:\/\/docs.microsoft.com\/en-us\/visualstudio\/ide\/create-portable-custom-editor-options\">our documentation<\/a>. <a href=\"https:\/\/www.visualstudio.com\/vs\/visual-studio-2017-rc\/\">Download the VS2017 RC<\/a> with the update to test out .NET code style in EditorConfig and let us know what you think! Over \u2018n\u2019 out, <strong>Kasey Uhlenhuth<\/strong>, Program Manager, <strong>.NET Managed Languages<\/strong><\/p>\n<h2>Known Issues<\/h2>\n<ul>\n<li>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.<\/li>\n<li>You must close and reopen any open files to have EditorConfig settings apply once it is added or edited.<\/li>\n<li>Only <code>indent_style<\/code>, <code>indent_size<\/code>, <code>tab_width<\/code>, <code>end_of_line<\/code>, and <code>charset<\/code> are supported code formatting rules in Visual Studio 2017 RC.<\/li>\n<li>IntelliSense and syntax highlighting are &#8220;in-progress&#8221; for EditorConfig files in Visual Studio right now. In the meantime, you can use <a href=\"http:\/\/vsixgallery.com\/extension\/1209461d-57f8-46a4-814a-dbe5fecef941\/\">MadsK\u2019s VS extension<\/a> for this support.<\/li>\n<li>Visual Basic-specific rules are not currently supported in EditorConfig beyond the ones that are covered by the <code>dotnet_style_*<\/code> group.<\/li>\n<li>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 <a href=\"https:\/\/github.com\/dotnet\/roslyn\/pull\/15065\">Roslyn repo<\/a>.<\/li>\n<li>There is no way to make a document adhere to all code style rules with a one-click cleanup (yet!).<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>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 [&hellip;]<\/p>\n","protected":false},"author":350,"featured_media":58792,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685],"tags":[],"class_list":["post-7745","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet"],"acf":[],"blog_post_summary":"<p>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 [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/7745","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/350"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=7745"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/7745\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/58792"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=7745"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=7745"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=7745"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}