Tutorial: Uso de MSBuild para crear un proyecto de Visual C++Walkthrough: Using MSBuild to Create a Visual C++ Project

En este tutorial se muestra cómo usar MSBuild en un símbolo del sistema para compilar un proyecto de Visual Studio C++.This walkthrough demonstrates how to use MSBuild in a command prompt to build a Visual Studio C++ project. Va a aprender a crear un archivo del proyecto .vcxproj basado en XML para una aplicación de consola de Visual C++.You'll learn how to create an XML-based .vcxproj project file for a Visual C++ console application. Después de compilar el proyecto, aprenderá a personalizar el proceso de compilación.After building the project, you'll learn how to customize the build process.

Importante

No use este enfoque si piensa editar el archivo del proyecto más adelante mediante el IDE de Visual Studio.Don't use this approach if you intend to edit the project file later by using the Visual Studio IDE. Si crea un archivo .vcxproj manualmente, es posible que el IDE de Visual Studio no pueda editarlo o cargarlo, sobre todo si el proyecto usa caracteres comodín en los elementos del proyecto.If you create a .vcxproj file manually, the Visual Studio IDE might not be able to edit or load it, especially if the project uses wildcards in project items. Para obtener más información, vea Estructura de los archivos .vcxproj y .props y Archivos .vcxproj y comodines.For more information, see .vcxproj and .props file structure and .vcxproj files and wildcards.

En el tutorial se muestran las tareas siguientes:This walkthrough illustrates these tasks:

  • Crear archivos de código fuente de C++ para el proyecto.Creating the C++ source files for your project.

  • Crear el archivo de proyecto de MSBuild en XML.Creating the XML MSBuild project file.

  • Usar MSBuild para compilar el proyecto.Using MSBuild to build your project.

  • Usar MSBuild para personalizar el proyecto.Using MSBuild to customize your project.

Requisitos previosPrerequisites

Para realizar este tutorial se necesitan estos requisitos previos:You need these prerequisites to complete this walkthrough:

  • Una copia de Visual Studio que tenga instalada la carga de trabajo Desarrollo de escritorio con C++ .A copy of Visual Studio with the Desktop development with C++ workload installed.

  • Conocimientos generales sobre el sistema MSBuild.A general understanding of the MSBuild system.

Nota

La mayoría de las instrucciones de compilación de bajo nivel se encuentran en los archivos .targets y .props definidos en la carpeta targets predeterminada, almacenada en la propiedad $(VCTargetsPath).Most of the low-level build instructions are contained in the .targets and .props files that are defined under the default targets folder, stored in the property $(VCTargetsPath). Ahí se encuentran archivos como Microsoft.Cpp.Common.props .It's where you'll find files such as Microsoft.Cpp.Common.props. La ruta de acceso predeterminada de estos archivos en Visual Studio 2015 y versiones anteriores está en %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\ .The default path for these files in Visual Studio 2015 and earlier versions is under %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\.

Nota

La mayoría de las instrucciones de compilación de bajo nivel se encuentran en los archivos .targets y .props definidos en la carpeta targets predeterminada, almacenada en la propiedad $(VCTargetsPath).Most of the low-level build instructions are contained in the .targets and .props files that are defined under the default targets folder, stored in the property $(VCTargetsPath). Ahí se encuentran archivos como Microsoft.Cpp.Common.props .It's where you'll find files such as Microsoft.Cpp.Common.props. La ruta de acceso predeterminada de estos archivos en Visual Studio 2017 está en %VSINSTALLDIR%Common7\IDE\VC\VCTargets\ .The default path for these files in Visual Studio 2017 is under %VSINSTALLDIR%Common7\IDE\VC\VCTargets\. Visual Studio 2015 y versiones anteriores los almacenaban en %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\ .Visual Studio 2015 and earlier versions stored them under %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\.

Nota

