使用 EditorConfig 定义一致的编码样式

  • 项目

可以向解决方案或项目添加 EditorConfig 文件，强制对使用基本代码的所有人实施一致的编码样式。 EditConfig 文件设置遵循 EditorConfig.org 维护的文件格式规范。许多代码编辑器和应用程序都支持 EditorConfig 文件，包括 Visual Studio。 它是一种随代码移动的可移植组件，甚至可以在 Visual Studio 外强制实施编码样式。

在 Visual Studio 中，EditorConfig 文件设置优先于全局文本编辑器设置（通过在“工具”>“选项”对话框中选择“文本编辑器”访问）。 这意味着，可以调整每种基本代码，以使用特定于该项目的文本编辑器设置。 使用 EditorConfig 文件时，仍可以在 Visual Studio 文本编辑器中继续设置自己的个人编辑器首选项。 只要正在使用的基本代码没有 EditorConfig 文件，或者 EditorConfig 文件未替代特定设置，将应用这些文本编辑器设置。 这种首选项的一个示例是是否使用制表符或空格作为代码缩进样式。

在 Visual Studio 中向项目添加 EditorConfig 文件后，仅根据 EditorConfig 设置对新代码行的格式进行设置。 除非运行以下命令之一，否则不会更改现有代码的格式：

  • 代码清理。

    在 Visual Studio 编辑器中选择“代码清理”，或按 Ctrl+K、Ctrl+E。 此命令适用于空白设置，例如缩进样式和所选代码样式设置，例如括号首选项。

  • 设置文档格式。

    选择“编辑”>“高级”>“设置文档格式”，或在默认配置文件中按 Ctrl+K、Ctrl+D。 此命令仅适用于空格设置，例如缩进样式。

注意

本主题适用于 Visual Studio for Windows。 对于 Visual Studio for Mac，请参阅在 Visual Studio for Mac 中创建和编辑自定义 EditorConfig 文件。

代码一致性

EditorConfig 文件设置可在代码库中保持一致的编码样式和约定，无论使用哪种编辑器或 IDE。 可以控制缩进样式、制表符宽度、行尾字符和编码等编码样式。 例如，如果 C# 代码库具有缩进使用五个空格字符、文档使用 UTF-8 编码，并且行以 CR/LF 结尾的约定，则可以将 EditorConfig 文件配置为使用此约定。

当您在个人项目中使用的编码约定与团队项目中使用的约定不同时，EditorConfig 文件非常有用。 例如，可能希望缩进在代码中添加制表符。 但是，团队可能希望缩进添加四个空格。 EditorConfig 文件让你能对每个方案进行配置，从而解决这一问题。

由于代码库中的 .editorconfig 文件包含 EditorConfig 设置，因此能与代码库一起移动。 只要在 EditorConfig 兼容的编辑器中打开代码文件，就能激活文本编辑器设置。

注意

EditorConfig 文件中设置的约定无法在 CI/CD 管道中强制执行为生成错误或警告。 任何样式偏差都仅显示在 Visual Studio 编辑器和“错误列表”中。

支持的设置

Visual Studio 中的编辑器支持 EditorConfig 属性的核心集：

  • indent_style
  • indent_size
  • tab_width
  • end_of_line
  • charset
  • trim_trailing_whitespace
  • insert_final_newline
  • root

EditorConfig 支持所有 Visual Studio 支持的语言（XML 除外）均支持 EditorConfig 编辑器设置。

EditorConfig 支持适用于 C# 和 Visual Basic 的代码样式约定（包括语言、格式设置）和命名约定。

添加和删除 EditorConfig 文件

向项目或基本代码添加 EditorConfig 文件后，Visual Studio 将为按照 EditorConfig 文件设置编写的所有新代码行设置格式。 但是，只有在设置文档格式或运行代码清理时，Visual Studio 才会将现有样式转换为新样式。 例如，如果文件中存在制表符格式的缩进，并添加了以空格设置缩进格式的 EditorConfig 文件，则缩进字符不会自动转换为空格。 如果设置文档格式（选择“编辑”>“高级”>“设置文档格式”或按Ctrl+K、Ctrl+D），则 EditorConfig 文件中的空格设置将应用到现有代码行。

如果从项目或基本代码库中删除 EditorConfig 文件，必须关闭并重新打开任何打开的代码文件，全局编辑器设置才会对新代码行生效。

将 EditorConfig 文件添加到项目

若要将 EditorConfig 文件添加到项目或解决方案中，请按照下列步骤操作：

  1. 在 Visual Studio 中打开项目或解决方案。 选择解决方案或项目节点，具体取决于 EditorConfig 设置是要应用于解决方案中的所有项目还是仅应用于一个。 还可在项目或解决方案中选择一个文件夹，向其添加 .editorconfig 文件。

  2. 从菜单中，选择“项目”>“添加新项”，或按 Ctrl+Shift+A。

    此时将打开“添加新项”对话框。

  3. 在搜索框中输入 editorconfig。

    搜索结果将显示两个 editorconfig 文件项模板。

    显示 Visual Studio 中的 EditorConfig 文件项模板的屏幕截图。

  4. 选择 editorconfig 文件（空）模板以添加用空格、代码样式和命名约定预填充 EditorConfig 默认选项的 EditorConfig 文件。 或者，选择 editorconfig File (.NET) 模板，添加使用默认的 .NET 空格、代码样式和命名约定预填充的 EditorConfig 文件。

    新的 .editorconfig 文件将显示在解决方案资源管理器中，该文件以新选项卡的形式在编辑器中打开。

    显示解决方案资源管理器和编辑器中的 .editorconfig 文件的屏幕截图。

  5. （可选）编辑文件，然后进行保存。

