Elementos de MSBuild

Artículo
10/07/2008

Actualización: noviembre 2007

Los elementos representan entradas en el sistema de generación que se agrupan en colecciones de elementos basadas en sus correspondientes nombres de colección definidos por el usuario. Estas colecciones de elementos se pueden utilizar como parámetros para tareas, las cuales utilizan elementos individuales incluidos en la colección para llevar a cabo los pasos del proceso de generación.

Crear elementos en un archivo de proyecto

Los elementos se declaran en el archivo de proyecto creando un elemento como elemento secundario de un elemento ItemGroup con el nombre del elemento. El atributo Include del elemento especifica qué archivos se deben incluir con esa colección de elementos. Por ejemplo, el código siguiente crea una colección de elementos denominada Compile que incluye dos archivos.

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

El código siguiente crea la misma colección de elementos declarando ambos archivos en un atributo Include, separados por punto y coma.

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

Hacer referencia a elementos en un archivo de proyecto

A lo largo del archivo de proyecto se hace referencia a las colecciones de elementos con la sintaxis @(ItemCollectionName). Por ejemplo, en el ejemplo anterior se hace referencia a la colección de elementos con @(Compile). Esta sintaxis permite pasar las colecciones de elementos a las tareas especificando la colección de elementos como un parámetro de dicha tarea. Para obtener más información, vea Cómo: Utilizar caracteres comodín para generar todos los archivos de un directorio.

De manera predeterminada, los elementos de las colecciones de elementos se separan mediante signos de punto y coma (;), cuando se expanden. Utilice la sintaxis @(nombreDeColecciónDeElementos, 'separador') para especificar un separador distinto al predeterminado. Para obtener más información, vea Cómo: Mostrar una colección de elementos separados con comas.

Utilizar comodines para especificar elementos

Se pueden utilizar los comodines **, * y ? para especificar un grupo de archivos como entradas de una generación en lugar de enumerar cada archivo por separado. Por ejemplo, para especificar todos los archivos .cs o .vb en el mismo directorio que el archivo de proyecto, use uno de los siguientes elementos en el archivo de proyecto:

O bien

Nota:
Sólo se pueden utilizar comodines con elementos para especificar las entradas de una generación. Por ejemplo, no se pueden utilizar comodines para especificar las entradas del parámetro Sources en la tarea Csc. MSBuild acepta comodines como valores de parámetro, pero los trata como literales de cadena y no los evalúa. El ejemplo siguiente utilizaría el literal de cadena .cs como el valor de parámetro Sources*.

Sólo se pueden utilizar comodines con elementos para especificar las entradas de una generación. Por ejemplo, no se pueden utilizar comodines para especificar las entradas del parámetro Sources en la tarea Csc. MSBuild acepta comodines como valores de parámetro, pero los trata como literales de cadena y no los evalúa. El ejemplo siguiente utilizaría el literal de cadena *.cs como el valor de parámetro Sources.

<Target Name="Compile">
    <CSC Sources="*.cs" />
</Target>

Para obtener más información sobre comodines, vea Cómo: Utilizar caracteres comodín para generar todos los archivos de un directorio.

Utilizar el atributo Exclude

Los elementos también pueden contener el atributo Exclude, que excluye archivos concretos de la colección de elementos. El atributo Exclude resulta útil cuando se utiliza con comodines. Por ejemplo, el código siguiente agrega cada archivo .cs en el directorio, excepto el archivo DoNotBuild.cs.

<ItemGroup>
    <CSFile
        Include="*.cs"
        Exclude="DoNotBuild.cs"/>
</ItemGroup>

Para obtener más información, vea Cómo: Generar todos los archivos de un directorio excepto uno.

Metadatos de elementos

Los elementos pueden contener metadatos además de la información recopilada de los atributos Include y Exclude. Estos metadatos los pueden utilizar aquellas tareas que requieren más información sobre elementos, o se pueden usar para procesar por lotes tareas y destinos. Para obtener más información sobre el procesamiento por lotes, vea Procesamiento por lotes de MSBuild.

Los metadatos de elementos se declaran en el archivo de proyecto creando un elemento con el nombre de los metadatos como elemento secundario del elemento. Un elemento puede tener cero o varios valores de metadatos. Por ejemplo, el elemento siguiente tiene los metadatos Culture con un valor de Fr.

<ItemGroup>
    <CSFile Include="main.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Hacer referencia a metadatos de elementos en un archivo de proyecto

A lo largo del archivo de proyecto se hace referencia a los metadatos de elementos con la sintaxis %(ItemMetadataName). Si hay alguna ambigüedad, se puede aclarar mediante el nombre de la colección de elementos, por ejemplo %(nombreDeColecciónDeElementos.nombreDeMetadatosDeElementos). El ejemplo siguiente usa los metadatos Display para procesar por lotes la tarea Message. Para obtener más información sobre cómo utilizar los metadatos de elementos para el procesamiento por lotes, vea Cómo: Procesar tareas por lotes utilizando metadatos de elementos.

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <Stuff Include="One.cs" >
            <Display>false</Display>
        </Stuff>
        <Stuff Include="Two.cs">
            <Display>true</Display>
        </Stuff>
    </ItemGroup>
    <Target Name="Batching">
        <Message Text="@(Stuff)" Condition=" '%(Display)' == 'true' "/>
    </Target>
</Project>

Metadatos de elementos conocidos

Siempre que se agrega un elemento a una colección de elementos, dicho elemento se crea y se le asignan metadatos de elementos conocidos, por ejemplo, %(Filename), que contiene el nombre de archivo del elemento. Para obtener una lista completa de metadatos de elementos conocidos, vea Metadatos de los elementos conocidos de MSBuild.

Transformar las colecciones de elementos

Las colecciones de elementos se pueden transformar en nuevas colecciones de elementos. Por ejemplo, una colección de elementos de archivos .cpp se puede transformar en una colección de archivos .obj mediante una expresión como @(CppFiles -> '%(Filename).obj'). Para obtener más información, vea Transformaciones de MSBuild.

Vea también