MSBuild-Eigenschaften

Artikel
02/26/2013

Eigenschaften sind Name/Wert-Paare, die zur Konfiguration von Builds verwendet werden können.Sie sind hilfreich, um Werte an Aufgaben zu übergeben, Bedingungen auszuwerten und Werte zu speichern, auf die in der gesamten Projektdatei verwiesen wird.

Definieren von und Verweisen auf Eigenschaften in einer Projektdatei

Eigenschaften werden deklariert, indem ein Element mit dem Namen der Eigenschaft als untergeordnetes Element eines PropertyGroup-Elements erstellt wird.Durch das folgende XML wird beispielsweise die Eigenschaft BuildDir mit dem Wert Build erstellt.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

In der gesamten Projektdatei wird mit der Syntax $(PropertyName) auf Eigenschaften verwiesen.Beispielsweise wird mit $(BuildDir) auf die Eigenschaft im vorangehenden Beispiel verwiesen.

Eigenschaftswerte können durch Neudefinieren der Eigenschaft geändert werden.Der Wert der Eigenschaft BuildDir kann mit folgendem XML geändert werden:

<PropertyGroup>
    <BuildDir>Alternate</BuildDir>
</PropertyGroup>

Eigenschaften werden in der Reihenfolge ausgewertet, in der sie in der Projektdatei angezeigt werden.Der neue Wert für BuildDir muss deklariert werden, nachdem der alte Wert zugewiesen wurde.

Reservierte Eigenschaften

Einige Eigenschaftennamen werden von MSBuild reserviert, um Informationen zur Projektdatei und zu den Binärdateien von MSBuild zu speichern.Auf diese Eigenschaften wird wie auf jede andere Eigenschaft mit der $-Notation verwiesen.Beispielsweise gibt $(MSBuildProjectFile) den vollständigen Namen der Projektdatei einschließlich der Dateinamenerweiterung zurück.

Weitere Informationen finden Sie unter Gewusst wie: Verweisen auf den Namen oder Speicherort der Projektdatei und Reservierte Eigenschaften für MSBuild.

Umgebungseigenschaften

Auf Umgebungsvariablen in Projektdateien kann auf die gleiche Weise verwiesen werden wie auf reservierte Eigenschaften.Um die PATH-Umgebungsvariable in der Projektdatei zu verwenden, verwenden Sie beispielsweise $(Path).Wenn das Projekt eine Eigenschaftendefinition enthält, die denselben Namen wie eine Umgebungseigenschaft hat, wird der Wert der Umgebungsvariablen von der Eigenschaft im Projekt überschrieben.

Jedes MSBuild-Projekt hat einen lokalisierten Umgebungsblock: es sieht nur liest und schreibt in einem eigenen - Block.MSBuild liest nur Umgebungsvariablen, wenn die Eigenschaftenauflistung initialisiert, bevor die Projektdatei ausgewertet oder erstellt wird.Danach sind Umgebungseigenschaften h. startet jedes generierte Tools mit denselben Namen und Werten statisch.

Um den aktuellen Wert der Umgebungsvariablen aus einem Tool generierten abzurufen, verwenden Sie das Eigenschaftenfunktionen System.Environment.GetEnvironmentVariable.Die bevorzugte Methode besteht jedoch darin, den - EnvironmentVariables zu verwenden.Die Umgebungseigenschaften, die in diesem Zeichenfolgenarray festgelegt sind, können dem generierten Tool übergeben werden, ohne die Systemumgebungsvariablen zu beeinflussen.

Tipp
Nicht alle Umgebungsvariablen werden gelesen, um ursprüngliche Eigenschaften zu werden.Jede Umgebungsvariable, deren Name nicht gültige MSBuild-Eigenschaftennamen, wie "386 " ist, wird ignoriert.

Weitere Informationen finden Sie unter Gewusst wie: Verwenden von Umgebungsvariablen in einem Build.

Registrierungseigenschaften

Systemregistrierungswerte können mit der nachfolgend angegebenen Syntax gelesen werden. Dabei steht Hive für den Registrierungshive (z. B. HKEY_LOCAL_MACHINE), Key steht für den Schlüsselnamen, SubKey für den Unterschlüsselnamen, und Value ist der Wert des Unterschlüssels.

$(registry:Hive\MyKey\MySubKey@Value)

Lassen Sie Value weg, um den Standardunterschlüsselwert abzurufen.

$(registry:Hive\MyKey\MySubKey)

Mit diesem Registrierungswert kann eine Buildeigenschaft initialisiert werden.Beispielsweise können Sie mit dem folgenden Code eine Buildeigenschaft erstellen, die die Webbrowser-Homepage für Visual Studio darstellt:

