Definiciones de elementosItem definitions

MSBuildMSBuild 2.0 permite la declaración estática de los elementos de archivos de proyecto mediante el elemento ItemGroup. 2.0 enables the static declaration of items in project files by using the ItemGroup element. Sin embargo, sólo se pueden agregar metadatos en el nivel de elemento, aunque los metadatos sean idénticos para todos los elementos.However, metadata may be added only at the item level, even if the metadata is identical for all items. A partir de MSBuildMSBuild 3.5, un elemento de proyecto denominado ItemDefinitionGroup resuelve esta limitación.Starting in MSBuildMSBuild 3.5, a project element named ItemDefinitionGroup overcomes this limitation. ItemDefinitionGroup permite definir un conjunto de definiciones de elementos, las cuales agregan valores de metadatos predeterminados a todos los elementos del tipo de elemento especificado.ItemDefinitionGroup lets you define a set of item definitions, which add default metadata values to all items in the named item type.

El elemento ItemDefinitionGroup aparece inmediatamente después del elemento Project del archivo de proyecto.The ItemDefinitionGroup element appears immediately after the Project element of the project file. Las definiciones de elementos proporcionan la funcionalidad siguiente:Item definitions provide the following functionality:

  • Puede definir metadatos predeterminados globales para los elementos fuera de un destino.You can define global default metadata for items outside a target. Es decir, los mismos metadatos se aplican a todos los elementos del tipo especificado.That is, the same metadata applies to all items of the specified type.

  • Los tipos de elementos pueden tener varias definiciones.Item types can have multiple definitions. Cuando se agregan otras especificaciones de metadatos al tipo, la última especificación tiene la prioridad.When additional metadata specifications are added to the type, the last specification takes precedence. (Los metadatos siguen el mismo orden de importación que las propiedades.)(The metadata follows the same import order as properties follow.)

  • Los metadatos pueden ser aditivos.Metadata can be additive. Por ejemplo, los valores de CDefines se acumulan condicionalmente, dependiendo de las propiedades que se establezcan.For example, CDefines values are accumulated conditionally, depending on the properties that are being set. Por ejemplo: MT;STD_CALL;DEBUG;UNICODE.For example, MT;STD_CALL;DEBUG;UNICODE.

  • Se puede quitar los metadatos.Metadata can be removed.

  • Se puede utilizar condiciones para controlar la inclusión de metadatos.Conditions can be used to control the inclusion of metadata.

Valores predeterminados de los metadatos de elementosItem metadata default values

Los metadatos de elemento definidos en ItemDefinitionGroup son simplemente una declaración de los metadatos predeterminados.Item metadata that is defined in an ItemDefinitionGroup is just a declaration of default metadata. Los metadatos no se aplican a menos que defina un elemento que utilice un ItemGroup para contener los valores de los metadatos.The metadata does not apply unless you define an Item that uses an ItemGroup to contain the metadata values.

Nota

En muchos de los ejemplos de este tema, se muestra un elemento de ItemDefinitionGroup pero se omite su definición de ItemGroup correspondiente para mayor claridad.In many of the examples in this topic, an ItemDefinitionGroup element is shown but its corresponding ItemGroup definition is omitted for clarity.

Los metadatos definidos explícitamente en un ItemGroup tienen prioridad sobre los metadatos de ItemDefinitionGroup.Metadata explicitly defined in an ItemGroup takes precedence over metadata in ItemDefinitionGroup. Los metadatos de ItemDefinitionGroup sólo se aplican para los metadatos no definidos en ItemGroup.Metadata in ItemDefinitionGroup is applied only for undefined metadata in an ItemGroup. Por ejemplo:For example:

<ItemDefinitionGroup>  
    <i>  
        <m>m1</m>  
        <n>n1</n>  
    </i>        
</ItemDefinitionGroup>  
<ItemGroup>  
    <i Include="a">  
        <o>o1</o>  
        <n>n2</n>  
    </i>  
</ItemGroup>  

En este ejemplo, los metadatos predeterminados "m" se aplican al elemento "i" porque los metadatos "m" no están definidos explícitamente por el elemento "i".In this example, the default metadata "m" is applied to Item "i" because metadata "m" is not explicitly defined by Item "i". Sin embargo, los metadatos predeterminados "n" no se aplican al elemento "i" porque los metadatos "n" ya están definidos por el elemento "i".However, default metadata "n" is not applied to Item "i" because metadata "n" is already defined by Item "i".

Nota

