Элементы MSBuild

Элементы MSBuild являются входными данными в систему сборки и обычно представляют файлы (файлы указываются в атрибуте Include ). Элементы группируются в типы элементов на основе их имен элементов. Типы элементов называются списками элементов, которые можно использовать в качестве параметров для задач. Задачи используют значения элементов для выполнения шагов процесса сборки.

Так как элементы именуются типом элемента, к которому они относятся, можно использовать термины "item" и "значение элемента".

Создание элементов в файле проекта

Элементы в файле проекта объявляют как дочерние элементы элемента 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>

Атрибут Include — это путь, интерпретируемый относительно папки файла проекта, $(MSBuildProjectPath)даже если элемент находится в импортированном файле, .targets например в файле.

Создание элементов во время выполнения

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

• Любая задача может выдавать элемент. Чтобы вывести элемент, элемент Task должен иметь дочерний элемент Output , имеющий ItemName атрибут.

• Задача CreateItem может выдавать элемент. Это использование устарело.

• Target элементы могут содержать элементы ItemGroup , которые могут содержать элементы элемента.

Ссылки на элементы в файле проекта

Чтобы ссылаться на типы элементов в файле проекта, используйте синтаксис @(ItemType). Например, вы будете ссылать на тип элемента в предыдущем примере с помощью @(Compile). С помощью этого синтаксиса можно передать элементы в задачи, указав тип элемента в качестве параметра этой задачи. Дополнительные сведения см. в разделе "Практическое руководство. Выбор файлов для сборки".

По умолчанию элементы типа элемента разделяются точкой с запятой (;) при развертывании. Синтаксис @(ItemType, 'separator') можно использовать для указания разделителя, отличного от значения по умолчанию. Дополнительные сведения см. в разделе "Практическое руководство. Отображение списка элементов, разделенного запятыми".

Использование подстановочных знаков для указания элементов

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

• Подстановочный ? знак соответствует одному символу.
• Подстановочный * знак соответствует нулю или нескольким символам.
• Подстановочный ** знак соответствует частичному пути.

Например, можно указать все .cs файлы в каталоге, который содержит файл проекта, используя следующий элемент в файле проекта.

<CSFile Include="*.cs"/>

Следующий элемент выбирает все .vb файлы на D: диске:

<VBFile Include="D:/**/*.vb"/>

Если вы хотите включить литералы * или ? символы в элемент без расширения подстановочных знаков, необходимо экранировать подстановочные знаки.

Дополнительные сведения о подстановочных знаках см. в разделе "Практическое руководство. Выбор файлов для сборки".

Использование атрибута Exclude

Элементы элемента могут содержать Exclude атрибут, который исключает определенные элементы (файлы) из типа элемента. Атрибут Exclude обычно используется вместе с подстановочными знаками. Например, следующий XML-файл добавляет каждый .cs файл в каталог CSFile в тип элемента, кроме файла 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 атрибутах. Эти метаданные можно использовать задачами, требующими дополнительных сведений об элементах или пакетных задачах и целевых объектах. Дополнительные сведения см. в разделе "Пакетная обработка".

Метаданные — это коллекция пар "ключ-значение", объявленных в файле проекта в качестве дочерних элементов элемента элемента. Имя дочернего элемента — это имя метаданных, а значение дочернего элемента — значение метаданных.

Метаданные связаны с элементом элемента, содержащего его. Например, следующий XML-код добавляет Culture метаданные, имеющие значение Fr как для one.cs, так и для элементов CSFile типа элемента.

<ItemGroup>
    <CSFile Include="one.cs;two.cs">
        <Culture>Fr</Culture>
    </CSFile>
</ItemGroup>

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

Метаданные ссылочного элемента в файле проекта

Вы можете ссылаться на метаданные элемента в файле проекта с помощью синтаксиса %(ItemMetadataName). Если неоднозначность существует, можно указать ссылку с помощью имени типа элемента. Например, можно указать %(ItemType.ItemMetaDataName). В следующем примере метаданные Display используются для пакетной обработки Message задачи. Дополнительные сведения об использовании метаданных элементов для пакетной обработки см. в разделе "Метаданные элементов" в пакетной обработке задач.

