MSBuild (Tarea)

Compila proyectos de MSBuild a partir de otro proyecto de MSBuild.

Parámetros

En la siguiente tabla se describen los parámetros de la tarea MSBuild.

Parámetro	Descripción
BuildInParallel	Parámetro Boolean opcional. Si su valor es true, los proyectos especificados en el parámetro Projects se compilan en paralelo, si es posible. El valor predeterminado es false.
Projects	Parámetro ITaskItem[] requerido. Especifica los archivos de proyecto que se van a compilar.
Properties	Parámetro String opcional. Lista de los pares de nombre y valor de propiedad delimitados por signos de punto y coma que se van a aplicar al proyecto secundario como propiedades globales. Especificar este parámetro equivale funcionalmente a establecer las propiedades con el modificador /property cuando se compila con MSBuild.exe. Por ejemplo: Properties="Configuration=Debug;Optimize=$(Optimize)" Cuando se pasan las propiedades al proyecto mediante el parámetro Properties, MSBuild crea una nueva instancia del proyecto aunque ya se haya cargado el archivo de proyecto. Cuando se ha creado una nueva instancia del proyecto, MSBuild la trata como un proyecto diferente con propiedades globales diferentes y que se puede compilar en paralelo con otras instancias del proyecto. Por ejemplo, una configuración Release podría compilarse al mismo tiempo que una configuración Debug.
RebaseOutputs	Parámetro Boolean opcional. Si es true, las rutas de acceso relativas de los elementos resultantes de destino de los proyectos compilados tienen las rutas de acceso ajustadas para ser relativas al proyecto que realiza la llamada. El valor predeterminado es false.
RemoveProperties	Parámetro String opcional. Especifica el conjunto de propiedades globales que se van a quitar.
RunEachTargetSeparately	Parámetro Boolean opcional. Si su valor es true, la tarea MSBuild invoca cada destino de la lista pasado a MSBuild de uno en uno, en lugar de todos al mismo tiempo. Establecer este parámetro en true garantiza que se invocarán los destinos siguientes aunque se produjera un error en los destinos previamente invocados. En caso contrario, un error de compilación detendría la invocación de todos los destinos siguientes. El valor predeterminado es false.
SkipNonexistentProjects	Parámetro Boolean opcional. Si es true, se omitirán los archivos de proyecto que no existen en el disco. De lo contrario, esos proyectos producirán un error.
StopOnFirstFailure	Parámetro Boolean opcional. Si es true, no se compilará ningún proyecto más cuando uno de los proyectos no se pueda compilar. Esta acción no se admite actualmente al compilar en paralelo (con varios procesadores).
TargetAndPropertyListSeparators	Parámetro String[] opcional. Especifica una lista de destinos y propiedades como metadatos del elemento Project). A los separadores se les quitarán los caracteres de escape antes del procesamiento. por ejemplo %3B (un ';' con escape) se tratará como si fuera un ';' sin escape.
TargetOutputs	Parámetro de salida de sólo lectura ITaskItem[] opcional. Devuelve los resultados de los destinos generados de todos los archivos de proyecto. Se devuelven únicamente los resultados de los destinos especificados; no se devuelven los resultados que puedan existir en los destinos de los que dependen esos destinos. El parámetro TargetOutputs también contiene los metadatos siguientes: MSBuildSourceProjectFile: archivo de proyecto de MSBuild que contiene el destino que establece los resultados. MSBuildSourceTargetName: El destino que establece los resultados. Nota Si desea identificar los resultados de cada archivo de proyecto o destino por separado, ejecute la tarea MSBuild por separado para cada archivo de proyecto o destino.Si ejecuta la tarea MSBuild sólo una vez para compilar todos los archivos de proyecto, los resultados de todos los destinos se recogen en una matriz.
Targets	Parámetro String opcional. Especifica el destino o destinos que se compilarán en los archivos de proyecto. Utilice un punto y coma para separar los nombres de destino en la lista. Si no se especifica ningún destino en la tarea MSBuild, se compilarán los destinos predeterminados especificados en los archivos de proyecto. Nota Los destinos deben existir en todos los archivos de proyecto.De lo contrario, se genera un error de compilación.
ToolsVersion	Parámetro String opcional. Especifica la ToolsVersion que se desea utilizar al compilar proyectos pasados a esta tarea. Permite a una tarea MSBuild compilar un proyecto que tiene como destino una versión diferente de .NET Framework que la especificada en el proyecto. Los valores válidos son 2.0, 3.0 y 3.5. El valor predeterminado es 3.5.
UnloadProjectsOnCompletion	Parámetro Boolean opcional. Si es true, se descargará el proyecto una vez completada la operación.
UseResultsCache	Parámetro Boolean opcional. Si es true, el resultado en caché será devuelto, si está presente. Si se ejecuta la tarea de MSBuild, su resultado se almacenará en caché en un ámbito (nombreDeArchivoDeProyecto, propiedadesGlobales)[nombresDeDestino] como una lista de elementos de compilación

Comentarios

Además de los parámetros mencionados anteriormente, esta tarea hereda los parámetros de la clase TaskExtension, que hereda de la clase Task. Para obtener una lista de estos parámetros adicionales y sus descripciones, vea TaskExtension (Clase base).

