Vergleich von Eigenschaften und Elementen

Artikel
02/26/2013

MSBuild-Eigenschaften und Elemente werden zum Übergeben von Informationen an Aufgaben, Auswerten von Bedingungen sowie zum Speichern von Werten verwendet, auf die in der gesamten Projektdatei verwiesen werden kann.

Eigenschaften sind Name-Wert-Paare.Weitere Informationen finden Sie unter MSBuild-Eigenschaften.
Elemente sind Objekte, die in der Regel Dateien darstellen.Elementobjekten können Metadatenauflistungen zugeordnet sein.Metadaten sind Name-Wert-Paare.Weitere Informationen finden Sie unter MSBuild-Elemente.

Skalare und Vektoren

Da MSBuild-Eigenschaften Name-Wert-Paare sind, die nur einen Zeichenfolgenwert aufweisen, werden sie häufig als Skalare beschrieben.Da MSBuild-Elementtypen Listen von Elementen sind, werden sie häufig als Vektoren beschrieben.In der Praxis können Eigenschaften jedoch mehrere Werte darstellen, und Elementtypen können 0 (null) oder ein Element besitzen.

Einfügen der Zielabhängigkeit

Zur Verdeutlichung der Darstellung mehrerer Werte durch Eigenschaften betrachten Sie ein häufiges Verwendungsmuster zum Hinzufügen eines Ziels zu einer Liste von zu erstellenden Zielen.Diese Liste wird in der Regel durch einen Eigenschaftswert dargestellt, wobei die Zielnamen durch Semikolons getrennt sind.

<PropertyGroup>
    <BuildDependsOn>
        BeforeBuild;
        CoreBuild;
        AfterBuild
    </BuildDependsOn>
</PropertyGroup>

Die BuildDependsOn-Eigenschaft wird meist als Argument eines DependsOnTargets-Zielattributs verwendet, wodurch dieses in eine Elementliste konvertiert wird.Diese Eigenschaft kann überschrieben werden, um ein Ziel hinzuzufügen oder die Ausführungsreihenfolge der Ziele zu ändern.Beispiel:

<PropertyGroup>
    <BuildDependsOn>
        $(BuildDependsOn);
        CustomBuild;
    </BuildDependsOn>
</PropertyGroup>

fügt der Zielliste das Ziel CustomBuild hinzu und weist BuildDependsOn den Wert BeforeBuild;CoreBuild;AfterBuild;CustomBuild zu.

Seit MSBuild 4.0 wird die Einfügung der Zielabhängigkeit als veraltet behandelt.Verwenden Sie stattdessen das AfterTargets-Attribut und das BeforeTargets-Attribut.Weitere Informationen finden Sie unter Buildreihenfolge für Ziele.

Konvertierungen zwischen Zeichenfolgen und Elementlisten

MSBuild führt nach Bedarf Konvertierungen aus und in Elementtypen und Zeichenfolgenwerte aus.Zur Verdeutlichung der Konvertierung einer Elementliste in einen Zeichenfolgenwert betrachten Sie den Ablauf bei der Verwendung eines Elementtyps als Wert einer MSBuild-Eigenschaft:

<ItemGroup>
    <OutputDir Include="KeyFiles\;Certificates\" />
  </ItemGroup>
<PropertyGroup>
    <OutputDirList>@(OutputDir)</OutputDirList>
</PropertyGroup>

Der OutputDir-Elementtyp verfügt über ein Include-Attribut mit dem Wert "KeyFiles\;Certificates\".MSBuild analysiert diese Zeichenfolge in zwei Elemente, KeyFiles\ und Certificates\.Wenn der OutputDir-Elementtyp als Wert der OutputDirList-Eigenschaft verwendet wird, konvertiert oder "vereinfacht" MSBuild den Elementtyp zur durch Semikolons getrennten Zeichenfolge "KeyFiles\;Certificates\".

Eigenschaften und Elemente in Aufgaben

Eigenschaften und Elemente werden als Eingaben und Ausgaben von MSBuild-Aufgaben verwendet.Weitere Informationen finden Sie unter MSBuild-Aufgaben.

Eigenschaften werden als Attribute an Aufgaben übergeben.Innerhalb der Aufgabe wird eine MSBuild-Eigenschaft durch einen Eigenschaftentyp dargestellt, dessen Wert in eine und aus einer Zeichenfolge konvertiert werden kann.Zu den unterstützten Eigenschaftenwerten zählen bool, char, DateTime, Decimal, Double, int, string sowie alle Typen, die von ChangeType behandelt werden können.

Elemente werden als ITaskItem-Objekte an Aufgaben übergeben.Innerhalb der Aufgabe stellt ItemSpec den Wert des Elements dar, und GetMetadata ruft dessen Metadaten ab.

Die Elementliste eines Elementtyps kann als Array von ITaskItem-Objekten übergeben werden.Seit .NET Framework 3.5 können Elemente mithilfe des Remove-Attributs aus einer Elementliste in einem Ziel entfernt werden.Da Elemente aus einer Elementliste entfernt werden können, kann ein Elementtyp 0 (null) Elemente aufweisen.Wenn eine Elementliste an eine Aufgabe übergeben wird, sollte der Code in der Aufgabe diese Möglichkeit überprüfen.

Auswertungsreihenfolge für Eigenschaften und Elemente

Während der Auswertungsphase eines Builds werden importierte Dateien in der Reihenfolge in den Build integriert, in der sie angegeben werden.Eigenschaften und Elemente werden in drei Durchläufen in der folgenden Reihenfolge definiert:

