Elemento Item (MSBuild)

  • Artigo

Contém um item definido pelo usuário e seus metadados. Cada item usado em um projeto MSBuild deve ser especificado como filho de um elemento ItemGroup.

<Projeto>
 <ItemGroup>
  <Item>

Syntax

<Item Include="*.cs"
        Exclude="MyFile.cs"
        Condition="'String A'=='String B'">
    <ItemMetadata1>...</ItemMetadata1>
    <ItemMetadata2>...</ItemMetadata2>
</Item>

Especificar metadados como atributos

No MSBuild 15.1 ou posterior, os metadados com um nome que não entra em conflito com a lista atual de atributos podem opcionalmente ser expressos como um atributo.

Por exemplo, para especificar uma lista de pacotes NuGet, você normalmente usará algo parecido com a sintaxe a seguir.

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json">
    <Version>9.0.1-beta1<Version>
  </PackageReference>
</ItemGroup>

No entanto, é possível passar os metadados Version como um atributo, como na seguinte sintaxe:

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="9.0.1-beta1" />
</ItemGroup>

Atributos e elementos

As seções a seguir descrevem atributos, elementos filho e elementos pai.

Atributos

Atributo Descrição
Include Atributo opcional.

O arquivo ou curinga a ser incluído na lista de itens.
Exclude Atributo opcional.

O arquivo ou curinga a ser excluído da lista de itens.
Condition Atributo opcional.

A condição a ser avaliada. Para obter mais informações, consulte Condições.
Remove Atributo opcional.

O arquivo ou curinga a ser removido da lista de itens.
MatchOnMetadata Atributo opcional.

Modifica atributos Remove que fazem referência a outros itens de modo a corresponder aos nomes dos metadados especificados em vez de corresponder aos valores dos itens referenciados.

Esse atributo só será válido se for especificado com um atributo Remove que contiver apenas referências a outros itens (por exemplo, Remove="@(Compile);@(Content)"). Mais detalhes em Itens.
MatchOnMetadataOptions Atributo opcional.

Especifica a estratégia de correspondência de cadeias de caracteres usada por MatchOnMetadata. Os valores possíveis são CaseSensitive, CaseInsensitive, ou PathLike. O valor padrão é CaseInsensitive.
KeepDuplicates Atributo opcional.

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. Para obter mais informações, consulte Itens.

Esse atributo será válido apenas se for especificado para um item em uma ItemGroup que esteja em um Target.
KeepMetadata Atributo opcional.

Os metadados dos itens de origem a serem adicionados nos itens de destino. Apenas os metadados cujos nomes são especificados na lista delimitada por ponto e vírgula são transferidos de um item de origem para um item de destino. Para obter mais informações, consulte Itens.

Esse atributo será válido apenas se for especificado para um item em uma ItemGroup que esteja em um Target.
RemoveMetadata Atributo opcional.

Os metadados dos itens de origem que não serão transferidos para os itens de destino. Todos os metadados são transferidos de um item de origem para um item de destino, exceto metadados cujos nomes estejam contidos na lista de nomes separados por ponto e vírgula. Para obter mais informações, consulte Itens.

Esse atributo será válido apenas se for especificado para um item em uma ItemGroup que esteja em um Target.
Update Atributo opcional. (Disponível somente para projetos do .NET Core no Visual Studio 2017 ou posterior.)

Permite modificar metadados de um item; normalmente usado para substituir os metadados padrão de itens específicos depois que um grupo de itens é inicialmente especificado (como com um curinga).

Esse atributo será válido apenas se for especificado para um item em um ItemGroup que não esteja em um Target.

Elementos filho

Elemento Descrição
ItemMetadata Uma chave de metadados de item definido pelo usuário, que contém o valor de metadados do item. Pode ser que não haja nenhum ou mais de um elemento ItemMetadata em um item.

Elementos pai

Elemento Descrição
ItemGroup Elemento grouping para itens.

Comentários

Os elementos Item definem entradas no sistema de compilação e são agrupados em coleções de itens com base em seus nomes de coleção definida pelo usuário. Essas coleções de itens podem ser usadas como parâmetros para tarefas, que usam os itens individuais nas coleções para executar as etapas do processo de build. Para obter mais informações, consulte Itens.

O uso da notação @(<myType>) permite que uma coleção de itens do tipo <myType> seja expandida para uma lista de cadeias de caracteres delimitadas por ponto e vírgula e passada para um parâmetro. Se o parâmetro for do tipo string, então o valor do parâmetro será a lista de elementos, separados por ponto e vírgula. Se o parâmetro for uma matriz de cadeias de caracteres (string[]), então cada elemento será inserido na matriz com base na localização dos pontos e vírgulas. Se o parâmetro de tarefa for do tipo ITaskItem[], então o valor é o conteúdo da coleção de itens juntamente com quaisquer metadados anexados. Para delimitar cada item usando um caractere que não seja ponto e vírgula, use a sintaxe @(<myType>, '<separator>').

O mecanismo MSBuild pode avaliar curingas como * e ?, bem como curingas recursivos como /**/*.cs. Para obter mais informações, consulte Itens.

Exemplos

O exemplo de código a seguir mostra como declarar dois itens do tipo CSFile. O segundo item declarado contém metadados que possuem MyMetadata definidos como HelloWorld.

<ItemGroup>
    <CSFile Include="engine.cs; form.cs" />
    <CSFile Include="main.cs" >
        <MyMetadata>HelloWorld</MyMetadata>
    </CSFile>
</ItemGroup>

O exemplo de código a seguir mostra como usar o atributo Update para modificar os metadados em um arquivo chamado somefile.cs incluído por meio de um glob. (Disponível somente para projetos do .NET Core no Visual Studio 2017 ou posterior.)

<ItemGroup>
    <Compile Update="somefile.cs">  // or Update="*.designer.cs"
        <MetadataKey>MetadataValue</MetadataKey>
    </Compile>
</ItemGroup>

Confira também