A diferencia de cuando se utiliza Exec (Tarea) para iniciar MSBuild.exe, esta tarea utiliza los mismos procesos de MSBuild para compilar los proyectos secundarios. Las compilaciones primarias y secundarias comparten la lista de destinos ya compilados que se pueden omitir. Esta tarea también es más rápida porque no se crea ningún nuevo proceso de MSBuild.

Esta tarea no sólo puede procesar archivos de proyecto sino también archivos de solución.

Es necesario que cualquier configuración requerida por MSBuild para que los proyectos se puedan compilar al mismo tiempo, aunque la configuración implique una infraestructura remota (por ejemplo, puertos, protocolos, tiempos de espera, intentos, etc.), debe poderse configurar mediante un archivo de configuración. Cuando sea posible, los elementos de configuración se deben poder especificar como parámetros en la tarea MSBuild.

A partir de MSBuild 3.5, los proyectos de solución extraen TargetOutputs de todos los subproyectos que compila.

Pasar propiedades a los proyectos

En las versiones de MSBuild anteriores a MSBuild 3.5, pasar conjuntos diferentes de propiedades a los diferentes proyectos enumerados en el elemento MSBuild resultaba un reto. Si utilizaba el atributo Properties de MSBuild (Tarea), se aplicaba su valor a todos los proyectos que se estaban compilando a menos que MSBuild (Tarea) se procesara por lotes y proporcionara condicionalmente las diferentes propiedades para cada proyecto de la lista del elemento.

MSBuild 3.5, sin embargo, dispone de dos nuevos elementos de metadatos reservados, Properties y AdditionalProperties, que ofrece una manera flexible de pasar las diferentes propiedades para los diferentes proyectos que se están compilando con MSBuild (Tarea).

Nota
Estos nuevos elementos de metadatos sólo se aplican a los elementos pasados en el atributo Projects de MSBuild (Tarea).

Ventajas de la compilación para varios procesadores

Una de las principales ventajas de utilizar estos nuevos metadatos se observa al compilar los proyectos en paralelo en un sistema de varios procesadores. Los metadatos permiten consolidar todos los proyectos en una única llamada a MSBuild (Tarea) sin tener que realizar cualquier tarea MSBuild por lotes o condicional. Y, cuando se llama a una única MSBuild (Tarea), todos los proyectos enumerados en el atributo Projects se compilan en paralelo. (Únicamente si el atributo BuildInParallel=true se encuentra en MSBuild (Tarea).) Para obtener más información, vea Generar para varios procesadores.

Metadatos Properties

Un escenario habitual es cuando se compilan varios archivos de solución mediante MSBuild (Tarea), utilizando únicamente diferentes configuraciones de compilación. Es posible que desee compilar la solución a1 con la configuración Debug y la solución a2 con la configuración Release. En MSBuild 2.0, este archivo de proyecto tendría el siguiente aspecto:

Nota
En el ejemplo siguiente, "…" representa los archivos de solución adicionales.

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Debug"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
    </Target>
</Project>

Sin embargo, con los metadatos Properties, puede simplificar este proceso y utilizar una única MSBuild (Tarea), como se muestra a continuación:

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…">
            <Properties>Configuration=Debug</Properties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"/>
    </Target>
</Project>

‑O bien-

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…"/>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)" 
          Properties="Configuration=Debug"/>
    </Target>
</Project>

Metadatos AdditionalProperties

Considere un escenario donde se están compilando dos archivos de solución mediante MSBuild (Tarea), ambos utilizan la configuración Release, pero uno utiliza la arquitectura x86 y el otro la arquitectura ia64. En MSBuild 2.0, sería necesario crear varias instancias de MSBuild (Tarea): una para compilar el proyecto con la configuración Release y la arquitectura x86, y otra con la configuración Release y la arquitectura ia64. Su archivo de proyecto tendría el siguiente aspecto:

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln…" Properties="Configuration=Release; 
          Architecture=x86"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release; 
          Architecture=ia64"/>
    </Target>
</Project>

Con los metadatos AdditionalProperties, puede simplificar este proceso para utilizar una única MSBuild (Tarea) utilizando lo siguiente:

a.proj

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln…">
            <AdditionalProperties>Architecture=x86
              </AdditionalProperties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <AdditionalProperties>Architecture=ia64
              </AdditionalProperties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)" 
          Properties="Configuration=Release"/>
    </Target>
</Project>

Ejemplo

En el ejemplo siguiente se utiliza la tarea MSBuild para compilar los proyectos especificados por la colección de elementos ProjectReferences. Los resultados de destino obtenidos se almacenan en la colección de elementos AssembliesBuiltByChildProjects.

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

    <ItemGroup>
        <ProjectReferences Include="*.*proj" />
    </ItemGroup>

    <Target Name="BuildOtherProjects">
        <MSBuild
            Projects="@(ProjectReferences)"
            Targets="Build">
            <Output
                TaskParameter="TargetOutputs"
                ItemName="AssembliesBuiltByChildProjects" />
        </MSBuild>
    </Target>

</Project>

Vea también

Conceptos

Tareas de MSBuild

Otros recursos

Referencia de tareas de MSBuild

Historial de cambios