<PropertyGroup>
  <VisualStudioWebBrowserHomePage>
    $(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\11.0\WebBrowser@HomePage)
  </VisualStudioWebBrowserHomePage>
<PropertyGroup>

Globale Eigenschaften

In MSBuild können Sie mit dem Schalter /property (oder mit dem Schalter /p) Eigenschaften in der Befehlszeile festlegen.Diese globalen Eigenschaftswerte überschreiben Eigenschaftswerte, die in der Projektdatei festgelegt werden.Dies betrifft auch Umgebungseigenschaften, nicht jedoch reservierte Eigenschaften ein, die nicht geändert werden können.

Im folgenden Beispiel wird die globale Configuration-Eigenschaft auf DEBUG festgelegt.

msbuild.exe MyProj.proj /p:Configuration=DEBUG

Globale Eigenschaften können auch für untergeordnete Projekte in einem Build mit mehreren Projekten festgelegt oder geändert werden, indem das Properties-Attribut der MSBuild-Aufgabe verwendet wird.Weitere Informationen finden Sie unter MSBuild-Aufgabe.

Wenn Sie eine Eigenschaft angeben, indem Sie das - Attribut in einem TreatAsLocalProperty Projekttag verwenden, überschreibt dieser globale Eigenschaftswert nicht den Eigenschaftswert, der in der Projektdatei festgelegt wird.Weitere Informationen finden Sie unter Project-Element (MSBuild) und Gewusst wie: Erstellen identischer Quelldateien mit unterschiedlichen Optionen.

Eigenschaftenfunktionen

In .NET Framework, Version 4, können Sie Eigenschaftenfunktionen verwenden, um MSBuild-Skripts auszuwerten.Sie können die Systemzeit lesen, Zeichenfolgen vergleichen, reguläre Ausdrücke abgleichen und viele weitere Aktionen ohne MSBuild-Aufgaben im Buildskript ausführen.

Sie können Zeichenfolgen-(Instanz-)Methoden für beliebige Eigenschaftswerte verwenden, und Sie können die statischen Methoden für zahlreiche Systemklassen aufrufen.Beispielsweise können Sie so eine Buildeigenschaft auf das heutige Datum festlegen:

<Today>$([System.DateTime]::Now.ToString("yyyy.MM.dd"))</Today>

Weitere Informationen und eine Liste der verfügbaren Eigenschaftenfunktionen finden Sie unter Eigenschaftenfunktionen.

Erstellen von Eigenschaften während der Ausführung

Eigenschaften außerhalb von Target-Elementen werden die Werte im Rahmen der Auswertungsphase eines Builds zugewiesen.Während der anschließenden Ausführungsphase können die Eigenschaften erstellt oder geändert werden, wie nachfolgend veranschaulicht:

Eigenschaften können von einer beliebigen Aufgabe ausgegeben werden.Um eine Eigenschaft auszugeben, muss das Task-Element über ein untergeordnetes Output-Element mit einem PropertyName-Attribut verfügen.
Eigenschaften können von der CreateProperty-Aufgabe ausgegeben werden.Diese Verwendung ist veraltet.
Ab .NET Framework 3.5 können PropertyGroup-Elemente mit Eigenschaftendeklarationen in Target-Elementen enthalten sein.

Speichern von XML in Eigenschaften

Eigenschaften können beliebigen XML-Code enthalten, um die Übergabe von Werten an Aufgaben oder das Anzeigen von Protokollierungsinformationen zu unterstützen.Im folgenden Beispiel wird die ConfigTemplate-Eigenschaft veranschaulicht, die über einen Wert verfügt, der XML- und andere Eigenschaftenverweise enthält.MSBuild ersetzt die Eigenschaftenverweise durch ihre jeweiligen Eigenschaftswerte.Eigenschaftswerte werden in der Reihenfolge zugewiesen, in der sie angezeigt werden.$(MySupportedVersion), $(MyRequiredVersion) und $(MySafeMode) sollten in diesem Beispiel daher bereits definiert worden sein.

<PropertyGroup>
    <ConfigTemplate>
        <Configuration>
            <Startup>
                <SupportedRuntime
                    ImageVersion="$(MySupportedVersion)"
                    Version="$(MySupportedVersion)"/>
                <RequiredRuntime
                    ImageVersion="$(MyRequiredVersion)
                    Version="$(MyRequiredVersion)"
                    SafeMode="$(MySafeMode)"/>
            </Startup>
        </Configuration>
    </ConfigTemplate>
</PropertyGroup>

Siehe auch