Los nombres de los elementos y parámetros XML distinguen entre mayúsculas y minúsculas.XML Element and Parameter names are case-sensitive. Los nombres de los metadatos de elemento y los nombres de elementos/propiedades no distinguen entre mayúsculas y minúsculas.Item metadata and Item/Property names are not case-sensitive. Por consiguiente, los elementos de ItemDefinitionGroup que tienen nombres que sólo difieren en las mayúsculas y minúsculas se deberán tratar como el mismo ItemGroup.Therefore, ItemDefinitionGroup items that have names that differ only by case should be treated as the same ItemGroup.

Orígenes de los valoresValue sources

Los valores de los metadatos definidos en ItemDefinitionGroup pueden proceder de muchos orígenes diferentes, como se indica a continuación:The values for metadata that is defined in an ItemDefinitionGroup can come from many different sources, as follows:

  • Propiedad PropertyGroupPropertyGroup Property

  • Elemento de un ItemDefinitionGroupItem from an ItemDefinitionGroup

  • Transformación de un elemento de ItemDefinitionGroupItem transform on an ItemDefinitionGroup Item

  • Variable de entornoEnvironment variable

  • Propiedad global (de la línea de comandos de MSBuild.exe)Global property (from the MSBuild.exe command line)

  • Propiedad reservadaReserved property

  • Metadatos conocidos en un elemento de un ItemDefinitionGroupWell-known metadata on an Item from an ItemDefinitionGroup

  • Sección CDATA<![CDATA[no se analiza nada de lo que se escriba aquí]]>CDATA section <![CDATA[anything here is not parsed]]>

Nota

Los metadatos de elemento de un ItemGroup no son útiles en una declaración de metadatos de ItemDefinitionGroup porque los elementos de ItemDefinitionGroup se procesan antes que los elementos de ItemGroup.Item metadata from an ItemGroup is not useful in an ItemDefinitionGroup metadata declaration because ItemDefinitionGroup elements are processed before ItemGroup elements.

Definiciones aditivas y múltiplesAdditive and multiple definitions

Al agregar definiciones o utilizar varios ItemDefinitionGroups, recuerde lo siguiente:When you add definitions or use multiple ItemDefinitionGroups, remember the following:

  • La especificación de los metadatos adicionales se agrega al tipo.Additional metadata specification is added to the type.

  • La última especificación tiene prioridad.The last specification takes precedence.

Cuando hay varios ItemDefinitionGroups, cada especificación posterior agrega sus metadatos a la definición anterior.When you have multiple ItemDefinitionGroups, each subsequent specification adds its metadata to the previous definition. Por ejemplo:For example:

<ItemDefinitionGroup>  
    <i>  
        <m>m1</m>  
        <n>n1</n>  
    </i>  
</ItemDefinitionGroup>  
<ItemDefinitionGroup>  
    <i>  
        <o>o1</o>  
    </i>  
</ItemDefinitionGroup>  

En este ejemplo, los metadatos "o" se agregan a "m" y "n".In this example, the metadata "o" is added to "m" and "n".

Además, se puede agregar también los valores de los metadatos previamente definidos.In addition, previously defined metadata values can also be added. Por ejemplo:For example:

<ItemDefinitionGroup>  
    <i>  
        <m>m1</m>  
    </i>  
</ItemDefinitionGroup>  
<ItemDefinitionGroup>  
    <i>  
        <m>%(m);m2</m>  
    </i>  
</ItemDefinitionGroup>    

En este ejemplo, el valor previamente definido para los metadatos "m" (m1) se agrega al nuevo valor (m2), de modo que el valor final es "m1;m2".In this example, the previously defined value for metadata "m" (m1) is added to the new value (m2), so that the final value is "m1;m2".

Nota

Esto también puede ocurrir en el mismo ItemDefinitionGroup.This can also occur in the same ItemDefinitionGroup.

Cuando se invalidan los metadatos previamente definidos, la última especificación toma la prioridad.When you override the previously defined metadata, the last specification takes precedence. En el ejemplo siguiente, el valor final de los metadatos "m" va de "m1" a "m1a".In the following example, the final value of metadata "m" goes from "m1" to "m1a".

<ItemDefinitionGroup>  
    <i>  
        <m>m1</m>  
    </i>  
</ItemDefinitionGroup>  
<ItemDefinitionGroup>  
    <i>  
        <m>m1a</m>  
    </i>  
</ItemDefinitionGroup>    

Uso de condiciones en ItemDefinitionGroupUse conditions in an ItemDefinitionGroup

Puede utilizar condiciones en un ItemDefinitionGroup para controlar la inclusión de metadatos.You can use conditions in an ItemDefinitionGroup to control the inclusion of metadata. Por ejemplo:For example:

