MSBuild

  • Artículo

Microsoft Build Engine es una plataforma para compilar aplicaciones. Este motor, que también se conoce como MSBuild, proporciona un esquema XML para un archivo del proyecto que controla cómo la plataforma de compilación procesa y compila el software. Visual Studio usa MSBuild, pero MSBuild no depende de Visual Studio. Al invocar msbuild.exe o dotnet build en el archivo de proyecto o solución, puede orquestar y compilar productos en entornos donde no está instalado Visual Studio.

Visual Studio utiliza MSBuild para cargar y compilar proyectos administrados. Los archivos de proyecto de Visual Studio ( .csproj, .vbproj, .vcxproj, etc.) contienen código XML de MSBuild que se ejecuta cuando se compila un proyecto mediante el IDE. Los proyectos de Visual Studio importan todos los valores y procesos de compilación necesarios para realizar el trabajo de desarrollo típico, pero se pueden extender o modificar dentro de Visual Studio o mediante un editor XML.

Para instalar MSBuild en un sistema Windows que no tiene Visual Studio, vaya a Herramientas de compilación para Visual Studio en la página de descargas. La instalación de MSBuild mediante este método le proporciona MSBuild.exe.

Para .NET Core y .NET 5 o posterior, otra manera de obtener el equivalente a MSBuild es instalar el SDK de .NET. El comando de compilación de .NET dotnet build está disponible con el SDK de .NET en macOS, Windows o Linux. El comando de compilación de .NET dotnet build es una envoltura delgada sobre la versión de .NET Core de MSBuild.exe. Puede usar la interfaz de la línea de comandos (CLI) de .NET Core, que usa MSBuild, para compilar proyectos destinados a .NET Core y .NET 5 y versiones posteriores.

A partir de Visual Studio 2022, al compilar en Visual Studio, se usa la versión de MSBuild de 64 bits.

Para obtener información sobre MSBuild para C++, consulte MSBuild (C++).

En los ejemplos siguientes se muestra cuándo se podrían ejecutar compilaciones mediante la invocación de MSBuild desde la línea de comandos en lugar de usar el IDE de Visual Studio.

  • Visual Studio no está instalado.

  • Quiere usar la versión de MSBuild de 64 bits y utiliza Visual Studio 2019 o versiones anteriores. Esta versión de MSBuild normalmente es innecesaria, pero permite que MSBuild tenga acceso a más memoria.

  • Desea ejecutar una compilación en varios procesos. Sin embargo, puede utilizar el IDE para lograr el mismo resultado en proyectos de C++ y C#.

  • Desea modificar el sistema de compilación. Por ejemplo, quizá desee habilitar las acciones siguientes:

    • Preprocesar los archivos antes de alcanzar el compilador.

    • Copiar los resultados de compilación en un lugar diferente.

    • Crear archivos comprimidos a partir de los resultados de la compilación.

    • Realizar un paso de procesamiento posterior. Por ejemplo, puede ser conveniente crear una marca de tiempo en un ensamblado con una versión diferente.

Puede escribir código en el IDE de Visual Studio, pero ejecutar las compilaciones con MSBuild. Otra alternativa consiste en compilar el código en el IDE en un equipo de desarrollo, pero ejecutar MSBuild desde la línea de comandos para compilar el código que se integra desde un repositorio de origen con la colaboración de varios desarrolladores.

Nota

Puede usar Azure Pipelines para compilar, probar e implementar de forma automática la aplicación. El sistema de compilación puede ejecutar automáticamente las compilaciones cuando los desarrolladores protegen el código (por ejemplo, como parte de una estrategia de integración continua) o según una programación (por ejemplo, una prueba nocturna de comprobación de la compilación). Azure Pipelines compila el código mediante MSBuild. Para obtener más información, consulte Azure Pipelines.

Para ver un tutorial introductorio de MSBuild en Windows, consulte Tutorial: Usar MSBuild.

Uso de MSBuild en un símbolo del sistema

Para ejecutar MSBuild en un símbolo del sistema, pase un archivo del proyecto a MSBuild.exe junto con las opciones de la línea de comandos adecuadas. Las opciones de la línea de comandos permiten establecer propiedades, ejecutar destinos concretos y establecer otras opciones que controlan el proceso de compilación. Por ejemplo, para compilar el archivo MyProj.proj con la propiedad Configuration establecida en Debug, usaría la siguiente sintaxis de línea de comandos.

