Travailler avec des fonctions d’élément

Le code dans les tâches et les cibles peut appeler des fonctions d’élément pour obtenir des informations sur les éléments du projet (dans MSBuild 4.0 et versions ultérieures). Ces fonctions simplifient l’obtention d’éléments distincts, et sont plus rapides que l’exécution d’une boucle parmi les éléments.

Fonctions d’élément de type chaîne

Vous pouvez utiliser des méthodes et des propriétés de chaîne dans le .NET Framework pour manipuler n’importe quelle valeur d’élément. Pour les méthodes String, spécifiez le nom de la méthode. Pour les propriétés String, spécifiez le nom de la propriété après « get_ ».

Pour les éléments qui ont plusieurs chaînes, la méthode ou la propriété de chaîne s’exécute sur chaque chaîne.

L’exemple suivant montre comment utiliser ces méthodes d’élément de type chaîne.

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

Fonctions d’élément intrinsèques

Le tableau ci-dessous liste les fonctions intrinsèques disponibles pour les éléments.

Fonction	Exemple	Description
Combine	@(MyItems->Combine('path'))	Retourne un nouvel ensemble d’éléments avec un chemin relatif donné ajouté à tous les éléments d’entrée.
Count	@(MyItems->Count())	Retourne le nombre d’éléments.
DirectoryName	@(MyItems->DirectoryName())	Retourne l’équivalent de Path.DirectoryName pour chaque élément.
Distinct	@(MyItems->Distinct())	Retourne les éléments qui ont des valeurs Include distinctes. Les métadonnées sont ignorées. La comparaison ne respecte pas la casse.
DistinctWithCase	@(MyItems->DistinctWithCase())	Retourne les éléments qui ont des valeurs itemspec distinctes. Les métadonnées sont ignorées. La comparaison respecte la casse.
Exists	@(MyItems->Exists())	Filtre un ensemble d’éléments sur ceux qui existent réellement sur le disque.
GetPathsOfAllDirectoriesAbove	@(MyItems->GetPathsOfAllFilesAbove())	Étant donné un ensemble d’éléments, retourne des éléments représentant tous les répertoires ancêtres. Aucun ordre n’est garanti.
Reverse	@(MyItems->Reverse())	Retourne les éléments en ordre inverse.
AnyHaveMetadataValue	@(MyItems->AnyHaveMetadataValue("MetadataName", "MetadataValue"))	Retourne un boolean pour indiquer si un élément a le nom et la valeur des métadonnées fournies. La comparaison ne respecte pas la casse.
ClearMetadata	@(MyItems->ClearMetadata())	Retourne les éléments avec leurs métadonnées effacées. Seul itemspec est conservé.
HasMetadata	@(MyItems->HasMetadata("MetadataName"))	Retourne les éléments qui ont le nom des métadonnées fourni. La comparaison ne respecte pas la casse.
Metadata	@(MyItems->Metadata("MetadataName"))	Retourne les valeurs des métadonnées qui ont le nom des métadonnées. Les éléments retournés ont les mêmes métadonnées que les valeurs sources.
WithMetadataValue	@(MyItems->WithMetadataValue("MetadataName", "MetadataValue"))	Retourne les éléments qui ont le nom et la valeur des métadonnées fournis. La comparaison ne respecte pas la casse.

Notes

Exists peut également être utilisé dans d’autres contextes, dans des conditions MSBuild, par exemple Condition="Exists('path')", ou dans des fonctions de propriété statiques, par exemple $([System.IO.File]::Exists("path")).

L’exemple suivant montre comment utiliser des fonctions d’élément intrinsèques.

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

Détection des doublons lors de l’utilisation de la fonction d’élément Metadata

La fonction d’élément Metadata conserve les métadonnées d’origine des éléments sources. Cela a certaines implications lorsque l’on évalue si les éléments retournés sont des doublons ou non. Pour contrôler la façon dont les éléments en double sont gérés, vous pouvez utiliser l’attribut KeepDuplicates. Vous pouvez également supprimer les métadonnées, si elles ne sont pas nécessaire, en ajoutant RemoveMetadata, auquel cas seules les valeurs elles-mêmes sont prises en compte lors de la détection des doublons.

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

La sortie se présente comme suit :

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

La modification suivante apportée au code entraîne la détection et la suppression de la valeur de l’élément en double :

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

Fonctions de condition MSBuild

La fonction HasTrailingSlash n’est pas une fonction d’élément. Elle peut être utilisée avec l’attribut Condition. Consultez Conditions MSBuild.

Contenu connexe

Vous pouvez également utiliser des attributs pour effectuer des opérations sur des listes d’éléments, telles que le filtrage sur les métadonnées d’élément. Pour plus d’informations, consultez l’article Éléments MSBuild.