Configurar a limpeza de inclusões de C/C++ no Visual Studio

A partir da versão 17.8 Preview 1, o Visual Studio pode limpar os arquivos que você #include para melhorar a qualidade do seu código C e C++ das seguintes maneiras:

  • Oferece a adição de arquivos de cabeçalho para código que é compilado apenas porque um arquivo de cabeçalho necessário foi incluído indiretamente por outro arquivo de cabeçalho.
  • Oferece a remoção de arquivos de cabeçalho não utilizados, melhorando os tempos de compilação.

Este artigo descreve como configurar o Include Cleanup no Visual Studio. Para obter mais informações sobre o Include Cleanup, confira Visão geral do C/C++ Include Cleanup.

Ativar o Include Cleanup

O recurso Incluir Limpeza está desativado por padrão.

Ative isso selecionando Ferramentas>Opções>Editor de Texto>C/C++>Limpeza de Código e selecionando Habilitar limpeza de #include.

Em seguida, use os menus suspensos para configurar o nível de severidade das notificações sobre oportunidades de adicionar cabeçalhos indiretos ou remover cabeçalhos não utilizados:

A caixa de diálogo Opções de ferramentas foi aberta na Limpeza de Código C/C++ > do Editor > de Texto.

Essas opções controlam o tipo de notificação que o recurso Incluir Limpeza fornece sobre cabeçalhos não utilizados:

Esmaecido

A Limpeza de Inclusões mostra arquivos de cabeçalho não utilizados esmaecendo a linha do arquivo de cabeçalho não utilizado no editor de código e exibindo uma mensagem na janela Lista de Erros. No editor de código, passe o cursor sobre o item esmaecido #include para exibir o menu de ações rápidas e escolha Mostrar possíveis correções, ou clique no menu suspenso da lâmpada, para ver ações relacionadas ao arquivo não utilizado.

Uma captura de tela de uma linha iostream < #include > esmaecida.

Refatoração somente: incluir ações de limpeza que você pode executar por meio do menu de ação rápida no editor de código ao passar o ponteiro do mouse sobre um #includecursor ou colocar o cursor na #include linha e pressionar Ctrl+period:

Uma captura de tela da ação rápida para remover um cabeçalho não utilizado.

Sugestão, Aviso, Erro: o Include Cleanup pode exibir mensagens do Include Cleanup como sugestões, avisos ou erros na janela Lista de Erros. Você determina qual. Na captura de tela a seguir da Lista de Erros, a Limpeza de Inclusão está configurada para mostrar cabeçalhos não utilizados com um aviso. Verifique se Compilar + Intellisense está selecionada no filtro do menu suspenso para que você possa ver a saída do Include Cleanup:

Uma captura de tela da janela Lista de Erros.

Ative-o selecionando>>>>>Limpeza > de códigoIncluir limpeza. Use os menus suspensos para configurar como você deseja ser notificado sobre oportunidades de destacar diretivas #include não utilizadas, diretivas #include que podem ser otimizadas (removidas depois que as inclusões transitivas necessárias forem adicionadas diretamente) e diretivas #include ausentes que são incluídas por transitividade.

Uma captura de tela da caixa de diálogo Opções de Ferramentas aberta em Todas as Configurações > Idiomas > C/C++ > Limpeza de código > Limpeza de inclusões.

O significado das opções:

Esmaecido

A Limpeza de Inclusões mostra arquivos de cabeçalho não utilizados esmaecendo a linha do arquivo de cabeçalho não utilizado no editor de código e também como uma mensagem na janela Lista de Erros. No editor de código, passe o cursor sobre o item esmaecido #include para exibir o menu de ação rápida e escolha Mostrar possíveis correções, ou clique no menu suspenso da lâmpada, para ver ações relacionadas ao arquivo não utilizado.

Uma captura de tela de uma linha iostream < #include > esmaecida.

Nenhum: Não realizar nenhuma ação. A Limpeza de inclusões ainda oferece ações que você pode executar no editor de código por meio do menu de ações rápidas ao passar o ponteiro do mouse sobre um #include ou colocar o cursor na linha #include e pressionar Ctrl+ponto:

Sugestão, Advertência, Erro: O Include Cleanup pode exibir mensagens do Include Cleanup como sugestões, advertências ou erros na janela Lista de Erros. Você determina qual. Na captura de tela a seguir da Lista de Erros, a Limpeza de Inclusão está configurada para mostrar cabeçalhos não utilizados com um aviso. Verifique se Compilar + Intellisense está selecionada no filtro do menu suspenso para que você possa ver a saída do Include Cleanup:

Uma captura de tela da janela Lista de Erros.

Outras opções de configuração

Mais configurações de Limpeza de #include estão disponíveis em Ferramentas>Opções>Editor de Texto>C/C++>Limpeza de Código:

  • Ordenar inclusões: Sinaliza diretivas #include que precisam ser ordenadas. Escolha o nível de notificação de severidade da mensagem que aparece na janela Lista de Erros : Nenhum (o recurso está desativado), Sugestão, Aviso ou Erro.
  • Estilo: controla como #include as instruções são classificadas. Escolha Ignorar para ordenar sem considerar o tipo de delimitador, Aspas para ordenar os includes entre aspas acima dos includes entre colchetes angulares, ou Colchetes angulares para ordenar os includes entre colchetes angulares acima dos includes entre aspas.
  • Diferenciar maiúsculas de minúsculas: quando selecionada, a ordenação compara os nomes de arquivos diferenciando maiúsculas de minúsculas. Quando desmarcada, a classificação não diferencia maiúsculas de minúsculas.

Captura de tela das Opções do Visual Studio com filtragem avançada, ordenar após edições, ordenar inclusões, prioridade de ordenação, estilo e configuração de diferenciação entre maiúsculas e minúsculas destacados.

Mais configurações de Limpeza de inclusões estão disponíveis em Ferramentas>Opções>Todas as Configurações>Idiomas>C/C++>Limpeza de código>Limpeza de inclusões:

  • Filtragem Avançada: quando selecionada, se você chamar uma função membro em um objeto de classe derivada, mas a função for definida na classe base, a ferramenta não sugerirá a adição do cabeçalho de classe base. Ative essa opção para reduzir sugestões barulhentas quando os símbolos usados forem provenientes de classes base em vez do tipo que você referencia diretamente.
  • Classificar as diretivas #include depois de fazer quaisquer edições para a limpeza de includes: quando selecionado, o recurso interno de classificação de includes é executado após qualquer ação de Limpeza de Includes.
  • Formatar as diretivas #include após fazer edições para limpeza de inclusões: Quando selecionado, o comando de formatação é executado após qualquer ação de limpeza de inclusões.

Captura de tela das opções de limpeza de includes do Visual Studio, com as configurações de filtragem avançada, classificação e formatação destacadas.

Configurar o Include Cleanup com .editorconfig

O recurso Include Cleanup tem mais opções, como excluir includes especificados das sugestões de limpeza e indicar que alguns arquivos de cabeçalho são necessários para que a ferramenta não os marque como não utilizados. Defina essas opções em um .editorconfig arquivo. Adicione esse arquivo ao seu projeto para impor estilos de codificação consistentes para todos que funcionam na base de código. Para obter mais informações sobre como adicionar um arquivo .editorconfig ao seu projeto, confira Criar configurações de editor portáteis e personalizadas com o EditorConfig.

As configurações de .editorconfig que você pode usar com o Include Cleanup são:

Configuração Valores Exemplo
cpp_include_cleanup_add_missing_error_tag_type

Define o nível de erro para adicionar mensagens de inclusão transitivas.		 none
suggestion
warning
error		 cpp_include_cleanup_add_missing_error_tag_type = suggestion
cpp_include_cleanup_alternate_files

Suprimir mensagens para inclusões indiretas. Por exemplo, se você #include <windows.h> e usar apenas o conteúdo dos arquivos de cabeçalho incluídos indiretamente winerror.h ou minwindef.h, a ferramenta não sugerirá incluí-los.		 file1:file2[:file3...][,file4:file5...] cpp_include_cleanup_alternate_files = windows.h:winerror.h:minwindef.h
Ou
cpp_include_cleanup_alternate_files = windows.h:winerror.h:minwindef.h,umbrella.h:internal.h
cpp_include_cleanup_excluded_files

Exclui os arquivos especificados das mensagens do Include Cleanup. Você não receberá uma sugestão relacionada ao cabeçalho, seja para adicioná-lo ou caso ele não seja utilizado.		 filename cpp_include_cleanup_excluded_files = vcruntime.h, vcruntime_string.h
cpp_include_cleanup_remove_unused_error_tag_type