MSBuild.exe MyProj.proj -property:Configuration=Debug

MSBuild no cambia su comportamiento en función de la extensión de archivo, pero la convención consiste en usar extensiones que terminan en proj, como .csproj, .vcxproj o .vbproj, para el archivo de entrada principal de MSBuild, denominado "archivo de proyecto".

Para obtener más información acerca de las opciones de la línea de comandos de MSBuild, vea Referencia de la línea de comandos.

Importante

Antes de descargar un proyecto, asegúrese de que su código es de confianza.

Para .NET Core y .NET 5 o posterior, normalmente se usa dotnet build para invocar MSBuild. Consulte dotnet build. Si instala solo el SDK de .NET y no Visual Studio ni la Visual Studio Build Tools, solo tiene MSBuild a través de dotnet build.

La línea de comandos dotnet build --help enumera las opciones de línea de comandos específicas de dotnet build, no todas las opciones de MSBuild.exe, pero aún puede usar todas las opciones de línea de comandos enumeradas en la referencia de línea de comandos de MSBuild. Las opciones que no se procesan mediante dotnet build se pasan a MSBuild.

Archivo del proyecto

MSBuild usa un formato de archivo del proyecto basado en XML que es sencillo y extensible. El formato de archivo del proyecto de MSBuild permite a los desarrolladores describir los elementos que se van a compilar, y también cómo se van a compilar en diferentes sistemas operativos y configuraciones. Además, el formato del archivo de proyecto permite a los desarrolladores crear reglas de compilación reutilizables que se pueden factorizar en archivos independientes para que las compilaciones se ejecuten de forma coherente en los distintos proyectos del producto.

El sistema de compilación de Visual Studio almacena la lógica específica del proyecto en el propio archivo de proyecto y usa archivos XML de MSBuild importados con extensiones como .props y .targets para definir la lógica de compilación estándar. Los archivos .props definen propiedades de MSBuild y los archivos .targets definen destinos de MSBuild. Estas importaciones a veces están visibles en el archivo del proyecto de Visual Studio, pero en los proyectos más recientes, como proyectos de .NET Core, .NET 5 y .NET 6, no se ven las importaciones en el archivo del proyecto; en su lugar, verá una referencia del SDK, que tiene el aspecto siguiente:

<Project Sdk="Microsoft.Net.Sdk">

Se denominan proyectos de estilo SDK. Cuando se hace referencia a un SDK, como el SDK de .NET, el SDK especifica implícitamente las importaciones de los archivos .props y .target.

En las secciones siguientes se describen algunos de los elementos básicos del formato de archivo de proyecto de MSBuild. Para obtener un tutorial sobre cómo crear un archivo de proyecto básico, vea Tutorial: Crear un archivo de proyecto de MSBuild desde cero.

Propiedades

Las propiedades representan pares clave/valor que se pueden utilizar para configurar compilaciones. Las propiedades se declaran mediante la creación de un elemento que tenga el nombre de la propiedad como elemento secundario de un elemento PropertyGroup. Por ejemplo, el código siguiente crea una propiedad denominada BuildDir cuyo valor es Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Puede definir una propiedad condicionalmente si coloca un atributo Condition en el elemento. El contenido de los elementos condicionales se omite, a menos que la condición se evalúe como true. En el ejemplo siguiente, se define la propiedad Configuration si aún no se ha definido.

<Configuration  Condition=" '$(Configuration)' == '' ">DefaultValue</Configuration>

Para hacer referencia a las propiedades en el archivo del proyecto, se utiliza la sintaxis $(<PropertyName>). Por ejemplo, se puede hacer referencia a las propiedades de los ejemplos anteriores mediante $(BuildDir) y $(Configuration).

Para más información sobre las propiedades, consulte Propiedades de MSBuild.

Elementos

Los elementos son entradas del sistema de compilación y suelen representar archivos. Se agrupan en tipos de elemento en función de los nombres de elemento definidos por el usuario. Estos tipos de elemento se pueden utilizar como parámetros para tareas, que utilizan los elementos individuales para llevar a cabo los pasos del proceso de compilación.

