在 Visual Studio 中配置 C/C++ 包含清理

从 17.8 预览版 1 开始，Visual Studio 可以清理你 #include 的文件，并通过以下方式提高 C 和 C++ 代码的质量：

• 为仅因所需头文件被另一个头文件间接包含而得以编译的代码提供添加头文件的功能。
• 提供移除未使用头文件的功能，从而缩短构建时间。

本文介绍如何在 Visual Studio 中配置 Include 清理。 有关 Include 清理的详细信息，请参阅 C/C++ Include 清理概述。

启用包含清理

默认情况下，“包括清理”功能处于关闭状态。

选择 “工具>选项>文本编辑器>C/C++>代码清理 ”并选择“ 启用 #include 清理”来启用它。

然后使用下拉列表配置有关可添加间接标头或移除未使用标头的通知的严重级别：

“启用 #include 清理”复选框已选中。 会显示“删除未使用包含项的建议级别”和“添加缺失包含项的建议级别”的下拉列表。 下拉列表中显示的内容分别为：“仅重构”“建议”“警告”和“错误”。 “删除未使用的包含指令建议级别”下拉列表提供相同的选项，另外还增加了“灰显”选项。

这些选项控制 Include Cleanup 功能针对未使用标头提供的通知类型：

灰显

Include Cleanup 通过在代码编辑器中将未使用头文件所在行显示为灰显，并在 Error List 窗口中显示一条消息，来显示未使用的头文件。 在代码编辑器中，将光标悬停在灰色 #include 上方以显示快速操作菜单，然后选择 “显示潜在修补程序”，或单击灯泡下拉列表以查看与未使用的文件相关的操作。

#include < iostream > 这一行会变灰，因为使用 iostream 的那行代码被注释掉了。该代码行是 // std::cout << "charSize = " << charSize; 此行的快速操作菜单也是可见的。 它表示此文件中未使用 #include < iostream >，并且具有“显示潜在修补程序”的链接。

仅限重构：当你将鼠标指针悬停在 #include 上，或将光标置于 #include 行并按 Ctrl+. 时，“包含清理”会在代码编辑器的快速操作菜单中提供可执行的操作：

如果将光标悬停在 # include iostream 上，将会显示一个灯泡，其文本内容为“此文件未使用 # include iostream。”

建议、警告、错误：“包括清理”可以在 “错误列表 ”窗口中将“包括清理”消息显示为建议、警告或错误。 由你决定选择哪个。 在如下的 错误列表 屏幕截图中，“Include Cleanup”已配置为以警告形式显示未使用的头文件。 确保在下拉筛选器中选择“Build + Intellisense”，这样您就可以看到 Include Cleanup 输出：

下拉筛选器设为“Build + IntelliSense”。 警告可见：VCIC002 - 此文件中未使用“#include ”。

其他配置选项

“工具>>>>”下提供了更多 Include Cleanup 设置：

• 对 include 进行排序：标记需要排序的 #include 指令。 选择“ 错误列表 ”窗口中显示的消息的严重性通知级别： “无 ”（功能已关闭）、 建议、 警告或 错误。
• 样式：控制语句的排序方式 #include 。 选择 忽略 可在排序时不考虑括号样式，选择 引号 可将带引号的 include 排在尖括号 include 之前，或选择 尖括号 可将尖括号 include 排在带引号的 include 之前。
• 区分大小写：选中时，排序时会以区分大小写的方式比较文件名。 清除后，排序不区分大小写。

使用 .editorconfig 配置包含清理

Include Cleanup 功能具有更多选项，例如从清理建议中排除指定的包括，并指示某些头文件是必需的，因此该工具不会将它们标记为未使用。 在 .editorconfig 文件中定义这些选项。 将此文件添加到项目，为在代码库中工作的每个人强制实施一致的编码样式。 有关将 .editorconfig 文件添加到项目的详细信息，请参阅使用 EditorConfig 创建可移植的自定义编辑器设置。

可与 Include 清理功能配合使用的 .editorconfig 设置包括：

设置	值	示例
cpp_include_cleanup_add_missing_error_tag_type 设置添加传递包含消息的错误级别。	none suggestion warning error	cpp_include_cleanup_add_missing_error_tag_type = suggestion
cpp_include_cleanup_alternate_files 屏蔽间接包含的信息。 例如，如果你 #include <windows.h>，并且只使用其间接包含的标头文件 winerror.h 或 minwindef.h 中的内容，该工具不会建议添加这些标头文件。	file1：file2[：file3...][，file4：file5...]	cpp_include_cleanup_alternate_files = windows.h:winerror.h:minwindef.h 或 cpp_include_cleanup_alternate_files = windows.h:winerror.h:minwindef.h,umbrella.h:internal.h
cpp_include_cleanup_excluded_files 将指定文件排除在 Include Cleanup 消息之外。 您根本不会收到与标题相关的建议，无论是添加它还是它未使用。	filename	cpp_include_cleanup_excluded_files = vcruntime.h, vcruntime_string.h
cpp_include_cleanup_remove_unused_error_tag_type 设置“移除未使用的 include”消息的错误级别。	none suggestion warning error dimmed	cpp_include_cleanup_remove_unused_error_tag_type = dimmed
cpp_include_cleanup_replacement_files 在 Include 清理处理期间将 file1 替换为 file2。 例如，你可能更喜欢使用 cstdio 而不是 stdio.h。 如果某个文件同时包含 #include <cstdio> 和 #include <stdio.h>，并且你仅使用来自 stdio.h 的内容，那么启用 Include Cleanup 时，它会提示你移除 stdio.h，因为它在处理过程中已将对 cstdio 的使用替换为对 stdio.h 的使用。 如果这两者中的内容你都不使用，Include Cleanup 会提示你将它们都移除。	file1：file2	cpp_include_cleanup_replacement_files = stdio.h:cstdio,stdint.h:cstdint
cpp_include_cleanup_required_files 指定 file1 的使用需要 file2。 例如，指定如果使用 atlwin.h，则还必须包含 altbase.h。	file1：file2	cpp_include_cleanup_required_files = atlwin.h:altbase.h, atlcom.h:altbase.h
cpp_sort_includes_error_tag_type 设置 sort-includes 消息的错误级别。 none 关闭该功能。 suggestion显示...波浪线，并将一条消息添加到错误列表中。 warning 显示绿色波浪线并添加警告。 error 显示红色波浪线并标记错误。	none suggestion warning error	cpp_sort_includes_error_tag_type = suggestion
cpp_sort_includes_priority_case_sensitive 当 true 时，排序比较会区分大小写地比较文件名。 当 false 时，排序不区分大小写。	true false	cpp_sort_includes_priority_case_sensitive = false
cpp_sort_includes_priority_style 控制排序是否考虑方括号样式。 ignore 排序而不考虑方括号。 quoted 将带引号的 include 排在尖括号 include 之前。 angle_brackets 将尖括号形式的 include 排在引号形式的 include 之前。	ignore quoted angle_brackets	cpp_sort_includes_priority_style = quoted

另请参阅

C/C++ 包含清理概述
包括清理消息