Itens do MSBuild
Itens do MSBuild são entradas no sistema de build e eles normalmente representam arquivos (os arquivos estão especificados no atributo Include). Os itens são agrupados em tipos de item com base em seus nomes de elemento. Os tipos de item são listas nomeadas de itens que podem ser usados como parâmetros para tarefas. As tarefas usam os valores do 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 alternadamente.
Criar itens em um arquivo de projeto
Os itens são declarados no arquivo de projeto como elementos filho de um elemento ItemGroup. Os nomes de item 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 atributo Include 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 de arquivo é acrescentado à lista de valores do tipo de item Compile.
O XML a seguir cria o mesmo tipo de item declarando os dois arquivos em um atributo Include. Observe que os nomes de arquivo são separados por ponto e vírgula.
<ItemGroup>
<Compile Include = "file1.cs;file2.cs"/>
</ItemGroup>
O atributo Include é um caminho interpretado em relação à pasta do arquivo de projeto, $(MSBuildProjectPath), mesmo que o item esteja em um arquivo importado, como um arquivo .targets.
Criar itens durante a execução
Os itens que estão fora dos elementos de destino são valores designados 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 filho Output que tem um atributo
ItemName.A tarefa CreateItem pode emitir um item. Esse uso é preterido.
Os elementos
Targetpodem conter elementos ItemGroup que podem conter elementos de item.
Referenciar itens em um arquivo de projeto
Para referenciar tipos de item em todo o arquivo de projeto, use a sintaxe @(ItemType). Por exemplo, você faria referência no tipo de item no exemplo anterior usando @(Compile). Usando esta sintaxe, você pode passar itens para tarefas, especificando o tipo de item como um parâmetro dessa tarefa. Para obter mais informações, confira 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 são expandidos. Use a sintaxe @(ItemType, 'separator') para especificar um separador diferente do padrão. Para obter mais informações, confira Como exibir uma lista de itens separada por 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 arquivos .cs no diretório que contém o arquivo de projeto usando o elemento a seguir no arquivo de projeto.
<CSFile Include="*.cs"/>
O seguinte elemento seleciona todos os arquivos .vb na unidade D::
<VBFile Include="D:/**/*.vb"/>
Para incluir caracteres literais * ou ? em um item sem expansão de curinga, você deve usar o escape para os caracteres curinga.
Para obter mais informações sobre caracteres curinga, confira Como selecionar os arquivos a serem compilados.
Usar o atributo Exclude
Os elementos de item podem conter o atributo Exclude, que exclui itens específicos (arquivos) do tipo de item. O atributo Exclude normalmente é usado junto com caracteres curinga. Por exemplo, o XML a seguir adiciona cada arquivo .cs no diretório ao tipo de item CSFile, exceto o arquivo DoNotBuild.cs.
<ItemGroup>
<CSFile Include="*.cs" Exclude="DoNotBuild.cs"/>
</ItemGroup>
O atributo Exclude afeta somente os itens adicionados pelo atributo Include no elemento do item que contém ambos. O exemplo a seguir não exclui 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, confira Como excluir arquivos do build.
Metadados do item
Os itens que podem conter metadados, além das informações nos atributos Include e Exclude. Esses metadados podem ser usados por tarefas que exigem mais informações sobre os itens ou para os destinos e tarefas de lote. Para obter mais informações, consulte Envio em lote.
Os metadados são uma coleção de pares chave-valor que são declarados no arquivo de projeto como elementos filho de um elemento do item. O nome do elemento filho é o nome dos metadados e o valor do elemento filho é o valor dos metadados.
Os metadados são associados ao elemento do item que os contém. Por exemplo, o XML a seguir adiciona metadados Culture que têm o valor Fr aos itens one.cs e two.cs do tipo de item CSFile.
<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 definir metadados para um valor vazio, você efetivamente vai removê-lo do build.
Referenciar metadados de item em um arquivo de projeto
Você pode fazer referência a metadados de item em todo o arquivo de projeto usando a sintaxe %(ItemMetadataName). Se existir a 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 metadados Display para colocar em lote a tarefa Message. Para obter mais informações sobre como usar os metadados de item para o envio em lote, confira Metadados de item no envio de tarefas em lote.
<Project xmlns="http://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>
Metadados de itens conhecidos
Sempre que um item é adicionado a um tipo de item, esse item é atribuído a alguns metadados conhecidos. Por exemplo, todos os itens que têm metadados %(Filename) conhecidos, cujo valor é o nome de arquivo do item (sem a extensão). Para obter mais informações, confira Metadados de item conhecidos.
Transformar os tipos de item usando metadados
Você pode transformar listas de itens em novas listas de item usando metadados. Por exemplo, você pode transformar um tipo de item CppFiles que tem itens que representam arquivos .cpp em uma lista correspondente de arquivos .obj usando a expressão @(CppFiles -> '%(Filename).obj').
O código a seguir cria um tipo de item CultureResource que contém cópias de todos os itens EmbeddedResource com metadados Culture. O valor de metadados Culture se torna 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 conhecer mais operações em itens, consulte Transformações e funções de item 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 estão associados a todos os itens do tipo de item especificado. Você pode substituir explicitamente metadados padrão em uma definição de item. Por exemplo, o XML a seguir fornece aos itens Compileone.cs e three.cs os metadados BuildDay com o valor "Monday". O código fornece ao item two.cs os metadados BuildDay com o valor "Tuesday".
<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, confira Definições de item.
Atributos de itens em um ItemGroup de um Target
Os elementos Target 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 é um Target.
Remover atributo
O atributo Remove remove itens específicos (arquivos) 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 arquivos .config do tipo de item Compile.
<Target>
<ItemGroup>
<Compile Remove="*.config"/>
</ItemGroup>
</Target>
Atributo MatchOnMetadata
O atributo MatchOnMetadata é aplicável somente a atributos Remove que fazem referência a outros itens (por exemplo, Remove="@(Compile);@(Content)") e instrui a operação Remove 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 de B que tenham metadados M, cujo valor de metadados V para M corresponda a 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 de item b2, c2 e d2 são removidos do item B porque:
b2ec2deBcorrespondem ab1deAemM1=2e emM2=xd2deBcorrespondem ac1deAemM1=3e emM2=y
A tarefa Message 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 MatchOnMetadata do MSBuild:
<_TransitiveItemsToCopyToOutputDirectory Remove="@(_ThisProjectItemsToCopyToOutputDirectory)" MatchOnMetadata="TargetPath" MatchOnMetadataOptions="PathLike" />
Esta linha remove itens de _TransitiveItemsToCopyToOutputDirectory que têm os mesmos valores de metadados TargetPath de itens em _ThisProjectItemsToCopyToOutputDirectory
Atributo MatchOnMetadataOptions
Especifica a estratégia de correspondência de cadeia de caracteres usada por MatchOnMetadata para corresponder os valores de metadados entre itens (a correspondência dos nomes de metadados é sempre feita sem diferenciar maiúsculas de minúsculas). Os valores possíveis são CaseSensitive, CaseInsensitive, ou 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 .. e tornar todos os caminhos relativos absolutos em relação ao diretório atual.
Atributo KeepMetadata
Se um item for gerado em um destino, o elemento de item poderá conter o atributo KeepMetadata. Se esse atributo for especificado, apenas os metadados que serão especificados na lista de nomes separados 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 especificação dele. O atributo KeepMetadata foi introduzido no .NET Framework 4.5.
O exemplo a seguir mostra como usar o atributo KeepMetadata.
<Project xmlns="http://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:
-->
Atributo RemoveMetadata
Se um item for gerado em um destino, o elemento de item poderá conter o atributo RemoveMetadata. 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 separados por ponto-e-vírgula. Um valor vazio para esse atributo é equivalente a não especificação dele. O atributo RemoveMetadata foi introduzido no .NET Framework 4.5.
O exemplo a seguir mostra como usar o atributo RemoveMetadata.
<Project ToolsVersion="4.0" xmlns="http://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:
-->
Para obter mais operações sobre itens, consulte Funções de item do MSBuild.
Atributo KeepDuplicates
Se um item for gerado em um destino, o elemento de item poderá conter o atributo KeepDuplicates. KeepDuplicates é um atributo Boolean que especifica se um item deverá ser adicionado ao grupo de destino se for uma duplicata exata de um item existente.
Se o item de origem e de destino tiverem o mesmo valor Include, mas metadados diferentes, o item será adicionado mesmo se KeepDuplicates estiver definido como false. Um valor vazio para esse atributo é equivalente a não especificação dele. O atributo KeepDuplicates foi introduzido no .NET Framework 4.5.
O exemplo a seguir mostra como usar o atributo KeepDuplicates.
<Project ToolsVersion="4.0" xmlns="http://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
-->
Como o atributo KeepDuplicates 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.
Atualizar metadados em itens em um ItemGroup fora de um Destino
Itens fora dos destinos podem ter seus metadados existentes atualizados por meio do atributo Update. Esse 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 atributo Update 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
-->
Comentários:
- Os metadados não qualificados (
%(MetadataName)) são associados ao tipo de item que está sendo atualizado (Item1no exemplo acima). Os metadados qualificados (%(Item2.Color)) são associados dentro do conjunto de tipos de item correspondentes capturados na 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 será capturada (portanto, um item capturado por tipo de item).
- Isso corresponde ao comportamento do envio em lote de itens de tarefa em destinos.
- Em que é 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.
Atualizar 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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de