Los elementos se declaran en el archivo del proyecto mediante la creación de un elemento con el nombre del tipo de elemento como elemento secundario de un elemento ItemGroup. Por ejemplo, el código siguiente crea un tipo de elemento denominado Compile que incluye dos archivos.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Para hacer referencia a los tipos de elemento en el archivo del proyecto, se utiliza la sintaxis @(<ItemType>). Por ejemplo, para hacer referencia al tipo de elemento del ejemplo, se usaría @(Compile).

En MSBuild, los nombres de elementos y atributos distinguen mayúsculas de minúsculas. Sin embargo, los nombres de propiedad, elemento y metadatos no las distinguen. El ejemplo siguiente crea el tipo de elemento Compile, comPile o cualquier otra variación de grafía, y asigna al tipo de elemento el valor "one.cs;two.cs".

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

Los elementos se pueden declarar utilizando caracteres comodín y pueden contener metadatos adicionales para escenarios de compilación más avanzados. Para obtener más información sobre los elementos, consulte Elementos.

Tareas

Las tareas son unidades de código ejecutable que se utilizan en proyectos de MSBuild para realizar operaciones de compilación. Por ejemplo, una tarea podría compilar archivos de entrada o ejecutar una herramienta externa. Las tareas se pueden reutilizar y las pueden compartir desarrolladores diferentes en distintos proyectos.

La lógica de ejecución de una tarea se escribe en código administrado y se asigna a MSBuild mediante el elemento UsingTask. Puede escribir una tarea creando un tipo administrado que implemente la interfaz ITask. Para más información sobre cómo escribir tareas, consulte Escribir tareas.

MSBuild incluye tareas comunes que puede modificar para adaptarlas a sus necesidades. Algunos ejemplos son Copy, que copia archivos, MakeDir, que crea directorios, y Csc, que compila archivos de código fuente de Visual C#. Para obtener una lista de las tareas disponibles junto con información de uso, consulte Referencia de tareas.

Para ejecutar una tarea en un archivo del proyecto de MSBuild, se crea un elemento con el nombre de la tarea como elemento secundario de un elemento Target. Las tareas aceptan normalmente parámetros, que se pasan como atributos del elemento. Tanto las propiedades como los elementos de MSBuild se pueden utilizar como parámetros. Por ejemplo, el código siguiente llama a la tarea MakeDir y le pasa el valor de la propiedad BuildDir que se declaró en el ejemplo anterior.

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

Para obtener más información sobre las tareas, consulte Tareas.

Destinos

Los destinos agrupan tareas en un orden particular y exponen secciones del archivo de proyecto como puntos de entrada en el proceso de compilación. Los destinos suelen agruparse en secciones lógicas para aumentar la legibilidad y permitir la expansión. Dividir los pasos de compilación en destinos permite llamar a una parte del proceso de compilación desde otros destinos sin necesidad de copiar dicha sección de código en cada destino. Por ejemplo, si varios puntos de entrada del proceso de compilación necesitan que se compilen referencias, se puede crear un destino que compile referencias y, a continuación, ejecutar dicho destino desde cada punto de entrada que sea necesario.

Los destinos se declaran en el archivo del proyecto mediante el elemento Target. Por ejemplo, en el código siguiente se crea un destino denominado Compile que, a continuación, llama a la tarea Csc que tiene la lista de elementos que se declaró en el ejemplo anterior.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

En escenarios más avanzados, los destinos se pueden usar para describir relaciones mutuas y llevar a cabo análisis de dependencia, de modo que se pueden omitir secciones completas del proceso de compilación si un destino concreto está actualizado. Para obtener más información sobre los destinos, consulte Destinos.

Registros de compilación

Puede registrar errores de compilación, advertencias y mensajes en la consola o en otro dispositivo de salida. Para más información, consulte Obtener registros de compilación con MSBuild.

Uso de MSBuild en Visual Studio

Visual Studio usa el formato de archivo de proyecto de MSBuild para almacenar información de generación sobre proyectos administrados. La configuración del proyecto que se agrega o se modifica mediante la interfaz de Visual Studio se refleja en el archivo .*proj que se genera para cada proyecto. Visual Studio utiliza una instancia hospedada de MSBuild para compilar proyectos administrados. Esto significa que un proyecto administrado se puede compilar en Visual Studio o en el símbolo del sistema (aunque Visual Studio no esté instalado) y los resultados serán idénticos.

Para obtener un tutorial sobre cómo utilizar MSBuild en Visual Studio, vea Tutorial: Usar MSBuild.