Eigenschaften werden in der Reihenfolge definiert und geändert, in der sie angegeben werden.
Elementdefinitionen werden in der Reihenfolge definiert und geändert, in der sie angegeben werden.
Elemente werden in der Reihenfolge definiert und geändert, in der sie angegeben werden.

Während der Ausführungsphase eines Builds werden in Zielen definierte Eigenschaften und Elemente zusammen in einer einzelnen Phase in der Reihenfolge ausgewertet, in der sie angegeben werden.

Dies ist jedoch nicht die ganze Wahrheit.Wenn eine Eigenschaft, eine Elementdefinition oder ein Element definiert wird, wird der zugehörige Wert ausgewertet.Bei der Ausdrucksauswertung wird die Zeichenfolge, die den Wert angibt, erweitert.Die Zeichenfolgenerweiterung ist von der Buildphase abhängig.Im Folgenden finden Sie eine detaillierte Auswertungsreihenfolge für Eigenschaften und Elemente:

Während der Auswertungsphase eines Builds:
- Eigenschaften werden in der Reihenfolge definiert und geändert, in der sie angegeben werden.Eigenschaftenfunktionen werden ausgeführt.Eigenschaftswerte der Form $(PropertyName) werden in den Ausdrücken erweitert.Die Eigenschaftenwert wird auf den erweiterten Ausdruck festgelegt.
- Elementdefinitionen werden in der Reihenfolge definiert und geändert, in der sie angegeben werden.Eigenschaftenfunktionen wurden bereits in den Ausdrücken erweitert.Metadatenwerte werden auf die erweiterten Ausdrücke festgelegt.
- Elementtypen werden in der Reihenfolge definiert und geändert, in der sie angegeben werden.Elementwerte der Form @(ItemType) werden erweitert.Elementtransformationen werden ebenfalls erweitert.Eigenschaftsfunktionen und Eigenschaftenwerte wurden bereits in den Ausdrücken erweitert.Die Elementliste und die Metadatenwerte werden auf die erweiterten Ausdrücke festgelegt.
Während der Ausführungsphase eines Builds:
- In Zielen definierte Eigenschaften und Elemente werden zusammen in der Reihenfolge ausgewertet, in der sie angegeben werden.Eigenschaftenfunktionen werden ausgeführt, und Eigenschaftswerte werden in Ausdrücken erweitert.Elementwerte und Elementtransformationen werden ebenfalls erweitert.Die Eigenschaftswerte, Elementtypwerte und Metadatenwerte werden auf die erweiterten Ausdrücke festgelegt.

Weitere Auswirkungen der Auswertungsreihenfolge

In der Auswertungsphase eines Builds besitzt die Eigenschaftenauswertung Vorrang vor der Elementauswertung.Trotzdem können Eigenschaften Werte besitzen, die scheinbar von Elementwerten abhängen.Betrachten Sie das folgende Skript:

<ItemGroup>
    <KeyFile Include="KeyFile.cs">
        <Version>1.0.0.3</Version>
    </KeyFile>
</ItemGroup>
<PropertyGroup>
    <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
</PropertyGroup>
<Target Name="AfterBuild">
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>

Beim Ausführen der Message-Aufgaben wird die folgende Meldung angezeigt:

KeyFileVersion: 1.0.0.3

Die Ursache dafür besteht darin, dass der Wert von KeyFileVersion eigentlich die Zeichenfolge "@(KeyFile->'%(Version)')" ist.Element und Elementtransformationen wurden bei der ersten Definition der Eigenschaft nicht erweitert, deshalb wurde der KeyFileVersion-Eigenschaft der Wert der nicht erweiterten Zeichenfolge zugewiesen.

Während der Ausführungsphase des Builds erweitert MSBuild beim Verarbeiten der Message-Aufgabe die Zeichenfolge "@(KeyFile->'%(Version)')" so, dass dies "1.0.0.3" ergibt.

Dieselbe Meldung würde auch bei umgekehrter Reihenfolge von Eigenschaften- und Elementgruppen angezeigt.

Betrachten Sie als zweites Beispiel die möglichen Folgen, wenn sich Eigenschaften- und Elementgruppen in den Zielen befinden:

<Target Name="AfterBuild">
    <PropertyGroup>
        <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
    </PropertyGroup>
    <ItemGroup>
        <KeyFile Include="KeyFile.cs">
            <Version>1.0.0.3</Version>
        </KeyFile>
    </ItemGroup>
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>

Beim Ausführen der Message-Aufgaben wird die folgende Meldung angezeigt:

KeyFileVersion:

Der Grund dafür besteht darin, dass während der Ausführungsphase des Builds in den Zielen definierte Eigenschaft- und Elementgruppen gleichzeitig von oben nach unten ausgewertet werden.Wenn KeyFileVersion definiert wurde, ist KeyFile unbekannt.Daher wird die Elementtransformation zu einer leeren Zeichenfolge erweitert.

In diesem Fall wird beim Umkehren der Reihenfolge von Eigenschaften- und Elementgruppen die ursprüngliche Nachricht wiederhergestellt:

<Target Name="AfterBuild">
    <ItemGroup>
        <KeyFile Include="KeyFile.cs">
            <Version>1.0.0.3</Version>
        </KeyFile>
    </ItemGroup>
    <PropertyGroup>
        <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
    </PropertyGroup>
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>

Der Wert von KeyFileVersion wird auf "1.0.0.3" und nicht auf "@(KeyFile->'%(Version)')" festgelegt.Beim Ausführen der Message-Aufgaben wird die folgende Meldung angezeigt:

KeyFileVersion: 1.0.0.3

Siehe auch

Weitere Ressourcen

Weiterführende MSBuild-Konzepte

Freigeben über