MSBuild (Tarea)

Actualización: noviembre 2007

Genera 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 generan en paralelo, si es posible. El valor predeterminado es true.
Projects	Parámetro ITaskItem[] requerido. Especifica los archivos de proyecto que se van a generar.
Properties	Parámetro String opcional. Una lista delimitada por punto y coma de pares de nombre/valor de propiedad que se aplicarán al proyecto secundario como propiedades globales. Especificar este parámetro equivale funcionalmente a establecer las propiedades con el modificador /property cuando se genera 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 generar en paralelo con otras instancias del proyecto. Por ejemplo, una configuración Release podría generarse al mismo tiempo que un configuración Debug.
ToolsVersion	Parámetro String opcional. Permite a una tarea MSBuild generar 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.
RebaseOutputs	Parámetro Boolean opcional. Si es true, las rutas de acceso relativas de los elementos resultantes de destino de los proyectos generados tienen las rutas de acceso ajustadas para ser relativas al proyecto que realiza la llamada. El valor predeterminado es false.
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.
StopOnFirstFailure	Parámetro Boolean opcional. Si su valor es true, obliga a que la tarea deje de generar los proyectos restantes en cuanto se produzca un error en cualquiera de ellos.
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 sólo los resultados de los destinos especificados, no cualquier resultado que pueda existir en los destinos de los que dependen esos destinos. El parámetro TargetOutputs también contiene los metadatos siguientes: MSBuildProjectFile: archivo de proyecto de MSBuild que contiene el destino que establece los resultados. MSBuildTargetName: 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 generar 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 generarán en los archivos de proyecto. Utilice un punto y coma para separar una lista de nombres de destino. Si no se especifica ningún destino en la tarea MSBuild, se generará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.

Comentarios

A diferencia de cuando se utiliza Exec (Tarea) para iniciar MSBuild.exe, esta tarea utiliza los mismos procesos de MSBuild para generar los proyectos secundarios. Las generaciones primarias y secundarias comparten la lista de destinos ya generados 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 generar 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 genera.

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 generando 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 generando 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 generar 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 generan 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 generan varios archivos de solución mediante MSBuild (Tarea), utilizando únicamente diferentes configuraciones de compilación. Es posible que desee generar 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 generando 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 generar 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 generar 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