La mayoría de las instrucciones de compilación de bajo nivel se encuentran en los archivos .targets y .props definidos en la carpeta targets predeterminada, almacenada en la propiedad $(VCTargetsPath).Most of the low-level build instructions are contained in the .targets and .props files that are defined under the default targets folder, stored in the property $(VCTargetsPath). Ahí se encuentran archivos como Microsoft.Cpp.Common.props .It's where you'll find files such as Microsoft.Cpp.Common.props. La ruta de acceso predeterminada de estos archivos está en %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\ .The default path for these files is under %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\. El elemento de la ruta de acceso <version> es específico de la versión de Visual Studio.The <version> path element is specific to the version of Visual Studio. Es v160 en el caso de Visual Studio 2019.It's v160 for Visual Studio 2019. Visual Studio 2017 almacenaba estos archivos en %VSINSTALLDIR%Common7\IDE\VC\VCTargets\ .Visual Studio 2017 stored these files under %VSINSTALLDIR%Common7\IDE\VC\VCTargets\. Visual Studio 2015 y versiones anteriores los almacenaban en %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\ .Visual Studio 2015 and earlier versions stored them under %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\.

Creación de los archivos de origen de C++Create the C++ source files

En este tutorial, creará un proyecto que tiene un archivo de origen y un archivo de encabezado.In this walkthrough, you'll create a project that has a source file and a header file. El archivo de origen main.cpp contiene la función main de la aplicación de consola.The source file main.cpp contains the main function for the console application. El archivo de encabezado main.h contiene código para incluir el archivo de encabezado <iostream> .The header file main.h contains code to include the <iostream> header file. Puede crear estos archivos de C++ mediante Visual Studio o un editor de texto, Visual Studio Code.You can create these C++ files by using Visual Studio or a text editor such as Visual Studio Code.

Para crear archivos de código fuente de C++ para el proyectoTo create the C++ source files for your project

  1. Cree una carpeta para el proyecto.Create a folder for your project.

  2. Cree un archivo denominado main.cpp y agréguele este código:Create a file named main.cpp and add this code to the file:

    // main.cpp : the application source code.
    #include <iostream>
    #include "main.h"
    int main()
    {
       std::cout << "Hello, from MSBuild!\n";
       return 0;
    }
    
  3. Cree un archivo denominado main.h y agréguele este código:Create a file named main.h and add this code to the file:

    // main.h: the application header code.
    /* Additional source code to include. */
    

Crear el archivo de proyecto de MSBuild en XMLCreating the XML MSBuild Project File

Un archivo de proyecto de MSBuild es un archivo XML que contiene un elemento raíz de proyecto (<Project>).An MSBuild project file is an XML file that contains a project root element (<Project>). En el proyecto de ejemplo que ha compilado, el elemento <Project> contiene siete elementos secundarios:In the example project you'll build, the <Project> element contains seven child elements:

  • Tres etiquetas de grupo de elementos (<ItemGroup>) que especifican la configuración del proyecto y la plataforma, el nombre del archivo de código fuente y el nombre del archivo de encabezado.Three item group tags (<ItemGroup>) that specify project configuration and platform, source file name, and header file name.

  • Tres etiquetas de importación (<Import>) que especifican la ubicación de la configuración de Microsoft Visual C++.Three import tags (<Import>) that specify the location of Microsoft Visual C++ settings.

  • Una etiqueta de grupo de propiedades (<PropertyGroup>) que especifica la configuración del proyecto.A property group tag (<PropertyGroup>) that specifies project settings.

