Elementos de MSBuild

Artículo
02/19/2013

Los elementos de MSBuild son entradas del sistema de compilación, y normalmente representan archivos.Se agrupan en tipos de acuerdo con el nombre de sus elementos.Los tipos de elemento son listas de elementos con nombre que se pueden usar como parámetros de las tareas.Las tareas utilizan los valores de los elementos para llevar a cabo los pasos del proceso de compilación.

Dado que los elementos viene determinado por el tipo de elemento al que pertenecen, los términos “elemento” y “valor de elemento” se pueden usar indistintamente.

En este tema

Crear elementos en un archivo de proyecto
Crear elementos durante la ejecución
Hacer referencia a elementos en un archivo de proyecto
Utilizar comodines para especificar elementos
Utilizar el atributo Exclude
Metadatos de elementos
- Hacer referencia a metadatos de elementos en un archivo de proyecto
- Metadatos de elementos conocidos
- Transformar tipos de elementos mediante metadatos
Definiciones de elementos
Atributos de los elementos en ItemGroup de un destino
- Quite el atributo
- Atributo de KeepMetadata
- Atributo de RemoveMetadata
- Atributo de KeepDuplicates

Crear elementos en un archivo de proyecto

Declare elementos en el archivo de proyecto como elementos secundarios de un elemento ItemGroup .El nombre del elemento secundario es el tipo del elemento.El atributo Include del elemento especifica qué elementos (archivos) se deben incluir en ese tipo de elemento.Por ejemplo, el siguiente código XML crea un tipo de elemento denominado Compile, que incluye dos archivos.

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

El elemento “file2.cs” no reemplaza el elemento “file1.cs”; en su lugar, el nombre de archivo se anexa a la lista de valores del tipo de elemento Compile .No puede quitar un elemento de un tipo de elemento durante la fase de evaluación de una compilación.

El siguiente código XML crea el mismo tipo de elemento declarando ambos archivos en un solo atributo Include.Observe que los nombres de archivo están separados por un signo de punto y coma.

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

Crear elementos durante la ejecución

Los elementos que son elementos fuera Destino se les asignan valores durante la fase de evaluación de una compilación.Durante la fase de ejecución, se pueden crear o modificar elementos de las maneras siguientes:

Cualquier tarea puede emitir un elemento.Para emitir un elemento, el elemento Task debe tener un elemento Output secundario que tenga un atributo ItemName.
La tarea CreateItem puede emitir un elemento.(desusado).
A partir de .NET Framework 3.5, los elementos Target pueden contener elementos ItemGroup que, a su vez, pueden contener elementos.

Hacer referencia a elementos en un archivo de proyecto

Para hacer referencia a los tipos de elemento en el archivo de proyecto, se usa la sintaxis @ (ItemType).Por ejemplo, para hacer referencia al tipo de elemento del ejemplo anterior mediante @(Compile).Con esta sintaxis, puede pasar elementos a una tarea especificando el tipo de elemento como parámetro de esa tarea.Para obtener más información, vea Cómo: Seleccionar los archivos que se van a compilar.

