Elementdefinitionen

MSBuild 2.0 aktiviert die statische Deklaration von Elementen in Projektdateien mithilfe des Elements ItemGroup. Metadaten können jedoch nur auf Elementebene hinzugefügt werden, auch wenn die Metadaten für alle Elemente gleich sind. In MSBuild 3.5 wurde das Projektelement ItemDefinitionGroup eingeführt, das diese Einschränkung aufhebt. Mit ItemDefinitionGroup können Sie einen Satz von Elementdefinitionen festlegen, um allen Elementen im benannten Elementtyp Standardwerte für Metadaten hinzuzufügen.

Das ItemDefinitionGroup-Element wird unmittelbar nach dem Project-Element der Projektdatei angezeigt. Elementdefinitionen bieten die folgenden Funktionen:

• Sie können globale Standardmetadaten für Elemente außerhalb eines Ziels definieren. Das heißt, für alle Elemente des angegebenen Typs gelten die gleichen Metadaten.

• Elementtypen können mehrere Definitionen aufweisen. Wenn dem Typ weitere Metadatenspezifikationen hinzugefügt werden, hat die letzte Spezifikation Vorrang. (Die Metadaten folgen der gleichen Importreihenfolge wie Eigenschaften.)

• Metadaten können additiv sein. Zum Beispiel werden CDefines-Werte bedingt akkumuliert, abhängig von den festgelegten Eigenschaften. Beispielsweise MT;STD_CALL;DEBUG;UNICODE.

• Metadaten können entfernt werden.

• Bedingungen können verwendet werden, um das Einschließen der Metadaten zu steuern.

Standardwerte von Elementmetadaten

Elementmetadaten, die in ItemDefinitionGroup definiert werden, sind nur eine Deklaration der Standardmetadaten. Die Metadaten finden nur dann Anwendung, wenn Sie ein Element definieren, das zum Einschließen der Metadatenwerte ItemGroup verwendet.

Explizit in einem ItemGroup-Element definierte Metadaten haben Vorrang vor Metadaten in einem ItemDefinitionGroup-Element. Metadaten in einem ItemDefinitionGroup-Element werden nur auf nicht definierte Metadaten in einem ItemGroup-Element angewendet. Zum Beispiel:

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

In diesem Beispiel wird das Standardmetadatum "m" auf das Element "i" angewendet, da das Metadatum "m" nicht explizit durch das Element "i" definiert wird. Das Standardmetadatum "n" wird jedoch nicht auf das Element "i" angewendet, da das Metadatum "n" bereits durch Element "i" definiert ist.

Wertquellen

Die Werte der in ItemDefinitionGroup definierten Metadaten können aus verschiedenen Quellen stammen:

• PropertyGroup-Eigenschaft

• Element aus ItemDefinitionGroup

• Elementtransformation für ein ItemDefinitionGroup-Element

• Umgebungsvariable

• Globale Eigenschaft (aus der MSBuild.exe-Befehlszeile)

• Reservierte Eigenschaft

• Bekannte Metadaten über ein Element aus ItemDefinitionGroup

• CDATA-Abschnitt <![CDATA[Dies hier wird nicht analysiert]]>

Additive und mehrfache Definitionen

Wenn Sie Definitionen hinzufügen oder mehrere ItemDefinitionGroups verwenden, beachten Sie Folgendes:

• Dem Typ werden zusätzliche Metadatenspezifikationen hinzugefügt.

• Die letzte Spezifikation hat Vorrang.

Wenn Sie über mehrere ItemDefinitionGroups verfügen, werden die Metadaten jeder folgenden Spezifikation der vorhergehenden Definition hinzugefügt. Zum Beispiel:

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

In diesem Beispiel werden die Metadaten"o" zu "m" und "n" hinzugefügt.

Darüber hinaus können auch bereits definierte Metadatenwerte hinzugefügt werden. Zum Beispiel:

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

In diesem Beispiel wird der bereits definierte Wert für die Metadaten "m" (m1) dem neuen Wert (m2) hinzugefügt, sodass der Endwert "m1;m2" lautet.

Wenn Sie die bereits definierten Metadaten überschreiben, hat die letzte Spezifikation Vorrang. Im folgenden Beispiel ändert sich der endgültige Wert der Metadaten "m" von "m1" in "m1a".

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

Verwenden von Bedingungen in ItemDefinitionGroup

Sie können Bedingungen in ItemDefinitionGroup verwenden, um das Einschließen von Metadaten zu steuern. Zum Beispiel:

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

In diesem Fall werden die Standardmetadaten "m1" für Element "i" nur dann eingeschlossen, wenn der Wert der "Configuration"-Eigenschaft "Debug" lautet.

Verweise auf Metadaten, die in einem früheren ItemDefinitionGroup definiert sind, sind für das Element lokal, nicht für die Definitionsgruppe. Das heißt, der Umfang der Verweise ist elementspezifisch. Zum Beispiel:

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

Im obigen Beispiel verweist Element „i“ auf das Element „test“ in seiner Bedingung. Diese Bedingung wird niemals „true“ ergeben, da MSBuild einen Verweis auf die Metadaten eines anderen Elements in einer ItemDefinitionGroup als leere Zeichenfolge interpretiert. Aus diesem Grund würde „m“ auf „m0“ festgelegt.

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

Im Beispiel oben würde für „m“ der Wert „m1“ festgelegt, da die Bedingung auf den Metadatenwert des Elements „i“ für Element „yes“ verweist.

Außerkraftsetzen und Löschen von Metadaten

In einem ItemDefinitionGroup-Element definierte Metadaten können in einem späteren ItemDefinitionGroup-Element überschrieben werden, indem der Metadatenwert auf einen anderen Wert festgelegt wird. Sie können ein Metadatenelement auch löschen, indem Sie es auf einen leeren Wert festlegen. Zum Beispiel:

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

Das Element "i" enthält immer noch die Metadaten "m", sein Wert ist jetzt jedoch leer.

Umfang der Metadaten

ItemDefinitionGroup weist einen globalen Gültigkeitsbereich für definierte und globale Eigenschaften auf, unabhängig davon, wo sie definiert sind. Standardmäßige Metadatendefinitionen in ItemDefinitionGroup können auf sich selbst verweisen. Nachfolgend wird beispielsweise ein einfacher Metadatenverweis verwendet:

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

Es kann auch ein qualifizierter Metadatenverweis verwendet werden:

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

Folgendes ist jedoch nicht gültig:

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

Ab MSBuild 3.5 kann ItemGroup auch auf sich selbst verweisen. Beispiel:

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

Zugehöriger Inhalt

• Batchverarbeitung