Элементы MSBuild
Элементы — входные данные для системы построения, как правило, представляющие файлы. Элементы группируются в типы на основе своих имен. Типы элементов являются именованными списками элементов, которые можно использовать в качестве параметров для задач. Значения элементов используются в задачах для выполнения процесса построения.
Поскольку имена элементов определяются содержащим их типом, понятия "элемент" и "значение элемента" являются взаимозаменяемыми.
Создание элементов в файле проекта
Элементы объявляются в файле проекта как дочерние элементы элемента ItemGroup. Имя дочернего элемента совпадает с типом этого элемента. В атрибуте Include элемента указываются элементы (файлы), которые нужно включить в данный тип элементов. Например, с помощью приведенного ниже XML-кода создается тип элементов с именем Compile, в который входят два файла.
<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>
Создание элементов во время выполнения
Элементам, размещенным за пределами элемента Target, значения присваиваются на этапе оценки построения. Элементы могут создаваться или изменяться и на последующем этапе выполнения с помощью перечисленных ниже методов.
Можно создать элементы посредством любой задачи. Для этого элемент 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 в элемент, содержащий оба этих атрибута. Например:
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
файл Form1.cs, добавленный в предыдущем элементе, не будет исключен.
Дополнительные сведения см. в разделе Практическое руководство. Исключение файлов из построения.
Использование атрибута Remove
Начиная с версии .NET Framework 3.5 элементы Target могут содержать элементы ItemGroup, в состав которых, в свою очередь, могут входить дочерние элементы. В этих элементах может также содержаться атрибут Remove, удаляющий определенные элементы (файлы) из типа элементов. Например, с помощью следующего XML-кода из типа элементов Compile удаляется каждый файл с расширением CONFIG.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
Метаданные элементов
Помимо сведений из атрибутов Include и Exclude в элементах могут также содержаться метаданные. Эти метаданные могут использоваться в задачах, для которых требуются дополнительные сведения об элементах, или в процессе пакетной обработки задач и целевых объектов. Дополнительные сведения о пакетной обработке см. в разделе Пакетная обработка в MSBuild.
Метаданные представляют собой коллекцию пар "ключ-значение", которые объявляются в файле проекта как дочерние по отношению к элементу. Имя и значение такого дочернего элемента совпадают с именем и значением метаданных.
Метаданные связаны с содержащим их элементом. Например, в следующем XML-коде в элементы "one.cs" и "two.cs" типа элементов CSFile добавляются метаданные Culture со значением Fr.
<ItemGroup>
<CSFile Include="one.cs;two.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Элемент может содержать ноль или более значений метаданных. Значения метаданных можно изменить в любое время. При задании метаданным пустого значения фактически происходит их удаление из построения.
Ссылки на метаданные элементов в файле проекта
Для ссылки на метаданные элементов в файле проекта используется синтаксис %(ItemMetadataName). При возникновении неоднозначности можно использовать в определении имя типа элементов, например %(ItemType.ItemMetaDataName). В приведенном ниже примере метаданные Display используются для пакетной обработки задачи Message. Дополнительные сведения об использовании метаданных элементов для пакетной обработки см. в разделе Метаданные элементов в пакетной обработке задач.
<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 со значением "Monday", а в элемент "two.cs" — метаданные BuildDay со значением "Tuesday".
<ItemDefinitionGroup>
<Compile>
<BuildDay>Monday</BuildDay>
</Compile>
</ItemDefinitionGroup>
<ItemGroup>
<Compile Include="one.cs;three.cs" />
<Compile Include="two.cs">
<BuildDay>Tuesday</BuildDay>
</Compile>
</ItemGroup>
Дополнительные сведения см. в разделе Определения элементов.
См. также
Задачи
Практическое руководство. Выбор файлов для построения
Практическое руководство. Исключение файлов из построения
Практическое руководство. Отображение списка элементов, разделенных запятыми