Definice položekItem definitions

MSBuild 2,0 umožňuje statické deklaraci položek v souborech projektu pomocí elementu ItemCollection .MSBuild 2.0 enables the static declaration of items in project files by using the ItemGroup element. Metadata však mohou být přidána pouze na úrovni položky, i když jsou metadata identická pro všechny položky.However, metadata may be added only at the item level, even if the metadata is identical for all items. Od MSBuild 3,5 se toto omezení přeItemDefinitionGroup prvkem projektu s názvem.Starting in MSBuild 3.5, a project element named ItemDefinitionGroup overcomes this limitation. ItemDefinitionGroup umožňuje definovat sadu definic položek, které přidávají výchozí hodnoty metadat všem položkám v typu pojmenované položky.ItemDefinitionGroup lets you define a set of item definitions, which add default metadata values to all items in the named item type.

Element ItemDefinitionGroup se zobrazí hned po elementu projektu souboru projektu.The ItemDefinitionGroup element appears immediately after the Project element of the project file. Definice položek poskytují následující funkce:Item definitions provide the following functionality:

  • Můžete definovat globální výchozí metadata pro položky mimo cíl.You can define global default metadata for items outside a target. To znamená, že stejná metadata platí pro všechny položky zadaného typu.That is, the same metadata applies to all items of the specified type.

  • Typy položek mohou mít více definicí.Item types can have multiple definitions. Při přidání dalších specifikací metadat k typu má přednost poslední specifikace.When additional metadata specifications are added to the type, the last specification takes precedence. (Tato metadata následují po stejném pořadí importu jako vlastnosti.)(The metadata follows the same import order as properties follow.)

  • Metadata lze přidávat.Metadata can be additive. Například hodnoty CDefines se sčítají podmíněně v závislosti na vlastnostech, které se nastavují.For example, CDefines values are accumulated conditionally, depending on the properties that are being set. Například, MT;STD_CALL;DEBUG;UNICODE.For example, MT;STD_CALL;DEBUG;UNICODE.

  • Metadata je možné odebrat.Metadata can be removed.

  • Podmínky lze použít k řízení zahrnutí metadat.Conditions can be used to control the inclusion of metadata.

Výchozí hodnoty metadat položkyItem metadata default values

Metadata položky, která jsou definována v ItemDefinitionGroup, jsou pouze deklarace výchozích metadat.Item metadata that is defined in an ItemDefinitionGroup is just a declaration of default metadata. Metadata se nevztahují, pokud nedefinujete položku, která používá danou položku, aby obsahovala hodnoty metadat.The metadata does not apply unless you define an Item that uses an ItemGroup to contain the metadata values.

Poznámka

V mnoha příkladech v tomto tématu je zobrazen element ItemDefinitionGroup, ale jeho odpovídající definice objektu Item je vynechána pro přehlednost.In many of the examples in this topic, an ItemDefinitionGroup element is shown but its corresponding ItemGroup definition is omitted for clarity.

Metadata explicitně definovaná v objektu ItemCollection mají přednost před metadaty v ItemDefinitionGroup.Metadata explicitly defined in an ItemGroup takes precedence over metadata in ItemDefinitionGroup. Metadata v ItemDefinitionGroup se aplikují pouze pro nedefinovaná metadata ve více položkách.Metadata in ItemDefinitionGroup is applied only for undefined metadata in an ItemGroup. Příklad:For example:

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

V tomto příkladu se výchozí metadata "m" aplikují na položku "i", protože metadata "m" nejsou explicitně definována položkou "i".In this example, the default metadata "m" is applied to Item "i" because metadata "m" is not explicitly defined by Item "i". Výchozí metadata "n" však nejsou použita na položku "i", protože metadata "n" jsou již definována položkou "i".However, default metadata "n" is not applied to Item "i" because metadata "n" is already defined by Item "i".

Poznámka

V názvech elementů XML a parametrů se rozlišují velká - a malá písmena.XML Element and Parameter names are case-sensitive. Názvy položek a / názvů vlastností položek nerozlišují velká a malá - písmena.Item metadata and Item/Property names are not case-sensitive. Proto by ItemDefinitionGroup položky, které mají názvy, které se liší pouze písmenem Case, měly být považovány za stejné pole Item.Therefore, ItemDefinitionGroup items that have names that differ only by case should be treated as the same ItemGroup.

Zdroje hodnotValue sources

Hodnoty metadat, které jsou definovány ve ItemDefinitionGroup, mohou pocházet z mnoha různých zdrojů, a to následujícím způsobem:The values for metadata that is defined in an ItemDefinitionGroup can come from many different sources, as follows:

  • Vlastnost PropertyPropertyGroup Property

  • Položka z ItemDefinitionGroupItem from an ItemDefinitionGroup

  • Transformace položky u položky ItemDefinitionGroupItem transform on an ItemDefinitionGroup Item

  • Proměnná prostředíEnvironment variable

  • Globální vlastnost (z příkazového řádku MSBuild.exe )Global property (from the MSBuild.exe command line)

  • Rezervovaná vlastnostReserved property

  • Dobře známá metadata položky z ItemDefinitionGroupWell-known metadata on an Item from an ItemDefinitionGroup

  • CDATA – oddíl <![CDATA[anything here is not parsed]]>CDATA section <![CDATA[anything here is not parsed]]>

