Partager via

Définitions d’éléments

MSBuild 2.0 active la déclaration statique d’éléments dans les fichiers projet à l’aide de l’élément ItemGroup . Toutefois, les métadonnées peuvent être ajoutées uniquement au niveau de l’élément, même si les métadonnées sont identiques pour tous les éléments. À compter de MSBuild 3.5, un élément de projet nommé ItemDefinitionGroup dépasse cette limitation. ItemDefinitionGroup vous permet de définir un ensemble de définitions d’éléments, qui ajoutent des valeurs de métadonnées par défaut à tous les éléments du type d’élément nommé.

L’élément ItemDefinitionGroup apparaît immédiatement après l’élément Project du fichier projet. Les définitions d’éléments fournissent les fonctionnalités suivantes :

  • Vous pouvez définir des métadonnées par défaut globales pour les éléments en dehors d’une cible. Autrement dit, les mêmes métadonnées s’appliquent à tous les éléments du type spécifié.

  • Les types d’éléments peuvent avoir plusieurs définitions. Lorsque des spécifications de métadonnées supplémentaires sont ajoutées au type, la dernière spécification est prioritaire. (Les métadonnées suivent le même ordre d’importation que les propriétés suivent.)

  • Les métadonnées peuvent être additifs. Par exemple, les valeurs CDefines sont accumulées de manière conditionnelle, en fonction des propriétés définies. Par exemple : MT;STD_CALL;DEBUG;UNICODE.

  • Les métadonnées peuvent être supprimées.

  • Les conditions peuvent être utilisées pour contrôler l’inclusion des métadonnées.

Valeurs par défaut des métadonnées d’élément

Les métadonnées d’élément définies dans un ItemDefinitionGroup ne sont qu’une déclaration de métadonnées par défaut. Les métadonnées ne s’appliquent pas, sauf si vous définissez un élément qui utilise un ItemGroup pour contenir les valeurs de métadonnées.

Remarque

Dans la plupart des exemples de cette rubrique, un élément ItemDefinitionGroup est affiché, mais sa définition ItemGroup correspondante est omise pour plus de clarté.

Les métadonnées explicitement définies dans un ItemGroup sont prioritaires sur les métadonnées dans ItemDefinitionGroup. Les métadonnées dans ItemDefinitionGroup sont appliquées uniquement pour les métadonnées non définies dans un ItemGroup. Par exemple:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <n>n1</n>
    </i>
</ItemDefinitionGroup>
<ItemGroup>
    <i Include="a">
        <o>o1</o>
        <n>n2</n>
    </i>
</ItemGroup>

Dans cet exemple, les métadonnées par défaut « m » sont appliquées à l’élément « i », car les métadonnées « m » ne sont pas définies explicitement par l’élément « i ». Toutefois, les métadonnées par défaut « n » ne sont pas appliquées à l’élément « i », car les métadonnées « n » sont déjà définies par l’élément « i ».

Remarque

Les noms d’éléments et de paramètres XML respectent la casse. Les métadonnées d’élément et les noms d’élément/propriété ne respectent pas la casse. Par conséquent, les éléments ItemDefinitionGroup qui ont des noms qui diffèrent uniquement par cas doivent être traités comme le même ItemGroup.

Sources de valeur

Les valeurs des métadonnées définies dans un ItemDefinitionGroup peuvent provenir de nombreuses sources différentes, comme suit :

  • PropertyGroup, propriété

  • Élément d’un ItemDefinitionGroup

  • Transformation d’élément sur un élément ItemDefinitionGroup

  • Variable d’environnement

  • Propriété globale (à partir de la ligne de commande MSBuild.exe )

  • Propriété réservée

  • Métadonnées connues sur un élément à partir d’un ItemDefinitionGroup

  • Section <CDATA ![ CDATA[n’importe quoi ici n’est pas analysé]]>

Remarque

Les métadonnées d’élément d’un ItemGroup ne sont pas utiles dans une déclaration de métadonnées ItemDefinitionGroup, car les éléments ItemDefinitionGroup sont traités avant les éléments ItemGroup.

Additifs et définitions multiples

Lorsque vous ajoutez des définitions ou utilisez plusieurs ItemDefinitionGroups, n’oubliez pas ce qui suit :

  • Une spécification de métadonnées supplémentaire est ajoutée au type.

  • La dernière spécification est prioritaire.

