Elementos de MSBuild

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

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

Crear elementos en un archivo de proyecto

Los elementos se declaran 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 al elemento "file1.cs" sino que se anexa a la lista de valores del tipo de elemento Compile. Durante la fase de evaluación de una compilación, no se puede quitar ningún elemento de un tipo de elemento.

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

A los elementos ubicados fuera de los elementos Target se les asignan valores durante la fase de evaluación de una compilación. En la siguiente fase de la ejecución, se pueden crear o modificar elementos de la siguiente manera:

  • Cualquier tarea puede emitir elementos. Para emitir un elemento, el elemento Task debe tener un elemento Output secundario que tenga un atributo ItemName.

  • La tarea CreateItem puede emitir elementos (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, se usaría @(Compile). Esta sintaxis permite pasar elementos a una tarea especificando el tipo de elemento como un parámetro de dicha tarea. Para obtener más información, vea Cómo: Seleccionar los archivos que se van a compilar.

De manera predeterminada, los elementos de un tipo de elemento se separan mediante signos de punto y coma (;) cuando se expande. Use la sintaxis @(tipoDeElemento, '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, para especificar todos los archivos .cs ubicados en el directorio que contiene el archivo de proyecto, use el siguiente elemento en el archivo de proyecto.

<CSFile Include="*.cs"/>

Un ejemplo de un elemento que selecciona todos los archivos .vb en la unidad D: sería

<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 sólo afecta a los elementos agregados por el atributo Include en el elemento que contiene ambos. Por ejemplo,

<Compile Include="*.cs" />

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

no excluiría el archivo Form1.cs, que se agregó en el elemento anterior.

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

Usar el atributo Remove

A partir de .NET Framework 3.5, los elementos Target pueden contener elementos ItemGroup que, a su vez, pueden contener elementos. Estos elementos pueden contener el atributo Remove, que quita elementos (archivos) concretos del tipo de elemento. Por ejemplo, el código XML siguiente quita todos los archivos .config del tipo de elemento Compile.

<Target>

<ItemGroup>

<Compile Remove="*.config"/>

</ItemGroup>

</Target>

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 los 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 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 tienen 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. Los valores de los metadatos se pueden cambiar en cualquier momento. Si se establecen los metadatos en un valor vacío, se quitan de la compilación.

Hacer referencia a metadatos de elementos en un archivo de proyecto

Para hacer referencia a los metadatos de los elementos en el archivo de proyecto, se usa la sintaxis %(ItemMetadataName). En caso de ambigüedad, se puede utilizar un calificador de tipo de elemento; por ejemplo, %(ItemType.ItemMetaDataName). En el siguiente ejemplo, se usan los metadatos Display para procesar por lotes 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 de archivo del elemento. Para obtener una lista de metadatos de elementos conocidos, vea Metadatos de los elementos conocidos de MSBuild.

Transformar tipos de elemento mediante metadatos

Las listas de elementos se pueden transformar en nuevas listas de elementos mediante metadatos. Por ejemplo, un tipo de elemento CppFiles que tiene elementos que representan archivos .cpp puede transformarse 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, el elemento ItemDefinitionGroup permite agregar metadatos predeterminados a cualquier tipo de elemento. Al igual que los metadatos conocidos, los metadatos predeterminados están asociados a todos los elementos del tipo de elemento especificado. Los metadatos predeterminados se pueden reemplazar explícitamente en una definición de elemento. Por ejemplo, el siguiente código XML asigna a los elementos "one.cs" y "three.cs" de Compile los metadatos BuildDay con el valor "Monday", y 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.

Vea también

Tareas

Cómo: Seleccionar los archivos que se van a compilar

Cómo: Excluir archivos de la compilación

Cómo: Mostrar una lista de elementos separados por comas

Referencia

Elemento Item (MSBuild)

Conceptos

Definiciones de elementos

Procesamiento por lotes de MSBuild

Otros recursos

Conceptos de MSBuild

MSBuild Overview

  • Last updated on