Defina estilos de codificación consistentes con EditorConfig

Para imponer estilos de codificación consistentes para todos los que trabajan en una base de código, puede añadir un archivo EditorConfig a su solución o proyecto. La configuración del archivo EditorConfig se adhiere a una especificación de formato de archivo mantenida por EditorConfig.org. Muchos editores de código y aplicaciones soportan archivos EditorConfig, incluyendo Visual Studio. Es un componente portátil que acompaña al código y se pueden aplicar estilos de codificación incluso fuera de Visual Studio.

En Visual Studio, la configuración del archivo EditorConfig tiene prioridad sobre la configuración global del editor de texto (a la que se accede seleccionando Editor de texto en el cuadro de diálogo Herramientas>Opciones). Esto significa que puede adaptar cada código base para que use la configuración del editor de texto específica para ese proyecto. Cuando utilice los archivos EditorConfig, podrá seguir configurando sus preferencias personales de editor en el editor de texto de Visual Studio. Estos ajustes del editor de texto se aplican siempre que trabajes en una base de código sin un archivo EditorConfig, o cuando el archivo EditorConfig no anula un ajuste concreto. Un ejemplo de este tipo de preferencias es si utilizar tabuladores o espacios para el estilo de sangría del código.

Cuando añade un archivo EditorConfig a su proyecto en Visual Studio, solo las nuevas líneas de código se formatean en función de la configuración de EditorConfig. El formato del código existente no cambia, a menos que ejecute uno de los comandos siguientes:

• Limpieza de código.

  Seleccione Limpieza de código en el editor de Visual Studio, o pulse Ctrl+K, Ctrl+E. Este comando se aplica a los ajustes de espacio en blanco, como el estilo de sangría, y a los ajustes de estilo de código seleccionados, como las preferencias de paréntesis.

• Formatear documento.

  Seleccione Edición>Avanzada>Formatear Documento, o pulse Ctrl+K, Ctrl+D en el perfil por defecto. Este comando solo se aplica a los ajustes de espacio en blanco, como el estilo de sangría.

Nota:

Este tema se aplica a Visual Studio para Windows. Para Visual Studio para Mac, consulte Creación y edición de un archivo EditorConfig personalizado en Visual Studio para Mac.

Coherencia del código

La configuración del archivo EditorConfig le permite mantener estilos y convenciones de codificación coherentes en una base de código, independientemente del editor o IDE que utilice. Algunos estilos de codificación que puede controlar son el estilo de sangría, el ancho de tabulación, los caracteres de fin de línea y la codificación. Por ejemplo, si su base de código C# tiene una convención por la que las sangrías utilizan cinco caracteres de espacio, los documentos utilizan codificación UTF-8, y las líneas terminan con CR/LF, puede configurar un archivo EditorConfig para utilizar esta convención.

Los archivos EditorConfig son útiles cuando las convenciones de codificación que utiliza en sus proyectos personales difieren de las convenciones utilizadas en los proyectos de su equipo. Por ejemplo, usted puede preferir que una sangría añada un carácter de tabulación en su código. Sin embargo, su equipo puede preferir que una sangría añada cuatro espacios en su lugar. Los archivos EditorConfig le permiten tener una configuración para cada escenario a fin de resolver este problema.

Debido a que un archivo .editorconfig en la base de código contiene la configuración de EditorConfig, viajan junto con esa base de código. Siempre que abra el archivo de código en un editor compatible con EditorConfig, la configuración del editor de texto se activará.

Configuración admitida

El editor de Visual Studio admite el conjunto principal de propiedades de EditorConfig:

• indent_style
• indent_size
• tab_width
• end_of_line
• charset
• trim_trailing_whitespace
• insert_final_newline
• raíz

EditorConfig admite todos los lenguajes compatibles con Visual Studio, excepto XML, que admite la configuración del editor EditorConfig.

EditorConfig admite convenciones de estilo de código, incluidas convenciones de lenguaje, formato y nomenclatura para C# y Visual Basic.

Incorporación y eliminación de los archivos EditorConfig

Cuando añades un archivo EditorConfig a tu proyecto o base de código, Visual Studio da formato a cualquier nueva línea de código que escribas de acuerdo con la configuración del archivo EditorConfig. Sin embargo, Visual Studio no convierte los estilos existentes a los nuevos hasta que se formatea el documento o se ejecuta Limpieza de código. Por ejemplo, si las sangrías de su archivo están formateadas con tabuladores y añade un archivo EditorConfig que formatea las sangrías con espacios, los caracteres de sangría no se convierten automáticamente en espacios. Cuando formatea el documento (seleccione Edición>Avanzada>Formatear Documento o pulse Ctrl+K, Ctrl+D), la configuración de espacios en blanco del archivo EditorConfig se aplica a las líneas de código existentes.

Si elimina un archivo EditorConfig de su proyecto o base de código, debe cerrar y volver a abrir cualquier archivo de código abierto para que la configuración global del editor afecte a las nuevas líneas de código.

Agregar un archivo EditorConfig a un proyecto

Para añadir un archivo EditorConfig a su proyecto o solución, siga estos pasos:

1. Abra un proyecto o una solución en Visual Studio. Seleccione el nodo de la solución o del proyecto, dependiendo de si la configuración de EditorConfig debe aplicarse a todos los proyectos de la solución o solo a uno. También puede seleccionar una carpeta del proyecto o de la solución donde agregar el archivo .editorconfig.

2. En el menú, seleccione Proyecto>Añadir nuevo elemento, o pulse Ctrl+Mayús+A.

   Se abrirá el cuadro de diálogo Agregar nuevo elemento.

3. En el cuadro de búsqueda, introduzca editorconfig.

   Se muestran dos plantillas de elemento Archivo editorconfig en los resultados de búsqueda.

   

