使用 EditorConfig 创建可移植的自定义编辑器设置Create portable, custom editor settings with EditorConfig

可以向项目或基本代码添加 EditorConfig 文件,强制对使用该基本代码的所有人实施一致的编码样式。You can add an EditorConfig file to your project or codebase to enforce consistent coding styles for everyone that works in the codebase. EditorConfig 设置优先于全局 Visual Studio 文本编辑器设置。EditorConfig settings take precedence over global Visual Studio text editor settings. 这意味着,可以调整每种基本代码,以使用特定于该项目的文本编辑器设置。This means that you can tailor each codebase to use text editor settings that are specific to that project. 仍然可以在 Visual Studio“选项” 对话框中设置个人编辑器首选项。You can still set your own personal editor preferences in the Visual Studio Options dialog box. 以下两种情况下将应用这些设置:每当在不具备 .editorconfig 文件的代码库中执行操作时,或者当 .editorconfig 文件不会替代特定设置时 。Those settings apply whenever you're working in a codebase without an .editorconfig file, or when the .editorconfig file doesn't override a particular setting. 此类首选项的一个示例为缩进样式 — 制表符或空格。An example of such a preference is indent style—tabs or spaces.

许多代码编辑器和 IDE(包括 Visual Studio)都支持 EditorConfig 设置。EditorConfig settings are supported by numerous code editors and IDEs, including Visual Studio. 它是一种随代码移动的可移植组件,甚至可以在 Visual Studio 外强制实施编码样式。It's a portable component that travels with your code, and can enforce coding styles even outside of Visual Studio.

在 Visual Studio 中向项目添加 EditorConfig 文件后,将按照 EditorConfig 设置对所有新代码行的格式进行设置。When you add an EditorConfig file to your project in Visual Studio, new lines of code are formatted according to the EditorConfig settings. 除非运行以下命令之一,否则不会更改现有代码的格式:The formatting of existing code is not changed unless you run one of the following commands:

  • 代码清除(Ctrl+K、Ctrl+E),适用于任何空格设置(如缩进样式)和所选的代码样式设置(例如如何对 using 指令进行排序 )。Code Cleanup (Ctrl+K, Ctrl+E), which applies any white space settings, such as indent style, and selected code style settings, such as how to sort using directives.
  • “编辑”>“高级”>“设置文档格式”(或在默认配置文件中按 Ctrl+K、Ctrl+D),仅应用空格设置,如缩进样式 。Edit > Advanced > Format Document (or Ctrl+K, Ctrl+D in the default profile), which only applies white space settings, such as indent style.

在 Visual Studio 中向项目添加 EditorConfig 文件后,将按照 EditorConfig 设置对所有新代码行的格式进行设置。When you add an EditorConfig file to your project in Visual Studio, new lines of code are formatted according to the EditorConfig settings. 现有代码的格式设置不会更改,除非设置文档格式(在默认配置文件中单击“编辑” > “高级” > “设置文档格式”或按 Ctrl+K、Ctrl+D) 。The formatting of existing code is not changed unless you run unless you format the document (Edit > Advanced > Format Document or Ctrl+K, Ctrl+D in the default profile). 文档格式设置只会影响空格设置(如缩进样式),除非已将“设置文档格式”配置为执行其他代码清理Formatting the document only affects white space settings, such as indent style, unless you've configured Format Document to perform additional code cleanup.

可定义希望“设置文档格式”在“设置格式”选项页面上应用的 EditorConfig 设置 。You can define which EditorConfig settings you want Format Document to apply on the Formatting options page.

Note

本主题适用于 Visual Studio Windows 版。This topic applies to Visual Studio on Windows. 对于 Visual Studio for Mac,请参阅Visual Studio for Mac 中的 EditorConfigFor Visual Studio for Mac, see EditorConfig in Visual Studio for Mac.

代码一致性Code consistency

EditorConfig 文件中的设置用于在基本代码库中维持一致的编码风格和设置,例如缩进样式、选项卡宽度、行尾字符以及编码等,而无需考虑使用的编辑器或 IDE。Settings in EditorConfig files enable you to maintain consistent coding styles and settings in a codebase, such as indent style, tab width, end of line characters, encoding, and more, regardless of the editor or IDE you use. 例如,使用 C# 编码时,如果基本代码约定为始终缩进五个空格字符、文档使用 UTF-8 编码,且每一行始终以 CR/LF 结束,则可以配置 .editorconfig 文件达到此效果 。For example, when coding in C#, if your codebase has a convention to prefer that indents always consist of five space characters, documents use UTF-8 encoding, and each line always ends with a CR/LF, you can configure an .editorconfig file to do that.

