Partilhar via

Itens do MSBuild

Os itens do MSBuild são entradas no sistema de compilação 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 compilação.

Como os itens são nomeados pelo tipo de item ao qual pertencem, os termos "item" e "valor do 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 hífen (-). 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 chamado 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 é anexado à 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 ponto-e-vírgula.

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

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

Criar itens durante a execução

Os itens que estão fora dos elementos Target recebem valores durante a fase de avaliação de uma compilação. 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 Output filho que tenha um ItemName atributo.

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

  • Target elementos podem conter elementos ItemGroup que podem conter elementos 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ê faria referência ao 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 separados por vírgulas.

Usar curingas para especificar itens

Você pode usar os caracteres curinga **, *e ? para especificar um grupo de arquivos como entradas para uma compilação 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 elemento a seguir seleciona todos os .vb arquivos na D: unidade:

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

Se você gostaria de incluir literal * ou ? caracteres em um item sem expansão curinga, você deve escapar dos caracteres curinga.

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

Usar o atributo Excluir

Os elementos de item podem conter o Exclude atributo, que exclui itens específicos (arquivos) do tipo de item. O Exclude atributo é normalmente usado em conjunto com caracteres curinga. Por exemplo, o XML a seguir adiciona todos os arquivos .cs no diretório ao tipo de CSFile 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 item que contém ambos. O exemplo a seguir não excluiria o Form1.cs de arquivo, 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 da compilação.

Metadados do item

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

Metadados são uma coleção de pares chave-valor que são declarados no arquivo de projeto como elementos filho de um elemento 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 item que os contém. Por exemplo, o XML a seguir adiciona Culture metadados que têm o valor Fr para os itens one.cs e two.cs do tipo de CSFile 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 os valores de metadados a qualquer momento. Se você definir metadados para um valor vazio, você efetivamente removê-los da compilação.

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

Você pode fazer referência aos metadados do item em todo o arquivo de projeto usando a sintaxe %(ItemMetadataName). Se houver ambiguidade, você pode 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 lotar a Message tarefa. Para obter mais informações sobre como usar metadados de item para processamento em lote , consulte Metadados de item em lotes 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 itens bem 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)bem conhecidos, cujo valor é o nome do arquivo do item (sem a extensão). Para obter mais informações, consulte Metadados de itens 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 tenha 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 de 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 Funções de item do MSBuild e Transformações.

Definições de itens

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 "Monday". O código dá o item two.cs 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 elementos podem conter elementos ItemGroup que podem conter elementos item. Os atributos nesta seção são válidos quando são especificados Targetpara um item em um ItemGroup arquivo .

Remover atributo

O Remove atributo remove itens específicos (arquivos) do tipo de item. Esse atributo foi introduzido no .NET Framework 3.5 (somente dentro de destinos). Os destinos internos e externos são suportados 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 de nomes de metadados especificados, em vez de corresponder com base nos valores de item.

Regra de correspondência para B Remove="@(A)" MatchOnMetadata="M": remova todos os itens que tenham metadados M, cujo valor V de B metadados para corresponde a M qualquer item de A com 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 b2de item , c2e d2 são removidos do item B porque:

  • b2e c2 do B jogo contra b1 a partir de A e M1=2M2=x
  • d2de B jogos contra c1 a partir de A e M1=3M2=y

A Message tarefa produz 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" />

Esta linha remove itens que têm os mesmos TargetPath valores de _TransitiveItemsToCopyToOutputDirectory metadados dos itens em_ThisProjectItemsToCopyToOutputDirectory

Atributo MatchOnMetadataOptions

Especifica a estratégia de correspondência de cadeia de caracteres usada para MatchOnMetadata fazer a correspondência dos valores de metadados entre itens (os nomes de metadados sempre diferenciam maiúsculas de minúsculas). Os valores possíveis são CaseSensitive, CaseInsensitive, ou PathLike. O valor predefinido é CaseSensitive.

PathLike aplica a normalização com reconhecimento de caminho aos valores como normalizar orientações de barras, 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 item poderá conter o KeepMetadata atributo. Se esse atributo for especificado, somente os metadados especificados na lista de nomes delimitada 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 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 os metadados cujos nomes estão contidos na lista de nomes delimitada por ponto-e-vírgula. 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 Funções de item do MSBuild.

Atributo KeepDuplicates

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

Se o item de origem e o item de destino tiverem 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 dos itens além dos valores dos itens, é importante saber o que está acontecendo com os metadados. Por exemplo, consulte Detetando duplicatas ao usar a função de item 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. Este atributo não está disponível para itens em 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 suporta 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:

  • Os metadados não qualificados (%(MetadataName)) ligam-se ao tipo de item que está a ser atualizado (Item1 no exemplo acima). Os metadados qualificados (%(Item2.Color)) são associados dentro do conjunto de tipos de itens 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 lote de itens de tarefa em destinos.
  • Onde se pode colocar %() referências:
    • Metadados
    • Condições dos 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