Compatibilidad con múltiples versiones (multi-targeting)

Con Visual Studio, puede compilar una aplicación para que se ejecute en cualquiera de las versiones de .NET Framework o .NET Core, incluidos .NET 5 y versiones posteriores. Por ejemplo, puede compilar una aplicación para que se ejecute en .NET Framework 4 en una plataforma de 32 bits y compilar esa misma aplicación para que se ejecute en .NET Framework 4.8 en una plataforma de 64 bits. La capacidad de compilar para más de una versión de Framework se denomina multitargeting.

Estas son algunas de las ventajas de la compatibilidad con múltiples versiones (multitargeting):

  • Puede desarrollar aplicaciones que tengan como destino versiones anteriores de .NET Framework, por ejemplo, las versiones 3.5 y 4.7.2.

  • Puede tener como destino un perfil de Framework, que es un subconjunto predefinido de un marco de trabajo de destino.

  • Si se publica un Service Pack para la versión actual de .NET Framework, podría usarlo como destino.

  • La compatibilidad con múltiples versiones (multitargeting) garantiza que una aplicación utilice solo la funcionalidad que está disponible en el marco y plataforma de destino.

Para obtener más información, consulte Compatibilidad con múltiples versiones (multi-targeting).

Personalización de la compilación

MSBuild ofrece compatibilidad con una amplia variedad de escenarios de compilación personalizada. La mayor parte de la funcionalidad integrada se puede reemplazar o ampliar. Consulte Personalizar una compilación.

Acceso a MSBuild mediante programación

Si va a desarrollar una herramienta de compilación, puede que quiera invocar MSBuild mediante programación desde una aplicación .NET. Con la API de MSBuild, puede controlar todos los aspectos de un sistema de compilación complejo. MSBuild proporciona un paquete NuGet con una API completa (el espacio de nombres de Microsoft.Build) que puede usar desde una aplicación .NET para estos fines. Consulte Usar la API de MSBuild.

MSBuild es código abierto

MSBuild es un proyecto de código abierto que acepta contribuciones de los usuarios, al igual que el resto del ecosistema .NET. El repositorio que contiene el código fuente de MSBuild está disponible en GitHub: repositorio de GitHub de MSBuild.

Vea también

Title Descripción
Tutorial: Crear un archivo de proyecto de MSBuild desde cero Muestra la forma de crear un archivo básico del proyecto de forma incremental, utilizando solo un editor de texto.
Tutorial: Usar MSBuild Presenta los bloques de compilación de MSBuild y muestra la forma de escribir, manipular y depurar proyectos de MSBuild sin cerrar el IDE de Visual Studio.
Conceptos de MSBuild Presenta los cuatro bloques de compilación de MSBuild: propiedades, elementos, destinos y tareas.
Elementos Describe los conceptos generales en que se basa el formato de archivo de MSBuild y la manera de encajar las piezas.
Propiedades de MSBuild Presenta las propiedades y las colecciones de propiedades. Las propiedades son pares clave/valor que se pueden utilizar para configurar compilaciones.
Destinos Explica cómo agrupar las tareas entre sí en un orden concreto y habilitar las secciones del proceso de compilación para que se las pueda llamar desde la línea de comandos.
Tareas Muestra la forma de crear una unidad de código ejecutable que MSBuild puede usar para realizar operaciones de compilación indivisibles.
Condiciones Explica la forma de utilizar el atributo Condition en un elemento de MSBuild.
Procesamiento por lotes Describe cómo MSBuild clasifica las listas de elementos por metadatos para su ejecución en tareas y destinos.
Compatibilidad con múltiples versiones (multi-targeting) Muestra cómo tener como destino varias versiones de .NET o varias plataformas.
Obtener registros de compilación Describe cómo registrar los eventos, mensajes y errores de compilación.
Cómo MSBuild compila los proyectos En este artículo se describe el proceso de compilación interno que se usa en MSBuild.
Creación de una tarea personalizada para la generación de código Muestra cómo crear una tarea personalizada, con un ejemplo de código.
Uso de MSBuild para generar un cliente de API de REST Muestra cómo extender la compilación para controlar la generación de clientes de API de REST, con un ejemplo de código.
Recursos adicionales Enumera los recursos de compatibilidad y comunidad para obtener más información sobre MSBuild.

Referencia