Definir estilos de codificação consistentes com EditorConfig

Para impor estilos de codificação consistentes para todos que funcionam em uma base de código, você pode adicionar um .editorconfig arquivo à sua solução ou projeto. As configurações de arquivo EditorConfig aderem a uma especificação de formato de arquivo mantida por EditorConfig.org. Muitos editores de código e aplicativos dão suporte a arquivos EditorConfig, incluindo o Visual Studio. Como as configurações estão em um arquivo, elas acompanham seu código e podem ser usadas mesmo fora do Visual Studio.

No Visual Studio, as configurações de arquivo EditorConfig têm precedência sobre as várias configurações globais do editor de texto disponíveis em Ferramentas>Opções>Editor de Texto>[C# | C/C++ | Visual Basic]>Estilo de Código. Você pode usar um arquivo EditorConfig para personalizar cada base de código para usar as configurações do editor de texto específicas para esse projeto.

Você pode preencher manualmente um arquivo EditorConfig ou gerá-lo automaticamente com base nas configurações de estilo de código escolhidas no Visual Studio. Para obter mais informações, consulte Maneiras de adicionar um arquivo EditorConfig.

Ao usar um arquivo EditorConfig, você ainda pode continuar definindo suas preferências de editor pessoal no editor de texto do Visual Studio. Essas configurações do editor de texto se aplicam sempre que você estiver trabalhando em uma base de código sem um arquivo EditorConfig ou quando o arquivo EditorConfig não substituir uma configuração específica. Um exemplo de tal preferência é a escolha entre usar tabulações ou espaços para o estilo de indentação do código.

Quando você adiciona um arquivo EditorConfig ao seu projeto no Visual Studio, apenas novas linhas de código são formatadas com base nas configurações do EditorConfig. A formatação do código existente não é alterada, a menos que você execute os comandos Limpeza de Código ou Formatar Documento . Para obter mais informações, consulte Aplicar estilos de código.

Consistência de código

As configurações de arquivo EditorConfig permitem manter convenções e estilos 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 da guia, caracteres de fim de linha e codificação. Por exemplo, se a base de código do C# tiver uma convenção de que os recuos usam 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 usadas em seus projetos pessoais diferem das convenções usadas nos projetos da sua equipe. Por exemplo, você pode preferir que um recuo adicione um caractere de guia em seu código. No entanto, sua equipe pode preferir que um recuo adicione quatro espaços. Os arquivos EditorConfig resolvem esse problema permitindo que você tenha uma configuração para cada cenário.

Como um .editorconfig arquivo na base de código contém as configurações de EditorConfig, eles viajam junto com essa base de código. Desde que você abra o arquivo de código em um editor compatível com EditorConfig, as configurações do editor de texto serão ativadas.

Definições suportadas

O editor no Visual Studio dá suporte ao conjunto principal de propriedades EditorConfig:

• indent_style
• tamanho_de_indentação
• largura_da_tabulação
• fim_de_linha
• conjunto de caracteres
• trim_trailing_whitespace
• insert_final_newline
• raiz

O EditorConfig dá suporte a todos os idiomas compatíveis com o Visual Studio, exceto para configurações do editor EditorConfig de suporte XML.

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

Adicionar e remover arquivos EditorConfig

Quando você adiciona um arquivo EditorConfig ao projeto ou à base de código, o Visual Studio formata todas as novas linhas de código que você escreve de acordo com as configurações do arquivo EditorConfig. No entanto, o Visual Studio não converte estilos existentes nos novos até que você formate o documento ou execute a Limpeza de Código. Por exemplo, se os recuos em seu arquivo forem formatados com guias e você adicionar um arquivo EditorConfig que formate recuos com espaços, os caracteres de recuo não serão convertidos automaticamente em espaços. Quando você formata o documento (selecione Editar>Documento de Formato> 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 projeto ou da base de código, deverá fechar e reabrir todos os arquivos de código abertos para que as configurações do editor global afetem novas linhas de código.

Maneiras de adicionar um arquivo EditorConfig

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

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

• Adicione manualmente o arquivo EditorConfig.

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

Gerar um EditorConfig a partir de configurações de estilo de código

Você pode preencher manualmente o arquivo EditorConfig ou gerar automaticamente o arquivo com base nas configurações de estilo de código escolhidas na caixa de diálogo Opções do Visual Studio. Esta página de opções está disponível em Ferramentas>Opções>Editor de Texto> [C# | C/C++ | Visual Basic] >Estilo de Código>Geral. Clique em Gerar arquivo .editorconfig das configurações para gerar automaticamente um arquivo .editorconfig de estilo de codificação com base nas configurações na página Opções.

Adicionar um arquivo EditorConfig a um projeto

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

1. Abra um projeto ou solução no Visual Studio. Selecione a solução ou o nó do projeto, dependendo se as configurações do EditorConfig devem ser aplicadas a todos os projetos na solução ou apenas a um. Você também pode selecionar uma pasta em seu projeto ou solução para adicionar o .editorconfig arquivo.

2. No menu, escolha Project>Add New Item ou pressione Ctrl+Shift+A.

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

3. Na caixa de pesquisa, insira a configuração do editor.

   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 as opções padrão EditorConfig para espaço em branco, estilo de código e convenções de nomenclatura. Ou selecione o modelo de arquivo editorconfig (.NET) para adicionar um arquivo EditorConfig pré-preenchido com o espaço em branco padrão do .NET, o estilo de código e as convenções de nomenclatura.

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

   

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

Hierarquia e precedência de arquivos

Quando você adiciona um .editorconfig arquivo a uma pasta em sua hierarquia de arquivos, suas configurações se aplicam a todos os arquivos aplicáveis nesse nível e inferiores. 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 ela use convenções diferentes de outras partes da base de código. Isso pode ser útil quando você incorpora o código de outro lugar e não deseja alterar suas convenções.

Siga estas diretrizes:

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

  

• Se você quiser substituir algumas, mas não todas as configurações, especifique apenas essas configurações no .editorconfig arquivo. Somente as propriedades que você lista explicitamente no arquivo de nível .editorconfig inferior são substituídas. Outras configurações de arquivos de nível superior .editorconfig ainda continuam aplicáveis.

• Se você quiser garantir que nenhuma configuração de arquivos de nível .editorconfig superior seja aplicada a essa parte da base de código, adicione a root=true propriedade ao arquivo de nível .editorconfig 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 encontrada mais recentemente com o mesmo nome terá precedência.

Editar arquivos EditorConfig

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

Depois de editar o arquivo EditorConfig, você deve recarregar os 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álogoOpções de >, defina as configurações de>do > de Texto para o editor de texto do Visual Studio para produzir quatro caracteres de espaço quando você pressionar a tecla Tab.

   

2. Como esperado, quando você pressiona a tecla Tab na próxima linha, ela recuará a linha adicionando quatro caracteres de espaço em branco.

   

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

   Selecione Usar Guias no arquivo EditorConfig.

   

4. Quando você pressiona a tecla Tab , os caracteres de tabulação agora aparecem em vez de espaços.

   

Solucionar problemas de configurações do EditorConfig

Se houver um arquivo EditorConfig em qualquer lugar na estrutura do diretório no local ou acima do seu projeto, o Visual Studio aplicará as configurações do editor nesse arquivo ao editor. Nesse caso, você pode 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 quaisquer configurações do editor no Ferramentas>Opções>Editor de Texto (como tamanho e estilo de recuo, tamanho da guia ou convenções de codificação) forem especificadas em um arquivo EditorConfig no mesmo nível ou acima do projeto na estrutura de diretórios, 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 do EditorConfig para Visual Studio, desmarque a opção Seguir convenções de codificação de projeto noEditor de Texto>>.

   

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

   dir .editorconfig /s
   

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

   O Visual Studio procura um arquivo nomeado .editorconfig no diretório do arquivo aberto e em todos os diretórios pai. A pesquisa termina quando atinge o caminho do arquivo raiz ou se um .editorconfig arquivo com root=true é encontrado.

Conteúdo relacionado

• Opções de regra de estilo de código para .NET
• Suporte ao EditorConfig para seu serviço de idioma
• EditorConfig.org
• Características do editor de código
• Arquivos de configuração para regras de análise de código