Para crear el archivo de proyecto de MSBuildTo create the MSBuild project file

  1. Use un editor de texto para crear un archivo del proyecto con el nombre myproject.vcxproj y luego agregue el elemento raíz <Project> que se muestra aquí.Use a text editor to create a project file that is named myproject.vcxproj , and then add the root <Project> element shown here. (Use ToolsVersion="14.0" si tiene Visual Studio 2015, ToolsVersion="15.0" si tiene Visual Studio 2017 o ToolsVersion="16.0" si tiene Visual Studio 2019).(Use ToolsVersion="14.0" if you're using Visual Studio 2015, ToolsVersion="15.0" if you're using Visual Studio 2017, or ToolsVersion="16.0" if you're using Visual Studio 2019.)

    <Project DefaultTargets="Build" ToolsVersion="16.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    </Project>
    

    Inserte los elementos de los siguientes pasos del procedimiento entre las etiquetas raíz <Project>.Insert the elements in the next procedure steps between the root <Project> tags.

  2. Agregue estos dos elementos secundarios <ProjectConfiguration> a un elemento <ItemGroup>.Add these two <ProjectConfiguration> child elements in an <ItemGroup> element. El elemento secundario especifica las configuraciones de depuración y de versión de un sistema operativo Windows de 32 bits:The child element specifies debug and release configurations for a 32-bit Windows operating system:

    <ItemGroup>
      <ProjectConfiguration Include="Debug|Win32">
        <Configuration>Debug</Configuration>
        <Platform>Win32</Platform>
      </ProjectConfiguration>
      <ProjectConfiguration Include="Release|Win32">
        <Configuration>Release</Configuration>
        <Platform>Win32</Platform>
      </ProjectConfiguration>
    </ItemGroup>
    
  3. Agregue un elemento <Import> que especifica la ruta de acceso de la configuración predeterminada de C++ de este proyecto:Add an <Import> element that specifies the path of the default C++ settings for this project:

    <Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
    
  4. Agregue un elemento de grupo de propiedades (<PropertyGroup>) que especifica dos propiedades del proyecto, <ConfigurationType> y <PlatformToolset>.Add a property group element (<PropertyGroup>) that specifies two project properties, <ConfigurationType> and <PlatformToolset>. (Use v140 como valor <PlatformToolset> si tiene Visual Studio 2015, v141 si tiene Visual Studio 2017 o v142 si tiene Visual Studio 2019).(Use v140 as the <PlatformToolset> value if you're using Visual Studio 2015, v141 if you're using Visual Studio 2017, or v142 if you're using Visual Studio 2019.)

    <PropertyGroup>
      <ConfigurationType>Application</ConfigurationType>
      <PlatformToolset>v142</PlatformToolset>
    </PropertyGroup>
    
  5. Agregue un elemento <Import> que especifica la ruta de acceso de la configuración actual de C++ de este proyecto:Add an <Import> element that specifies the path of the current C++ settings for this project:

    <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
    
  6. Agregue un elemento secundario <ClCompile> a un elemento <ItemGroup>.Add a <ClCompile> child element in an <ItemGroup> element. El elemento secundario especifica el nombre del archivo de código fuente de C/C++ que se va a compilar:The child element specifies the name of the C/C++ source file to compile:

    <ItemGroup>
      <ClCompile Include="main.cpp" />
    </ItemGroup>
    

    Nota

    <ClCompile> es un destino de compilación y se define en la carpeta targets predeterminada.<ClCompile> is a build target and is defined in the default targets folder.

  7. Agregue un elemento secundario <ClInclude> a un elemento <ItemGroup>.Add a <ClInclude> child element in an <ItemGroup> element. El elemento secundario especifica el nombre del archivo de encabezado para el archivo de código fuente de C/C++:The child element specifies the name of the header file for the C/C++ source file:

    <ItemGroup>
      <ClInclude Include="main.h" />
    </ItemGroup>
    
  8. Agregue un elemento <Import> que especifica la ruta de acceso del archivo que define el destino de este proyecto:Add an <Import> element that specifies the path of the file that defines the target for this project:

    <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Targets" />
    

Completar el archivo de proyectoComplete Project File

Este código muestra el archivo del proyecto completo creado en el procedimiento anterior.This code shows the complete project file that you created in the previous procedure. (Use ToolsVersion="15.0" para Visual Studio 2017 o ToolsVersion="14.0" para Visual Studio 2015).(Use ToolsVersion="15.0" for Visual Studio 2017, or ToolsVersion="14.0" for Visual Studio 2015.)

<Project DefaultTargets="Build" ToolsVersion="16.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <ProjectConfiguration Include="Debug|Win32">
      <Configuration>Debug</Configuration>
      <Platform>Win32</Platform>
    </ProjectConfiguration>
    <ProjectConfiguration Include="Release|Win32">
      <Configuration>Release</Configuration>
      <Platform>Win32</Platform>
    </ProjectConfiguration>
  </ItemGroup>
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
  <PropertyGroup>
    <ConfigurationType>Application</ConfigurationType>
    <PlatformToolset>v142</PlatformToolset>
  </PropertyGroup>
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
  <ItemGroup>
    <ClCompile Include="main.cpp" />
  </ItemGroup>
  <ItemGroup>
    <ClInclude Include="main.h" />
  </ItemGroup>
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Targets" />
</Project>

Usar MSBuild para compilar el proyectoUsing MSBuild to Build Your Project

Escriba este comando en el símbolo del sistema para compilar la aplicación de consola:Enter this command at the command prompt to build your console application:

msbuild myproject.vcxproj /p:configuration=debug

MSBuild crea una carpeta para los archivos de salida y luego compila y vincula el proyecto para generar el programa Myproject.exe .MSBuild creates a folder for the output files, and then compiles and links your project to generate the Myproject.exe program. Al finalizar el proceso de compilación, use este comando para ejecutar la aplicación desde la carpeta de depuración:After the build process finishes, use this command to run the application from the debug folder:

myproject

La aplicación debe mostrar "Hello, from MSBuild!" (Hola de parte de MSBuild)The application should display "Hello, from MSBuild!" en la ventana de la consola.in the console window.

Personalizar el proyectoCustomizing Your Project

MSBuild permite ejecutar destinos de compilación predefinidos, aplicar propiedades definidas por el usuario y usar herramientas, eventos y pasos de compilación personalizados.MSBuild enables you to execute predefined build targets, apply user-defined properties, and use custom tools, events, and build steps. En esta sección se explican estas tareas:This section illustrates these tasks:

  • Usar MSBuild con destinos de compilación.Using MSBuild with build targets.

  • Usar MSBuild con propiedades de compilación.Using MSBuild with build properties.

  • Usar MSBuild con las herramientas y el compilador de 64 bits.Using MSBuild with the 64-bit compiler and tools.

  • Usar MSBuild con conjuntos de herramientas diferentes.Using MSBuild with different toolsets.

  • Agregar personalizaciones de MSBuild.Adding MSBuild customizations.

Usar MSBuild con destinos de compilaciónUsing MSBuild with Build Targets

Un destino de compilación es un conjunto con nombre de comandos predefinidos o definidos por el usuario que se pueden ejecutar durante la compilación.A build target is a named set of predefined or user-defined commands that can be executed during the build. Use la opción de línea de comandos de destino ( /t ) para especificar un destino de compilación.Use the target command-line option ( /t ) to specify a build target. En el proyecto de ejemplo myproject, el destino clean predefinido elimina todos los archivos de la carpeta de depuración y crea un nuevo archivo de registro.For the myproject example project, the predefined clean target deletes all files in the debug folder and creates a new log file.

En el símbolo del sistema, escriba este comando para limpiar myproject:At the command prompt, enter this command to clean myproject:

msbuild myproject.vcxproj /t:clean

Usar MSBuild con propiedades de compilaciónUsing MSBuild with Build Properties

La opción de línea de comandos de propiedad (/p) permite reemplazar una propiedad en el archivo de compilación del proyecto.The property command-line option (/p) enables you to override a property in your project build file. En el proyecto de ejemplo myproject, la configuración de compilación de versión o de depuración se especifica mediante la propiedad Configuration.In the myproject example project, the release or debug build configuration is specified by the Configuration property. El sistema operativo que va a usar para ejecutar la aplicación compilada se especifica mediante la propiedad Platform.The operating system that you'll use to run the built application is specified by the Platform property.

En el símbolo del sistema, escriba este comando para crear una compilación de depuración de la aplicación myproject que se ejecute en Windows de 32 bits:At the command prompt, enter this command to create a debug build of the myproject application to run on 32-bit Windows:

msbuild myproject.vcxproj /p:configuration=debug /p:platform=win32

Supongamos que el proyecto de ejemplo myproject también define una configuración para Windows de 64 bits y otra configuración para un sistema operativo personalizado denominado myplatform.Assume that the myproject example project also defines a configuration for 64-bit Windows, and another configuration for a custom operating system named myplatform.

En el símbolo del sistema, escriba este comando para crear una compilación de versión que se ejecute en Windows de 64 bits:At the command prompt, enter this command to create a release build that runs on 64-bit Windows:

msbuild myproject.vcxproj /p:configuration=release /p:platform=x64

En el símbolo del sistema, escriba este comando para crear una compilación de versión para myplatform:At the command prompt, enter this command to create a release build for myplatform:

msbuild myproject.vcxproj /p:configuration=release /p:platform=myplatform

Usar MSBuild con las herramientas y el compilador de 64 bitsUsing MSBuild with the 64-bit Compiler and Tools

Si ha instalado Visual Studio en Windows de 64 bits, las herramientas cruzadas y nativas x64 de 64 bits se instalan de forma predeterminada.If you have installed Visual Studio on 64-bit Windows, the 64-bit x64 native and cross tools are installed by default. Puede configurar MSBuild para usar las herramientas y el compilador de 64 bits para compilar la aplicación mediante la configuración de la propiedad PreferredToolArchitecture.You can configure MSBuild to use the 64-bit compiler and tools to build your application by setting the PreferredToolArchitecture property. Esta propiedad no afecta a las propiedades de la plataforma o la configuración del proyecto.This property doesn't affect the project configuration or platform properties. De forma predeterminada, se usa la versión de 32 bits de las herramientas.By default, the 32-bit version of the tools is used. Para especificar la versión de 64 bits del compilador y las herramientas, agregue este elemento de grupo de propiedades al archivo del proyecto Myproject.vcxproj después del elemento <Import /> del archivo Microsoft.Cpp.default.props :To specify the 64-bit version of the compiler and tools, add this property group element to the Myproject.vcxproj project file after the Microsoft.Cpp.default.props file <Import /> element:

<PropertyGroup>
    <PreferredToolArchitecture>x64</PreferredToolArchitecture>
</PropertyGroup>

En el símbolo del sistema, escriba este comando para usar las herramientas de 64 bits para compilar la aplicación:At the command prompt, enter this command to use the 64-bit tools to build your application:

msbuild myproject.vcxproj /p:PreferredToolArchitecture=x64

Usar MSBuild con conjuntos de herramientas diferentesUsing MSBuild with a different toolset

Si tiene instalados conjuntos de herramientas y bibliotecas para otras versiones de Visual C++, MSBuild puede compilar las aplicaciones para la versión de Visual C++ actual o para las demás versiones instaladas.If you have the toolsets and libraries for other versions of Visual C++ installed, MSBuild can build applications for either the current Visual C++ version or for the other installed versions. Por ejemplo, si ha instalado Visual Studio 2012, para especificar el conjunto de herramientas de Visual C++ 11.0 para Windows XP, agregue este elemento de grupo de propiedades al archivo del proyecto Myproject.vcxproj después del elemento <Import /> del archivo Microsoft.Cpp.props :For example, if you have installed Visual Studio 2012, to specify the Visual C++ 11.0 toolset for Windows XP, add this property group element to the Myproject.vcxproj project file after the Microsoft.Cpp.props file <Import /> element:

<PropertyGroup>
    <PlatformToolset>v110_xp</PlatformToolset>
</PropertyGroup>

Para recompilar el proyecto con el conjunto de herramientas de Visual C++ 11.0 para Windows XP, escriba este comando:To rebuild your project with the Visual C++ 11.0 Windows XP toolset, enter this command:

msbuild myproject.vcxproj /p:PlatformToolset=v110_xp /t:rebuild

Agregar personalizaciones de MSBuildAdding MSBuild customizations

MSBuild ofrece varias maneras de personalizar el proceso de compilación.MSBuild provides various ways to customize your build process. En estos artículos se explica cómo agregar pasos de compilación, herramientas y eventos personalizados a un proyecto de MSBuild:These articles show how to add custom build steps, tools, and events to your MSBuild project: