Creación de un archivo de proyecto de MSBuild desde cero

Artículo
02/07/2025

Los lenguajes de programación que tienen como destino .NET Framework usan archivos de proyecto de MSBuild para describir y controlar el proceso de compilación de la aplicación. Cuando se usa Visual Studio para crear un archivo de proyecto de MSBuild, el XML adecuado se agrega automáticamente al archivo. Sin embargo, es posible que le resulte útil comprender cómo se organiza el XML y cómo puede cambiarlo para controlar una compilación.

Nota

Este artículo es adecuado si desea obtener información sobre los aspectos básicos de cómo funciona MSBuild independientemente de cualquier SDK. La compilación con un SDK, como cuando se usa dotnet build o se agrega el atributo Sdk al elemento de proyecto raíz, no se trata en este artículo. Consulte SDKs de un proyecto .NET.

La lógica de compilación importada por archivos .csproj estándar admite muchas más opciones y un proceso de compilación mucho más complejo que este ejemplo.

Para obtener información sobre cómo crear un archivo de proyecto para un proyecto de C++, vea MSBuild (C++).

En este tutorial se muestra cómo crear un archivo de proyecto básico de forma incremental mediante solo un editor de texto. El tutorial sigue estos pasos:

Amplíe la variable de entorno PATH.
Cree un archivo de origen de aplicación mínimo.
Cree un archivo de proyecto de MSBuild mínimo.
Compile la aplicación mediante el archivo de proyecto.
Agregar propiedades para controlar la compilación.
Controlar la compilación cambiando los valores de propiedad.
Agregar destinos a la compilación.
Controlar la compilación especificando destinos.
Compile incrementalmente.

En este tutorial se muestra cómo compilar el proyecto desde la línea de comandos y examinar los resultados. Para obtener más información sobre MSBuild y cómo ejecutar MSBuild en la línea de comandos, consulte Uso de MSBuild.

Para completar el tutorial, debe tener Instalado Visual Studio porque incluye MSBuild y el compilador de C#, que son necesarios para el tutorial.

Ampliación de la ruta de acceso

Para poder usar MSBuild, debe ampliar la variable de entorno PATH para incluir todas las herramientas necesarias.

Si se ejecuta en Windows, puede usar el símbolo del sistema para desarrolladores de para Visual Studio. Búselo en el cuadro de búsqueda de Windows en la barra de tareas de Windows. Para configurar el entorno en un símbolo del sistema normal o en un entorno de scripting, ejecute VSDevCmd.bat en la subcarpeta Common7/Tools de una instalación de Visual Studio.

Creación de una aplicación mínima

En esta sección se muestra cómo crear un archivo de origen de aplicación de C# mínimo mediante un editor de texto.

En el símbolo del sistema, vaya a la carpeta en la que quiere crear la aplicación, por ejemplo, \My Documents\ o \Desktop.
Cree una subcarpeta denominada \HelloWorld\ y cambie el directorio para entrar en ella.

En un editor de texto, cree un archivo nuevo HelloWorld.cs y, a continuación, copie y pegue el código siguiente:

using System;

class HelloWorld
{
    static void Main()
    {
#if DebugConfig
        Console.WriteLine("WE ARE IN THE DEBUG CONFIGURATION");
#endif

        Console.WriteLine("Hello, world!");
    }
}

Escriba csc helloworld.cs en el símbolo del sistema para compilar la aplicación.
Escriba helloworld en el símbolo del sistema para probar la aplicación.

El mensaje ¡Hola, mundo! debe mostrarse.
Elimine el archivo ejecutable.

Creación de un archivo de proyecto mínimo de MSBuild

Ahora que tiene un archivo de origen de aplicación mínimo, puede crear un archivo de proyecto mínimo para compilar la aplicación. Este archivo de proyecto contiene los siguientes elementos:

El nodo raíz Project necesario.
Un nodo ItemGroup para contener los elementos.
Elemento que hace referencia al archivo de origen de la aplicación.
Nodo Target que contiene tareas necesarias para compilar la aplicación.
Elemento Task para iniciar el compilador de C# para compilar la aplicación.

Para crear un archivo de proyecto de MSBuild mínimo

En el editor de texto, cree un nuevo archivo HelloWorld.fromscratchproj y escriba el código siguiente:
```
<Project>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
</Project>
```
Este ItemGroup contiene un elemento Compile y especifica un archivo de origen como elemento.
Agregue un nodo Target como elemento secundario del nodo Project. Asigne al nodo el nombre Build.
```
<Target Name="Build">
</Target>
```
Inserte este elemento de tarea como elemento secundario del nodo Target:
```
<Csc Sources="@(Compile)"/>
```
Guarde este archivo de proyecto y asígnele el nombre Helloworld.fromscratchproj.

El archivo de proyecto mínimo debe ser similar al código siguiente:

<Project>
  <ItemGroup>
    <Compile Include="helloworld.cs"/>
  </ItemGroup>
  <Target Name="Build">
    <Csc Sources="@(Compile)"/>
  </Target>
</Project>

Las tareas en el destino Build se ejecutan secuencialmente. En este caso, la tarea del compilador de C# Csc es la única tarea. Espera una lista de archivos de origen para compilar, proporcionada por el valor del elemento Compile. El elemento Compile hace referencia solo a un archivo de origen, Helloworld.cs.

Nota

En el elemento , puede usar el carácter comodín asterisco (*) para hacer referencia a todos los archivos que tienen la extensión de nombre de archivo .cs, como se indica a continuación:

<Compile Include="*.cs" />

Compilación de la aplicación

Ahora, para compilar la aplicación, use el archivo de proyecto que acaba de crear.

En la línea de comandos, escriba msbuild helloworld.fromscratchproj -t:Build.

Esto compila el destino build del archivo de proyecto Helloworld invocando el compilador de C# para crear la aplicación Helloworld.
Pruebe la aplicación escribiendo helloworld.

El mensaje ¡Hola, mundo! debe mostrarse.

Nota

Puede ver más detalles sobre la compilación aumentando el nivel de detalle. Para establecer el nivel de detalle en "detailed", escriba este comando en el símbolo del sistema:

msbuild helloworld.fromscratchproj -t:Build -verbosity:detailed

Agregar propiedades de compilación

Puede agregar propiedades de compilación al archivo de proyecto para controlar aún más la compilación. Ahora agregue estas propiedades:

Propiedad AssemblyName para especificar el nombre de la aplicación.
Propiedad OutputPath para especificar una carpeta que contenga la aplicación.

Para agregar propiedades de compilación

Elimine el archivo ejecutable de aplicación existente (más adelante, agregará un destino de Clean para controlar la eliminación de archivos de salida antiguos).

En el archivo del proyecto, inserte este elemento PropertyGroup justo después del elemento de apertura Project:

<PropertyGroup>
  <AssemblyName>MSBuildSample</AssemblyName>
  <OutputPath>Bin\</OutputPath>
</PropertyGroup>

Agregue esta tarea al destino Build, justo antes de la tarea Csc:
```
<MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
```
La tarea MakeDir crea una carpeta denominada por la propiedad OutputPath, siempre que no exista ninguna carpeta por ese nombre actualmente.
Agregue este atributo OutputAssembly a la tarea Csc:
```
<Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
```
Esto indica al compilador de C# que genere un ensamblado denominado por la propiedad AssemblyName y que lo coloque en la carpeta denominada por la propiedad OutputPath.
Guarde los cambios.

El archivo del proyecto debería parecerse ahora al código siguiente:

<Project>
  <PropertyGroup>
    <AssemblyName>MSBuildSample</AssemblyName>
    <OutputPath>Bin\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
  </Target>
</Project>

Nota

Se recomienda agregar el delimitador de ruta de acceso de barra diagonal inversa (\) al final del nombre de la carpeta al especificarlo en el elemento OutputPath, en lugar de agregarlo en el atributo OutputAssembly de la tarea Csc. Por lo tanto

<OutputPath>Bin\</OutputPath>

OutputAssembly="$(OutputPath)$(AssemblyName).exe" />

es mejor que

<OutputPath>Bin</OutputPath>

OutputAssembly="$(OutputPath)\$(AssemblyName).exe" />

Prueba de las propiedades de compilación

Ahora puede compilar la aplicación mediante el archivo de proyecto en el que usó propiedades de compilación para especificar la carpeta de salida y el nombre de la aplicación.

En el símbolo del sistema, escriba msbuild helloworld.fromscratchproj -t:Build.

Esto crea la carpeta \Bin\ y, a continuación, invoca al compilador de C# para crear la aplicación msBuildSample y la coloca en la carpeta \Bin\.
Para comprobar que se ha creado la carpeta \Bin\ y que contiene la aplicación msBuildSample, escriba dir Bin .
Para probar la aplicación, escriba Bin\MSBuildSample para ejecutar el archivo ejecutable.

El mensaje "¡Hola, mundo!" debe mostrarse.

Agregar destinos de compilación

A continuación, agregue dos destinos más al archivo de proyecto, como se indica a continuación:

Un objetivo de limpieza que elimina los archivos antiguos.
Un destino Rebuild que utilice el atributo DependsOnTargets para obligar a que la tarea Clean se ejecute antes que la tarea Build.

Ahora que tiene varios destinos, puede establecer el destino Build como destino predeterminado.

Para agregar destinos de compilación

En el archivo del proyecto, agregue estos dos destinos justo después del destino Build:
```
<Target Name="Clean" >
  <Delete Files="$(OutputPath)$(AssemblyName).exe" />
</Target>
<Target Name="Rebuild" DependsOnTargets="Clean;Build" />
```
El destino Clean invoca la tarea Eliminar para eliminar la aplicación. El destino de recompilación no se ejecuta hasta que se hayan ejecutado tanto el destino limpio como el destino de compilación. Aunque el destino Rebuild no tiene tareas, hace que el destino Clean se ejecute antes del destino build.
Agregue este atributo DefaultTargets al elemento de apertura Project:
```
<Project DefaultTargets="Build">
```
Esto establece el destino Build como destino predeterminado.

El archivo del proyecto debería parecerse ahora al código siguiente:

<Project DefaultTargets="Build">
  <PropertyGroup>
    <AssemblyName>MSBuildSample</AssemblyName>
    <OutputPath>Bin\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Clean" >
    <Delete Files="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Rebuild" DependsOnTargets="Clean;Build" />
</Project>

Prueba de los destinos de compilación

Puede utilizar los nuevos objetivos de compilación para probar estas funcionalidades del archivo de proyecto:

Compilar la compilación predeterminada.
Configurar el nombre de la aplicación en la línea de comandos.
Eliminar la aplicación antes de compilar otra aplicación.
Eliminar la aplicación sin crear otra aplicación.

Para probar los destinos de compilación

En el símbolo del sistema, escriba msbuild helloworld.fromscratchproj -p:AssemblyName=Greetings.

Dado que no ha usado el modificador -t para establecer explícitamente el destino, MSBuild ejecuta el destino de compilación predeterminado. El modificador -p invalida la propiedad AssemblyName y le proporciona el nuevo valor, Greetings. Esto hace que se cree una nueva aplicación, Greetings.exe, en la carpeta \Bin\.
Para comprobar que la carpeta \Bin\ contiene tanto la aplicación MSBuildSample como la nueva aplicación Greetings, escriba dir Bin.
Pruebe la aplicación Greetings (por ejemplo, escribiendo Bin\Greetings en Windows).

El mensaje Hola, mundo! debe mostrarse.
Para eliminar la aplicación MSBuildSample, escriba msbuild helloworld.fromscratchproj -t:clean.

Esto ejecuta la tarea Clean para quitar la aplicación que tiene el valor de propiedad AssemblyName predeterminado, MSBuildSample.
Para eliminar la aplicación Greetings, escriba msbuild helloworld.fromscratchproj -t:clean -p:AssemblyName=Greetings.

Esto ejecuta la tarea Clean para quitar la aplicación que tiene el valor de propiedad AssemblyName dado, Greetings.
Para comprobar que la carpeta de \Bin\ está vacía, escriba dir Bin .
Escriba msbuild.

Aunque no se especifica un archivo de proyecto, MSBuild compila el helloworld.fromscratchproj archivo porque solo hay un archivo de proyecto en la carpeta actual. Esto hace que la aplicación MSBuildSample se cree en la carpeta \Bin\.

Para comprobar que la carpeta \Bin\ contiene la aplicación MSBuildSample, escriba dir Bin.

Construir de manera incremental

Puede indicar a MSBuild que compile un destino solo si los archivos de origen o los archivos de destino de los que depende el destino han cambiado. MSBuild usa la marca de tiempo de un archivo para determinar si ha cambiado.

Para construir de forma incremental

En el archivo del proyecto, agregue estos atributos al objetivo de compilación inicial:
```
Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe"
```
Esto especifica que el destino de compilación depende de los archivos de entrada que se especifican en el grupo de elementos de Compile y que el destino de salida es el archivo de aplicación.

El destino Build resultante debe ser similar al código siguiente:
```
<Target Name="Build" Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe">
  <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
  <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
</Target>
```
Escriba msbuild -v:d en el símbolo del sistema para probar el destino Build.

Recuerde que helloworld.fromscratchproj es el archivo de proyecto predeterminado y que Build es el destino predeterminado.

El modificador -v:d es una abreviatura del -verbosity:detailed usado anteriormente.

Si ya ha compilado la salida, se deben mostrar estas líneas:

Se omitirá el destino "Build" porque todos los archivos de salida están actualizados respecto a los archivos de entrada.

MSBuild omite el destino de compilación porque ninguno de los archivos de origen ha cambiado desde la última compilación de la aplicación.

Ejemplo de C#

En el ejemplo siguiente se muestra un archivo de proyecto que compila una aplicación de C# y registra un mensaje que contiene el nombre del archivo de salida.

Código

<Project DefaultTargets = "Compile">

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldCS</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <CSFile Include = "*.cs"/>
    </ItemGroup>

    <Target Name="Compile">
        <!-- Run the C# compilation using input files of type CSFile -->
        <CSC
            Sources = "@(CSFile)"
            OutputAssembly = "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the CSC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </CSC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

Ejemplo de Visual Basic

En el ejemplo siguiente se muestra un archivo de proyecto que compila una aplicación de Visual Basic y registra un mensaje que contiene el nombre del archivo de salida.

Código

<Project DefaultTargets = "Compile">

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldVB</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <VBFile Include = "consolehwvb1.vb"/>
    </ItemGroup>

    <Target Name = "Compile">
        <!-- Run the Visual Basic compilation using input files of type VBFile -->
        <VBC
            Sources = "@(VBFile)"
            OutputAssembly= "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the VBC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </VBC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

¿Qué es lo siguiente?

Visual Studio puede realizar automáticamente gran parte del trabajo que se muestra en este tutorial. Para obtener información sobre cómo usar Visual Studio para crear, editar, compilar y probar archivos de proyecto de MSBuild, consulte Usar MSBuild.

Compartir a través de

Creación de un archivo de proyecto de MSBuild desde cero

Ampliación de la ruta de acceso

Creación de una aplicación mínima

Creación de un archivo de proyecto mínimo de MSBuild

Para crear un archivo de proyecto de MSBuild mínimo

Compilación de la aplicación

Agregar propiedades de compilación

Para agregar propiedades de compilación

Prueba de las propiedades de compilación

Agregar destinos de compilación

Para agregar destinos de compilación

Prueba de los destinos de compilación

Para probar los destinos de compilación

Construir de manera incremental

Para construir de forma incremental

Ejemplo de C#

Código

Ejemplo de Visual Basic

Código

¿Qué es lo siguiente?

Comentarios

Recursos adicionales

Compartir a través de

Creación de un archivo de proyecto de MSBuild desde cero

Ampliación de la ruta de acceso

Creación de una aplicación mínima

Creación de un archivo de proyecto mínimo de MSBuild

Para crear un archivo de proyecto de MSBuild mínimo

Compilación de la aplicación

Agregar propiedades de compilación

Para agregar propiedades de compilación

Prueba de las propiedades de compilación

Agregar destinos de compilación

Para agregar destinos de compilación

Prueba de los destinos de compilación

Para probar los destinos de compilación

Construir de manera incremental

Para construir de forma incremental

Ejemplo de C#

Código

Ejemplo de Visual Basic

Código

¿Qué es lo siguiente?

Contenido relacionado

Comentarios

Recursos adicionales