Compartilhar via

Itens do MSBuild

Os itens do MSBuild são entradas no sistema de build e normalmente representam arquivos (os arquivos são especificados no Include atributo). Os itens são agrupados em tipos de item com base em seus nomes de elementos. Os tipos de item são listas nomeadas de itens que podem ser usados como parâmetros para tarefas. As tarefas usam os valores de item para executar as etapas do processo de build.

Como os itens são nomeados pelo tipo de item ao qual pertencem, os termos "item" e "valor de item" podem ser usados de forma intercambiável.

Criar itens em um arquivo de projeto

Você declara itens no arquivo de projeto como elementos filho de um elemento ItemGroup . Os nomes de itens válidos começam com uma letra maiúscula ou minúscula ou sublinhado (_); os caracteres subsequentes válidos incluem caracteres alfanuméricos (letras ou dígitos), sublinhado e hifen (-). O nome do elemento filho é o tipo do item. O Include atributo do elemento especifica os itens (arquivos) a serem incluídos com esse tipo de item. Por exemplo, o XML a seguir cria um tipo de item nomeado Compile, que inclui dois arquivos.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

O item file2.cs não substitui o item file1.cs; em vez disso, o nome do arquivo é acrescentado à lista de valores para o Compile tipo de item.

O XML a seguir cria o mesmo tipo de item declarando ambos os arquivos em um Include atributo. Observe que os nomes de arquivo são separados por um ponto-e-vírgula.

<ItemGroup>
    <Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>

O Include atributo é um caminho interpretado em relação à pasta do arquivo de projeto, $(MSBuildProjectPath)mesmo que o item esteja em um arquivo importado, como um .targets arquivo.

Criar itens durante a execução

Itens que estão fora dos elementos de destino recebem valores durante a fase de avaliação de um build. Durante a fase de execução subsequente, os itens podem ser criados ou modificados das seguintes maneiras:

  • Qualquer tarefa pode emitir um item. Para emitir um item, o elemento Task deve ter um elemento De saída filho que tenha um ItemName atributo.

  • A tarefa CreateItem pode emitir um item. Esse uso foi preterido.

  • Target os elementos podem conter elementos ItemGroup que podem conter elementos de item.

Itens de referência em um arquivo de projeto

Para fazer referência a tipos de item em todo o arquivo de projeto, use a sintaxe @(ItemType). Por exemplo, você referenciaria o tipo de item no exemplo anterior usando @(Compile). Usando essa sintaxe, você pode passar itens para tarefas especificando o tipo de item como um parâmetro dessa tarefa. Para obter mais informações, consulte Como selecionar os arquivos a serem compilados.

Por padrão, os itens de um tipo de item são separados por ponto-e-vírgula (;) quando ele é expandido. Você pode usar a sintaxe @(ItemType, 'separator') para especificar um separador diferente do padrão. Para obter mais informações, consulte Como exibir uma lista de itens separada com vírgulas.

Usar curingas para especificar itens

Você pode usar os **caracteres curinga e , *para ? especificar um grupo de arquivos como entradas para um build em vez de listar cada arquivo separadamente.

  • O ? caractere curinga corresponde a um único caractere.
  • O * caractere curinga corresponde a zero ou mais caracteres.
  • A ** sequência de caracteres curinga corresponde a um caminho parcial.

Por exemplo, você pode especificar todos os .cs arquivos no diretório que contém o arquivo de projeto usando o seguinte elemento em seu arquivo de projeto.

<CSFile Include="*.cs"/>

O seguinte elemento seleciona todos os .vb arquivos na D: unidade:

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

Se você quiser incluir literais * ou ? caracteres em um item sem expansão curinga, você deverá escapar dos caracteres curinga.

Para obter mais informações sobre caracteres curinga, consulte Como selecionar os arquivos a serem compilados.

Usar o atributo Excluir

Os elementos de item podem conter o Exclude atributo, que exclui itens (arquivos) específicos do tipo de item. O Exclude atributo normalmente é usado junto com caracteres curinga. Por exemplo, o XML a seguir adiciona cada arquivo .cs no diretório ao CSFile tipo de item, exceto o arquivo DoNotBuild.cs .

<ItemGroup>
    <CSFile  Include="*.cs"  Exclude="DoNotBuild.cs"/>
</ItemGroup>

O Exclude atributo afeta apenas os itens que são adicionados pelo Include atributo no elemento de item que contém ambos. O exemplo a seguir não excluiria o arquivo Form1.cs, que foi adicionado no elemento de item anterior.

<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">

