Im ersten Teil der MSBuild Artikelserie wurden verschiedene Basics der MSBuild Thematik erklärt. In diesem Post gehen wir, wie der Title schon erahnen lässt, etwas weiter.
Zunächst erstellen wir, wie versprochen, das “HelloBuildWorld – Reloaded” Build-File. Der Unterschied zum Original besteht darin, dass die Ausgabe um eine Variable erweitert wird. Hierfür werden MSBuild – Properties benutzt.
MSBuild Properties
MSBuild Properties sind Schlüssel-Wert-Paare, die der Entwickler beim Erstellen eines Build-Scriptes hinterlegen kann. Properties werden in MSBuild-Files immer in eine PropertyGroup zusammengefasst.
Eine Property erstellen
Das Xml-Rootelement “Project” kann beliebig viele PropertyGroup-Nodes als direkte Kind-Elemente haben, welches wiederum aus beliebig vielen MSBuild-Properties bestehen kann.
Listing 1 zeigt wie eine einfache MSBuild-PropertyGroup aussieht.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<!-- some properties will be defined here...-->
</PropertyGroup>
</Project>
Somit ist der Container für die Properties schon mal geschafft! Das war einfach, oder? Jetzt kommen wir aber zum interessanten Teil dieser Passage, die eigentlichen Properties.
Um eine Property zu definieren muss lediglich ein neues XML-Node erstellt werden. Hierfür gibt es keinerlei Vorgaben! Die XML-Node kann man nennen wie man will.
Der Name der XML-Node entspricht dem Key der Property!
Die eben erstellte Propertygruppe erweitern wir nun einfach um eine Einstellung, die einen Benutzernamen speichern soll. Daher vergeben wir den Key “UserName” und ein beliebiges value.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<UserName>Thorsten Hans</UserName>
</PropertyGroup>
</Project>
Somit ist die erste MSBuild Property auch definiert, doch hier noch eine kleine Info
Visual Studio zeigt für die gerade angelegte Property eine Warnung im XML-Editor an, dies tritt bei jeder ersten Property im Dokument auf, dar diese Nodes natürlich nicht Bestandteil des XML-Schemas sein können.
Diese Warnung kann allerdings getrost ignoriert werden!
Eine MSBuild Property verwenden
Die Property ist definiert, doch wie sage ich MSBuild, dass es diese nun Verwenden soll?
Auch dass ist sehr einfach. Um eine Property irgendwo im Build-File verwenden zu können, muss einfach ein leichter Syntax befolgt werden.
$(PropertyKey)
In unserem Fall wäre wohl eher $(UserName) korrekt. Um das Beispiel zu komplettieren, hier nochmals das ganze Buildscript, welches eine revolutionäre Meldung auf die Console zaubert.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<UserName>Thorsten Hans</UserName>
</PropertyGroup>
<Target Name="HelloBuildWorldReloaded">
<Message Text="Hello MSBuild world! What's up $(UserName)?" />
</Target>
</Project>
Nachdem die Projektdatei gespeichert wurde, kann diese einfach mittels MSBuild.exe aus der VS-Command-Line gestartet werden. Hierzu verwendet man folgende Parameter
msbuild.exe HelloBuildWorldReloaded.proj /t:HelloBuildWorldReloaded
Wenn ihr alles korrekt gemacht habt, solltet ihr folgende Ausgabe auf der Console bekommen
Wie man leicht erkennen kann wurde in Zeile 4 die zuvor definierte Property UserName ausgegeben. Jetzt gibt es allerdings öfters Szenarien, bei denen man eine variable direkt bei der Ausführung von MSBuild setzen möchte und nicht nochmals extra das XML-Dokument anfassen möchte.
Hierfür kennt MSBuild.exe auch einen entsprechenden Parameter. Durch Angabe des Parameters /p kann man einfach eine Property im Build Script setzen. Passen wir das MSBuild Kommando nun dementsprechend an, so dass folgendes Kommando entsteht
msbuild.exe HelloBuildWorldReloaded.proj /t:HelloBuildWorldReloaded /p:UserName=”.NET Community”
Unser Ergebnis wird nach der erneuten Ausführung nun etwas Community-freundlicher sein.
Ok, damit sollte man in der Lage sein Properties, die man zuvor definiert hat auch zu setzen, doch gibt es noch weitere Möglichkeiten die mir MSBuild Properties liefern? – Auch hier ein ganz klares !JA!
Spezielle MSBuild Properties
Neben eigens definierten Properties kann man in MSBuild durch Properties auf Umgebungsvariablen und Registry-Werte zurückgreifen, darüber hinaus bringt MSBuild schon eine ganze Reihe von vordefinierten Properties mit sich.
Umgebungsvariablen
Sämtliche Umgebungsvariablen, die der aktuelle Benutzer Aufgrund vorhandener Sicherheitseinstellungen zugreifen kann, sind auch in MSBuild verfügbar.
Die berühmteste wird wohl die “PATH” Variable sein. Möchte man diese in einem Build-Script verwenden so kann man dies einfach über den bereits gelernten Property-Syntax erreichen.
$(Path) wäre es in diesem Fall.
Registry Einträge
Umgebungsvariablen sind nett, doch oft benötigt man noch Einstellungen oder Werte aus der Windows-Registry (für all die jungen Leser aus der Generation-Klick START->AUSFÜHREN->REGEDIT) :D … Auch dies kann man in MSBuild-Files schnell und einfach realisieren. Hierfür benötigt man allerdings eine etwas erweiterte Property-Syntax-Form
$(registry:HKEY_CURRENT_USER\Software\MSBuildTutorials@Level)
Bei diesem Fragment gibt es einige wenige Punkte zu beachten
- Prefix verwenden
- Scope der Registry angeben
- “HKEY_CURRENT_USER”
- “HKEY_CURRENT_CONFIG”
- …
- Schlüssel angeben
- “@Level”
- keine Angabe eines Schlüssels gibt den Standardschlüssel zurück
Vordefinierte MSBuild Properties
Die letzte Gruppe an “speziellen” Properties bilden die bereits vordefinierten Properties. Diese wurden vom MSBuild Team deklariert und bringen hauptsächlich Runtime-Informationen ans Tageslicht. Deren Verwendung ist analog zur Verwendung von eigens definierten MSBuild Properties
$(MSBuildProjectName) würde zum Beispiel den Namen der Projektdatei ohne die Dateiendung liefern
Eine gesamte Liste aller vordefinierten MSBuild Properties findet man untern http://msdn.microsoft.com/en-us/library/ms164309.aspx
MSBuild Properties Unleashed
Wie man einfache Properties erstellt oder verwendet wäre damit abgehandelt nun kommen wir zu etwas nützlicheren Dingen in Sachen Properties, den Bedingungen. Bedingungen kann man sowohl auf Ebene der PropertyGroup, als auch auf Ebene einer einzelnen Property verwenden.
MSBuild Properties mit Conditions
Das Node PropertyGroup und jede selbst definierte Property können um das XML-Attribut “Condition” erweitert werden. Dieses Attribut wird dazu verwendet um beliebige Bedingungen im MSBuild – Script zu definieren und zu verwenden.
Bei der Definition von Konditionen sollte man zwei Dinge beachten, die einem das Leben leichter machen werden
- Einen Standardfall definieren
- Properties und somit auch Konditionen werden sequentiell ausgewertet von MSBuild
Wenn man diese beiden Punkte verinnerlicht, stellen Property-Conditions eine mächtige Funktionalität dar, die dennoch recht einfach und schnell zu erlernen ist.
Als Beispiel für Konditionen möchte ich ein einfaches Build-Script nehmen, welches anhand einer Property einen bestimmten Wert definiert und diesen im späteren Verlauf des Scripts ausgibt.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<UserName>Thorsten Hans</UserName>
<UseBusinessSettings Condition="'$(UseBusinessSettings)'==''">TRUE</UseBusinessSettings>
</PropertyGroup>
<PropertyGroup Condition="'$(UseBusinessSettings)'=='TRUE'">
<Email>thorsten.hans[at]dataone.de</Email>
</PropertyGroup>
<PropertyGroup Condition="'$(UseBusinessSettings)'=='FALSE'">
<Email>thorstenhans[at]hotmail.com</Email>
</PropertyGroup>
<Target Name="PrintMailAddress">
<Message Text="The mailaddress is $(Email)"/>
</Target>
</Project>
“UseBusinessSettings” ist in diesem kleinen Build-Script die Kontrollproperty, abhängig von dessen Wert wird die Email-Adresse angegeben und im weiteren Verlauf des Scriptes an die registrierte Console ausgegeben.
Wie man in Zeile vier sehen kann, wird, insofern kein Wert für “UseBusinessSettings” angegeben ist, der Wert “TRUE” verwendet. Genau dieser Wert wird dann von den beiden folgenden PropertyGroups ausgewertet und gibt somit an welche Initialisierung der Property “Email” genutzt wird.
Bei Conditions ist das Escaping des Feldes und des Vergleichswertes zu beachten!
Führt man dieses Build-File nun mit MSBuild.exe aus ergibt sich folgende Ausgabe
In Zeile 4 wird der die “Business-Email” ausgegeben, weil die Property “UseBusinessSettings” bei der ersten Verwendung noch keinen Wert hat und somit der Standardwert “TRUE” verwendet wird.
Wenn man jetzt mit dem Parameter /p der MSBuild.exe “UseBusinessSettings” auf “FALSE” setzt, wird die private Email-Adresse ausgegeben was dann so aussieht
Fazit
Eigentlich wollte ich in diesem Teil des Tutorials wie angekündigt noch einige weitere Tasks von MSBuild zeigen, doch es erschien mir doch wichtiger zunächst alle Funktionen und Möglichkeiten von MSBuild-Properties zu zeigen.
Im nächsten Teil der MSBuild Artikelserie werde ich MSBuild Items vorstellen und zeigen was man damit schönes anstellen kann. Die Standard MSBuild-Tasks werden dann aber darauf folgen.