Definir estilos de codificação consistentes com EditorConfig

Para impor estilos de codificação consistentes para todos que trabalham em uma base de código, você pode adicionar um arquivo EditorConfig à sua solução ou projeto. As configurações do arquivo EditConfig seguem uma especificação de formato de arquivo mantida pela EditorConfig.org. Muitos editores de código e aplicativos oferecem suporte a arquivos EditorConfig, incluindo o Visual Studio. Ele é um componente portátil que acompanha o seu código e pode impor estilos de codificação mesmo fora do Visual Studio.

No Visual Studio, as configurações do arquivo EditorConfig têm precedência sobre as configurações globais do editor de texto (acessadas selecionando Editor de Texto na caixa de diálogo Ferramentas>Opções). Isso significa que é possível personalizar cada base de código para usar as configurações de editor de texto específicas para esse projeto. Quando usa arquivos EditorConfig, você ainda pode continuar a definir suas próprias preferências de editor pessoal no editor de texto do Visual Studio. Essas configurações do editor de texto se aplicam sempre que você trabalha em uma base de código sem um arquivo EditorConfig ou quando o arquivo EditorConfig não substitui uma configuração específica. Um exemplo dessa preferência é usar guias ou espaços para o estilo de recuo de código.

Quando você adiciona um arquivo EditorConfig ao projeto no Visual Studio, somente novas linhas de código são formatadas com base nas configurações de EditorConfig. A formatação do código existente não será alterada a menos que você execute um dos seguintes comandos:

• Limpeza de código.

  Selecione Limpeza de código no editor do Visual Studio, ou pressione Ctrl+K, Ctrl+E. Esse comando aplica-se a configurações de espaço em branco, como estilo de recuo, e configurações de estilo de código selecionadas, como preferências de parênteses.

• Formatar Documento.

  Selecione Edit>Avançado>Formatar Documento, ou pressione Ctrl+K, Ctrl+D no perfil padrão. Esse comando aplica-se somente a configurações de espaço em branco, como estilo de recuo.

Observação

Este tópico aplica-se ao Visual Studio para Windows. Para o Visual Studio para Mac, consulte Criar e editar um arquivo EditorConfig personalizado no Visual Studio para Mac.

Consistência do código

As configurações do arquivo EditorConfig permitem que você mantenha estilos e convenções de codificação consistentes em uma base de código, independentemente do editor ou IDE usado. Alguns estilos de codificação que você pode controlar são estilo de recuo, largura de tabulação, caracteres de fim de linha e codificação. Por exemplo, se sua base de código C# tiver uma convenção que recua usando cinco caracteres de espaço, os documentos usam codificação UTF-8 e as linhas terminam com CR/LF, você pode configurar um arquivo EditorConfig para usar essa convenção.

Os arquivos EditorConfig são úteis quando as convenções de codificação que você usa em seus projetos pessoais diferem daquelas convenções usadas nos projetos de sua equipe. Por exemplo, talvez você prefira que um recuo adicione um caractere de tabulação no seu código. Porém, sua equipe pode preferir que um recuo adicione quatro espaços. Arquivos EditorConfig resolvem esse problema permitindo que você tenha uma configuração para cada cenário.

Como um arquivo .editorconfig na base de código contém as configurações de EditorConfig, elas viajam juntamente com essa base de código. Desde que você abra o arquivo de código em um editor em conformidade com EditorConfig, as configurações do editor de texto são ativadas.

Configurações com suporte

O editor no Visual Studio é compatível com o conjunto principal de propriedades do EditorConfig:

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

O EditorConfig é compatível com todas as linguagens com suporte do Visual Studio, exceto configurações do editor EditorConfig com suporte para XML.

O EditorConfig dá suporte a convenções de estilo de código, incluindo linguagem, formatação e convenções de nomenclatura para C# e Visual Basic.

Adicionar e remover arquivos EditorConfig

Quando você adiciona um arquivo EditorConfig ao seu projeto ou base de código, o Visual Studio formata qualquer linha de código nova que você escreve de acordo com o arquivo EditorConfig. No entanto, o Visual Studio não converte estilos existentes em novos até que você formate o documento ou execute uma Limpeza de Código. Por exemplo, se os recuos no arquivo formatados com tabulações e adicionar um arquivo EditorConfig com recuos com espaços, os caracteres de recuo não serão convertidos automaticamente em espaços. Quando você formata o documento (selecione Editar>Avançado>Formatar Documento ou pressione Ctrl+K, Ctrl+D), as configurações de espaço em branco no arquivo EditorConfig são aplicadas às linhas de código existentes.

Se você remover um arquivo EditorConfig do seu projeto ou da base de código, será necessário fechar e reabrir os arquivos de código aberto para as configurações globais do editor entrarem em vigor nas novas linhas de código.

Adicionar um arquivo EditorConfig a um projeto

Para adicionar um arquivo EditorConfig ao seu projeto ou solução, execute estas etapas:

1. Abra um projeto ou uma solução no Visual Studio. Selecione o nó da solução ou do projeto, dependendo se as configurações de EditorConfig devem ser aplicadas a todos os projetos na solução ou a apenas um. Também é possível selecionar uma pasta no projeto ou na solução para adicionar o arquivo .editorconfig.

2. No menu, selecione Projeto>Adicionar Novo Item, ou pressione Ctrl+Shift+A.

   A caixa de diálogo Adicionar Novo Item é aberta.

3. Na caixa de pesquisa, digite editorconfig.

   Dois modelos de item de Arquivo editorconfig são mostrados nos resultados da pesquisa.

   