Lorsque vous avez plusieurs ItemDefinitionGroups, chaque spécification suivante ajoute ses métadonnées à la définition précédente. Par exemple:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <n>n1</n>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <o>o1</o>
    </i>
</ItemDefinitionGroup>

Dans cet exemple, les métadonnées « o » sont ajoutées à « m » et « n ».

En outre, les valeurs de métadonnées précédemment définies peuvent également être ajoutées. Par exemple:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m>%(m);m2</m>
    </i>
</ItemDefinitionGroup>

Dans cet exemple, la valeur définie précédemment pour les métadonnées « m » (m1) est ajoutée à la nouvelle valeur (m2), afin que la valeur finale soit « m1 ; m2".

Remarque

Cela peut également se produire dans le même ItemDefinitionGroup.

Lorsque vous remplacez les métadonnées précédemment définies, la dernière spécification est prioritaire. Dans l’exemple suivant, la valeur finale des métadonnées « m » passe de « m1 » à « m1a ».

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m>m1a</m>
    </i>
</ItemDefinitionGroup>

Utiliser des conditions dans un ItemDefinitionGroup

Vous pouvez utiliser des conditions dans un ItemDefinitionGroup pour contrôler l’inclusion des métadonnées. Par exemple:

<ItemDefinitionGroup Condition="'$(Configuration)'=='Debug'">
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>

Dans ce cas, les métadonnées par défaut « m1 » sur l’élément « i » sont incluses uniquement si la valeur de la propriété « Configuration » est « Debug ».

Remarque

Seules les références de métadonnées locales sont prises en charge dans les conditions.

Les références aux métadonnées définies dans un ÉlémentDefinitionGroup antérieur sont locales à l’élément, et non au groupe de définitions. Autrement dit, l’étendue des références est spécifique à l’élément. Par exemple:

<ItemDefinitionGroup>
    <test>
        <yes>1</yes>
    </test>
    <i>
        <m>m0</m>
        <m Condition="'%(test.yes)'=='1'">m1</m>
    </i>
</ItemDefinitionGroup>

Dans l’exemple ci-dessus, l’élément « i » fait référence à l’élément « test » dans sa condition. Cette condition ne sera jamais vraie, car MSBuild interprète une référence aux métadonnées d’un autre élément dans un ItemDefinitionGroup comme chaîne vide. Par conséquent, « m » est défini sur « m0 ».

  <ItemDefinitionGroup>
    <i>
      <m>m0</m>
      <yes>1</yes>
      <m Condition="'%(i.yes)'=='1'">m1</m>
    </i>
  </ItemDefinitionGroup>

Dans l’exemple ci-dessus, « m » est défini sur la valeur « m1 », car la condition fait référence à la valeur de métadonnées de l’élément « i » pour l’élément « oui ».

Remplacer et supprimer des métadonnées

Les métadonnées définies dans un élément ItemDefinitionGroup peuvent être substituées dans un élément ItemDefinitionGroup ultérieur en définissant la valeur des métadonnées sur une autre valeur. Vous pouvez également supprimer efficacement un élément de métadonnées en le définissant sur une valeur vide. Par exemple:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m></m>
    </i>
</ItemDefinitionGroup>

L’élément « i » contient toujours les métadonnées « m », mais sa valeur est maintenant vide.

Étendue des métadonnées

Les ItemDefinitionGroups ont une étendue globale sur les propriétés définies et globales où qu’elles soient définies. Les définitions de métadonnées par défaut dans un ItemDefinitionGroup peuvent être autoréférentielles. Par exemple, les éléments suivants utilisent une référence de métadonnées simple :

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>%(m);m2</m>
    </i>
</ItemDefinitionGroup>

Vous pouvez également utiliser une référence de métadonnées qualifiée :

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>%(i.m);m2</m>
    </i>
</ItemDefinitionGroup>

Toutefois, les éléments suivants ne sont pas valides :

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>@(x)</m>
    </i>
</ItemDefinitionGroup>

À compter de MSBuild 3.5, ItemGroups peut également être autoréférentiel. Par exemple:

<ItemGroup>
    <item Include="a">
        <m>m1</m>
        <m>%(m);m2</m>
    </item>
</ItemGroup>

Contenu connexe

  • Last updated on