通过

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

  • 项目

要为在代码库中工作的每个人强制实施一致的编码风格，您可以将 .editorconfig 文件添加到您的解决方案或项目中。 EditorConfig 文件设置遵循 EditorConfig.org 维护的文件格式规范。许多代码编辑器和应用程序都支持 EditorConfig 文件，包括 Visual Studio。 由于设置位于文件中，因此它们附带代码，并且即使在 Visual Studio 外部也可使用。

在 Visual Studio 中，EditorConfig 文件设置优先于“工具>选项>文本编辑器”下提供的各种全局文本编辑器>设置[C# |C/C++ |Visual Basic]>代码样式。 可以使用 EditorConfig 文件定制每个基本代码，以使用特定于该项目的文本编辑器设置。

可以手动填充 EditorConfig 文件，或根据 Visual Studio 中选择的代码样式设置自动生成它。 有关详细信息，请参阅 添加 EditorConfig 文件的方法。

使用 EditorConfig 文件时，仍可以在 Visual Studio 文本编辑器中继续设置自己的个人编辑器首选项。 只要你在没有 EditorConfig 文件的代码库中工作，或者 EditorConfig 文件不重写特定设置，这些文本编辑器设置就适用。 此类首选项的示例是是否对代码缩进样式使用制表符或空格。

在 Visual Studio 中将 EditorConfig 文件添加到项目时，只有新代码行会根据 EditorConfig 设置进行格式化。 除非运行 代码清理 或 设置文档 格式命令，否则现有代码的格式不会更改。 有关详细信息，请参阅 “应用代码样式”。

代码一致性

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

当对个人项目使用的编码约定不同于团队项目中使用的约定时，EditorConfig 文件非常有用。 例如，你可能偏好缩进在代码中添加一个制表符。 但是，你的团队可能偏好缩进添加四个空格。 EditorConfig 文件通过允许针对每个场景进行配置来解决此问题。

因为代码库中的 .editorconfig 文件包含 EditorConfig 设置，因此它们会随着代码库一起传输。 只要在符合 EditorConfig 的编辑器中打开代码文件，文本编辑器设置将激活。

注释

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

支持的设置

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

  • 缩进样式 (indent_style)
  • indent_size
  • tab_width
  • end_of_line
  • 字符集
  • 删除尾随空格
  • 插入最终换行符
  • 根

EditorConfig 支持所有 Visual Studio 支持的语言，但 XML 支持 EditorConfig 编辑器设置除外。

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

添加和删除 EditorConfig 文件

将 EditorConfig 文件添加到项目或代码库时，Visual Studio 将设置根据 EditorConfig 文件设置编写的任何新代码行的格式。 但是，在设置文档格式或运行 代码清理之前，Visual Studio 不会将现有样式转换为新样式。 例如，如果文件中的缩进格式为制表符，并且你添加一个 EditorConfig 文件，以空格格式缩进，则缩进字符不会自动转换为空格。 设置文档的格式（选择“编辑>高级>格式文档”或按 CtrlK、Ctrl++D）时，EditorConfig 文件中的空白设置将应用于现有代码行。

如果从项目或代码库中删除 EditorConfig 文件，您必须关闭并重新打开任何打开的代码文件，以便全局编辑器设置能影响新代码行。

添加 EditorConfig 文件的方法

可通过多种方式向项目添加 EditorConfig 文件：

从代码样式设置生成 EditorConfig

可以手动填充 EditorConfig 文件，也可以根据 Visual Studio 选项 对话框中选择的代码样式设置自动生成该文件。 “ 工具>选项>”文本编辑器> [C# | C/C++ | Visual Basic] >代码样式>常规中提供了此选项页。 单击“通过设置生成 .editorconfig 文件”，基于此“选项”页上的设置来自动生成编码样式 .editorconfig 文件。

“从设置生成编辑器配置文件”的屏幕截图。

可以手动填充 EditorConfig 文件，也可以根据 Visual Studio 选项 对话框中选择的代码样式设置自动生成该文件。 此选项页可在 工具>选项>文本编辑器> [C# 或 基本] >代码样式>常规下找到。 单击“通过设置生成 .editorconfig 文件”，基于此“选项”页上的设置来自动生成编码样式 .editorconfig 文件。

“从设置生成编辑器配置文件”的屏幕截图。

将 EditorConfig 文件添加到项目

若要将 EditorConfig 文件添加到项目或解决方案，请执行以下步骤：

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

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

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

  3. 在搜索框中，输入 editorconfig。

    搜索结果中显示了两个 编辑器配置文件 项模板。

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

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

    解决方案资源管理器中会显示一个新 .editorconfig 文件，并在编辑器中作为新选项卡打开。

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

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

文件层次结构和优先级

将文件添加到 .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#>Tabs 设置设置为在按 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 约定的范围，请在存储库根目录的文件或项目所在的目录中设置 root=true 属性 .editorconfig 。

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

相关内容