Trabalhar com funções de item

O código em tarefas e destinos pode chamar funções de item para obter informações sobre os itens no projeto (no MSBuild 4.0 e mais recente). Essas funções simplificam a obtenção de itens distintos e são mais rápidas do que executar loop nos itens.

Funções de item de cadeia de caracteres

É possível usar métodos e propriedades de cadeia de caracteres no .NET Framework para operar em qualquer valor de item. Para métodos String, especifique o nome do método. Para propriedades String, especifique o nome da propriedade após "get_".

Para itens que têm várias cadeias de caracteres, o método ou propriedade da cadeia de caracteres será executado em cada cadeia de caracteres.

O exemplo a seguir mostra como usar essas funções de item de cadeia de caracteres.

<ItemGroup>
    <theItem Include="andromeda;tadpole;cartwheel" />
</ItemGroup>

<Target Name = "go">
    <Message Text="IndexOf  @(theItem->IndexOf('r'))" />
    <Message Text="Replace  @(theItem->Replace('tadpole', 'pinwheel'))" />
    <Message Text="Length   @(theItem->get_Length())" />
    <Message Text="Chars    @(theItem->get_Chars(2))" />
</Target>

  <!--
  Output:
    IndexOf  3;-1;2
    Replace  andromeda;pinwheel;cartwheel
    Length   9;7;9
    Chars    d;d;r
  -->

Funções de item intrínsecas

A tabela a seguir lista as funções intrínsecas disponíveis para itens.

Função	Exemplo	Descrição
Combine	@(MyItems->Combine('path'))	Retorna um novo conjunto de itens com um determinado caminho relativo acrescentado a todos os itens de entrada.
Count	@(MyItems->Count())	Retorna a contagem dos itens.
DirectoryName	@(MyItems->DirectoryName())	Retorna o equivalente de Path.DirectoryName para cada item.
Distinct	@(MyItems->Distinct())	Retorna itens com valores Include distintos. Os metadados são ignorados. A comparação não diferencia maiúsculas de minúsculas.
DistinctWithCase	@(MyItems->DistinctWithCase())	Retorna itens com valores itemspec distintos. Os metadados são ignorados. A comparação diferencia maiúsculas de minúsculas.
Exists	@(MyItems->Exists())	Filtra um conjunto de itens para aqueles que realmente existem no disco.
GetPathsOfAllDirectoriesAbove	@(MyItems->GetPathsOfAllFilesAbove())	Dado um conjunto de itens, retorna itens que representam todos os diretórios ancestrais. Nenhuma ordem é garantida.
Reverse	@(MyItems->Reverse())	Retorna os itens em ordem inversa.
AnyHaveMetadataValue	@(MyItems->AnyHaveMetadataValue("MetadataName", "MetadataValue"))	Retorna um boolean para indicar se qualquer item tem o valor e o nome de metadados especificado. A comparação não diferencia maiúsculas de minúsculas.
ClearMetadata	@(MyItems->ClearMetadata())	Retorna os itens com seus metadados desmarcados. Somente o itemspec é mantido.
HasMetadata	@(MyItems->HasMetadata("MetadataName"))	Retorna os itens que têm o nome de metadados especificado. A comparação não diferencia maiúsculas de minúsculas.
Metadata	@(MyItems->Metadata("MetadataName"))	Retorna os valores dos metadados que têm o nome de metadados. Os itens retornados têm os mesmos metadados que os valores de origem.
WithMetadataValue	@(MyItems->WithMetadataValue("MetadataName", "MetadataValue"))	Retorna os itens que têm o nome e o valor de metadados especificado. A comparação não diferencia maiúsculas de minúsculas.

Observação

Exists também pode ser usado em outros contextos; em condições do MSBuild, por exemplo Condition="Exists('path')", ou em funções de propriedade estáticas, por exemplo $([System.IO.File]::Exists("path")).

O exemplo a seguir mostra como usar funções intrínsecas de item.

<ItemGroup>
    <TheItem Include="first">
        <Plant>geranium</Plant>
    </TheItem>
    <TheItem Include="second">
        <Plant>algae</Plant>
    </TheItem>
    <TheItem Include="third">
        <Plant>geranium</Plant>
    </TheItem>
</ItemGroup>

<Target Name="go">
    <Message Text="MetaData:    @(TheItem->Metadata('Plant'))" />
    <Message Text="HasMetadata: @(theItem->HasMetadata('Plant'))" />
    <Message Text="WithMetadataValue: @(TheItem->WithMetadataValue('Plant', 'geranium'))" />
    <Message Text=" " />
    <Message Text="Count:   @(theItem->Count())" />
    <Message Text="Reverse: @(theItem->Reverse())" />
</Target>

  <!--
  Output:
    MetaData:    geranium;algae;geranium
    HasMetadata: first;second;third
    WithMetadataValue: first;third

    Count:   3
    Reverse: third;second;first
  -->

Detectar duplicatas ao usar a função de item de metadados.

A função de item Metadata preserva os metadados originais dos itens de origem. Isso tem algumas implicações ao considerar se os itens retornados são duplicados ou não. Para controlar como os itens duplicados são tratados, você pode usar o atributo KeepDuplicates. Você também pode remover os metadados, se não forem necessários, adicionando o RemoveMetadata; nesse caso, somente os próprios valores são considerados ao detectar duplicatas.

  <Target Name="MetadataToItem">
    <ItemGroup>
      <Sample Include="AAA" SomeItems="1;2;3" />
      <Sample Include="BBB" SomeItems="3;4;5" />
    </ItemGroup>

    <ItemGroup>
      <AllSomeItems Include="@(Sample->Metadata('SomeItems'))" KeepDuplicates="false" />
    </ItemGroup>
    <Message Text="AllSomeItems is @(AllSomeItems)" />
  </Target>

A saída é da seguinte maneira:

MetadataToItem:
  AllSomeItems is 1;2;3;3;4;5

A seguinte alteração no código faz com que o valor do item duplicado seja detectado e removido com êxito:

    <ItemGroup>
      <AllSomeItems Include="@(Sample->Metadata('SomeItems'))" KeepDuplicates="false" RemoveMetadata="SomeItems" />
    </ItemGroup>

Funções de condição do MSBuild

A função HasTrailingSlash não é uma função de item. Ela está disponível para uso com o atributo Condition. Confira Condições do MSBuild.

Conteúdo relacionado

Você também pode usar atributos para executar operações em listas de itens, como filtragem em metadados de item. Para obter mais informações, consulte Itens.