Элементы MSBuild
Элементы MSBuild входов в систему построения, и они обычно представляют файлы. Элементы группируются в типы на основе своих имен. Типы элементов являются именованными списками элементов, которые можно использовать в качестве параметров для задач. Значения элементов используются в задачах для выполнения процесса построения.
Поскольку элементы называются типом элемента, к которому они принадлежат элементы "элемент" и "элемент" можно использовать взаимозаменимо.
Содержание раздела
Создание элементов в файле проекта
Создание элементов во время выполнения
Ссылки на элементы в файле проекта
Использование знаков подстановки для указания элементов
Использование атрибута Exclude
Метаданные элементов
Ссылки на метаданные элементов в файле проекта
Стандартные метаданные элементов
Преобразование типов элементов с помощью метаданных
Определения элементов
Атрибуты элементов ItemGroup целевого объекта
Удалите атрибут
Атрибут KeepMetadata
Атрибут RemoveMetadata
Атрибут KeepDuplicates
Создание элементов в файле проекта
Объявленные элементы в файле проекта как дочерние элементы элемента ItemGroup. Имя дочернего элемента совпадает с типом этого элемента. В атрибуте Include элемента указываются элементы (файлы), которые нужно включить в данный тип элементов. Например, следующий код XML создает тип элемента с именем Compile, который включает 2 файла.
<ItemGroup>
<Compile Include = "file1.cs"/>
<Compile Include = "file2.cs"/>
</ItemGroup>
Элемент "file2.cs" не заменяет элемент "file1.cs"; вместо этого имя файла добавлено в список значений типа элемента Compile. Невозможно удалить элемент из типа элемента на этапе оценки построения.
С помощью следующего XML-кода тот же тип элементов создается посредством объявления обоих файлов в одном атрибуте Include. Обратите внимание, что имена файлов разделяются точкой с запятой.
<ItemGroup>
<Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>
Создание элементов во время выполнения
Элементы, внешние элементы целевой объект присвоить значения на этапе оценки построения. Во время следующего этапа выполнения, элементы можно создать или изменить следующими способами:
Любая задача может создать элемент. Для этого элемент Task должен содержать дочерний элемент Output с атрибутом ItemName.
Задача CreateItem может создать элемент. Этот метод не рекомендуется использовать.
Начиная с версии .NET Framework 3.5 элементы Target могут содержать элементы ItemGroup, в состав которых, в свою очередь, могут входить дочерние элементы.
Ссылки на элементы в файле проекта
Для ссылки на типы элементов в файле проекта используется синтаксис @ (ItemType). Например, реализации бы на тип элемента в предыдущем примере с помощью @(Compile). С помощью следующего синтаксиса можно передать элементы задачам, указав тип элемента в качестве параметра этой задачи. Дополнительные сведения см. в разделе Практическое руководство. Выбор файлов для построения.
По умолчанию элементы типа элемента разделяются точками с запятой (;), когда оно развернуть. Можно использовать синтаксис @ (ItemType"разделитель"), чтобы указать разделитель, отличное от значения по умолчанию. Дополнительные сведения см. в разделе Практическое руководство. Отображение списка элементов, разделенных запятыми.
Использование знаков подстановки для указания элементов
С помощью подстановочных знаков **, * и ? можно указать группу файлов в качестве входных данных для построения, не перечисляя все эти файлы по отдельности.
Знак "?" соответствует какому-либо одному знаку.
Подстановочный знак "*" соответствует любому количеству символов.
Последовательность подстановочных знаков "**" соответствует частичному пути.
Например, можно указать все файлы с расширением cs в каталоге, содержащем файл проекта с помощью следующего элемента в файле проекта.
<CSFile Include="*.cs"/>
Выбирает следующий элемент на все файлы vb D: диск:
<VBFile Include="D:/**/*.vb"/>
Дополнительные сведения о подстановочных знаках см. в разделе Практическое руководство. Выбор файлов для построения.
Использование атрибута Exclude
В элементах может также содержаться атрибут Exclude, исключающий определенные элементы (файлы) из типа элементов. Атрибут Exclude обычно используется вместе с подстановочными знаками. Например, с помощью следующего XML-кода в тип элементов CSFile добавляется каждый файл с расширением CS из каталога, кроме файла DoNotBuild.cs.
<ItemGroup>
<CSFile Include="*.cs" Exclude="DoNotBuild.cs"/>
</ItemGroup>
Аффекты атрибута Exclude только элементы, добавлены атрибутом Include в элемент, содержащий оба этих атрибута. В следующем примере не исключил бы файл Form1.cs, который был добавлен в предыдущем элементе элемента.
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
Дополнительные сведения см. в разделе Практическое руководство. Исключение файлов из построения.
Метаданные элементов
Элементы могут также содержаться метаданные в дополнение к сведениям в атрибутах Include и Exclude. Этот метаданные могут использоваться в задачах, для которых требуются дополнительные сведения об элементах или к задачам и целевым объектам пакета. Дополнительные сведения см. в разделе Пакетная обработка в MSBuild.
Метаданные представляют собой коллекцию пар "ключ-значение", которые объявляются в файле проекта как дочерние по отношению к элементу. Имя и значение такого дочернего элемента совпадают с именем и значением метаданных.
Метаданные связаны с содержащим их элементом. Например, следующий код XML добавляет метаданные Culture, который имеет значение Fr, как в "one.cs", так и элементы "two.cs" типа элементов CSFile.
<ItemGroup>
<CSFile Include="one.cs;two.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Элемент может содержать ноль или более значений метаданных. Можно изменить значения метаданных в любое время. Если метаданные набора к пустому значению, фактически удалить ее из построения.
Ссылки на метаданные элементов в файле проекта
Ссылки на метаданные элементов в файле проекта используется синтаксис % (ItemMetadataName). Если неоднозначности существует, можно дополнить ссылку, используя имя типа элемента. Например, можно указать % (ItemType.ItemMetaDataName). Следующий пример использует метаданные отображения для пакетной обработки задачи сообщения. Дополнительные сведения об использовании метаданных элементов для пакетной обработки см. в разделе Метаданные элементов в пакетной обработке задач.
<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>
Стандартные метаданные элементов
При добавлении элемента к типу элементов ему присваиваются некоторые стандартные метаданные. Например, все элементы имеют стандартные метаданные %(Filename), значение которых имя файла элемента. Дополнительные сведения см. в разделе Общеизвестные метаданные элементов MSBuild.
Преобразование типов элементов с помощью метаданных
Можно преобразовать списки элементов в новые списки элементов с помощью метаданных. Например, можно преобразовать тип элемента CppFiles, который содержит элементы, представляющие файлы .cpp в соответствующем списке obj-файлов с помощью выражения @(CppFiles -> '%(Filename).obj').
В следующем коде создается тип элементов CultureResource, в котором содержатся копии всех элементов EmbeddedResource с метаданными Culture. Метаданным Culture присваивается значение новых метаданных CultureResource.TargetDirectory.
<Target Name="ProcessCultureResources">
<ItemGroup>
<CultureResource Include="@(EmbeddedResource)"
Condition="'%(EmbeddedResource.Culture)' != ''">
<TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
</CultureResource>
</ItemGroup>
</Target>
Дополнительные сведения см. в разделе Преобразования MSBuild.
Определения элементов
Начиная с .NET Framework 3.5 можно добавить метаданные по умолчанию к любому типу элемента с помощью элемент ItemDefinitionGroup. Как стандартные метаданные, по умолчанию метаданные сопоставлены со всеми элементами типа элемента. Можно явно переопределять по умолчанию метаданных в определении элемента. Например, следующий код XML содержит элементы "one.cs" и "three.cs" Compile метаданные BuildDay со значением "понедельником". Код позволяет элементу "two.cs" метаданные BuildDay со значением "вторником".
<ItemDefinitionGroup>
<Compile>
<BuildDay>Monday</BuildDay>
</Compile>
</ItemDefinitionGroup>
<ItemGroup>
<Compile Include="one.cs;three.cs" />
<Compile Include="two.cs">
<BuildDay>Tuesday</BuildDay>
</Compile>
</ItemGroup>
Дополнительные сведения см. в разделе Определения элементов.
Атрибуты элементов ItemGroup целевого объекта
Начиная с версии .NET Framework 3.5 элементы Target могут содержать элементы ItemGroup, в состав которых, в свою очередь, могут входить дочерние элементы. Атрибуты в этом разделе, является допустимым, если они определены для элемента в ItemGroup, в Target.
Удалите атрибут
Элементы в ItemGroup целевого объекта могут содержать атрибут Remove, который удаляет определенные элементы (файлы) из типа элементов. Этот атрибут был представлен в платформе .NET Framework 3.5.
Следующий пример удаляет каждый файл config от типа элемента компилировать.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
Атрибут KeepMetadata
Если элемент создается в целевой объект, то элемент может содержать атрибут KeepMetadata. Если этот атрибут указан, только метаданные, определенный в список, разделенных точкой с запятой имен будут Переключены из элемента источника к элементу целевого объекта. Пустое значение для этого атрибута соответствует не задан его. Атрибут KeepMetadata был представлен в платформе .NET Framework 4,5.
В следующем примере показано, как использовать атрибут KeepMetadata.
<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003"
ToolsVersion="4.0">
<ItemGroup>
<FirstItem Include="rhinoceros">
<Class>mammal</Class>
<Size>large</Size>
</FirstItem>
</ItemGroup>
<Target Name="MyTarget">
<ItemGroup>
<SecondItem Include="@(FirstItem)" KeepMetadata="Class" />
</ItemGroup>
<Message Text="FirstItem: %(FirstItem.Identity)" />
<Message Text=" Class: %(FirstItem.Class)" />
<Message Text=" Size: %(FirstItem.Size)" />
<Message Text="SecondItem: %(SecondItem.Identity)" />
<Message Text=" Class: %(SecondItem.Class)" />
<Message Text=" Size: %(SecondItem.Size)" />
</Target>
</Project>
<!--
Output:
FirstItem: rhinoceros
Class: mammal
Size: large
SecondItem: rhinoceros
Class: mammal
Size:
-->
Атрибут RemoveMetadata
Если элемент создается в целевой объект, то элемент может содержать атрибут RemoveMetadata. Если этот атрибут указан, то все метаданные Переключены из элемента источника к элементу целевого объекта, за исключением метаданных, имена которых содержатся в списке, разделенных точкой с запятой имен. Пустое значение для этого атрибута соответствует не задан его. Атрибут RemoveMetadata был представлен в платформе .NET Framework 4,5.
В следующем примере показано, как использовать атрибут RemoveMetadata.
<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<MetadataToRemove>Size;Material</MetadataToRemove>
</PropertyGroup>
<ItemGroup>
<Item1 Include="stapler">
<Size>medium</Size>
<Color>black</Color>
<Material>plastic</Material>
</Item1>
</ItemGroup>
<Target Name="MyTarget">
<ItemGroup>
<Item2 Include="@(Item1)" RemoveMetadata="$(MetadataToRemove)" />
</ItemGroup>
<Message Text="Item1: %(Item1.Identity)" />
<Message Text=" Size: %(Item1.Size)" />
<Message Text=" Color: %(Item1.Color)" />
<Message Text=" Material: %(Item1.Material)" />
<Message Text="Item2: %(Item2.Identity)" />
<Message Text=" Size: %(Item2.Size)" />
<Message Text=" Color: %(Item2.Color)" />
<Message Text=" Material: %(Item2.Material)" />
</Target>
</Project>
<!--
Output:
Item1: stapler
Size: medium
Color: black
Material: plastic
Item2: stapler
Size:
Color: black
Material:
-->
Атрибут KeepDuplicates
Если элемент создается в целевой объект, то элемент может содержать атрибут KeepDuplicates. KeepDuplicates атрибут Boolean, указывающее, должен ли элемент быть добавлены к целевой группе, если элемент точный дубликат существующего элемента.
Если элемент источника и целевого объекта имеет такие же включить значение, но разные метаданные, то элемент добавляется, даже если KeepDuplicates установлено в false. Пустое значение для этого атрибута соответствует не задан его. Атрибут KeepDuplicates был представлен в платформе .NET Framework 4,5.
В следующем примере показано, как использовать атрибут KeepDuplicates.
<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<ItemGroup>
<Item1 Include="hourglass;boomerang" />
<Item2 Include="hourglass;boomerang" />
</ItemGroup>
<Target Name="MyTarget">
<ItemGroup>
<Item1 Include="hourglass" KeepDuplicates="false" />
<Item2 Include="hourglass" />
</ItemGroup>
<Message Text="Item1: @(Item1)" />
<Message Text=" %(Item1.Identity) Count: @(Item1->Count())" />
<Message Text="Item2: @(Item2)" />
<Message Text=" %(Item2.Identity) Count: @(Item2->Count())" />
</Target>
</Project>
<!--
Output:
Item1: hourglass;boomerang
hourglass Count: 1
boomerang Count: 1
Item2: hourglass;boomerang;hourglass
hourglass Count: 2
boomerang Count: 1
-->
См. также
Задачи
Практическое руководство. Выбор файлов для построения
Практическое руководство. Исключение файлов из построения
Практическое руководство. Отображение списка элементов, разделенных запятыми