Define o nível de erro para remover mensagens de inclusão não usadas.		 none
suggestion
warning
error
dimmed		 cpp_include_cleanup_remove_unused_error_tag_type = dimmed
cpp_include_cleanup_replacement_files

Substitui file1 por file2 durante o processamento do Include Cleanup. Por exemplo, você pode preferir usar cstdio, em vez de stdio.h. Se você tiver um arquivo com #include <cstdio> e #include <stdio.h>, e você consumir conteúdo somente de stdio.h, com essa configuração, o Include Cleanup indicará que você remova stdio.h, porque ele substituiu o uso de cstdio por stdio.h durante o processamento. Se você não usar o conteúdo de nenhum dos dois, o recurso Include Cleanup indicará que você remova ambos.		 file1:file2 cpp_include_cleanup_replacement_files = stdio.h:cstdio,stdint.h:cstdint
cpp_include_cleanup_required_files

Especifique que o uso de file1 exige file2. Por exemplo, especifique que, se você usar atlwin.h, altbase.h também deve ser incluído.		 file1:file2 cpp_include_cleanup_required_files = atlwin.h:altbase.h, atlcom.h:altbase.h
cpp_sort_includes_error_tag_type

Define o nível de erro das mensagens de sort-includes. none desativa o recurso. suggestion mostra um ... rabiscos e adiciona uma mensagem à lista de erros. warning mostra um rabiscos verde e adiciona um aviso. error mostra um rabiscos vermelhos e adiciona um erro.		 none
suggestion
warning
error		 cpp_sort_includes_error_tag_type = suggestion
cpp_sort_includes_priority_case_sensitive

Quando true, as comparações de ordenação consideram nomes de arquivo com distinção entre maiúsculas e minúsculas. Quando false, a classificação não diferencia letras maiúsculas de minúsculas.		 true
false		 cpp_sort_includes_priority_case_sensitive = false
cpp_sort_includes_priority_style

Controla se a ordenação leva em conta o tipo de colchete. ignore classifica sem considerar colchetes. quoted as classificações entre aspas incluem o colchete angular acima. angle_brackets ordena as diretivas de inclusão entre sinais de menor e maior acima das diretivas de inclusão entre aspas.		 ignore
quoted
angle_brackets		 cpp_sort_includes_priority_style = quoted

As seguintes configurações estão disponíveis a partir do Visual Studio 2026:

Configuração Valores Exemplo
cpp_include_cleanup_format_after_edits

Quando true, executa o comando de formatação após qualquer ação de limpeza incluída. Útil quando você tem o clang-format configurado para ordenar suas diretivas #include.		 true
false		 cpp_include_cleanup_format_after_edits = true
cpp_include_cleanup_sort_after_edits

Quando true, executa o recurso de classificação interno inclui após qualquer ação Incluir Limpeza. Útil quando você não estiver usando o formato clang para classificar suas #include diretivas.		 true
false		 cpp_include_cleanup_sort_after_edits = true

Suprimir mensagens não incluídas por meio do código

A partir do Visual Studio 2026, você pode suprimir mensagens de Include Cleanup em uma única diretiva #include adicionando um comentário // VCIC-Excluded na mesma linha. A ferramenta Incluir Limpeza não sugere a remoção dessa inclusão, mesmo que ela pareça não usada. Forneça texto de justificativa opcional após o marcador para que os leitores futuros saibam por que a inclusão está lá:

#include "Header2.h" // VCIC-Excluded: needed for the ATL macros used below

Você também pode usar o menu da lâmpada para adicionar o comentário // VCIC-Excluded a uma diretiva #include. Verifique se a Limpeza de includes está ativada em Ferramentas>Opções>Todas as Configurações>Linguagens>C/C++>Limpeza de código>Limpeza de includes, pois essa opção vem desativada por padrão. Em seguida, passe o cursor sobre a linha #include, selecione Outras correções> e Suprimir VCIC002 no código-fonte::

Captura de tela do menu da lâmpada do Visual Studio, mostrando Suprimir VCIC002 no código-fonte.

O comentário // VCIC-Excluded se aplica somente ao #include do arquivo. Definir cpp_include_cleanup_excluded_files em .editorconfig faz com que essa exclusão se aplique a todos os arquivos regidos por .editorconfig.

Confira também

Visão geral do C/C++ Include Cleanup
Incluir mensagens de limpeza

  • Last updated on