4. Seleccione la plantilla editorconfig File (vacía) para añadir un archivo EditorConfig con las opciones predeterminadas de EditorConfig para espacios en blanco, estilo de código y convenciones de nomenclatura. O bien, seleccione la plantilla editorconfig File (.NET) para añadir un archivo EditorConfig con los espacios en blanco, estilo de código y convenciones de nomenclatura .NET predeterminados.

   Aparecerá un nuevo archivo .editorconfig en el Explorador de soluciones, que se abrirá en el editor como una nueva pestaña.

   

5. Si lo desea, edite el archivo y guárdelo.

Otras maneras de agregar un archivo EditorConfig

Hay un par de formas más de agregar un archivo EditorConfig a su proyecto:

• Utilice IntelliCode para Visual Studio para generar un archivo .editorconfig en su solución. Haga clic con el botón derecho del ratón en el Explorador de soluciones y seleccione Agregar>Nueva configuración del editor (IntelliCode) en el menú contextual. IntelliCode para Visual Studio infiere sus estilos de código a partir del código existente y, a continuación, crea un archivo EditorConfig con sus preferencias de estilo de código predefinidas.

• Generar automáticamente un archivo EditorConfig basado en su configuración de estilo de código.

Prioridad y jerarquía de los archivos

Cuando añada un archivo .editorconfig a una carpeta de su jerarquía de archivos, su configuración se aplicará a todos los archivos aplicables en ese nivel e inferiores. También puede anular la configuración de EditorConfig para un proyecto, código base o parte de código base concretos, como una que use convenciones distintas a otras partes del código base. Esto puede ser útil cuando se incorpora código de otro lugar y no se desea cambiar sus convenciones.

Siga estas directrices.

• Para anular algunas configuraciones de EditorConfig o todas ellas, agregue un archivo .editorconfig en el nivel de la jerarquía de archivos en la que quiera que se aplique esa configuración anulada. La nueva configuración del archivo EditorConfig se aplica a los archivos del mismo nivel y a los archivos de cualquier subdirectorio.

  

• Si solo quiere anular algunos valores de configuración, pero no todos, especifique tan solo esos valores en el archivo .editorconfig. Solo aquellas propiedades que usted enumera explícitamente en el archivo .editorconfig de nivel inferior son anuladas. El resto de configuraciones de cualquier archivo .editorconfig de nivel superior se siguen aplicando.

• Si quiere asegurarse de que no se aplica ninguna configuración de ningún fichero .editorconfig de nivel superior a esta parte del código base, añada la propiedad root=true al fichero .editorconfig de nivel inferior.

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

Los ficheros EditorConfig se leen de arriba a abajo. Si hay varias propiedades con el mismo nombre, tiene prioridad la última que se haya encontrado con el mismo nombre.

Edición de los archivos EditorConfig

Visual Studio 2022 proporciona un editor visual para los archivos EditorConfig.

Después de editar el archivo EditorConfig, debe volver a cargar los archivos de código para que la nueva configuración surta efecto.

Ejemplo

El siguiente ejemplo muestra el estado de sangría de un fragmento de código C# antes y después de añadir un archivo EditorConfig al proyecto:

1. En el cuadro de diálogo Herramientas>Opciones, establezca la configuración Editor de texto>C#>Tabuladores para que el editor de texto de Visual Studio produzca cuatro caracteres de espacio cuando pulse la tecla Tabulador.

   

2. Como se esperaba, cuando presione la tecla Tabulador en la línea siguiente, se aplica la sangría en la línea agregando cuatro caracteres de espacio en blanco.

   

3. Use EditorConfig para cambiar la configuración de pestañas para usar pestañas.

   Seleccione Usar pestañas en el archivo EditorConfig.

   

4. Al pulsar la tecla Tabulador, ahora aparecen caracteres de tabulación en lugar de espacios.

   

Solución de problemas de las opciones de configuración de EditorConfig

Si existe un archivo EditorConfig en cualquier lugar de la estructura de directorios en la ubicación de su proyecto o por encima de ella, Visual Studio aplica la configuración del editor en ese archivo a su editor. En este caso, es posible que vea el mensaje siguiente en la barra de estado:

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

Esto significa que si los valores de configuración del editor de Herramientas>Opciones>Editor de texto (como el tamaño y estilo de la sangría, el tamaño de la tabulación o las convenciones de codificación) se especifican en un archivo EditorConfig en la estructura de directorios, en el proyecto o por encima de este, las convenciones del archivo EditorConfig invalidan la configuración que aparece en Editor de texto.

Para solucionar problemas de EditorConfig, siga estos pasos:

1. Para desactivar la compatibilidad de EditorConfig con Visual Studio, desactive la opción Seguir las convenciones de codificación del proyecto en Herramientas>Opciones>Editor de texto.

   

2. Para encontrar cualquier archivo EditorConfig en los directorios padre de su proyecto, abra un símbolo del sistema y ejecute el siguiente comando desde la raíz del disco que contiene su proyecto.

   dir .editorconfig /s
   

3. Para controlar el alcance de sus convenciones EditorConfig, establezca la propiedad root=true en el archivo .editorconfig en la raíz de su repositorio o en el directorio donde reside su proyecto.

   Visual Studio busca un archivo denominado .editorconfig en el directorio del archivo abierto y en todos los directorios principales. La búsqueda finaliza cuando se llega a la ruta de acceso del archivo raíz o si se encuentra un archivo .editorconfig con root=true.

Contenido relacionado

• Opciones de reglas de estilo de código para .NET
• Soporte de EditorConfig para su servicio de idiomas
• EditorConfig.org
• Características del editor de código
• Creación y edición de un archivo EditorConfig personalizado en Visual Studio para Mac