Personalizar una compilación

  • Artículo

Los proyectos de MSBuild que usan el proceso de compilación estándar (la importación de Microsoft.Common.props y Microsoft.Common.targets) tienen varios enlaces de extensibilidad que se pueden usar para personalizar el proceso de compilación.

Muchas operaciones de compilación personalizables se controlan mediante propiedades. Es importante saber cómo y dónde establecer el valor de una propiedad para que tenga el efecto deseado. Puede establecer propiedades en la línea de comandos (y en archivos de respuesta), en archivos especiales como Directory.Build.props, en archivos importados o en el archivo de proyecto. Es importante saber dónde se utiliza, establece o cambia una propiedad y el orden de los archivos importados, incluidas las importaciones implícitas de SDK, como el SDK de .NET.

Para obtener una lista de propiedades, consulte propiedades comunes de MSBuild.

Exploración de las opciones de personalización

Las opciones de personalización siguientes se enumeran de menor a mayor complejidad y ámbito de influencia. Recomendamos utilizar la opción de personalización menos compleja que sirva a su propósito, empezando por la parte superior de esta lista.

Opción de personalización Descripción
Adición de argumentos a la línea de comandos de MSBuild Establezca las propiedades globales que afectan a la compilación del proyecto principal y a las compilaciones de todos los proyectos dependientes.
Personalización de la compilación para un solo proyecto Agregue propiedades a los archivos .props o .targets para personalizar la configuración de compilación.
Control de archivos generados en el proceso de compilación Cómo asegurarse de que los archivos generados se incluyen correctamente en la salida de compilación.
Personalización de la compilación para uno o más proyectos Agregue propiedades a Directory.Build.props o propiedades y destinos a Directory.Build.targets para personalizar la compilación de todos los proyectos de una carpeta. Esta técnica es útil para establecer propiedades que un SDK establece o utiliza, así como para determinar el ámbito de las personalizaciones de forma que afecten a todos los proyectos de una carpeta o subcarpeta.
Personalización de la compilación local Realice cambios de compilación solo en su máquina local, sin que afecten a los archivos de código fuente compartidos.
Personalización de todas las compilaciones de .NET Personalice la compilación con un ámbito para todo el sistema en las compilaciones de .NET.
Personalización de compilaciones de C++ Personalice la compilación de C++, con un ámbito de proyecto, solución, carpeta o todas las compilaciones gobernadas por una instalación de MSBuild en un sistema.

Adición de argumentos a las invocaciones de MSBuild de línea de comandos para el proyecto

Puede establecer propiedades globales en la línea de comandos. Las propiedades globales afectan a todas las compilaciones del proyecto, incluidas las dependencias. Recuerde que compilar un proyecto desencadena automáticamente una posible compilación para todas las dependencias del proyecto. El comportamiento normal de MSBuild es compilar todos los proyectos dependientes obsoletos. Esas compilaciones de proyectos dependientes se inician con la misma configuración de propiedad global desde la línea de comandos que el proyecto original.

Un archivo Directory.Build.rsp en el directorio de origen o por encima se aplica a las compilaciones de línea de comandos del proyecto. Para obtener más información, vea Archivos de respuesta de MSBuild.

Elección entre la adición de propiedades a un archivo .props o .targets

MSBuild depende del orden de importación y la última definición de una propiedad (o una UsingTask o destino) es la definición usada.

Al usar importaciones explícitas, puede importar desde un archivo .props o .targets en cualquier momento. Esta es la convención que se usa ampliamente:

  • Los archivos .props se importan de forma temprana en el orden de importación.

  • Los archivos .targets se importan de forma tardía en el orden de compilación.

Las importaciones <Project Sdk="SdkName"> aplican esta convención (es decir, primero se muestra la importación de Sdk.props, antes que todo el contenido del archivo, para después hacerlo la de Sdk.targets, después de todo este contenido).

Para decidir dónde colocar las propiedades, use las siguientes instrucciones generales:

  • En el caso de que sean muchas las propiedades, no importa dónde se definan, ya que no se sobrescriben y serán de solo lectura en tiempo de ejecución.

  • Para un comportamiento que podría personalizarse en un proyecto individual, establezca valores predeterminados en los archivos .props.

  • Evite establecer propiedades dependientes en los archivos .props leyendo el valor de una propiedad posiblemente personalizada, ya que la personalización no tendrá lugar hasta que MSBuild lea el proyecto del usuario.

  • Establezca propiedades dependientes en los archivos .targets, ya que recogerán personalizaciones de proyectos individuales.

  • Si tiene que reemplazar propiedades, hágalo en un archivo .targets, después de que todas las personalizaciones de proyecto de usuario hayan tenido la oportunidad de surtir efecto. Tenga cuidado al usar propiedades derivadas, ya que también puede ser necesario reemplazarlas.

  • Incluya elementos en los archivos .props (condicionados por una propiedad). Se tienen en cuenta todas las propiedades antes que cualquier elemento, por lo que se recogen personalizaciones de propiedades de proyecto de usuario y tener elementos importados en archivos .props proporciona al proyecto del usuario la oportunidad de Remove o Update cualquier elemento incorporado por la importación.

  • Defina los destinos en los archivos .targets. Sin embargo, si un SDK importa el archivo .targets, recuerde que este escenario aumenta la dificultad del reemplazo del destino, ya que el proyecto del usuario carece de un lugar para reemplazarlo de forma predeterminada.

  • Si es posible, opte por la personalización de propiedades en tiempo de evaluación en lugar del cambio de las mismas dentro de un destino. Esta instrucción hace que resulte más fácil cargar un proyecto y saber lo que hace.

Contenido relacionado