Элемент Item (MSBuild)

  • Статья

Содержит определяемый пользователем элемент и его метаданные. Каждый элемент, используемый в проекте MSBuild, должен быть указан как дочерний для элемента ItemGroup.

<Проект>
 <ItemGroup>
  <Элемент>

Синтаксис

<Item Include="*.cs"
        Exclude="MyFile.cs"
        Condition="'String A'=='String B'">
    <ItemMetadata1>...</ItemMetadata1>
    <ItemMetadata2>...</ItemMetadata2>
</Item>

Указание метаданных в качестве атрибутов

В MSBuild 15.1 или более поздних версиях все метаданные с именем, которое не противоречит текущему списку атрибутов, при необходимости можно выразить в виде атрибута.

Например, чтобы указать список пакетов NuGet, обычно используется примерно следующий синтаксис.

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json">
    <Version>9.0.1-beta1<Version>
  </PackageReference>
</ItemGroup>

Теперь можно передать метаданные Version как атрибут, например как в следующем синтаксисе:

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="9.0.1-beta1" />
</ItemGroup>

Элементы и атрибуты

В следующих разделах описаны атрибуты, дочерние и родительские элементы.

Атрибуты

Атрибут Description
Include Необязательный атрибут элемента .

Файл или подстановочный знак, включаемый в список элементов.
Exclude Необязательный атрибут элемента .

Файл или подстановочный знак, исключаемый из списка элементов.
Condition Необязательный атрибут элемента .

Проверяемое условие. Дополнительные сведения см. в разделе Условия.
Remove Необязательный атрибут элемента .

Файл или подстановочный знак, удаляемый из списка элементов.
MatchOnMetadata Необязательный атрибут элемента .

Отвечает за изменение атрибутов Remove, ссылающихся на другие элементы, для сопоставления с указанными именами метаданных, а не со значениями таких элементов.

Этот атрибут допустим только в том случае, если он указан вместе с атрибутом Remove, который содержит только ссылки на другие элементы (например, Remove="@(Compile);@(Content)"). Дополнительные сведения см. в статье Элементы.
MatchOnMetadataOptions Необязательный атрибут элемента .

Указывает стратегию сопоставления строк, используемую MatchOnMetadata. Возможные значения: CaseSensitive, CaseInsensitiveили PathLike. Значение по умолчанию — CaseInsensitive.
KeepDuplicates Необязательный атрибут элемента .

Указывает, следует ли добавлять элемент в целевую группу при наличии точной копией существующего элемента. Если исходный и целевой элементы имеют одинаковое значение Include, но различные метаданные, элемент добавляется в целевую группу, даже если KeepDuplicates имеет значение false. Дополнительные сведения см. в разделе Элементы.

Этот атрибут является допустимым только в том случае, если он указан для элемента ItemGroup, находящегося в Target.
KeepMetadata Необязательный атрибут элемента .

Метаданные для исходных элементов, добавляемые в целевые элементы. Из исходного элемента в целевой передаются только метаданные, имена которых указаны в списке с разделителем точкой с запятой. Дополнительные сведения см. в разделе Элементы.

Этот атрибут является допустимым только в том случае, если он указан для элемента ItemGroup, находящегося в Target.
RemoveMetadata Необязательный атрибут элемента .

Метаданные для исходных элементов, не передаваемые в целевые элементы. Из исходного элемента в целевой передаются все метаданные за исключением метаданных, имена которых содержатся в списке имен, разделенных точкой с запятой. Дополнительные сведения см. в разделе Элементы.

Этот атрибут является допустимым только в том случае, если он указан для элемента ItemGroup, находящегося в Target.
Update Необязательный атрибут элемента . (Доступен только для проектов .NET Core в Visual Studio 2017 или более поздних версиях.)

Позволяет изменять метаданные элемента; обычно используется для переопределения метаданных по умолчанию определенных элементов после первоначального указания группы элементов (например, с диким карта).

Этот атрибут является допустимым только в том случае, если он указан для элемента ItemGroup, не находящегося в Target.

Дочерние элементы

Элемент Description
ItemMetadata Определяемый пользователем ключ метаданных элемента, содержащий значение метаданных элемента. Элемент может содержать любое число элементов ItemMetadata, включая ноль.

Родительские элементы

Элемент Description
ItemGroup Группирующий элемент для элементов.

Замечания

Элементы Item определяют входные данные для системы построения и группируются в коллекции элементов на основании определенных пользователем имен коллекции. Эти коллекции элементов можно использовать в качестве параметров для задач, в которых с помощью отдельных элементов выполняются этапы процесса построения. Дополнительные сведения см. в разделе Элементы.

Использование нотации @(<myType>) позволяет расширить коллекцию элементов типа <myType> до списка строк, разделяемых точкой с запятой, и передать в параметр. Если параметр имеет тип string, значением параметра является список элементов, разделенных точкой с запятой. Если параметр представляет собой массив строк (string[]), каждый элемент вставляется в массив на основании расположения точек с запятой. Если параметр задачи имеет тип ITaskItem[], значением является содержимое коллекции элементов и все присоединенные метаданные. Чтобы разделять элементы с помощью символа, отличного от точки с запятой, используйте синтаксис @(<myType>, '<разделитель>').

Подсистема MSBuild может оценивать подстановочные знаки, такие как * и ?, и рекурсивные подстановочные знаки, такие как /**/*.cs. Дополнительные сведения см. в разделе Элементы.

Примеры

В следующем примере кода показано объявление двух элементов типа CSFile. Второй объявленный элемент содержит метаданные, где MyMetadata имеет значение HelloWorld.

<ItemGroup>
    <CSFile Include="engine.cs; form.cs" />
    <CSFile Include="main.cs" >
        <MyMetadata>HelloWorld</MyMetadata>
    </CSFile>
</ItemGroup>

В следующем примере кода показано, как использовать атрибут Update для изменения метаданных в файле с именем somefile.cs, включенном с помощью glob. (Доступен только для проектов .NET Core в Visual Studio 2017 или более поздних версиях.)

<ItemGroup>
    <Compile Update="somefile.cs">  // or Update="*.designer.cs"
        <MetadataKey>MetadataValue</MetadataKey>
    </Compile>
</ItemGroup>

См. также