添加 EditorConfig 文件的其他方式

还可以通过其他几种方法将 EditorConfig 文件添加到项目中：

文件层次结构和优先级

如果将 .editorconfig 文件添加到文件层次结构中的某文件夹，则其设置将应用于该级别及更低级别的所有适用文件。 还可替代特定项目、代码库或部分代码库的 EditorConfig 设置，以使其使用与代码库其他部分不同的约定。 当要包含其他地方的代码而不想更改其约定时，这样做会很有用。

请遵循这些指导：

  • 若要替代部分或全部 EditorConfig 设置，请在要应用这些替代设置的文件层次结构级别添加 .editorconfig 文件。 新的 EditorConfig 文件设置应用于同级目录和任何子目录中的文件。

    显示 EditorConfig 层次结构的屏幕截图。

  • 如果想替代一部分而非所有设置，请在 .editorconfig 文件中仅指定这些设置。 仅替代较低级别 .editorconfig 文件中显式列出的属性。 任何更高级别 .editorconfig 文件中的其他设置会继续应用。

  • 如果要确保任何更高级别的 .editorconfig 文件中没有设置应用于此部分代码库，请将 root=true 属性添加到较低级别的 .editorconfig 文件中。

    # top-most EditorConfig file for this level
root = true

从上到下读取 EditorConfig 文件。 如果有多个具有相同名称的属性，则最近找到的具有该名称的属性具有优先权。

编辑 EditorConfig 文件

Visual Studio 2022 为 EditorConfig 文件提供可视化编辑器。

编辑 EditorConfig 文件后，必须重载代码文件，新设置才会生效。

Visual Studio 提供 IntelliSense 完成列表，帮助你编辑 EditorConfig 文件。 例如：

显示 EditorConfig 文件中的 IntelliSense 的屏幕截图。

如果编辑大量 EditorConfig 文件，可能会发现 EditorConfig 语言服务扩展很有用。 该扩展的一些功能包括语法高亮显示、改进的 IntelliSense、验证和代码格式。

显示带有 EditorConfig 语言服务扩展的 IntelliSense 的屏幕截图。

示例

以下示例演示将 EditorConfig 文件添加到项目之前和之后 C# 代码片段的缩进状态：

  1. 在 Visual Studio 文本编辑器的“工具”>“选项”对话框中设置“文本编辑器”>“C#”>“选项卡”设置，以在按 Tab 键时生成四个空格字符。

    显示“文本编辑器”选项卡设置的屏幕截图。

  2. 在下一行中按 Tab 键应该会让这一行首行缩进四个空格字符。

    显示在代码中添加空格的 Tab 键的屏幕截图。

    显示在代码中添加空格的 Tab 键的屏幕截图。

  3. 使用 EditorConfig 切换选项卡设置以使用选项卡。

    在 EditorConfig 文件中选择“使用选项卡”。

    显示为 Tab 键配置选项卡用法的屏幕截图。

    将具有以下内容的名为 .editorconfig 的新文件添加到项目。 [*.cs] 指示符意味着此更改仅应用于项目中的 C# 代码文件。

    # Top-most EditorConfig file
root = true

# Tab indentation
[*.cs]
indent_style = tab

  4. 按 Tab 键时，现在会显示制表符而不是空格。

    显示在代码中添加制表符的 Tab 键的屏幕截图。

    显示在代码中添加制表符的 Tab 键的屏幕截图。

EditorConfig 设置疑难解答

如果在目录结构中处于或高于你项目所在位置的任何位置存在 EditorConfig 文件，则 Visual Studio 会将该文件中的编辑器设置应用于编辑器。 在这种情况下，可能会在状态栏中看到以下消息：

User preferences for this file type are overridden by this project's coding conventions.

这意味着如果目录结构中与项目位于相同位置或在项目之上的某个 EditorConfig 文件中指定了“工具”>“选项”>“文本编辑器”中的任何编辑器设置（如缩进尺寸和样式、制表符大小或编码约定），则 EditorConfig 文件中的约定会替代“文本编辑器”中的设置。

若要解决 EditorConfig 问题，请按照下列步骤操作：

  1. 若要关闭 Visual Studio 的 EditorConfig 支持，请清除“工具”>“选项”>“文本编辑器”中的“关注项目编码约定”选项。

    显示“关注项目编码约定”设置的屏幕截图。

  2. 若要在项目的父目录中查找任何 EditorConfig 文件，请打开命令提示符并从包含项目的磁盘的根目录运行以下命令。

    dir .editorconfig /s

  3. 若要控制 EditorConfig 约定的范围，请在存储库的根目录或项目所在目录的 .editorconfig 文件中设置 root=true 属性。

    Visual Studio 会在打开的文件的目录和每个父目录中查找名为 .editorconfig 的文件。 到达根文件路径时或找到具有 root=true 的 .editorconfig 文件时搜索结束。

相关内容