<ItemDefinitionGroup Condition="'$(Configuration)'=='Debug'">  
    <i>  
        <m>m1</m>  
    </i>  
</ItemDefinitionGroup>  

En este caso, los metadatos predeterminados "m1" en el elemento "i" sólo se incluyen si el valor de la propiedad "Configuration" es "Debug".In this case, the default metadata "m1" on item "i" is included only if the value of the "Configuration" property is "Debug".

Nota

Las condiciones sólo admiten las referencias a los metadatos locales.Only local metadata references are supported in conditions.

Las referencias a los metadatos definidos en un ItemDefinitionGroup anterior son locales del elemento, no del grupo de definiciones.References to metadata defined in an earlier ItemDefinitionGroup are local to the item, not the definition group. Es decir, el ámbito de las referencias es específico del elemento.That is, the scope of the references are item-specific. Por ejemplo:For example:

<ItemDefinitionGroup>  
    <test>  
        <yes>1</yes>  
    </test>  
    <i> 
        <m>m0</m>
        <m Condition="'%(test.yes)'=='1'">m1</m>  
    </i>  
</ItemDefinitionGroup>  

En el ejemplo anterior, el elemento "i" hace referencia al elemento "test" de Condition.In the above example, item "i" references item "test" in its Condition. Esta condición nunca será true porque MSBuild interpreta una referencia a metadatos de otro elemento en ItemDefinitionGroup como una cadena vacía.This Condition will never be true because MSBuild interprets a reference to another item's metadata in an ItemDefinitionGroup as the empty string. Por lo tanto, "m" se establecerá en "m0".Therefore, "m" would be set to "m0."

  <ItemDefinitionGroup>
    <i>
      <m>m0</m>
      <yes>1</yes>
      <m Condition="'%(i.yes)'=='1'">m1</m>
    </i>
  </ItemDefinitionGroup>

En el ejemplo anterior, "m" se establecería en el valor "m1", ya que Condition hace referencia al valor de metadatos de "i" para el elemento "yes".In the above example, "m" would be set to the value "m1" as the Condition references item "i"'s metadata value for item "yes."

Invalidación y eliminación de metadatosOverride and delete metadata

Los metadatos definidos en un elemento ItemDefinitionGroup se pueden invalidar en un elemento ItemDefinitionGroup posterior estableciendo los valores de los metadatos en blanco.Metadata defined in an ItemDefinitionGroup element can be overridden in a later ItemDefinitionGroup element by setting the metadata value to blank. También puede eliminar eficazmente un elemento de metadatos estableciéndolo en un valor vacío.You can also effectively delete a metadata item by setting it to an empty value. Por ejemplo:For example:

<ItemDefinitionGroup>  
    <i>  
        <m>m1</m>  
    </i>  
</ItemDefinitionGroup>  
<ItemDefinitionGroup>  
    <i>  
        <m></m>  
    </i>  
</ItemDefinitionGroup>  

El elemento "i" aún los metadatos "m" pero, ahora, su valor es vacío.The item "i" still contains metadata "m", but its value is now empty.

Ámbito de metadatosScope of metadata

ItemDefinitionGroup tiene un ámbito global en las propiedades definidas y globales, independientemente de donde se definan.ItemDefinitionGroups have global scope on defined and global properties wherever they are defined. Las definiciones de los metadatos predeterminadas en un ItemDefinitionGroup pueden ser de autorreferencia.Default metadata definitions in an ItemDefinitionGroup can be self-referential. Por ejemplo, a continuación se utiliza una referencia de metadatos simple:For example, the following uses a simple metadata reference:

<ItemDefinitionGroup>  
    <i>  
        <m>m1</m>  
        <m>%(m);m2</m>  
    </i>  
</ItemDefinitionGroup>  

También se puede utilizar una referencia de metadatos calificada:A qualified metadata reference can also be used:

<ItemDefinitionGroup>  
    <i>  
      <m>m1</m>  
      <m>%(i.m);m2</m>  
    </i>  
</ItemDefinitionGroup>  

Sin embargo, el siguiente ejemplo no es válido:However, the following is not valid:

<ItemDefinitionGroup>  
    <i>  
        <m>m1</m>  
        <m>@(x)</m>  
    </i>  
</ItemDefinitionGroup>  

A partir de MSBuildMSBuild 3.5, ItemGroups también puede ser de autorreferencia.Beginning in MSBuildMSBuild 3.5, ItemGroups can also be self-referential. Por ejemplo:For example:

<ItemGroup>  
    <item Include="a">  
        <m>m1</m>  
        <m>%(m);m2</m>  
    </item>  
</ItemGroup>  

Vea tambiénSee also

Procesamiento por lotesBatching