Poznámka

Metadata položky ze složky Item nejsou užitečná v deklaraci metadat ItemDefinitionGroup, protože prvky ItemDefinitionGroup jsou zpracovávány před prvky Item.Item metadata from an ItemGroup is not useful in an ItemDefinitionGroup metadata declaration because ItemDefinitionGroup elements are processed before ItemGroup elements.

Doplňková a vícenásobná definiceAdditive and multiple definitions

Pokud přidáte definice nebo použijete více ItemDefinitionGroups, pamatujte na následující:When you add definitions or use multiple ItemDefinitionGroups, remember the following:

  • Do tohoto typu se přidá další specifikace metadat.Additional metadata specification is added to the type.

  • Poslední specifikace má přednost.The last specification takes precedence.

Pokud máte více ItemDefinitionGroups, každá další specifikace přidá svá metadata do předchozí definice.When you have multiple ItemDefinitionGroups, each subsequent specification adds its metadata to the previous definition. Příklad:For example:

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

V tomto příkladu se metadata "o" přidají do "m" a "n".In this example, the metadata "o" is added to "m" and "n".

Kromě toho je možné přidat i dříve definované hodnoty metadat.In addition, previously defined metadata values can also be added. Příklad:For example:

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

V tomto příkladu je dříve definovaná hodnota pro metadata "m" ( M1 ) přidána na novou hodnotu ( m2 ) , takže konečná hodnota je 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".

Poznámka

K tomu může dojít také ve stejném ItemDefinitionGroup.This can also occur in the same ItemDefinitionGroup.

Pokud přepíšete dříve definovaná metadata, má přednost poslední specifikace.When you override the previously defined metadata, the last specification takes precedence. V následujícím příkladu poslední hodnota metadat "m" přechází z "M1" na "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>

Použití podmínek v ItemDefinitionGroupUse conditions in an ItemDefinitionGroup

Můžete použít podmínky v ItemDefinitionGroup k řízení zahrnutí metadat.You can use conditions in an ItemDefinitionGroup to control the inclusion of metadata. Příklad:For example:

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

V tomto případě je výchozí metadata "M1" u položky "i" obsažena pouze v případě, že hodnota vlastnosti "konfigurace" je "ladit".In this case, the default metadata "m1" on item "i" is included only if the value of the "Configuration" property is "Debug".

Poznámka

V podmínkách jsou podporovány pouze místní odkazy na metadata.Only local metadata references are supported in conditions.

Odkazy na metadata definovaná v dřívějším ItemDefinitionGroup jsou místní pro položku, nikoli pro skupinu definic.References to metadata defined in an earlier ItemDefinitionGroup are local to the item, not the definition group. To znamená, že rozsah odkazů je specifický pro položky.That is, the scope of the references are item-specific. Příklad:For example:

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

Ve výše uvedeném příkladu položka "i" odkazuje na položku "test" ve své podmínce.In the above example, item "i" references item "test" in its Condition. Tato podmínka nebude nikdy pravdivá, protože nástroj MSBuild interpretuje odkaz na metadata jiné položky v ItemDefinitionGroup jako prázdný řetězec.This Condition will never be true because MSBuild interprets a reference to another item's metadata in an ItemDefinitionGroup as the empty string. Proto bude "m" nastaven na "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>

Ve výše uvedeném příkladu by se hodnota "m" nastavila na hodnotu "M1", protože položka odkazuje na metadata položky "i" pro položku "Ano".In the above example, "m" would be set to the value "m1" as the Condition references item "i"'s metadata value for item "yes."

Přepsat a odstranit metadataOverride and delete metadata

Metadata definovaná v elementu ItemDefinitionGroup lze přepsat v pozdějším elementu ItemDefinitionGroup nastavením hodnoty metadata na jinou hodnotu.Metadata defined in an ItemDefinitionGroup element can be overridden in a later ItemDefinitionGroup element by setting the metadata value to another value. Můžete také efektivně odstranit položku metadat tím, že ji nastavíte na prázdnou hodnotu.You can also effectively delete a metadata item by setting it to an empty value. Příklad:For example:

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

Položka "i" stále obsahuje metadata "m", ale její hodnota je nyní prázdná.The item "i" still contains metadata "m", but its value is now empty.

Rozsah metadatScope of metadata

ItemDefinitionGroups mají globální rozsah u definovaných a globálních vlastností bez ohledu na jejich definování.ItemDefinitionGroups have global scope on defined and global properties wherever they are defined. Výchozí definice metadat v ItemDefinitionGroup můžou být odkazující samy na sebe.Default metadata definitions in an ItemDefinitionGroup can be self-referential. Například následující příklad používá jednoduchou referenci metadat:For example, the following uses a simple metadata reference:

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

Lze také použít kvalifikovaný odkaz na metadata:A qualified metadata reference can also be used:

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

Následující jsou však neplatné:However, the following is not valid:

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

Od verze MSBuild 3,5 může být ItemGroups také odkazující na sebe.Beginning in MSBuild 3.5, ItemGroups can also be self-referential. Příklad:For example:

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

Viz takéSee also