<Project>
    <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), значение которого — имя файла элемента (без расширения). Дополнительные сведения см. в разделе метаданных известных элементов.

Преобразование типов элементов с помощью метаданных

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

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

Метаданные по умолчанию можно добавить в любой тип элемента с помощью элемента ItemDefinitionGroup. Как и известные метаданные, метаданные по умолчанию связаны со всеми элементами указанного типа элемента. Вы можете явно переопределить метаданные по умолчанию в определении элемента. Например, следующий XML-код предоставляет Compile элементы one.cs и three.cs метаданные 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 целевого объекта

Target элементы могут содержать элементы ItemGroup , которые могут содержать элементы элемента. Атрибуты в этом разделе допустимы, если они указаны для элемента в ItemGroup объекте, который находится в объекте Target.

Удаление атрибута

Атрибут Remove удаляет определенные элементы (файлы) из типа элемента. Этот атрибут появился в .NET Framework 3.5 (только в целевых объектах). Поддерживаются как внутри, так и вне целевых объектов, начиная с MSBuild 15.0.

В следующем примере каждый .config файл удаляется из Compile типа элемента.

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

Атрибут MatchOnMetadata

Атрибут MatchOnMetadata применим только к Remove атрибутам, ссылающимся на другие элементы (например, Remove="@(Compile);@(Content)") и предписывает Remove операции сопоставлять элементы на основе значений указанных имен метаданных вместо сопоставления на основе значений элементов.

Правило сопоставления дляB Remove="@(A)" MatchOnMetadata="M": удалите все элементы из B этих метаданныхM, значение метаданных VM которого соответствует любому элементу из A метаданных M значенияV.

<Project>
  <ItemGroup>
    <A Include='a1' M1='1' M2='a' M3="e"/>
    <A Include='b1' M1='2' M2='x' M3="f"/>
    <A Include='c1' M1='3' M2='y' M3="g"/>
    <A Include='d1' M1='4' M2='b' M3="h"/>

    <B Include='a2' M1='x' m2='c' M3="m"/>
    <B Include='b2' M1='2' m2='x' M3="n"/>
    <B Include='c2' M1='2' m2='x' M3="o"/>
    <B Include='d2' M1='3' m2='y' M3="p"/>
    <B Include='e2' M1='3' m2='Y' M3="p"/>
    <B Include='f2' M1='4'        M3="r"/>
    <B Include='g2'               M3="s"/>

    <B Remove='@(A)' MatchOnMetadata='M1;M2'/>
  </ItemGroup>

  <Target Name="PrintEvaluation">
    <Message Text="%(B.Identity) M1='%(B.M1)' M2='%(B.M2)' M3='%(B.M3)'" />
  </Target>
</Project>

В примере значения b2c2элементов и d2 удаляются из элементаB, так как:

• b2 и c2 от B матча против b1 от AM1=2 и M2=x
• d2от B матчей против c1 от AM1=3 иM2=y

Задача выводит следующее Message :

  a2 M1='x' M2='c' M3='m'
  e2 M1='3' M2='Y' M3='p'
  f2 M1='4' M2='' M3='r'
  g2 M1='' M2='' M3='s'

Пример использования MatchOnMetadata из MSBuild:

      <_TransitiveItemsToCopyToOutputDirectory Remove="@(_ThisProjectItemsToCopyToOutputDirectory)" MatchOnMetadata="TargetPath" MatchOnMetadataOptions="PathLike" />

Эта строка удаляет элементы из _TransitiveItemsToCopyToOutputDirectory элементов с одинаковыми TargetPath значениями метаданных из элементов _ThisProjectItemsToCopyToOutputDirectory

Атрибут MatchOnMetadataOptions

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

PathLike Применяет нормализацию с учетом путей к таким значениям, как нормализация ориентаций косой черты, игнорировать конечные косые черты, устранять . и .., а также делать все относительные пути абсолютными для текущего каталога.

Атрибут KeepMetadata

Если элемент создается в целевом объекте, элемент элемента может содержать KeepMetadata атрибут. Если этот атрибут указан, то только метаданные, указанные в списке имен с запятой, будут переданы из исходного элемента в целевой элемент. Пустое значение этого атрибута эквивалентно не указанию. Атрибут KeepMetadata появился в .NET Framework 4.5.

В следующем примере показано, как использовать KeepMetadata атрибут.

<Project>
    <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>

    <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:
-->

Дополнительные операции с элементами см. в разделе "Функции элементов MSBuild".

Атрибут KeepDuplicates

Если элемент создается в целевом объекте, элемент элемента может содержать KeepDuplicates атрибут. KeepDuplicates Boolean— это атрибут, указывающий, следует ли добавить элемент в целевую группу, если элемент является точным дубликатом существующего элемента.

Если исходный и целевой элемент имеют одно и то же Include значение, но разные метаданные, он добавляется даже в том случае, если KeepDuplicates задано значение false. Пустое значение этого атрибута эквивалентно не указанию. Атрибут KeepDuplicates появился в .NET Framework 4.5.

В следующем примере показано, как использовать KeepDuplicates атрибут.

<Project>

    <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
-->

KeepDuplicates Так как атрибут рассматривает метаданные элементов в дополнение к значениям элементов, важно знать, что происходит с метаданными. Например, см. сведения об обнаружении дубликатов при использовании функции элемента метаданных.

Обновление метаданных для элементов в ItemGroup за пределами целевого объекта

Элементы вне целевых объектов могут обновлять существующие метаданные с помощью атрибута Update . Этот атрибут недоступен для элементов в целевых объектах.

<Project>
    <PropertyGroup>
        <MetadataToUpdate>pencil</MetadataToUpdate>
    </PropertyGroup>

    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
        <Item1 Include="pencil">
            <Size>small</Size>
            <Color>yellow</Color>
            <Material>wood</Material>
        </Item1>
        <Item1 Include="eraser">
            <Color>red</Color>
        </Item1>
        <Item1 Include="notebook">
            <Size>large</Size>
            <Color>white</Color>
            <Material>paper</Material>
        </Item1>

        <Item2 Include="notebook">
            <Size>SMALL</Size>
            <Color>YELLOW</Color>
        </Item2>

        <!-- Metadata can be expressed either as attributes or as elements -->
        <Item1 Update="$(MetadataToUpdate);stapler;er*r;@(Item2)" Price="10" Material="">
            <Color>RED</Color>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <Message Text="Item1: %(Item1.Identity)
    Size: %(Item1.Size)
    Color: %(Item1.Color)
    Material: %(Item1.Material)
    Price: %(Item1.Price)" />
    </Target>
</Project>

<!--  
Item1: stapler
    Size: medium
    Color: RED
    Material:
    Price: 10
Item1: pencil
    Size: small
    Color: RED
    Material:
    Price: 10
Item1: eraser
    Size:
    Color: RED
    Material:
    Price: 10
Item1: notebook
    Size: large
    Color: RED
    Material:
    Price: 10
-->

В MSBuild версии 16.6 и более поздних версиях Update атрибут поддерживает квалифицированные ссылки на метаданные для упрощения импорта метаданных из двух или более элементов.

<Project>
    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
        <Item1 Include="pencil">
            <Size>small</Size>
            <Color>yellow</Color>
            <Material>wood</Material>
        </Item1>
        <Item1 Include="eraser">
            <Size>small</Size>
            <Color>red</Color>
            <Material>gum</Material>
        </Item1>
        <Item1 Include="notebook">
            <Size>large</Size>
            <Color>white</Color>
            <Material>paper</Material>
        </Item1>

        <Item2 Include="pencil">
            <Size>MEDIUM</Size>
            <Color>RED</Color>
            <Material>PLASTIC</Material>
            <Price>10</Price>
        </Item2>

        <Item3 Include="notebook">
            <Size>SMALL</Size>
            <Color>BLUE</Color>
            <Price>20</Price>
        </Item3>

        <!-- Metadata can be expressed either as attributes or as elements -->
        <Item1 Update="@(Item2);er*r;@(Item3)" Size="%(Size)" Color="%(Item2.Color)" Price="%(Item3.Price)" Model="2020">
            <Material Condition="'%(Item2.Material)' != ''">Premium %(Item2.Material)</Material>
        </Item1>
    </ItemGroup>

    <Target Name="MyTarget">
        <Message Text="Item1: %(Item1.Identity)
    Size: %(Item1.Size)
    Color: %(Item1.Color)
    Material: %(Item1.Material)
    Price: %(Item1.Price)
    Model: %(Item1.Model)" />
    </Target>
</Project>

<!--  
Item1: stapler
    Size: medium
    Color: black
    Material: plastic
    Price:
    Model:
Item1: pencil
    Size: small
    Color: RED
    Material: Premium PLASTIC
    Price:
    Model: 2020
Item1: eraser
    Size: small
    Color:
    Material: gum
    Price:
    Model: 2020
Item1: notebook
    Size: large
    Color:
    Material: paper
    Price: 20
    Model: 2020
-->

Примечания:

• Неквалифицированные метаданные (%(MetadataName)) привязываются к обновляемой типу элемента (Item1 в приведенном выше примере). Квалифицированные метаданные (%(Item2.Color)) привязываются внутри набора захваченных типов элементов из выражения Update.
• Если элемент совпадает несколько раз в пределах и между несколькими ссылочными элементами:
  • Последнее вхождение из каждого типа элемента, на который ссылается ссылка, фиксируется (поэтому один захваченный элемент для каждого типа элемента).
  • Это соответствует поведению пакетной обработки элементов задачи в целевых объектах.
• Где можно поместить %() ссылки:
  • Метаданные
  • Условия метаданных
• Сопоставление имен метаданных не учитывает регистр.

Обновление метаданных для элементов в itemGroup целевого объекта

Метаданные также могут быть изменены внутри целевых объектов с помощью менее экспрессивного синтаксиса, чем Update:

<Project>
    <ItemGroup>
        <Item1 Include="stapler">
            <Size>medium</Size>
            <Color>black</Color>
            <Material>plastic</Material>
        </Item1>
        <Item1 Include="pencil">
            <Size>small</Size>
            <Color>yellow</Color>
            <Material>wood</Material>
        </Item1>
        <Item1 Include="eraser">
            <Size>small</Size>
            <Color>red</Color>
            <Material>gum</Material>
        </Item1>
        <Item1 Include="notebook">
            <Size>large</Size>
            <Color>white</Color>
            <Material>paper</Material>
        </Item1>

        <Item2 Include="pencil">
            <Size>MEDIUM</Size>
            <Color>RED</Color>
            <Material>PLASTIC</Material>
            <Price>10</Price>
        </Item2>

        <Item2 Include="ruler">
            <Color>GREEN</Color>
        </Item2>

    </ItemGroup>

    <Target Name="MyTarget">
        <ItemGroup>
            <!-- Metadata can be expressed either as attributes or as elements -->
            <Item1 Size="GIGANTIC" Color="%(Item2.Color)">
                <Material Condition="'%(Item2.Material)' != ''">Premium %(Item2.Material)</Material>
            </Item1>
        </ItemGroup>

        <Message Text="Item1: %(Item1.Identity)
    Size: %(Item1.Size)
    Color: %(Item1.Color)
    Material: %(Item1.Material)
    Price: %(Item1.Price)
    Model: %(Item1.Model)" />
    </Target>
</Project>

<!--  
Item1: stapler
    Size: GIGANTIC
    Color: GREEN
    Material: Premium PLASTIC
    Price:
    Model:
Item1: pencil
    Size: GIGANTIC
    Color: GREEN
    Material: Premium PLASTIC
    Price:
    Model:
Item1: eraser
    Size: GIGANTIC
    Color: GREEN
    Material: Premium PLASTIC
    Price:
    Model:
Item1: notebook
    Size: GIGANTIC
    Color: GREEN
    Material: Premium PLASTIC
    Price:
    Model:
-->

Связанный контент

• Элемент Item (MSBuild)
• Общие элементы проектов MSBuild
• концепции MSBuild
• MSBuild
• Практическое руководство. Выбор файлов для сборки
• Практическое руководство. Исключение файлов из сборки
• Практическое руководство. Отображение списка элементов, разделенного запятыми
• Определения элементов
• пакетной обработки