Определения элементов
В MSBuild 2.0 поддерживается статическое объявление элементов в файлах проекта с использованием элемента ItemGroup. Но метаданные можно добавлять только на уровне элемента, даже если метаданные одинаковы для всех элементов. В MSBuild 3.5 появился элемент проекта с именем ItemDefinitionGroup, который позволяет устранить это ограничение. С помощью элемента ItemDefinitionGroup можно задать набор определений элементов, которые добавляют значения метаданных по умолчанию для всех элементов в указанном типе.
Элемент ItemDefinitionGroup располагается непосредственно за элементом Project в файле проекта. Ниже перечислены функциональные возможности, предоставляемые определениями элементов.
Можно определить используемые по умолчанию глобальные метаданные для элементов вне целевого объекта. То есть одни и те же метаданные применяются ко всем элементам заданного типа.
Типы элементов могут иметь несколько определений. Когда к типу добавляются дополнительные спецификации метаданных, приоритет получает последняя добавленная спецификация. (Для метаданных применяется тот же порядок импорта, что и для свойств.)
Метаданные можно добавлять. Например, значения CDefines накапливаются при определенных условиях, в зависимости от задаваемых свойств. Например, MT;STD_CALL;DEBUG;UNICODE.
Метаданные можно удалять.
Можно использовать условия для управления включением метаданных.
Значения метаданных элементов по умолчанию
Метаданные элементов, определяемые в ItemDefinitionGroup, являются просто объявлением используемых по умолчанию метаданных. Метаданные не применяются, если не определен элемент, использующий ItemGroup для хранения значений метаданных.
Примечание
Во многих примерах, приведенных в этом разделе, показан элемент ItemDefinitionGroup, но соответствующее определение ItemGroup опущено для простоты.
Метаданные, определенные явным образом в ItemGroup, имеют приоритет по сравнению с метаданными в ItemDefinitionGroup. Метаданные в ItemDefinitionGroup применяются только для метаданных, не определенных в ItemGroup. Пример.
<ItemDefinitionGroup>
<i>
<m>m1</m>
<n>n1</n>
</i>
</ItemDefinitionGroup>
<ItemGroup>
<i Include="a">
<o>o1</o>
<n>n2</n>
</i>
</ItemGroup>
В этом примере к элементу "i" применяются метаданные по умолчанию "m", поскольку метаданные "m" не определены явным образом элементом "i". Однако метаданные по умолчанию "n" не применяются к элементу "i", поскольку метаданные "n" уже определены элементом "i".
Примечание
Имена элементов и параметров XML зависят от регистра.Имена метаданных и свойств элемента не зависят от регистра.Поэтому элементы ItemDefinitionGroup с именами, отличающимися только регистром, должны рассматриваться как одинаковые элементы ItemGroup.
Источники значений
Значения для метаданных, определенных в ItemDefinitionGroup, могут поступать из множества различных источников, таких как:
Свойство PropertyGroup
Элемент из ItemDefinitionGroup
Преобразование элемента в элементе ItemDefinitionGroup
Переменная среды
Глобальное свойство (из командной строки MSBuild.exe)
Зарезервированное свойство
Стандартные метаданные в элементе из ItemDefinitionGroup
Раздел CDATA <![CDATA[содержимое здесь не анализируется]]>
Примечание
Метаданные элемента из ItemGroup неприменимы в объявлении метаданных ItemDefinitionGroup, поскольку элементы ItemDefinitionGroup обрабатываются раньше элементов ItemGroup.
Добавочные и множественные определения
При добавлении определений или использовании нескольких элементов ItemDefinitionGroup помните о следующем:
Дополнительные спецификации метаданных добавляются к типу.
Последняя спецификация имеет приоритет.
Если имеется несколько элементов ItemDefinitionGroup, каждая последующая спецификация добавляет метаданные в предыдущее определение. Пример.
<ItemDefinitionGroup>
<i>
<m>m1</m>
<n>n1</n>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<o>o1</o>
</i>
</ItemDefinitionGroup>
В этом примере метаданные "o" добавляются к "m" и "n".
Кроме того, можно добавить ранее определенные значения метаданных. Пример.
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m>%(m);m2</m>
</i>
</ItemDefinitionGroup>
В этом примере ранее определенное значение для метаданных "m" (m1) добавляется к новому значению (m2), в результате чего получается значение "m1;m2".
Примечание
Это также возможно в рамках одной группы ItemDefinitionGroup.
Когда осуществляется переопределение ранее определенных метаданных, приоритет получает последняя спецификация. В следующем примере результирующее значение метаданных "m" меняется с "m1" на "m1a".
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m>m1a</m>
</i>
</ItemDefinitionGroup>
Использование условий в ItemDefinitionGroup
Используя условия в ItemDefinitionGroup, можно контролировать включение метаданных. Пример.
<ItemDefinitionGroup Condition="'$(Configuration)'=='Debug'">
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
В данном случае метаданные по умолчанию "m1" в элемент "i" включаются только в том случае, если свойство Configuration имеет значение "Debug".
Примечание
В условиях поддерживаются только локальные ссылки на метаданные.
Ссылки на метаданные, определенные ранее в ItemDefinitionGroup, являются локальными по отношению к элементу, а не группой определений. То есть область действия ссылок определяется элементом. Пример.
<ItemDefinitionGroup>
<test>
<yes>1</yes>
</test>
<i>
<m Condition="'%(test.yes)'=='1'">m1</m>
</i>
</ItemDefinitionGroup>
В этом примере элемент "i" содержит ссылку на элемент "test" в свойстве Condition.
Переопределение и удаление метаданных
Метаданные, определенные в элементе ItemDefinitionGroup, можно переопределить в последующем элементе ItemDefinitionGroup, не указывая значение метаданных. Можно также удалить элемент метаданных, задавая для него пустое значение. Пример.
<ItemDefinitionGroup>
<i>
<m>m1</m>
</i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
<i>
<m></m>
</i>
</ItemDefinitionGroup>
Элемент "i" по-прежнему содержит метаданные "m", но их значение теперь пустое.
Область действия метаданных
Область действия элементов ItemDefinitionGroup распространяется на заданные и глобальные свойства независимо от того, где они определены. Определения метаданных по умолчанию в ItemDefinitionGroup могут соотноситься с самими собой. Например, в следующем коде используется простая ссылка на метаданные:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>%(m);m2</m>
</i>
</ItemDefinitionGroup>
Можно также использовать более точную ссылку на метаданные:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>%(i.m);m2</m>
</i>
</ItemDefinitionGroup>
Однако следующая ссылка недопустима:
<ItemDefinitionGroup>
<i>
<m>m1</m>
<m>@(x)</m>
</i>
</ItemDefinitionGroup>
Начиная с MSBuild 3.5 элементы ItemGroup также могут соотноситься сами с собой. Пример.
<ItemGroup>
<item Include="a">
<m>m1</m>
<m>%(m);m2</m>
</item>
</ItemGroup>