个人项目中使用的编码约定可能不同于团队项目使用的编码约定。Coding conventions you use on your personal projects may differ from those used on your team's projects. 例如,你可能倾向在编码时,缩进操作会添加制表符。For example, you might prefer that when you're coding, indenting adds a tab character. 但你的团队可能更倾向使用四个空格字符的缩进,而不是制表符。However, your team might prefer that indenting adds four space characters instead of a tab character. EditorConfig 文件让你能对每个方案进行配置,从而解决这一问题。EditorConfig files resolve this problem by enabling you to have a configuration for each scenario.

由于这些设置包含在基本代码的文件中,因此能与基本代码一起移动。Because the settings are contained in a file in the codebase, they travel along with that codebase. 只要在 EditorConfig 兼容的编辑器中打开代码文件,就能实现文本编辑器设置。As long as you open the code file in an EditorConfig-compliant editor, the text editor settings are implemented. 有关 EditorConfig 文件的详细信息,请参阅 EditorConfig.org 网站。For more information about EditorConfig files, see the EditorConfig.org website.

Note

EditorConfig 文件中设置的约定暂无法在 CI/CD 管道中强制执行为生成错误或警告。Conventions that are set in an EditorConfig file cannot currently be enforced in a CI/CD pipeline as build errors or warnings. 任何样式偏差都仅显示在 Visual Studio 编辑器和“错误列表” 中。Any style deviations appear only in the Visual Studio editor and Error List.

支持的设置Supported settings

Visual Studio 中的编辑器支持 EditorConfig 属性的核心集:The editor in Visual Studio supports the core set of EditorConfig properties:

  • indent_styleindent_style
  • indent_sizeindent_size
  • tab_widthtab_width
  • end_of_lineend_of_line
  • charsetcharset
  • trim_trailing_whitespacetrim_trailing_whitespace
  • insert_final_newlineinsert_final_newline
  • root

所有 Visual Studio 支持的语言(XML 除外)均支持 EditorConfig 编辑器设置。EditorConfig editor settings are supported in all Visual Studio-supported languages except for XML. 此外,EditorConfig 还支持适用于 C# 和 Visual Basic 的代码样式约定(包括语言格式设置)和命名约定。In addition, EditorConfig supports code style conventions including language, formatting, and naming conventions for C# and Visual Basic.

添加和删除 EditorConfig 文件Add and remove EditorConfig files

向项目或基本代码添加 EditorConfig 文件后,将按照 EditorConfig 文件设置编写的所有新代码行的格式。When you add an EditorConfig file to your project or codebase, any new lines of code you write are formatted according to the EditorConfig file. 但是,只有在设置文档的格式或运行代码清理时,添加 EditorConfig 文件才会将现有样式转换为新样式。However, adding an EditorConfig file does not convert existing styles to the new ones until you format the document or run Code Cleanup. 例如,如果文件中存在制表符格式的缩进,并添加了以空格缩进的 EditorConfig 文件,则缩进字符不会自动转换为空格。For example, if you have indents in your file that are formatted with tabs and you add an EditorConfig file that indents with spaces, the indent characters are not automatically converted to spaces. 如果设置文档格式(“编辑” > “高级” > “设置文档格式”或 Ctrl+K、Ctrl+D),则 EditorConfig 文件中的空格设置将应用到现有代码行 。When you format the document (Edit > Advanced > Format Document or Ctrl+K, Ctrl+D), the white space settings in the EditorConfig file are applied to existing lines of code.

如果从项目或基本代码库中删除 EditorConfig 文件,并想要使用全局编辑器设置设置新代码行的格式,必须关闭并重新打开任何打开的代码文件。If you remove an EditorConfig file from your project or codebase and you want new lines of code to be formatted according to the global editor settings, you must close and reopen any open code files.