De forma predeterminada, los elementos de un tipo de elemento se separan mediante puntos y coma (;) cuando ha expandido.Puede utilizar la sintaxis @ (ItemType, “separador") para especificar un separador distinto del predeterminado.Para obtener más información, vea Cómo: Mostrar una lista de elementos separados por comas.

Utilizar comodines para especificar elementos

Puede usar los caracteres comodín **, * y ?para especificar un grupo de archivos como entrada de una compilación en lugar de enumerar cada archivo por separado.

El carácter comodín ?coincide con un carácter individual.
El carácter comodín * coincide con cero o más caracteres.
La secuencia de caracteres ** coincide con una ruta de acceso parcial.

Por ejemplo, puede especificar todos los archivos .cs ubicados en el directorio que contiene el archivo de proyecto mediante el elemento siguiente en el archivo de proyecto.

<CSFile Include="*.cs"/>

El elemento siguiente selecciona todos los archivos .vb en d: unidad:

<VBFile Include="D:/**/*.vb"/>

Para obtener más información sobre los caracteres comodín, vea Cómo: Seleccionar los archivos que se van a compilar.

Utilizar el atributo Exclude

Los elementos pueden contener el atributo Exclude, que excluye elementos (archivos) concretos del tipo de elemento.El atributo Exclude suele usarse con caracteres comodín.Por ejemplo, el código XML siguiente agrega todos los archivos .cs ubicados en el directorio al tipo de elemento CSFile, excepto el archivo DoNotBuild.cs.

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

El atributo Exclude solo afecta a los elementos que son agregados por el atributo Include en el elemento que contiene ambos.El ejemplo siguiente no excluiría el archivo Form1.cs, que se agregó en el elemento anterior.

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

Para obtener más información, vea Cómo: Excluir archivos de la compilación.

Metadatos de elementos

Los elementos pueden contener metadatos además de la información sobre los atributos Include y Exclude .Estos metadatos los pueden utilizar las tareas que requieren más información sobre los elementos o a tareas y destinos de lote.Para obtener más información, vea Procesamiento por lotes de MSBuild.

Los metadatos son una colección de pares clave-valor que se declaran en el archivo de proyecto como elementos secundarios de un elemento.El nombre y el valor del elemento secundario es el nombre y el valor de los metadatos.

Los metadatos están asociados al elemento que los contiene.Por ejemplo, el código XML siguiente agrega los metadatos Culture que tiene el valor Fr a los elementos “one.cs” y “two.cs” del tipo de elemento CSFile.

<ItemGroup>
    <CSFile Include="one.cs;two.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

Un elemento puede tener cero o varios valores de metadatos.Puede cambiar los valores de los metadatos en cualquier momento.Si los metadatos establecidos en un valor vacío, lo quita eficazmente de compilación.

Hacer referencia a metadatos de elementos en un archivo de proyecto

Puede hacer referencia a metadatos de elemento en el archivo de proyecto con la sintaxis % (ItemMetadataName).Si existe la ambigüedad, puede calificar una referencia utilizando el nombre del tipo de elemento.Por ejemplo, puede especificar % (ItemType.ItemMetaDataName). El ejemplo siguiente usa los metadatos de presentación al lote la tarea message.Para obtener más información sobre cómo usar los metadatos de los elementos para el procesamiento por lotes, vea Metadatos de elementos en el procesamiento por lotes de tareas.

<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

Cuando se agrega un elemento a un tipo de elemento, se le asignan metadatos conocidos.Por ejemplo, todos los elementos tienen los metadatos conocidos %(Filename), cuyo valor es el nombre del elemento.Para obtener más información, vea Metadatos de los elementos conocidos de MSBuild.

Transformar tipos de elementos mediante metadatos

Puede transformar listas de elementos en listas de elementos mediante metadatos.Por ejemplo, puede transformar un tipo de elemento CppFiles que tiene elementos que representan archivos .cpp en una lista correspondiente de archivos .obj mediante la expresión @(CppFiles -> '%(Filename).obj').

El código siguiente crea un tipo de elemento CultureResource que contiene copias de todos los elementos EmbeddedResource con metadatos Culture.El valor de los metadatos Culture pasa a ser el valor de los nuevos metadatos CultureResource.TargetDirectory.

<Target Name="ProcessCultureResources">
    <ItemGroup>
        <CultureResource Include="@(EmbeddedResource)"
            Condition="'%(EmbeddedResource.Culture)' != ''">
            <TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
        </CultureResource>
    </ItemGroup>
</Target>

Para obtener más información, vea Transformaciones de MSBuild.

Definiciones de elementos

A partir de .NET Framework 3.5, puede agregar metadatos predeterminados a cualquier tipo de elemento mediante Elemento ItemDefinitionGroup.Como metadatos conocidos, los metadatos predeterminados están asociados a todos los elementos del tipo de elemento especificado.Puede reemplazar explícitamente metadatos predeterminados en una definición de elemento.Por ejemplo, el siguiente código XML asigna a los elementos “one.cs” y “three.cs” Compile metadatos BuildDay con el valor “monday”.El código asigna al elemento “two.cs” los metadatos BuildDay con el valor “tuesday”.

<ItemDefinitionGroup>
    <Compile>
        <BuildDay>Monday</BuildDay>
    </Compile>
</ItemDefinitionGroup>
<ItemGroup>
    <Compile Include="one.cs;three.cs" />
    <Compile Include="two.cs">
        <BuildDay>Tuesday</BuildDay>
    </Compile>
</ItemGroup>

Para obtener más información, vea Definiciones de elementos.

Atributos de los elementos en ItemGroup de un destino

A partir de .NET Framework 3.5, los elementos Target pueden contener elementos ItemGroup que, a su vez, pueden contener elementos.Los atributos de esta sección son válidos cuando se especifican para un elemento en ItemGroup que esté en Target.

Quite el atributo

Los elementos ItemGroup de un destino pueden contener el atributo Remove , que quita elementos (archivos) concretos del tipo de elemento.Este atributo se incorporó en .NET Framework 3.5.

El ejemplo siguiente quita todos los archivos .config del tipo de elemento compile.

<Target>
    <ItemGroup>
        <Compile Remove="*.config"/>
    </ItemGroup>
</Target>

Atributo de KeepMetadata

Si un elemento se representa dentro de un destino, el elemento puede contener el atributo KeepMetadata .Si se especifica este atributo, solo los metadatos que se especifica en la lista delimitada por puntos y comas de nombres se transferirán del elemento de origen al elemento de destino.Un valor vacío para este atributo equivale a no especificarlo.El atributo KeepMetadata se incorporó en .NET Framework 4,5.

El ejemplo siguiente se muestra cómo utilizar el atributo KeepMetadata .

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

    <ItemGroup>
        <FirstItem Include="rhinoceros">
            <Class>mammal</Class>
            <Size>large</Size>
        </FirstItem>

    </ItemGroup>
    <Target Name="MyTarget">
        <ItemGroup>
            <SecondItem Include="@(FirstItem)" KeepMetadata="Class" />
        </ItemGroup>

        <Message Text="FirstItem: %(FirstItem.Identity)" />
        <Message Text="  Class: %(FirstItem.Class)" />
        <Message Text="  Size:  %(FirstItem.Size)"  />

        <Message Text="SecondItem: %(SecondItem.Identity)" />
        <Message Text="  Class: %(SecondItem.Class)" />
        <Message Text="  Size:  %(SecondItem.Size)"  />
    </Target>
</Project>

<!--
Output:
  FirstItem: rhinoceros
    Class: mammal
    Size:  large
  SecondItem: rhinoceros
    Class: mammal
    Size: 
-->

Atributo de RemoveMetadata

Si un elemento se representa dentro de un destino, el elemento puede contener el atributo RemoveMetadata .Si se especifica este atributo, todos los metadatos se transfieren del elemento de origen al elemento de destino excepto los metadatos cuyos nombres contiene la lista delimitada por puntos y comas de nombres.Un valor vacío para este atributo equivale a no especificarlo.El atributo RemoveMetadata se incorporó en .NET Framework 4,5.

El ejemplo siguiente se muestra cómo utilizar el atributo RemoveMetadata .

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

    <PropertyGroup>
        <MetadataToRemove>Size;Material</MetadataToRemove>
    </PropertyGroup>

    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item2 Include="@(Item1)" RemoveMetadata="$(MetadataToRemove)" />
        </ItemGroup>

        <Message Text="Item1: %(Item1.Identity)" />
        <Message Text="  Size:     %(Item1.Size)" />
        <Message Text="  Color:    %(Item1.Color)" />
        <Message Text="  Material: %(Item1.Material)" />
        <Message Text="Item2: %(Item2.Identity)" />
        <Message Text="  Size:     %(Item2.Size)" />
        <Message Text="  Color:    %(Item2.Color)" />
        <Message Text="  Material: %(Item2.Material)" />
    </Target>
</Project>

<!--
Output: 
  Item1: stapler
    Size:     medium
    Color:    black
    Material: plastic
  Item2: stapler
    Size:     
    Color:    black
    Material: 
-->

Atributo de KeepDuplicates

Si un elemento se representa dentro de un destino, el elemento puede contener el atributo KeepDuplicates .KeepDuplicates es un atributo Boolean que especifica si un elemento se debe agregar al grupo destino si el elemento es un duplicado exacto de un elemento existente.

Si el elemento de origen y de destino tiene el mismo valor de inclusión pero distintos metadatos, se agrega el elemento aunque KeepDuplicates se establece en false.Un valor vacío para este atributo equivale a no especificarlo.El atributo KeepDuplicates se incorporó en .NET Framework 4,5.

El ejemplo siguiente se muestra cómo utilizar el atributo KeepDuplicates .

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

    <ItemGroup>
        <Item1 Include="hourglass;boomerang" />
        <Item2 Include="hourglass;boomerang" />
    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <Item1 Include="hourglass" KeepDuplicates="false" />
            <Item2 Include="hourglass" />
        </ItemGroup>

        <Message Text="Item1: @(Item1)" />
        <Message Text="  %(Item1.Identity)  Count: @(Item1->Count())" />
        <Message Text="Item2: @(Item2)" />
        <Message Text="  %(Item2.Identity)  Count: @(Item2->Count())" />
    </Target>
</Project>

<!--
Output: 
  Item1: hourglass;boomerang
    hourglass  Count: 1
    boomerang  Count: 1
  Item2: hourglass;boomerang;hourglass
    hourglass  Count: 2
    boomerang  Count: 1
-->

Vea también

Compartir a través de