Поделиться через

Элементы 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>

Элемент может содержать ноль или более значений метаданных.Можно изменить значения метаданных в любое время.Если метаданные набора к пустому значению, фактически удалить ее из построения.

ms171453.collapse_all(ru-ru,VS.110).gifСсылки на метаданные элементов в файле проекта

Ссылки на метаданные элементов в файле проекта используется синтаксис % (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>

ms171453.collapse_all(ru-ru,VS.110).gifСтандартные метаданные элементов

При добавлении элемента к типу элементов ему присваиваются некоторые стандартные метаданные.Например, все элементы имеют стандартные метаданные %(Filename), значение которых имя файла элемента.Дополнительные сведения см. в разделе Общеизвестные метаданные элементов MSBuild.

ms171453.collapse_all(ru-ru,VS.110).gifПреобразование типов элементов с помощью метаданных

Можно преобразовать списки элементов в новые списки элементов с помощью метаданных.Например, можно преобразовать тип элемента 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.

ms171453.collapse_all(ru-ru,VS.110).gifУдалите атрибут

Элементы в ItemGroup целевого объекта могут содержать атрибут Remove, который удаляет определенные элементы (файлы) из типа элементов.Этот атрибут был представлен в платформе .NET Framework 3.5.

Следующий пример удаляет каждый файл config от типа элемента компилировать.

<Target>
    <ItemGroup>
        <Compile Remove="*.config"/>
    </ItemGroup>
</Target>

ms171453.collapse_all(ru-ru,VS.110).gifАтрибут 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: 
-->

ms171453.collapse_all(ru-ru,VS.110).gifАтрибут 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: 
-->

ms171453.collapse_all(ru-ru,VS.110).gifАтрибут 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
-->

См. также

Задачи

Практическое руководство. Выбор файлов для построения

Практическое руководство. Исключение файлов из построения

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

Ссылки

Элемент Item (MSBuild)

Основные понятия

Определения элементов

Пакетная обработка в MSBuild

Другие ресурсы

Основные возможности MSBuild

MSBuild