4. Selecione o modelo Arquivo editorconfig (vazio) para adicionar um arquivo EditorConfig pré-preenchido com opções padrão do EditorConfig para espaço em branco, estilo de código e convenções de nomenclatura. Ou selecione o modelo Arquivo editorconfig (.NET) para adicionar um arquivo EditorConfig pré-preenchido com convenções de nomenclatura, espaço em branco .NET e estilo de código .NET.

   Um novo arquivo .editorconfig aparece no Gerenciador de Soluções, que é aberto no editor como uma nova guia.

   

5. Opcionalmente, edite o arquivo e salve-o.

Outras formas de adicionar um arquivo EditorConfig

Há algumas outras maneiras de adicionar um arquivo EditorConfig ao projeto:

• Use o IntelliCode para Visual Studio para gerar um arquivo .editorconfig na sua solução. Clique com o botão direito do mouse no Gerenciador de Soluções e selecione Adicionar>Novo EditorConfig (IntelliCode) no menu de contexto. O IntelliCode para Visual Studio infere seus estilos de código do código existente e, em seguida, cria um arquivo EditorConfig com suas preferências de estilo de código predefinidas.

• Gere automaticamente um arquivo EditorConfig com base em suas configurações de estilo de código.

Precedência e hierarquia de arquivos

Quando você adiciona um arquivo .editorconfig a uma pasta em sua hierarquia de arquivos, as configurações se aplicam a todos os arquivos aplicáveis nesse nível e abaixo dele. Você também pode substituir as configurações de EditorConfig para um projeto específico, uma base de código ou parte de uma base de código, de modo que ele use convenções diferentes do que as outras partes da base de código. Isso pode ser útil quando você incorpora código de outro lugar e não quer alterar suas convenções.

Siga estas diretrizes:

• Para substituir algumas ou todas as configurações do EditorConfig, adicione um arquivo .editorconfig no nível da hierarquia de arquivos em que você deseja aplicar essas configurações substituídas. As novas configurações de arquivo do EditorConfig aplicam-se aos arquivos no mesmo nível e a arquivos em qualquer subpasta.

  

• Se você quiser substituir algumas, mas não todas as configurações, especifique apenas essas configurações no arquivo .editorconfig. Somente as propriedades que você listar explicitamente no arquivo de nível inferior .editorconfig são substituídas. As outras configurações de qualquer arquivo .editorconfig de nível superior continuam sendo aplicadas.

• Para garantir que nenhuma configuração de nenhum arquivo .editorconfig de nível superior seja aplicada a essa parte da base de código, adicione a propriedade root=true ao arquivo .editorconfig de nível inferior.

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

Os arquivos EditorConfig são lidos de cima para baixo. Se houver várias propriedades com o mesmo nome, a propriedade mais recente encontrada com o mesmo nome terá precedência.

Editar os arquivos EditorConfig

O Visual Studio 2022 fornece um editor visual para arquivos EditorConfig.

Depois de editar seu arquivo EditorConfig, será necessário recarregar seus arquivos de código para que as novas configurações entrem em vigor.

Exemplo

O exemplo a seguir mostra o estado de recuo de um snippet de código C# antes e depois de adicionar um arquivo .EditorConfig ao projeto:

1. Na caixa de diálogo Ferramentas>Opções, defina as configurações de Editor de texto>C#>Tabs para o editor de texto do Visual Studio para inserir quatro caracteres de espaço quando você pressionar a tecla Tab.

   

2. Conforme esperado, ao pressionar a tecla Tab na próxima linha, ele recua por meio da adição de quatro caracteres de espaço em branco.

   

3. Use EditorConfig para alterar a configuração de guias para usar guias.

   Selecione Usar Tabs no arquivo EditorConfig.

   

4. Ao pressionar a tecla Tab, agora você obtém caracteres de tabulação em vez de espaços.

   

Solução de problemas de configurações do EditorConfig

Se existir um arquivo do EditorConfig na estrutura do diretório no local do seu projeto ou acima desse local, o Visual Studio aplicará as configurações do editor nesse arquivo ao seu editor. Nesse caso, você poderá ver a seguinte mensagem na barra de status:

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

Isso significa que, se as configurações do editor em Ferramentas>Opções>Editor de Texto (como tamanho e estilo do recuo, tamanho da tabulação ou convenções de codificação) forem especificadas em um arquivo EditorConfig no projeto ou acima dele na estrutura de diretório, as convenções no arquivo EditorConfig substituirão as configurações no Editor de texto.

Para solucionar problemas do EditorConfig, siga estas etapas:

1. Para desativar o suporte a EditorConfig para Visual Studio, desmarque a opção Seguir convenções de codificação de projeto em Ferramentas>Opções>Editor de texto.

   

2. Para localizar quaisquer arquivos EditorConfig nos diretórios pai do seu projeto, abra um prompt de comando e execute o seguinte comando na raiz do disco que contém o seu projeto.

   dir .editorconfig /s
   

3. Para controlar o escopo das convenções do EditorConfig, configure a propriedade root=true no arquivo .editorconfig na raiz do seu repositório ou no diretório em que o projeto reside.

   O Visual Studio procurará um arquivo chamado .editorconfig no diretório do arquivo aberto e em todos os diretórios pai. A pesquisa terminará quando atingir o caminho do arquivo raiz ou se um arquivo .editorconfig com root=true for encontrado.

Conteúdo relacionado

• Opções de regra de estilo de código do .NET
• Suporte ao EditorConfig para o serviço de linguagem
• EditorConfig.org
• Recursos do editor de código
• Criando e editando um arquivo EditorConfig personalizado no Visual Studio para Mac