将 EditorConfig 文件添加到项目Add an EditorConfig file to a project

  1. 在 Visual Studio 中打开项目或解决方案。Open a project or solution in Visual Studio. 根据要应用 .editorconfig 设置的对象(是解决方案中的所有项目还是其中一个项目),选择项目或解决方案节点 。Select either the project or solution node, depending on whether your .editorconfig settings should apply to all projects in the solution or just one. 还可在项目或解决方案中选择一个文件夹,向其添加 .editorconfig 文件 。You can also select a folder in your project or solution to add the .editorconfig file to.

  2. 从菜单栏中,选择“项目” > “添加新项”,或按 Ctrl+Shift+A 。From the menu bar, choose Project > Add New Item, or press Ctrl+Shift+A.

    此时将打开“添加新项” 对话框。The Add New Item dialog box opens.

  3. 在搜索框中,搜索“editorconfig” 。In the search box, search for editorconfig.

    搜索结果将显示两个 editorconfig 文件项模板。 Two editorconfig File item templates are shown in the search results.

    Visual Studio 中的 EditorConfig 文件项模板

  4. 选择“editorconfig 文件(默认)”模板,添加使用针对缩进样式和尺寸的两个核心 EditorConfig 选项预填充的 EditorConfig 文件。 Select the editorconfig File (default) template to add an EditorConfig file prepopulated with two core EditorConfig options for indent style and size. 或者,选择“editorconfig 文件(.NET)”模板,添加使用默认的 .NET 代码样式、格式设置和命名约定预填充的 EditorConfig 文件。 Or, select the editorconfig File (.NET) template to add an EditorConfig file prepopulated with default .NET code style, formatting, and naming conventions.

    解决方案资源管理器中随即显示一个 .editorconfig 文件,且文件在编辑器中打开 。An .editorconfig file appears in Solution Explorer, and it opens in the editor.

    解决方案资源管理器和编辑器中的 .editorconfig 文件

  5. 根据需要编辑文件。Edit the file as desired.

添加 EditorConfig 文件的其他方式Other ways to add an EditorConfig file

还可以通过其他几种方法将 EditorConfig 文件添加到项目中:There are a couple other ways you can add an EditorConfig file to your project:

文件层次结构和优先级File hierarchy and precedence

如果将 .editorconfig 文件添加到文件层次结构中的某文件夹,则其设置将应用于该级别及更低级别的所有适用文件 。When you add an .editorconfig file to a folder in your file hierarchy, its settings apply to all applicable files at that level and below. 还可替代特定项目、代码库或部分代码库的 EditorConfig 设置,以使其使用与代码库其他部分不同的约定。You can also override EditorConfig settings for a particular project, codebase, or part of a codebase, such that it uses different conventions than other parts of the codebase. 当要包含其他地方的代码而不想更改其约定时,这会很有用。This can be useful when you incorporate code from somewhere else, and don’t want to change its conventions.

若要替代部分或全部 EditorConfig 设置,请在要应用这些替代设置的文件层次结构级别添加 .editorconfig 文件 。To override some or all of the EditorConfig settings, add an .editorconfig file at the level of the file hierarchy you want those overridden settings to apply. 新的 EditorConfig 文件设置应用于同级目录和任何子目录中的文件。The new EditorConfig file settings apply to files at the same level and any subdirectories.

EditorConfig 层次结构

如果想替代一部分而非所有设置,请在 .editorconfig 文件中仅指定这些设置 。If you want to override some but not all of the settings, specify just those settings in the .editorconfig file. 仅替代较低级别文件中显式列出的属性。Only those properties that you explicitly list in the lower-level file are overridden. 更高级别 .editorconfig 文件中的其他设置会继续应用 。Other settings from higher-level .editorconfig files continue to apply. 如果要确保_任何_更高级别的 .editorconfig 文件中_没有_设置应用于此部分代码库,请将 root=true 属性添加到较低级别的 .editorconfig 文件中 :If you want to ensure that no settings from any higher-level .editorconfig files are applied to this part of the codebase, add the root=true property to the lower-level .editorconfig file:

# top-most EditorConfig file
root = true

从上到下读取 EditorConfig 文件。EditorConfig files are read top to bottom. 如果有多个具有相同名称的属性,则最近找到的具有该名称的属性具有优先权。If there are multiple properties with the same name, the most recently found property with that name takes precedence.

编辑 EditorConfig 文件Edit EditorConfig files

Visual Studio 提供 IntelliSense 完成列表,帮助你编辑 .editorconfig 文件 。Visual Studio helps you edit .editorconfig files by providing IntelliSense completion lists.

.editorconfig 文件中的 IntelliSense

编辑 EditorConfig 文件后,必须重载代码文件,新设置才会生效。After you've edited your EditorConfig file, you must reload your code files for the new settings to take effect.

如果编辑大量 .editorconfig 文件,可能会发现 EditorConfig 语言服务扩展很有用 。If you edit numerous .editorconfig files, you may find the EditorConfig Language Service extension helpful. 该扩展的一些功能包括语法高亮显示、改进的 IntelliSense、验证和代码格式。Some of the features of this extension include syntax highlighting, improved IntelliSense, validation, and code formatting.

带有 EditorConfig 语言服务扩展的 IntelliSense

示例Example

以下示例演示将 .editorconfig 文件添加到项目之前和之后 C# 代码片段的缩进状态 。The following example shows the indent state of a C# code snippet before and after adding an .editorconfig file to the project. Visual Studio 文本编辑器“选项”对话框中的“Tab”设置设置为按 Tab 键时可生成空格字符。 The Tabs setting in the Options dialog box for the Visual Studio text editor is set to produce space characters when you press the Tab key.

文本编辑器 Tab 设置

在下一行中按 Tab 键应该会让这一行首行缩进四个空格字符。As expected, pressing the Tab key on the next line indents the line by adding four additional white-space characters.

使用 EditorConfig 之前的代码

将具有以下内容的名为 .editorconfig 的新文件添加到项目 。Add a new file called .editorconfig to the project, with the following contents. [*.cs] 设置意味着此更改仅应用于项目中的 C# 代码文件。The [*.cs] setting means that this change applies only to C# code files in the project.

# Top-most EditorConfig file
root = true

# Tab indentation
[*.cs]
indent_style = tab

现在按 Tab 键时,会获得制表符而不是空格。Now, when you press the Tab key, you get tab characters instead of spaces.

使用 Tab 键添加制表符

EditorConfig 设置疑难解答Troubleshoot EditorConfig settings

如果在目录结构中处于或高于你项目所在位置的任何位置存在 EditorConfig 文件,则 Visual Studio 会将该文件中的编辑器设置应用于编辑器。If there is an EditorConfig file anywhere in the directory structure at or above your project's location, Visual Studio applies the editor settings in that file to your editor. 在这种情况下,可能会在状态栏中看到以下消息:In this case, you may see the following message in the status bar:

“该项目编码约定覆盖了此文件类型的用户首选项” 。"User preferences for this file type are overridden by this project's coding conventions."

这意味着如果目录结构中与项目位于相同位置或在项目之上的某个 EditorConfig 文件中指定了“工具” > “选项” > “文本编辑器”中的任何编辑器设置(如缩进尺寸和样式、制表符大小或编码约定),则 EditorConfig 文件中的约定会替代“选项”中的设置 。This means that if any editor settings in Tools > Options > Text Editor (such as indent size and style, tab size, or coding conventions) are specified in an EditorConfig file at or above the project in the directory structure, the conventions in the EditorConfig file override the settings in Options. 可以通过在“工具” > “选项” > “文本编辑器” 中切换“遵循项目编码约定” 选项来控制此行为。You can control this behavior by toggling the Follow project coding conventions option in Tools > Options > Text Editor. 取消选中该选项会关闭 Visual Studio 的 EditorConfig 支持。Unchecking the option turns off EditorConfig support for Visual Studio.

工具选项 - 遵循项目编码约定

还可以通过打开命令提示符并从包含项目的磁盘的根目录运行以下命令,在父目录中查找任何 .editorconfig 文件 :You can find any .editorconfig files in parent directories by opening a command prompt and running the following command from the root of the disk that contains your project:

dir .editorconfig /s

可以通过在存储库的根目录或项目所在目录的 .editorconfig 文件中设置 root=true 属性,控制 EditorConfig 约定的范围 。You can control the scope of your EditorConfig conventions by setting the root=true property in the .editorconfig file at the root of your repo or in the directory that your project resides. Visual Studio 会在打开的文件的目录和每个父目录中查找名为 .editorconfig 的文件 。Visual Studio looks for a file named .editorconfig in the directory of the opened file and in every parent directory. 到达根文件路径时或找到具有 root=true 的 .editorconfig 文件时搜索结束 。The search ends when it reaches the root filepath, or if an .editorconfig file with root=true is found.

请参阅See also