Para obter mais informações, consulte Como excluir arquivos do build.

Metadados do item

Os itens podem conter metadados além das informações e IncludeExclude atributos. Esses metadados podem ser usados por tarefas que exigem mais informações sobre os itens ou tarefas e destinos em lote. Para obter mais informações, consulte Envio em lote.

Metadados é uma coleção de pares chave-valor que são declarados no arquivo de projeto como elementos filho de um elemento de item. O nome do elemento filho é o nome dos metadados e o valor do elemento filho é o valor dos metadados.

Os metadados estão associados ao elemento de item que o contém. Por exemplo, o XML a seguir adiciona Culture metadados que têm o valor Fr ao one.cs e aos itens two.cs do CSFile tipo de item.

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

Um item pode ter zero ou mais valores de metadados. Você pode alterar valores de metadados a qualquer momento. Se você definir metadados como um valor vazio, remova-os efetivamente do build.

Metadados de item de referência em um arquivo de projeto

Você pode referenciar metadados de item em todo o arquivo de projeto usando a sintaxe %(ItemMetadataName). Se houver ambiguidade, você poderá qualificar uma referência usando o nome do tipo de item. Por exemplo, você pode especificar %(ItemType.ItemMetaDataName). O exemplo a seguir usa os Display metadados para colocar a tarefa em Message lote em lote. Para obter mais informações sobre como usar metadados de item para envio em lote, consulte metadados de item no envio em lote de tarefas.

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

Metadados de item conhecidos

Quando um item é adicionado a um tipo de item, esse item recebe alguns metadados conhecidos. Por exemplo, todos os itens têm os metadados %(Filename)conhecidos, cujo valor é o nome do arquivo do item (sem a extensão). Para obter mais informações, consulte metadados de item bem conhecidos.

Transformar tipos de item usando metadados

Você pode transformar listas de itens em novas listas de itens usando metadados. Por exemplo, você pode transformar um tipo CppFiles de item que tem itens que representam .cpp arquivos em uma lista correspondente de .obj arquivos usando a expressão @(CppFiles -> '%(Filename).obj').

O código a seguir cria um CultureResource tipo de item que contém cópias de todos os EmbeddedResource itens com Culture metadados. O Culture valor dos metadados torna-se o valor dos novos metadados CultureResource.TargetDirectory.

<Target Name="ProcessCultureResources">
    <ItemGroup>
        <CultureResource Include="@(EmbeddedResource)"
            Condition="'%(EmbeddedResource.Culture)' != ''">
            <TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>
        </CultureResource>
    </ItemGroup>
</Target>

Para obter mais operações em itens, consulte as funções e transformações de itens do MSBuild.

Definições de item

Você pode adicionar metadados padrão a qualquer tipo de item usando o elemento ItemDefinitionGroup. Como metadados conhecidos, os metadados padrão são associados a todos os itens do tipo de item especificado. Você pode substituir explicitamente os metadados padrão em uma definição de item. Por exemplo, o XML a seguir fornece os Compile itens one.cs e three.cs os metadados BuildDay com o valor "Segunda-feira". O código fornece o item two.cs os metadados BuildDay com o valor "Terça-feira".

<ItemDefinitionGroup>
    <Compile>
        <BuildDay>Monday</BuildDay>
    </Compile>
</ItemDefinitionGroup>
<ItemGroup>
    <Compile Include="one.cs;three.cs" />
    <Compile Include="two.cs">
        <BuildDay>Tuesday</BuildDay>
    </Compile>
</ItemGroup>

Para obter mais informações, consulte definições de item.

Atributos para itens em um ItemGroup de um destino

Target os elementos podem conter elementos ItemGroup que podem conter elementos de item. Os atributos nesta seção são válidos quando são especificados para um item em um ItemGroup que está em um Target.

Remover atributo

O Remove atributo remove itens (arquivos) específicos do tipo de item. Esse atributo foi introduzido no .NET Framework 3.5 (somente dentro de destinos). Há suporte para destinos internos e externos a partir do MSBuild 15.0.

O exemplo a seguir remove todos os .config arquivos do Compile tipo de item.

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

Atributo MatchOnMetadata

O MatchOnMetadata atributo é aplicável somente a atributos que fazem referência a Remove outros itens (por exemplo) Remove="@(Compile);@(Content)"e instrui a Remove operação a corresponder itens com base nos valores dos nomes de metadados especificados, em vez de corresponder com base nos valores do item.

Regra de correspondência para B Remove="@(A)" MatchOnMetadata="M": remova todos os itens B que têm metadados M, cujo valor V de metadados corresponde M a qualquer item com A metadados M de valor 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>

No exemplo, os valores de item e b2 são removidos c2d2do item B porque:

  • b2 e c2 da B partida contra b1 de A diante M1=2 e M2=x
  • d2 de B partidas contra c1 de A diante M1=3 e M2=y

A Message tarefa gera o seguinte:

  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'

Exemplo de uso do MatchOnMetadataMSBuild:

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

Essa linha remove itens que _TransitiveItemsToCopyToOutputDirectory têm os mesmos TargetPath valores de metadados de itens em _ThisProjectItemsToCopyToOutputDirectory

Atributo MatchOnMetadataOptions

Especifica a estratégia de correspondência de cadeia de caracteres usada MatchOnMetadata para corresponder aos valores de metadados entre itens (os nomes de metadados sempre correspondem a maiúsculas de minúsculas). Os valores possíveis são CaseSensitive, CaseInsensitiveou PathLike. O valor padrão é CaseSensitive.

PathLike aplica a normalização com reconhecimento de caminho aos valores como normalizar orientações de barra, ignorar barras à direita, eliminar . e ..tornar todos os caminhos relativos absolutos em relação ao diretório atual.

Atributo KeepMetadata

Se um item for gerado dentro de um destino, o elemento de item poderá conter o KeepMetadata atributo. Se esse atributo for especificado, somente os metadados especificados na lista de nomes delimitados por ponto-e-vírgula serão transferidos do item de origem para o item de destino. Um valor vazio para esse atributo é equivalente a não especificá-lo. O KeepMetadata atributo foi introduzido no .NET Framework 4.5.

O exemplo a seguir ilustra como usar o KeepMetadata atributo.

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

Atributo RemoveMetadata

Se um item for gerado dentro de um destino, o elemento de item poderá conter o RemoveMetadata atributo. Se esse atributo for especificado, todos os metadados serão transferidos do item de origem para o item de destino, exceto metadados cujos nomes estão contidos na lista delimitada por ponto-e-vírgula de nomes. Um valor vazio para esse atributo é equivalente a não especificá-lo. O RemoveMetadata atributo foi introduzido no .NET Framework 4.5.

O exemplo a seguir ilustra como usar o RemoveMetadata atributo.

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

Para obter mais operações em itens, consulte as funções de item do MSBuild.

Atributo KeepDuplicates

Se um item for gerado dentro de um destino, o elemento de item poderá conter o KeepDuplicates atributo. KeepDuplicates é um Boolean atributo que especifica se um item deve ser adicionado ao grupo de destino se o item for uma duplicata exata de um item existente.

Se o item de origem e de destino tiver o mesmo Include valor, mas metadados diferentes, o item será adicionado mesmo que KeepDuplicates esteja definido como false. Um valor vazio para esse atributo é equivalente a não especificá-lo. O KeepDuplicates atributo foi introduzido no .NET Framework 4.5.

O exemplo a seguir ilustra como usar o KeepDuplicates atributo.

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

Como o KeepDuplicates atributo considera os metadados de itens além dos valores de item, é importante saber o que está acontecendo com os metadados. Por exemplo, consulte Detectar duplicatas ao usar a função de item de metadados.

Atualizando metadados em itens em um ItemGroup fora de um destino

Itens fora dos destinos podem ter seus metadados existentes atualizados por meio do Update atributo. Esse atributo não está disponível para itens sob destinos.

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

No MSBuild versão 16.6 e posterior, o Update atributo dá suporte a referências de metadados qualificados para facilitar a importação de metadados de dois ou mais itens.

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

Observações:

  • Metadados não qualificados (%(MetadataName)) associam-se ao tipo de item que está sendo atualizado (Item1 no exemplo acima). Metadados qualificados (%(Item2.Color)) associam-se dentro do conjunto de tipos de item correspondentes capturados da expressão Update.
  • Se um item corresponder várias vezes dentro e entre vários itens referenciados:
    • A última ocorrência de cada tipo de item referenciado é capturada (portanto, um item capturado por tipo de item).
    • Isso corresponde ao comportamento do envio em lote de item de tarefa sob destinos.
  • Onde é possível colocar referências %():
    • Metadados
    • Condições de metadados
  • A correspondência de nomes de metadados não diferencia maiúsculas de minúsculas.

Atualizando metadados em itens em um ItemGroup de um destino

Os metadados também podem ser modificados dentro de destinos por uma sintaxe menos expressiva do que 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:
-->

Conteúdo relacionado

  • Last updated on